Technical Q&As

FL 10 - Accessing File Control Blocks (2-Nov-98)

Q What is the correct way to access a File Control Block for an open file?

A The correct way to access the information from the FCB is using PBGetFCBInfo. In some cases, it may also be correct to use the File System Manager (FSM) FCB accessors. Under no circumstances should you access the file control block table or file control blocks (FCBs) directly. You've been warned many times about this in the past:

  • Inside Macintosh II, page 127, "Warning: The size and structure of a file control block may be different in future versions of Macintosh system software."
  • Inside Macintosh IV, page 181, "Warning: The size and structure of a file control block may be different in future versions of Macintosh system software."
  • Inside Macintosh V, page 386, "Do not directly examine or manipulate system data structures, such as file control blocks (FCB) or volume control blocks (VCB), in memory. Use File Manager calls to access FCB and VCB information."
  • Inside Macintosh: Files, page 2-81, "Note: The size and structure of a file control block may be different in future versions of Macintosh system software. To be safe, you should get information from the FCB allocated for an open file by calling the File Manager function PBGetFCBInfo."

Now, we really mean it.

There is really only one good reason to access a FCB directly and that is: your code is the file system that owns the volume the open file is on.

Applications should always use PBGetFCBInfo to get information from the FCB for an open file. The few fields in a FCB not returned by PBGetFCBInfo are either file system- specific, or they are reserved for the File Manager's own use. (For example, some fields in an FCB are used for different purposes by the Macintosh file system code for accessing HFS or HFS Plus volumes than what they are used for by the File Exchange file system code for accessing DOS or ProDOS volumes.) In addition, some network file systems (for example, AppleShare) use PBGetFCBInfo to update the information they keep in the FCB and return in the FCBPBRec, so accessing the FCB directly may give you stale data.

However, we know there are reasons for patches to file system traps or debugging tools (such as MacsBug's FILE dcmd) to look directly at a file control block. So in the interest of allowing useful things to keep working, and to allow Apple to provide future enhancements to the File Manager, we will soon require code that accesses FCBs to use a single set of accessor functions to get to FCBs. The accessor functions have been public since 1994 as part of the File System Manager (FSM) and the File System Manager has been part of Mac OS since System 7.5. You can check for the presence of FSM with Gestalt by using the gestaltFSAttr selector and checking for the gestaltHasFileSystemManager bit.

Do not assume a file reference number is an offset into a table of FCBs pointed to by the low-memory location FCBSPtr, or that the length of an FCB is stored in the low-memory location FSFCBLen.

The four FCB accessor functions are:

  • UTLocateFCB, which finds an FCB by file number and volume. (You can also search by filename and volume, but that is not very useful since multiple files can have the same name on a volume.)
  • UTLocateNextFCB, which finds additional FCBs (after using UTLocateFCB) by file number (or name) and volume.
  • UTIndexFCB, which indexes through the open FCBs on a volume.
  • UTResolveFCB, which maps a file reference number to its FCB.

All four functions return a pointer to a FCB and all but UTResolveFCB (where the file reference number is an input parameter) also return the corresponding file reference number for the FCB.

A recap of the rules:

  • Use PBGetFCBInfo to access FCB information.
  • Use the FSM utility functions UTLocateFCB, UTLocateNextFCB, UTIndexFCB, and UTResolveFCB if you must access the FCB directly.

-- Jim Luther
Mac OS Releases Engineering

Technical Q&As
Previous Question | Next Question

To contact us, please use the Contact Us page.