Technical Notes
OverviewFunction names end in "_f" or "_h" whenever it may be necessary to clarify whether a function accepts an ASCIIZ pathname ("_f") or a DOS file handle ("_h"). The "_h" suffix is used primarily for functions in the file I/O unit.
The following table demonstrates the relationship between internal format and DOS format:
DOS Format Internal Format Different? C: C: No C:\ C:\ No TEST.CPP TEST.CPP No C:TEST.CPP C:TEST.CPP No C:\TEST.CPP C:\TEST.CPP No C:SPONTASM C:SPONTASM\ Yes C:SPONTASM\TEST.CPP C:SPONTASM\TEST.CPP No C:\LANGS\SPONTASM C:\LANGS\SPONTASM\ Yes C:\LANGS\SPONTASM\TEST.CPP C:\LANGS\SPONTASM\TEST.CPP NoUnless otherwise specified, the functions in this unit accept path strings in either internal format or DOS format, and they only return path strings in internal format. Internal format is required by a function only if it is necessary to distinguish between path-only and path-filename strings.
_ch_dir, _mk_dir, and _rm_dir each accept a full or partial path and a drive specifier in a pathname string. If the operation is to take place on the active drive, the drive specifier may be omitted from the pathname string. Similarly, if the operation is to take place on the current path of a drive, the path may be omitted from the pathname string.
The _expand_path function validates a partial path and returns the full path. The partial path string may include a filename. For example, if the current working directory on drive C: were "\SPONTASM" and the partial path "TEST.CPP" were passed to _expand_path, then "C:\SPONTASM\TEST.CPP" would be returned. _expand_path would also indicate that the returned path refers to a filename rather than a subdirectory.
_get_cwd and _get_curdir return complete ASCIIZ path strings which describe the current directory on a given drive. _get_cwd returns the current working directory on the active or default drive. _get_curdir returns the current directory on the specified drive. A string returned by either of these functions includes a drive specifier as well as a trailing backslash character. For example, these functions might produce the following string:
"C:\LANGS\SPONTASM\"
_ch_dir, _mk_dir, _rm_dir, and _expand_path always expect directory names as arguments. Therefore, they accept path strings in either internal or DOS format.
_get_drive returns the ASCII uppercase drive letter which identifies the current drive. _set_drive changes the current drive.
The _access_f and _exist_f functions are generally used to determine whether or not a file or directory exists. A complete path may be specified. Wildcard characters, however, are not allowed in the filename.
_find_first and _find_next search a specified directory for any file or directory which matches a filename template. Detailed information is returned about each matching file, including the file's name, size, attributes, and date/time stamp.
The _search_path function searches for a file (or a file matching a filename template) in the current directory and all directories in an arbitrary path string. The full path and filename (or filename template, if one was used) is returned as an ASCIIZ string.
The _merge_... functions copy a specified path element from one path string to another. The source and/or destination strings may be partial or full pathname strings or NULL strings. If the source string is a NULL string, the appropriate element of the destination string is removed (if it exists). Otherwise, the appropriate element from the source string replaces the one in the destination string. Note that the path portion of each pathname string must end with a backslash or the last path element will be mistaken for a filename.
The _split_... functions return a specified pathname element from a pathname string. If the specified element does not exist, a NULL string is returned.
_fix_path converts a path string to DOS format by removing any terminal backslash character which does not indicate a root directory. This function is most often used when preparing a path string for display. It should also be used to prepare a path string for direct use with a DOS function since DOS will return an error if it is passed a subdirectory name with a terminal backslash. DOS 2.1 may, in some cases, return an error code even after it has successfully performed the requested directory operation.
_term_path converts a path string to internal format by appending a terminal backslash character (unless the string already ends with a backslash or a colon). This function is intended for use only with path strings which do not include a filename.
The _fix_filename function is used to validate a filename in a path string. If required, it truncates the filename and extension to 8 filename characters and 3 extension characters. If an extension does not exist, a period is not returned in the resulting filename.
The _getmode_f and _setmode_f functions are used to obtain or alter the attributes of a file. _getmode_f may also be used to obtain the attributes of a subdirectory. However, because these functions are used almost exclusively with files, they accept only DOS-compatible path strings.
The _mk_temp function is similar to the mktemp function provided in many C libraries. It is used to generate unique filenames. _mk_temp supports a more flexible template--any hook character (?) in the filename portion of the template is replaced with an ascii number between 0 and 9 until an unused filename is encountered. The template may include a complete path.
The _remove_f function deletes a file.
The _rename_f function is commonly used to rename files. This function can also be used to move files from one directory to another directory on the same drive. When using DOS 3.0 or higher, _rename_f can also be used to rename directories.