Filesystem operations all take a directory pointer as one of their +arguments. A directory pointer is an opaque handle managed by the +filesystem. It should encapsulate a reference to a specific directory +within the filesystem. For example, it may be a pointer to the data +structure that represents that directory (such as an inode), or a +pointer to a pathname for the directory.
The chdir() filesystem function pointer has two +modes of use. When passed a pointer in the +dir_out argument, it should locate the named +directory and place a directory pointer there. If the +dir_out argument is NULL then the +dir argument is a previously generated +directory pointer that can now be disposed of. When the infrastructure +is implementing the chdir() function it makes two +calls to filesystem chdir() functions. The first +is to get a directory pointer for the new current directory. If this +succeeds the second is to dispose of the old current directory +pointer.
The opendir() function is used to open a +directory for reading. This results in an open file object that can be +read to return a sequence of struct dirent +objects. The only operations that are allowed on this file are +read, lseek and +close. Each read operation on this file should +return a single struct dirent object. When +the end of the directory is reached, zero should be returned. The only +seek operation allowed is a rewind to the start of the directory, by +supplying an offset of zero and a whence +specifier of SEEK_SET.
Most of these considerations are invisible to clients of a filesystem +since they will access directories via the POSIX +opendir(), readdir() and +closedir() functions.
Support for the getcwd() function is provided by +three mechanisms. The first is to use the +FS_INFO_GETCWD getinfo key on the filesystem to use +any internal support that it has for this. If that fails it falls back +on one of the two other mechanisms. If +CYGPKG_IO_FILEIO_TRACK_CWD is set then the current +directory is tracked textually in chdir() and the result of that is +reported in getcwd(). Otherwise an attempt is made to traverse the +directory tree to its root using ".." entries.
This last option is complicated and expensive, and relies on the +filesystem supporting "." and ".." entries. This is not always the +case, particularly if the filesystem has been ported from a +non-UNIX-compatible source. Tracking the pathname textually will +usually work, but might not produce optimum results when symbolic +links are being used.