Legacy Document

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-Level	HFS Low-Level	Description
FSpOpenDF	HOpenDF	PBHOpenDF	Open a file's data fork.
FSpOpenRF	HOpenRF	PBHOpenRF	Open a file's resource fork.
	HOpen	PBHOpen	Open 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:

CONST
   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.

Note

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

High-Level	Low-Level	Description
FSRead	PBRead	Read bytes from an open file fork.
FSWrite	PBWrite	Write bytes to an open file fork.
FSClose	PBClose	Close an open file fork.
GetFPos	PBGetFPos	Get the position of the file mark.
SetFPos	PBSetFPos	Set the position of the file mark.
GetEOF	PBGetEOF	Get the current logical end-of-file.
SetEOF	PBSetEOF	Set the current logical end-of-file.
Allocate	PBAllocate	Add allocation blocks to a file fork.
AllocContig	PBAllocContig	Add contiguous allocation blocks to a file fork.
	PBFlushFile	Update 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-Level	HFS Low-Level	Description
FSpCreate	HCreate	PBHCreate	Create both forks of a new file.
FSpDelete	HDelete	PBHDelete	Delete both forks of a file.
FSpGetFInfo	HGetFInfo	PBHGetFInfo	Get a file's Finder information.
FSpSetFInfo	HSetFInfo	PBHSetFInfo	Set a file's Finder information.
FSpSetFLock	HSetFLock	PBHSetFLock	Lock a file.
FSpRstFLock	HRstFLock	PBHRstFLock	Unlock a file.
FSpCatMove	CatMove	PBCatMove	Move a file or directory within a volume.
FSpRename	HRename	PBHRename	Rename a file or directory.
		PBGetCatInfo	Get information about a file or directory.
		PBSetCatInfo	Set information about a file or directory.

Note

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.