Previous Book Contents Book Index Next

Inside Macintosh: Files /
Chapter 2 - File Manager / About the File Manager

File Manipulation

The File Manager provides a number of routines that allow you to manipulate files. You can open a file fork, read and write the data in it, adjust its logical end-of-file, set the file mark, allocate blocks to a file, and close a file.

To manipulate the data in a file, you first need to open the file. You can open a file using one of several routines, depending on whether you want to use low-level or high-level routines and how you identify the file to open. Table 2-1 lists the file-opening routines.
Table 2-1 Routines for opening file forks
FSSpec HFS High-LevelHFS Low-LevelDescription
FSpOpenDFHOpenDFPBHOpenDFOpen a file's data fork.
FSpOpenRFHOpenRFPBHOpenRFOpen a file's resource fork.
 HOpenPBHOpenOpen a driver or file data fork.

All the high-level FSSpec routines require you to specify a file using a file system specification record. All the HFS routines, whether high or low level, require you to specify a file by its volume, directory, and name.

No matter which routine you use to open a file, you need to specify a file permission that governs the kind of access your application can have to that file. You can specify one of these constants:

   fsCurPerm      =  0;    {whatever permission is allowed}
   fsRdPerm       =  1;    {read permission}
   fsWrPerm       =  2;    {write permission}
   fsRdWrPerm     =  3;    {exclusive read/write permission}
   fsRdWrShPerm   =  4;    {shared read/write permission}
Use the constant fsCurPerm to request whatever permission is currently allowed. If write access is unavailable (because the file is locked or because the file is already open with write access), then read permission is granted. Otherwise, read/write permission
is granted.

Use the constant fsRdPerm to request permission to read the file. Similarly, use the constant fsWrPerm to request permission to write to the file. If write permission is granted, no other access paths are granted write permission. Note, however, that the File Manager does not support write-only access to a file. As a result, fsWrPerm is synonymous with fsRdWrPerm.

There are two types of read/write permission--exclusive and shared. Often you want exclusive read/write permission, so that users can safely read and alter portions of a file. If your application requests and is granted exclusive read/write permission, no users are granted permission to write to the file; other users may, however, be granted permission to read the file.

Shared read/write permission allows multiple access paths for writing and reading. It is safe to have multiple read/write paths open to a file only if there is some way of locking a portion of the file before writing to that portion of the file. You can use the File Manager functions PBLockRange and PBUnlockRange to lock and unlock ranges of bytes in a file. These functions, however, are supported only on remotely mounted volumes or on local volumes that are sharable on the network. As a result, you should request shared read/write permission only if range locking is available. See "Shared File Access Permissions" on page 2-15 for details on permissions in shared environments.

Don't assume that successfully opening a file for writing ensures that you can actually write data to the file. The File Manager allows you to open with write permission a file located on a locked volume, and you won't receive an error until you first try to write data to the file. To be safe, you can call the PBHGetVInfo function to make sure that the volume is writable.
When you successfully open a file fork, you receive a file reference number that uniquely identifies the open file. You can pass that number to the File Manager routines that allow you to manipulate open files. Table 2-2 lists the routines that operate on
open files.

The File Manager provides a number of routines that allow you to operate on files that are closed. You can create, delete, get and set information, and lock and unlock files.
You can also move files within a volume and exchange data in two files. Table 2-2 lists these routines.
Table 2-2 Routines for operating on open file forks
FSReadPBReadRead bytes from an open file fork.
FSWritePBWriteWrite bytes to an open file fork.
FSClosePBCloseClose an open file fork.
GetFPosPBGetFPosGet the position of the file mark.
SetFPosPBSetFPosSet the position of the file mark.
GetEOFPBGetEOFGet the current logical end-of-file.
SetEOFPBSetEOFSet the current logical end-of-file.
AllocatePBAllocateAdd allocation blocks to a file fork.
AllocContigPBAllocContigAdd contiguous allocation blocks to a file fork.
 PBFlushFileUpdate the disk contents of a file fork.
GetVRefNum Get volume reference number of an open file.
Table 2-3 Routines for operating on closed files
FSSpec HFS High-LevelHFS Low-LevelDescription
FSpCreateHCreatePBHCreateCreate both forks of a
new file.
FSpDeleteHDeletePBHDeleteDelete both forks of a file.
FSpGetFInfoHGetFInfoPBHGetFInfoGet a file's Finder information.
FSpSetFInfoHSetFInfoPBHSetFInfoSet a file's Finder information.
FSpSetFLockHSetFLockPBHSetFLockLock a file.
FSpRstFLockHRstFLockPBHRstFLockUnlock a file.
FSpCatMoveCatMovePBCatMoveMove a file or directory within a volume.
FSpRenameHRenamePBHRenameRename a file or directory.
  PBGetCatInfoGet information about a file or directory.
  PBSetCatInfoSet information about a file or directory.

You can use the functions listed in Table 2-2 on open files as well, except for those functions that create or delete file forks.
You can exchange the data in two files using the FSpExchangeFiles and PBExchangeFiles functions. If you need to create a file system specification record, you can use the FSMakeFSSpec or PBMakeFSSpec function.

Previous Book Contents Book Index Next

© Apple Computer, Inc.
2 JUL 1996