Technical Q&A FL10

Accessing File Control Blocks

Q: What is the correct way to access a file control block (FCB) for an open file?

A: The correct way to access the information from an FCB is to use FSGetForkCBInfo (or its parameter block variants PBGetForkCBInfoSync and PBGetForkCBInfoAsync, or PBGetFCBInfoSync and PBGetFCBInfoAsync on pre-Mac OS 9.0 systems). In cases where you need immediate access to the FCB it may be necessary to use the File System Manager (FSM) FCB accessors. If FSM is available, you should never access the FCB table or file control blocks (FCBs) directly.

In Mac OS 9.0, FCBs are no longer stored in a table pointed to by the low-memory global FCBSPtr. If your software accesses FCBs using this low-memory global, it will either not work in mysterious ways (for 68K code), or halt the system with a dsMustUseFCBAccessors (119) system error (PowerPC code that calls LMGetFCBSPtr, LMSetFCBSPtr, or LMSetFSFCBLen).

There is really only one good reason to access an FCB immediately: your code is the file system that controls the volume on which the open file resides.

Application-level code should always use File Manager routines to get information from the FCB for an open file. Appropriate File Manager routines include:

• the high-level routine FSGetForkCBInfo (Mac OS 9.0 and higher)
• the parameter block routines PBGetForkCBInfoSync and PBGetForkCBInfoAsync (Mac OS 9.0 and higher)
• the parameter block routines PBGetFCBInfoSync or PBGetFCBInfoAsync (pre-Mac OS 9.0)

The only fields in the FCB not returned by these routines 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 built-in (HFS or HFS Plus) file system than what they are used for by the File Exchange (DOS or ProDOS) file system.) In addition, some network file systems (for example, AppleShare) use PBGetFCBInfo to update the information they keep in the FCB, so accessing the FCB immediately may give you stale data.

However, we recognize that there are circumstances where developers need immediate access to the FCB, for example, a file system trap patch, or debugging tools such as MacsBug’s FILE dcmd. In the interest of allowing useful things to keep working, and to allow future enhancements to the File Manager, we now require that you access FCBs using accessor functions. The accessor functions have been public since 1994 as part of the File System Manager (FSM) and FSM has been part of Mac OS since System 7.5. You can check for the presence of FSM with Gestalt by requesting the gestaltFSAttr selector and checking for the gestaltHasFileSystemManager bit in the response.

The four FCB accessor functions are:

1. 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.)
2. UTLocateNextFCB, which finds additional FCBs (after using UTLocateFCB) by file number (or name) and volume.
3. UTIndexFCB, which indexes through the open FCBs on a volume.
4. UTResolveFCB, which maps a file reference number to its FCB.

All four functions return a pointer to an 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 File Manager routines to access FCB information in most cases;
• if you must access the FCB directly, use the FSM accessor functions UTLocateFCB, UTLocateNextFCB, UTIndexFCB, and UTResolveFCB; and
• only look at the FCB table when FSM is not available (that is, prior to System 7.5).

For more information on this topic, see DTS Technote 1184, “FCBs, Now and Forever.”