Legacy Document

Inside Macintosh: Files /

Chapter 2 - File Manager / About the File Manager

Volume Searching

The File Manager provides several routines that you can use to search a volume for files or directories having specific characteristics. For example, you can search for all files with modification dates of two days ago or less or all directories with the string "Temp" in their names.

In general, you should avoid searching entire volumes, because a search of large volumes can consume significant amounts of time. Suppose you are looking for a particular file (for example, a dictionary file against which your application needs to check the spelling of a document). In this case, you can save time and increase the chances of finding the correct file by storing and later resolving an alias record that describes the desired file. See the chapter "Alias Manager" in this book for details on using alias records.

Alternatively, suppose you need to find the location of a standard system directory, such as the Preferences folder or the Temporary Items folder. To perform this search most efficiently, you should use the FindFolder function. See the chapter "Finder Interface" in Inside Macintosh: Macintosh Toolbox Essentials for details.

In some cases, however, you do need to search volumes. For instance, a backup utility needs to search an entire volume to find which files and directories, if any, might need to be backed up. In these cases, you can choose either of two general search strategies: you can search the volume's catalog by calling the PBCatSearch function, or you can use a recursive, indexed search by calling the PBGetCatInfo function (see Table 2-2).

Table 2-7 Routines for manipulating working directories

Routine	Description
PBCatSearch	Search a volume's catalog file for files or directories.
PBGetCatInfo	Get information about a single catalog file entry.

Using the PBCatSearch function is the fastest and most reliable way to search the catalog file of an HFS volume for files and directories satisfying certain criteria. The PBCatSearch function returns a list of FSSpec records describing the files or directories that match the criteria specified by your application.

However, PBCatSearch is not available on all volumes or in all versions of the
File Manager. See "Determining the Features of the File Manager" on page 2-32
for instructions on how to determine whether the system software and the target
volume both support the PBCatSearch function.

Note

The PBCatSearch function is available on all volumes that support the AppleTalk Filing Protocol (AFP) version 2.1. This includes volumes and directories shared using the file sharing software introduced in system software version 7.0 and using the AppleShare 3.0 file server software.

In environments where PBCatSearch is not available, you'll need to do a search that recursively descends the directory hierarchy and reads through the catalog entries of all files and directories located in each directory in that hierarchy. You can do this by making indexed calls to the PBGetCatInfo function, which is supported by all system software versions and by all volumes. However, using this recursive, indexed search method is usually significantly slower than using the PBCatSearch function. (For example, a recursive, indexed search that takes over 6 minutes might take about 20 seconds using PBCatSearch.)

See "Searching a Volume" beginning on page 2-38 for examples of using both PBCatSearch and PBGetCatInfo to search a volume for files and directories.