Reading, Writing, and Closing Files

Mac OS X header:	CoreServices/CoreServices.h
Mac OS 9 header:	Files.h

Reading, Writing, and Closing Files Functions
FSRead	Reads any number of bytes from an open file.
FSReadFork	Reads data from an open fork.
FSWrite	Writes any number of bytes to an open file.
PBReadForkSync	Reads data from an open fork.
FSClose	Closes an open file.
PBReadForkAsync	Reads data from an open fork.
FSWriteFork	Writes data to an open fork.
PBWriteForkSync	Writes data to an open fork.
PBWriteForkAsync	Writes data to an open fork.
FSCloseFork	Closes an open fork.
PBCloseForkSync	Closes an open fork.
PBCloseForkAsync	Closes an open fork.

Reads any number of bytes from an open file.

OSErr FSRead (
    SInt16 refNum, 
    SInt32 *count, 
    void *buffPtr
);

Parameter descriptions

refNum

The file reference number of the open file from which to read.

count

On input, a pointer to the number of bytes to read; on output, a pointer to the number of bytes actually read.

buffPtr

A pointer to the data buffer into which the data will be read. This buffer is allocated by your application and must be at least as large as the count parameter.

function result

A result code.

Discussion

Because the read operation begins at the current mark, you might want to set the mark first by calling the SetFPos function. If you try to read past the logical end-of-file, FSRead reads in all the data up to the end-of-file, moves the mark to the end-of-file, and returns eofErr as its function result. Otherwise, FSRead moves the file mark to the byte following the last byte read and returns noErr.

The low-level functions PBReadSync and PBReadAsync let you set the mark without having to call SetFPos. Furthermore, if you want to read data in newline mode, you must use PBReadSync or PBReadAsync instead of FSRead. For a description of the PBReadSync and PBReadAsync functions, see the Device Manager Reference.

If you wish to read from named forks other than the data or resource forks, or from files larger than 2GB, you must use the FSReadFork function, or one of its corresponding parameter block calls, PBReadForkSync and PBReadForkAsync. If you attempt to use FSRead to read from a file larger than 2GB, you will receive an error message.

Availability

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.

Reads data from an open fork.

OSErr FSReadFork (
    SInt16 forkRefNum, 
    UInt16 positionMode, 
    SInt64 positionOffset, 
    ByteCount requestCount, 
    void *buffer, 
    ByteCount actualCount
);

Parameter descriptions

forkRefNum

The reference number of the fork to read from. You should have previously opened this fork using the FSOpenFork call, or one of the corresponding parameter block calls, PBOpenForkSync and PBOpenForkAsync.

positionMode

A constant specifying the base location within the fork for the start of the read. See “Position Mode Constants” for a description of the constants which you can use to specify the base location.

The caller can also use this parameter to hint to the File Manager whether the data being read should or should not be cached. Caching reads appropriately can be important in ensuring that your program access files efficiently.

If you add the forceReadMask constant to the value you pass in this parameter, this tells the File Manager to force the data to be read directly from the disk. This is different from adding the noCacheMask constant since forceReadMask tells the File Manager to flush the appropriate part of the cache first, then ignore any data already in the cache. However, data that is read may be placed in the cache for future reads. The forceReadMask constant is also passed to the device driver, indicating that the driver should avoid reading from any device caches.

See “Cache Constants” for further description of the constants that you can use to indicate your preference for caching the read.

positionOffset

The offset from the base location for the start of the read.

requestCount

The number of bytes to read.

buffer

A pointer to the buffer where the data will be returned.

actualCount

On return, a pointer to the number of bytes actually read. The value pointed to by the actualCount parameter should be equal to the value in the requestCount parameter unless there was an error during the read operation.

This parameter is optional; if you don’t want this information returned, set actualCount to NULL.

function result

A result code. If there are fewer than requestCount bytes from the specified position to the logical end-of-file, then all of those bytes are read, and eofErr is returned.

Discussion

FSReadFork reads data starting at the position specified by the positionMode and positionOffset parameters. The function reads up to requestCount bytes into the buffer pointed to by the buffer parameter and sets the fork’s current position to the byte immediately after the last byte read (that is, the initial position plus actualCount).

To verify that data previously written has been correctly transferred to disk, read it back in using the forceReadMask constant in the positionMode parameter and compare it with the data you previously wrote.

When reading data from a fork, it is important to pay attention to that way that your program accesses the fork, because this can have a significant performance impact. For best results, you should use an I/O size of at least 4KB and block align your read requests. On Mac OS X, you should align your requests to 4KB boundaries; on the traditional Mac OS, byte-alignments beyond 512-bytes are irrelevant, but 4KB aligned requests will perform well on current and future versions.

Availability

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 9 or later.

Writes any number of bytes to an open file.

OSErr FSWrite (
    SInt16 refNum, 
    SInt32 *count, 
    const void *buffPtr
);

Parameter descriptions

refNum

The file reference number of the open file to which to write.

count

On input, a pointer to the number of bytes to write to the file; on output, a pointer to the number of bytes actually written.

buffPtr

A pointer to the data buffer containing the data to write.

function result

A result code.

Discussion

The FSWrite function takes the specified number of bytes from the data buffer and attempts to write them to the file. Because the write operation begins at the current mark, you might want to set the mark first by calling the SetFPos function.

If the write operation completes successfully, FSWrite moves the file mark to the byte following the last byte written and returns noErr. If you try to write past the logical end-of-file, FSWrite moves the logical end-of-file. If you try to write past the physical end-of-file, FSWrite adds one or more clumps to the file and moves the physical end-of-file accordingly.

The low-level functions PBWriteSync and PBWriteAsync let you set the mark without having to call SetFPos. For a description of the PBWriteSync and PBWriteAsync functions, see the Device Manager Reference.

If you wish to write to named forks other than the data or resource forks, or grow files larger than 2GB, you must use the FSWriteFork function, or one of its corresponding parameter block calls, PBWriteForkSync and PBWriteForkAsync. If you attempt to use FSWrite to write to a file larger than 2GB, you will receive an error message.

Availability

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.

Reads data from an open fork.

OSErr PBReadForkSync (
    FSForkIOParam *paramBlock
);

Parameter descriptions

paramBlock

A pointer to a fork I/O parameter block. See FSForkIOParam for a description of the FSForkIOParam data type.

function result

A result code. If there are fewer than requestCount bytes from the specified position to the logical end-of-file, then all of those bytes are read, and eofErr is returned.

Discussion

The relevant fields of the parameter block are:

• forkRefNum

  On input, the reference number of the fork to read from. You should have previously opened this fork using the FSOpenFork call, or one of the corresponding parameter block calls, PBOpenForkSync and PBOpenForkAsync.

• positionMode

  On input, a constant specifying the base location within the fork for the start of the read. See “Position Mode Constants” for a description of the constants which you can use to specify the base location.

  The caller can also use this parameter to hint to the File Manager whether the data being read should or should not be cached. Caching reads appropriately can be important in ensuring that your program access files efficiently.

  If you add the forceReadMask constant to the value you pass in this parameter, this tells the File Manager to force the data to be read directly from the disk. This is different from adding the noCacheMask constant since forceReadMask tells the File Manager to flush the appropriate part of the cache first, then ignore any data already in the cache. However, data that is read may be placed in the cache for future reads. The forceReadMask constant is also passed to the device driver, indicating that the driver should avoid reading from any device caches.

  See “Cache Constants” for further description of the constants that you can use to indicate your preference for caching the read.

• positionOffset

  On input, the offset from the base location for the start of the read.

• requestCount

  On input, the number of bytes to read. The value that you pass in this field should be greater than zero.

• buffer

  A pointer to the buffer where the data will be returned.

• actualCount

  On output, the number of bytes actually read. The value in this field should be equal to the value in the requestCount field unless there was an error during the read operation.

PBReadForkSync reads data starting at the position specified by the positionMode and positionOffset fields. The function reads up to requestCount bytes into the buffer pointed to by the buffer field and sets the fork’s current position to the byte immediately after the last byte read (that is, the initial position plus actualCount).

To verify that data previously written has been correctly transferred to disk, read it back in using the forceReadMask constant in the positionMode field and compare it with the data you previously wrote.

When reading data from a fork, it is important to pay attention to that way that your program accesses the fork, because this can have a significant performance impact. For best results, you should use an I/O size of at least 4KB and block align your read requests. On Mac OS X, you should align your requests to 4KB boundaries; on the traditional Mac OS, byte-alignments beyond 512-bytes are irrelevant, but 4KB aligned requests will perform well on current and future versions.

Version Notes

Note that on Mac OS 8 and 9, it is possible to call PBReadForkSync with a value of 0 in the requestCount field; however, this behavior is not supported on Mac OS X. On OS X, PBReadForkSync returns a paramErr error if the value in the requestCount field is 0

Availability

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 9 or later.

Closes an open file.

OSErr FSClose (
    SInt16 refNum
);

Parameter descriptions

refNum

The file reference number of the open file.

function result

A result code.

Discussion

The FSClose function removes the access path for the specified file and writes the contents of the volume buffer to the volume.

The FSClose function calls the PBFlushFileSync function internally to write the file’s bytes onto the volume. To ensure that the file’s catalog entry is updated, you should call FlushVol after you call FSClose.

Availability

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.

Special Considerations

Make sure that you do not call FSClose with a file reference number of a file that has already been closed. Attempting to close the same file twice may result in loss of data on a volume.

Reads data from an open fork.

void PBReadForkAsync (
    FSForkIOParam *paramBlock
);

Parameter descriptions

paramBlock

A pointer to a fork I/O parameter block. See FSForkIOParam for a description of the FSForkIOParam data type.

Discussion

The relevant fields of the parameter block are:

• ioCompletion

  On input, a pointer to a completion routine. For more information on completion routines, see IOCompletionProcPtr.

• ioResult

  On output, the result code of the function. If there are fewer than requestCount bytes from the specified position to the logical end-of-file, then all of those bytes are read, and eofErr is returned.

• forkRefNum

  On input, the reference number of the fork to read from. You should have previously opened this fork using the FSOpenFork call, or one of the corresponding parameter block calls, PBOpenForkSync and PBOpenForkAsync.

• positionMode

  On input, a constant specifying the base location within the fork for the start of the read. See “Position Mode Constants” for a description of the constants which you can use to specify the base location.

  The caller can also use this parameter to hint to the File Manager whether the data being read should or should not be cached. Caching reads appropriately can be important in ensuring that your program access files efficiently.

  If you add the forceReadMask constant to the value you pass in this parameter, this tells the File Manager to force the data to be read directly from the disk. This is different from adding the noCacheMask constant since forceReadMask tells the File Manager to flush the appropriate part of the cache first, then ignore any data already in the cache. However, data that is read may be placed in the cache for future reads. The forceReadMask constant is also passed to the device driver, indicating that the driver should avoid reading from any device caches.

  See “Cache Constants” for further description of the constants that you can use to indicate your preference for caching the read.

• positionOffset

  On input, the offset from the base location for the start of the read.

• requestCount

  On input, the number of bytes to read. The value that you pass in this field should be greater than zero.

• buffer

  A pointer to the buffer where the data will be returned.

• actualCount

  On output, the number of bytes actually read. The value in this field should be equal to the value in the requestCount field unless there was an error during the read operation.

PBReadForkAsync reads data starting at the position specified by the positionMode and positionOffset fields. The function reads up to requestCount bytes into the buffer pointed to by the buffer field and sets the fork’s current position to the byte immediately after the last byte read (that is, the initial position plus actualCount).

To verify that data previously written has been correctly transferred to disk, read it back in using the forceReadMask constant in the positionMode field and compare it with the data you previously wrote.

When reading data from a fork, it is important to pay attention to that way that your program accesses the fork, because this can have a significant performance impact. For best results, you should use an I/O size of at least 4KB and block align your read requests. On Mac OS X, you should align your requests to 4KB boundaries; on the traditional Mac OS, byte-alignments beyond 512-bytes are irrelevant, but 4KB aligned requests will perform well on current and future versions.

Version Notes

Note that on Mac OS 8 and 9, it is possible to call PBReadForkAsync with a value of 0 in the requestCount field; however, this behavior is not supported on Mac OS X. On OS X, PBReadForkAsync returns a paramErr error if the value in the requestCount field is 0.

Availability

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 9 or later.

Writes data to an open fork.

OSErr FSWriteFork (
    SInt16 forkRefNum, 
    UInt16 positionMode, 
    SInt64 positionOffset, 
    ByteCount requestCount, 
    const void *buffer, 
    ByteCount actualCount
);

Parameter descriptions

forkRefNum

The reference number of the fork to which to write. You should have previously opened the fork using the FSOpenFork function, or one of the corresponding parameter block calls, PBOpenForkSync and PBOpenForkAsync.

positionMode

A constant specifying the base location within the fork for the start of the write. See “Position Mode Constants” for a description of the constants which you can use to specify the base location.

The caller can also use this parameter to hint to the File Manager whether the data being written should or should not be cached. See “Cache Constants” for further description of the constants that you can use to indicate your preference for caching.

positionOffset

The offset from the base location for the start of the write.

requestCount

The number of bytes to write.

buffer

A pointer to a buffer containing the data to write.

actualCount

On return, a pointer to the number of bytes actually written. The value pointed to by the actualCount parameter will be equal to the value in the requestCount parameter unless there was an error during the write operation.

This parameter is optional; if you don’t want this information, set actualCount to NULL.

function result

A result code. If there is not enough space on the volume to write requestCount bytes, then dskFulErr is returned.

Discussion

FSWriteFork writes data starting at the position specified by the positionMode and positionOffset parameters. The function attempts to write requestCount bytes from the buffer pointed at by the buffer parameter and sets the fork’s current position to the byte immediately after the last byte written (that is, the initial position plus actualCount).

When writing data to a fork, it is important to pay attention to that way that your program accesses the fork, because this can have a significant performance impact. For best results, you should use an I/O size of at least 4KB and block align your write requests. On Mac OS X, you should align your requests to 4KB boundaries; on the traditional Mac OS, byte-alignments beyond 512-bytes are irrelevant, but 4KB aligned requests will perform well on current and future versions.

Availability

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 9 or later.

Writes data to an open fork.

OSErr PBWriteForkSync (
    FSForkIOParam *paramBlock
);

Parameter descriptions

paramBlock

A pointer to a fork I/O parameter block. See FSForkIOParam for a description of the FSForkIOParam.

function result

A result code. If there is not enough space on the volume to write requestCount bytes, then dskFulErr is returned.

Discussion

The relevant fields of the parameter block are:

• ioResult

  On output, the result code of the function. If there is not enough space on the volume to write requestCount bytes, then dskFulErr is returned.

• forkRefNum

  On input, the reference number of the fork to which to write. You should have previously opened the fork using the FSOpenFork function, or one of the corresponding parameter block calls, PBOpenForkSync and PBOpenForkAsync.

• positionMode

  On input, a constant specifying the base location within the fork for the start of the write. See “Position Mode Constants” for a description of the constants which you can use to specify the base location.

  The caller can also use this parameter to hint to the File Manager whether the data being written should or should not be cached. See “Cache Constants” for further description of the constants that you can use to indicate your preference for caching.

• positionOffset

  On input, the offset from the base location for the start of the write.

• requestCount

  On input, the number of bytes to write.

• buffer

  A pointer to a buffer containing the data to write.

• actualCount

  On output, the number of bytes actually written. The value in the actualCount field will be equal to the value in the requestCount field unless there was an error during the write operation.

PBWriteForkSync writes data starting at the position specified by the positionMode and positionOffset fields. The function attempts to write requestCount bytes from the buffer pointed to by the buffer field and sets the fork’s current position to the byte immediately after the last byte written (that is, the initial position plus actualCount).

When writing data to a fork, it is important to pay attention to that way that your program accesses the fork, because this can have a significant performance impact. For best results, you should use an I/O size of at least 4KB and block align your write requests. On Mac OS X, you should align your requests to 4KB boundaries; on the traditional Mac OS, byte-alignments beyond 512-bytes are irrelevant, but 4KB aligned requests will perform well on current and future versions.

Availability

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 9 or later.

Writes data to an open fork.

void PBWriteForkAsync (
    FSForkIOParam *paramBlock
);

Parameter descriptions

paramBlock

A pointer to a fork I/O parameter block. See FSForkIOParam for a description of the FSForkIOParam.

Discussion

The relevant fields of the parameter block are:

• ioCompletion

  On input, a pointer to a completion routine. For more information on completion routines, see IOCompletionProcPtr.

• ioResult

  On output, the result code of the function. If there is not enough space on the volume to write requestCount bytes, then dskFulErr is returned.

• forkRefNum

  On input, the reference number of the fork to which to write. You should have previously opened the fork using the FSOpenFork function, or one of the corresponding parameter block calls, PBOpenForkSync and PBOpenForkAsync.

• positionMode

  On input, a constant specifying the base location within the fork for the start of the write. See “Position Mode Constants” for a description of the constants which you can use to specify the base location.

  The caller can also use this parameter to hint to the File Manager whether the data being written should or should not be cached. See “Cache Constants” for further description of the constants that you can use to indicate your preference for caching.

• positionOffset

  On input, the offset from the base location for the start of the write.

• requestCount

  On input, the number of bytes to write.

• buffer

  A pointer to a buffer containing the data to write.

• actualCount

  On output, the number of bytes actually written. The value in the actualCount field will be equal to the value in the requestCount field unless there was an error during the write operation.

PBWriteForkAsync writes data starting at the position specified by the positionMode and positionOffset fields. The function attempts to write requestCount bytes from the buffer pointed to by the buffer field and sets the fork’s current position to the byte immediately after the last byte written (that is, the initial position plus actualCount).

When writing data to a fork, it is important to pay attention to that way that your program accesses the fork, because this can have a significant performance impact. For best results, you should use an I/O size of at least 4KB and block align your write requests. On Mac OS X, you should align your requests to 4KB boundaries; on the traditional Mac OS, byte-alignments beyond 512-bytes are irrelevant, but 4KB aligned requests will perform well on current and future versions.

Availability

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 9 or later.

Closes an open fork.

OSErr FSCloseFork (
    SInt16 forkRefNum
);

Parameter descriptions

forkRefNum

The reference number of the fork to close. After the call to this function, the reference number in this parameter is invalid.

function result

A result code.

Discussion

The FSCloseFork function causes all data written to the fork to be written to disk, in the same manner as the FSFlushFork function, before it closes the fork.

Availability

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 9 or later.

Closes an open fork.

OSErr PBCloseForkSync (
    FSForkIOParam *paramBlock
);

Parameter descriptions

paramBlock

A pointer to a fork I/O parameter block. See FSForkIOParam for a description of the FSForkIOParam.

function result

A result code.

Discussion

The relevant field of the parameter block is:

• forkRefNum

  On input, the reference number of the fork to close. After the call to this function, the reference number in this parameter is invalid.

The PBCloseForkSync function causes all data written to the fork to be written to disk, in the same manner as the PBFlushForkSync function, before it closes the fork.

Availability

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 9 or later.

Closes an open fork.

void PBCloseForkAsync (
    FSForkIOParam *paramBlock
);

Parameter descriptions

paramBlock

A pointer to a fork I/O parameter block. See FSForkIOParam for a description of the FSForkIOParam.

Discussion

The relevant fields of the parameter block are:

• ioCompletion

  On input, a pointer to a completion routine. For more information on completion routines, see IOCompletionProcPtr.

• ioResult

  On output, the result code of the function.

• forkRefNum

  On input, the reference number of the fork to close. After the call to this function, the reference number in this parameter is invalid.

The PBCloseForkAsync function causes all data written to the fork to be written to disk, in the same manner as the PBFlushForkAsync function, before it closes the fork.

Availability

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 9 or later.

© 2001 Apple Computer, Inc. (Last Updated July 17, 2001)