The File System: 4.2 Directories and Paths: Current Path and Directory Stack

FileSetCurrentPath(), FileGetCurrentPath(), FileConstructFullPath(), FileParseStandardPath(), FileResolveStandardPath(), FilePushDir(), FilePopDir(), FileResolveStandardPathFlags

Every thread has a current path . When the thread opens a file, it can pass just the name of the file; the file system combines this name with the current path to find the file. The path is a combination of a disk handle and a directory sequence. To set the thread's current path, call the routine FileSetCurrentPath() , which takes two arguments: a disk handle and a pointer to a null-terminated string. The string should contain a sequence of directories specified in the normal DOS convention. To change to a standard path, pass the path constant as the disk handle and a null string (i.e. a pointer to a null byte). To change to a subdirectory of a standard path, pass the path constant as the disk handle and a pointer to a relative or absolute path specification; for example, to change to the HELLO directory in PRIVDATA, pass the disk handle constant SP_PRIVATE_DATA and a pointer to the string "HELLO". FileSetCurrentPath() returns the handle of the disk. If you change to a standard path, it returns the path constant; if you change to a directory within a standard path, it returns the constant of the closest standard path. In the event of error, it returns a null handle and sets the thread's error value. The error most commonly returned is ERROR_PATH_NOT_FOUND, indicating that the specified directory could not be found or does not exist. To set the current path equal to a standard path, use the FileSetStandardPath() routine.

To find out the current path, call the routine FileGetCurrentPath() . This routine takes two arguments: the address of a character buffer and the size of the buffer. It returns the handle of the current path's disk and writes the path (without drive specifier) to the buffer, truncating the path if the buffer is too small. If the directory is a standard path or a subdirectory of one, FileGetCurrentPath() will return the disk-handle constant for that path and will write an absolute path to the buffer. If you want a full path, use FileConstructFullPath() , described below.

To translate a standard path into a full path, call FileConstructFullPath() , which takes five arguments:

A Boolean value indicating whether the drive name should be prepended to the path string returned.
The handle of a disk. A null argument indicates that the path string passed is relative to the current working directory. The handle may be a standard path constant, indicating that the path string passed is relative to that standard path.
A pointer to a string containing a path relative to the location indicated by the previous argument. This may be an empty string.
A pointer to a pointer to a character buffer. The path will be written to this buffer. The routine will update this to be a pointer to a pointer to the null terminator.
The length of that buffer.

The routine writes the full path to the buffer and returns the disk handle. If it is unable to construct a full path, it returns a null handle. The pointer to the path buffer will have been changed to point to the end of the string; you may want to keep a copy of the old value of the pointer around when using this routine.

To find the standard path to a given location, call the routine FileParseStandardPath() . This routine is passed two arguments:

The handle of the disk. Passing a null disk handle indicates that the path string contains a drive specifier.
A pointer to a pointer to a path string. This path should begin at the root of the disk specified.

FileParseStandardPath() returns the standard path constant. It also updates the pointer to point to the remaining portion of the path. For example, if you pass a pointer to a pointer to the string "\GEOWORKS\DOCUMENT\MEMOS\APRIL", the pointer would be updated to point to the "\MEMOS\APRIL" portion, and the handle SP_DOCUMENT would be returned. If the path passed does not belong to a standard path, the constant SP_NOT_STANDARD_PATH will be returned, and the pointers will not be changed.

Because each standard path is made up of one or more directories (possibly on different devices), it can be hard to know just where a file is. For that reason, GEOS provides FileResolveStandardPath() . This routine is passed a relative path to a file; it then constructs the full path of the file, starting from the root of the disk ( not from a standard path); it also returns the handle of the actual disk containing the file. FileResolveStandardPath() is passed several arguments:

A pointer to a pointer to a character buffer. The full path will be written to that buffer, and the pointer will be updated to point to the null terminator.
The length of the buffer, in bytes.
A pointer to a relative path string. This path is relative to the current working directory, which is usually a standard path.
A set of FileResolveStandardPathFlags.
A pointer to an empty FileAttrs buffer; the routine will fill in this buffer with the passed file's attributes, if any.

FileResolveStandardPath() writes the full, absolute path to the buffer specified. It also returns the handle of the disk containing that file. If it cannot find the file specified, it returns a null handle. There are two FileResolveStandardPathFlags available:

FRSPF_ADD_DRIVE_NAME: The path string written to the buffer should begin with the drive name (e.g., "C:\GEOWORKS\DOCUMENT\MEMOS").
FRSPF_RETURN_FIRST_DIR: FileResolveStandardPath() should not check whether the passed path actually exists; instead, it should assume that the path exists in the first directory comprising the standard path, and return accordingly.

In addition to having a current path, every thread has a directory stack . The stack is used for switching paths quickly. You can at any time push the current path onto the stack by calling FilePushDir() . This routine pushes the directory on the directory stack and returns nothing. You can change the current path to the one on top of the directory stack by calling FilePopDir() . This pops the top directory off the stack and makes it the current path. (If the directory stack is empty, the result is undefined.) These routines are very useful when you write subroutines which may need to change the current working directory; they can push the old directory at the start of the routine and pop it at the end.

Files are often specified "by their paths." This simply means specifying them with a string containing the directory path and ending with the file name. This path may be either relative or absolute.

GEOS SDK TechDocs |

4.1 Standard Paths | Next:

4.3 Creating and Deleting Directories