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 ).
WARNING:
Do not assume a file reference number is an
offset into a table of FCBs pointed to by the
low-memory global FCBSPtr , or that the
length of an FCB is stored in the low-memory global
FSFCBLen . This is no longer the case
in Mac OS 9.0 and higher.
|
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 Managers 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 MacsBugs
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:
-
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 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.
|