Legacy Document

Inside Macintosh: Files /

Chapter 2 - File Manager / File Manager Reference

Low-Level File Access Routines

This section describes the low-level file access routines. These low-level routines, whose names begin with the letters PB, provide two advantages over the corresponding high-level file access routines:

• These routines can be executed asynchronously, returning control to your application before the operation is completed.
• In certain cases, these routines provide more extensive information or perform advanced operations.

All of these routines exchange parameters with your application through a parameter block of type ParamBlock. When you call a low-level routine, you pass the address of the parameter block to the routine.

Assembly-Language Note

When you call any of these low-level routines, register A0 must point to a parameter block containing the parameters for the routine. If you want the routine to be executed asynchronously, set bit 10 of the routine trap word. You can do this by supplying the word ASYNC as the second argument to the routine macro. Here's an example:

_Read, ASYNC

You can set or test bit 10 of a trap word using the global constant asyncTrpBit.

The hierarchical extensions of certain basic File Manager routines actually are not new calls. For instance, _Open and _HOpen both trap to the same routine. The trap word generated by the _HOpen macro is the same as the trap word that would be generated by invoking the _Open macro with bit 9 set. The setting of this bit tells the File Manager to expect a larger parameter block containing the additional fields (such as a directory ID) needed to handle a hierarchical directory volume. You can set or test bit 9 of a trap word by using the global constant hfsBit.

All File Manager routines return a result code in register D0.

These low-level file access routines can run either synchronously or asynchronously. There are three versions of each routine. The first takes two parameters: a pointer to the parameter block and a Boolean parameter that specifies whether the routine is to run asynchronously (TRUE) or synchronously (FALSE). For example, the first version of the low-level routine to read bytes from a file has this declaration:

FUNCTION PBRead (paramBlock: ParmBlkPtr; async: Boolean): OSErr;

The second version does not take a second parameter; instead, it adds the suffix Async to the name of the routine.

FUNCTION PBReadAsync (paramBlock: ParmBlkPtr): OSErr;

Similarly, the third version of the routine does not take a second parameter; instead, it adds the suffix Sync to the name of the routine.

FUNCTION PBReadSync (paramBlock: ParmBlkPtr): OSErr;

Only the first version of each routine is documented in this section. (See "Summary of the File Manager," beginning on page 2-240, for a listing of all three versions of these routines.) Note, however, that the second and third versions of these routines do not use the glue code that the first version uses and are therefore more efficient.

Note

Although you can execute low-level file access routines asynchronously, the underlying device driver may not support asynchronous operation. The SCSI Manager, for example, currently supports only synchronous data transfers. Data transfers to a floppy disk or to a network server, however, can be made asynchronously.

---

Subtopics

Reading, Writing, and Closing Files

Manipulating the File Mark

Manipulating the End-of-File

Allocating File Blocks

Updating Files