Inside Macintosh: Files /

Chapter 2 - File Manager

About the File Manager

The File Manager is the part of the Macintosh Operating System that manages the organization, reading, and writing of data located on physical data storage devices
such as disk drives. This data includes the data in documents as well as other
collections of data used to maintain the hierarchical file system (HFS) and other system software services. To accomplish these tasks, the File Manager interacts with many
other components of the system software. For example, the Resource Manager uses
File Manager routines when it needs to read and write resource data. Similarly, the File Manager calls the Device Manager to perform the actual reading and writing of data
on a physical data storage device. In general, you'll use the Resource Manager to read and write data in a file's resource fork and the File Manager to read and write data in
a file's data fork. You'll also use the File Manager to perform operations on directories and volumes.

The File Manager provides a large number of routines for performing various operations on files, directories, and volumes. The requirements of your application will dictate which of these routines you will need to use. Many applications simply need to open files, read and write the data in those files, and then close the files. Other applications might provide more capabilities, such as the ability to copy a file or move a file to another directory. A few file-system utilities perform even more extensive file operations and hence need to use some of the advanced routines provided by the File Manager. For example, a disk scavenger might need to make a byte-by-byte search through a volume to find pieces of a deleted file.

You can often use one of several File Manager routines to accomplish a particular task. This is because many of the File Manager routines are provided in two different forms: high level and low level. The low-level routines generally provide the greatest control over the requested task; they are identified by the prefixes PB and PBH, indicating that they take the address of a parameter block as a parameter. The high-level routines are always defined in terms of low-level routines; they are identified by prefixes such as FSp or H, indicating how you identify files or directories using those routines, or by no special prefix at all.

You pass information to a high-level routine using the routine's parameters. A high-level routine has as many parameters as are necessary to pass the information it requires.

You pass information to a low-level routine by filling in fields in a parameter block and then passing the address of the parameter block to the routine. In all cases, a low-level routine uses more fields in the parameter block than there are parameters in the corresponding high-level routine. As a result, you can use those low-level routines to perform more advanced operations or to provide more extensive information than you can with the corresponding high-level routines. This is the principal reason you might choose to use a low-level routine instead of its corresponding high-level routine.

IMPORTANT

If you use the low-level File Manager routines, be sure to clear all unused fields of the parameter block.

Low-level routines also accept a parameter indicating whether you want the routine to be executed synchronously or asynchronously. If you request synchronous execution, control does not return to your application until the routine has been executed. This allows you to inspect the routine's result code to see whether the routine was successfully completed. If so, your application can continue by performing other operations that depend on the successful completion of that routine.

If you request asynchronous execution, an I/O request is put into the file I/O queue and control returns to your application immediately--possibly even before the actual I/O operation is completed. The File Manager takes requests from the queue one at a time and processes them; meanwhile, your application is free to work on other things. Routines that are executed asynchronously return control to your application with the result code noErr as soon as the call is placed in the file I/O queue. Return of control does not signal successful completion of the call, but simply successful queuing of the request. To determine when the call is actually completed, you can poll the ioResult field of the parameter block. This field is set to a positive number when the call is made and set to the actual result code when the call is completed. If necessary, you can also install a completion routine that is executed when the asynchronous call is completed. See "Completion Routines" on page 2-238 for details about completion routines.

Note

Although you can request asynchronous execution for most low-level routines, the device driver for the device on which the target file, directory, or volume resides might not support asynchronous operations. For example, the current implementation of the SCSI Manager allows synchronous execution only. The Sony disk driver and AppleShare server software do, however, support asynchronous operation.

The following sections describe the various capabilities of the File Manager. For full details on any of the routines mentioned in these sections, see the descriptions given in "File Manager Reference" beginning on page 2-86.

---

Subtopics

File Manipulation

Directory Manipulation

Volume Manipulation

Volume Searching

Shared Environments

File ID Reference Routines