Legacy Document

Inside Macintosh: Files /

Chapter 2 - File Manager / Identifying Files, Directories, and Volumes

Search Paths

Whenever you specify a value of 0 for the directory ID in an HFS specification, the File Manager first looks for the desired file in the directory indicated by the two other relevant HFS parameters or fields--namely, the pathname and the volume specification. If the specified file is not found in that directory, the File Manager continues searching for the file along a path known as the poor man's search path. You need to be aware of this behavior so that you do not accidentally open, delete, or otherwise manipulate the wrong file.

Note

The File Manager uses the poor man's search path only when the directory ID parameter or field has the value 0. You can avoid the consequences of accidentally opening or deleting the wrong file by specifying a directory explicitly with its directory ID.

If the volume specification is a working directory reference number, the File Manager searches in the directory whose directory ID is encoded in that working directory reference number. If the volume specification is a volume reference number or 0, the File Manager searches in the default directory on the indicated volume. (See "Manipulating the Default Volume and Directory" on page 2-35 for information about default directories.) If you provide a full pathname, the File Manager searches in the directory whose name is contained in the pathname.

If the File Manager cannot find the specified file in the first directory it searches, it next searches the root directory of the boot volume, but only if the first directory searched is located on the boot volume. If the specified file is still not found, or if the first directory searched is not located on the boot volume, the File Manager next searches the System Folder, if one exists, on the volume containing the first directory searched. If the file still cannot be found, the File Manager gives up and returns the result code fnfErr (file not found) to your application.

As you can see, the use of the poor man's search path might lead to unexpected results. Suppose, for example, that you call the HOpenDF function like this:

myErr := HOpenDF(0, 0, ':Ackees', fsRdWrPerm, myRefNum);

The values of 0 for the first two parameters (the volume specification and directory ID) indicate that you want the File Manager to look for the named file in the default directory. If, however, there is no such file in that directory, the File Manager continues looking along the poor man's search path for a file with the specified name. The result might be that you open the wrong file. (Worse yet, if you had called HDelete instead of HOpenDF, you might have deleted the wrong file!)

The File Manager uses the poor man's search path for all routines that can return the fnfErr result code and to which you passed a directory ID of zero. It does not use the poor man's search path when you specify a nonzero directory ID or when you call an indexed routine (that is, when the ioFDirIndex field of the parameter block has a nonzero value). The File Manager also does not use the poor man's search path when you create a file (perhaps by calling PBHCreate) or move a file between directories (by calling PBCatMove).

Note

The poor man's search path might not be supported in future versions of system software. You should not depend on its availability.