List of Known Pitfalls

This document is supposed to be sort-of a checklist for DJGPP programmers especially when porting programs from either Unix or some other Dos compiler. You should be able to go through the list and say ``I thought of that'' or ``that doesn't apply to this program'' to every item. Sometimes you'll have to say ``OK, I'll document this.''

You might very well also want to take a look at the Frequently Asked Questions (FAQ).

Programmer Beware!

Binary versus text files.

Text files on disk under Dos are traditionally terminated by CR LF (or "\r\n" if you like). Unix files are terminated by only LF (or "\n").

DJGPP will supply automatic conversion in such a way that the program will see Unix-style files when the files are opened as text files. This is specified using O_TEXT for (e.g.) open or a t for (e.g.) fopen. For binary files the corresponding names are O_BINARY and b.

If unspecified, the value of _fmode is used. This is O_TEXT per default.

You will want to think about the mode for every file you open. If you're porting a Unix program, setting _fmode to O_BINARY at the start of your program might be a good idea. Read also the documentation for setmode and crlf2nl.

Preprocessor symbols.

Use __DJGPP__ to mark code special to DJGPP; use __MSDOS__ to mark code special to Dos. (If you have to write code that works with DJGPP V1 also, consider using __GO32__ which was defined also in V1.)

Seeking in text files.

This doesn't work at all due to the translation of end-of-line markers.

Unix Programmer Beware!

Current directory.

Dos maintains a current directory for every drive. The current directory is independent of processes whereas Unix has one per process.

Devices.

Dos devices don't exist in the file system, i.e., there is no actual entry for the anywhere in the file system. Any valid path (or as a special case /dev/) supplied with a device name is ignored. Anything from and including the first dot in the final path component is also ignored. The null device is called NUL. See also file names.

The environment.

Dos' standard shell (command.com) changes all references to environment variables to upper case. The environment as such has case sensitivity, but the user has no simply way of using that. Also, there is no simple way to set a variable to the empty string.

File modes.

Dos only have one file mode bit you can change, namely the w-bit for the user. This bit is used for ordinary files only. Functions that return file modes will give you an illusion of the usual r- and x-bits also.

File names.

File names under Dos are caseless, but for accentless letters `A'/`a' through 'Z'/'z' only. DJGPP's library will return file names in lower case.

Only one dot is allowed in every path component and it must not be the first character. Only the first eight characters before the dot and the first three after are significant. The only significance of the dot is to separate the two parts.

Since Dos uses drive letters, paths that start with a slash are not absolute.

Front slashes (/) and backslashes (\) are equivalent. DJGPP's C library will make sure you see front slashes only.

Links.

DJGPP will simulate hard links with a file copy. There is no such thing as a symbolic link under Dos. (There is a way to get the same argv[0] effect for programs, see the FAQ on symlinks and the documentation for the stubedit program if that exists.)

Pipes.

There is no multi-tasking on Dos so the pipe works by running the producer and the consumer sequentially.

Running a subshell.

When running a subshell (using $SHELL) note that the standard Dos shell (command.com) takes /c where Unix' takes -c. You should avoid using the shell if you can because command.com imposes limits on the length of a command line and will zero the return code. Using system is OK.

Running subprocesses.

DJGPP does not multi-task. Period. Command lines for subprocesses can be no longer than 126 characters unless you are executing a DJGPP compiled program. The system function uses command.com only for commands like dir and batch files, and will handle redirection for you. See also the FAQ on command-lines and about current directory.

UIDs and GIDs.

These are bogus. Dos knows of no such things.

unlink semantics.

An unlinked file under Dos is gone! Some Unix programs use the fact that deleted files under Unix stay around until you close the last open handle referencing the file. This simply doesn't work with Dos -- you can get very bizarre errors (like ``Read error on drive C:'' or ``Sector not found'') if you try.

Dos Programmer Beware!

Devices.

There is no colon in the names of devices. (The colon is a property of command.com, not Dos as such.)

File names.

You will see front slashes (/) and not backslashes (\) from the library functions that give you file names except for parts you supplied yourself. You can use either yourself.

Interrupt calling.

You should try to use the library routines and not call interrupts directly. If you have to, you should know that passing values in segment registers takes care, and that passing addresses of objects in your program to Dos is not possible. Check out the documentation for __dpmi_int.

Interrupt hooking.

Your program will run under Dos Protected Mode Interface, probably version 0.9, which makes hooking interrupts a little more complicated that you might be used to. See the DPMI API Specification.

Memory model.

All pointers are `near', but 32 bits wide. Simulated far pointers exist via the farptr.h header file, which see. Key words like near, far, and huge can probably be ignored or #defined away.

rename semantics.

DJGPP's rename will move files like the Unix rename does. In particular, the target will be deleted if it exists and you can move directories (``prune-and-graft'').

Size of int.

The size of an int is 32 bits. If you need a 16 bit int, use short. (For readability and portability you might be far better off defining int8, int16, and int32 types.)

unlink semantics.

DJGPP's unlink (remove) will delete files like the Unix unlink. This means that the read-only flag on the file is ignored.