_put_path

Syntax

#include <libc/dosio.h> int _put_path(const char *path); int _put_path2(const char *path, int offset);

Description

These functions are used internally by all low-level library functions that need to pass file names to DOS. _put_path copies its argument path to the transfer buffer (see section _go32_info_block) starting at the beginning of the transfer buffer; _put_path2 does the same except that it puts the file name starting at offset bytes from the beginning of the transfer buffer.

These functions are meant to be called by low-level library functions, not by applications. You should only call them if you know what you are doing. In particular, if you call any library function between a call to _put_path or _put_path2 and the call to a DOS function that uses the file name, the file name in the transfer buffer could be wiped out, corrupted or otherwise changed. You have been warned!

Some constructs in file names are transformed while copying them, to allow transparent support for nifty features. Here's the list of these transformations:

• Multiple forward slashes are collapsed into a single slash.

  Unix treats multiple slashes as a single slash, so some ported programs pass names like `c:/foo//bar' to library functions. DOS functions choke on such file names, so collapsing the slashes prevents these names from failing.

• Trailing slashes are removed, except for root directories.

  Various DOS calls cannot cope with file names like `c:/foo/'; this feature solves this problem.

• Translation of Unix device names.

  Unix `/dev/null' is mapped to DOS-standard `NUL', and Unix `/dev/tty' to DOS-standard `CON'. This provides for transparent support of these special devices, e.g. in Unix shell scripts.

• Translation of DOS device names.

  Any file name which begins with `/dev/' or `x:/dev/' (where x: is any valid DOS drive letter) has the `/dev/' or `x:/dev/' prefix removed (if the `/dev/' directory does not exist), and the rest is passed to DOS. This is because some DOS functions don't recognize device names unless they are devoid of the drive and directory specifications, and programs could add a drive and a directory if they convert a name like `/dev/con' to a fully-qualified path name. Because of the different behavior when the `/dev/' directory exists, you should only add the prefix `/dev/' to your DOS device names if necessary and be sure that the `/dev/' does not exist. Due to the additional overhead of checking if `/dev/' exists, functions working with DOS device names with the prefix will be slower.

• `/dev/x/' is translated into `x:/'.

  This allows to use Unix-style absolute path names that begin with a slash, instead of DOS-style names with a drive letter. Some Unix programs and shell scripts fail for file names that include colons, which are part of the drive letter specification; this feature allows to work around such problems by using e.g. `/dev/c/' where `c:/' would fail.

• `/dev/env/foo/' is replaced by the value of the environment variable foo.

  (In other words, you can think of environment variables as if they were sub-directories of a fictitious directory `/dev/env'.)

  This allows to use environment variable names inside path names compiled into programs, and have them transparently expanded at run time. For example, `/dev/env/DJDIR/include' will expand to the exact path name of the DJGPP include directory, no matter where DJGPP is installed on the machine where the program runs. (The value of DJDIR is computed by the DJGPP startup code and pushed into the environment of every DJGPP program before main is called.)

  Note that environment variables are case-sensitive, so `/dev/env/foo' and `/dev/env/FOO' are not the same. DOS shells usually upcase the name of the environment variable if you set it with the built-in command `SET', so if you type e.g. `SET foo=bar', the shell defines a variable named FOO.

  If the environment variable is undefined, it will expand into an empty string. The expansion is done recursively, so environment variables may reference other environment variables using the same `/dev/env/' notation. For example, if the variable HOME is set to `/dev/env/DJDIR/home', and DJGPP is installed in `c:/software/djgpp', then `/dev/env/HOME/sources' will expand to `c:/software/djgpp/home/sources'.

  It is possible to supply a default value, to be used if the variable is not defined, or has an empty value. To this end, put the default value after the name of the variable and delimit it by `~', like in `/dev/env/DJDIR~c:/djgpp~/include'.

  If you need to include a literal character `~' in either the environment variable name or in the default value that replaces it, use two `~'s in a row. For example, `/dev/env/FOO~~' will expand to the value of the variable FOO~. Likewise, `/dev/env/FOO~~BAR~foo~~baz~' will expand to the value of the variable FOO~BAR if it is defined and nonempty, and to `foo~baz' otherwise. Leading `~' in the default value isn't supported (it is interpreted as part of the preceding variable name).

  The default value may also reference (other) environment variables, but nested default values can get tricky. For example, `/dev/env/foo~/dev/env/bar~' will work, but `/dev/env/foo~/dev/env/bar~baz~~' will not. To use nested default values, you need to double the quoting of the `~' characters, like in `/dev/env/foo~/dev/env/bar~~baz~~~'.

Return Value

Both functions return the offset into the transfer buffer of the terminating null character that ends the file name.

ANSI/ISO C	No
POSIX	No

Example

These functions are meant to be called by low-level library functions, not by applications. You should only call them if you know what you are doing. In particular, if you call any library function between a call to _put_path or _put_path2 and the call to a DOS function that uses the file name, the file name in the transfer buffer could be wiped out, corrupted and otherwise changed. You have been warned!

__dpmi_regs r; _put_path("/dev/c/djgpp/bin/"); r.x.ax = 0x4300; /* get file attributes */ r.x.ds = __tb >> 4; r.x.dx = __tb & 0x0f; __dpmi_int(0x21, &r);