---

Deprecated Device Manager Reference (Legacy) Functions

A function identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in Mac OS X v10.5

PBCloseAsync

Closes an open file. (Deprecated in Mac OS X v10.5. Use PBCloseForkAsync instead.)

OSErr PBCloseAsync (
   ParmBlkPtr paramBlock
);

Parameters

paramBlock

A pointer to a basic File Manager parameter block.

Return Value

A result code. See “Device Manager Result Codes.”

Discussion

The relevant fields of the parameter block are:

• ioCompletion On input, a pointer to a completion routine.

• ioResult On output, the result code of the function.

• ioRefNum On input, a file reference number to the file to close.

The PBCloseAsync function writes the contents of the access path buffer specified by the ioRefNum field to the volume and removes the access path.

Special Considerations

Some information stored on the volume won’t be updated until PBFlushVolAsync is called.

Do not call PBCloseAsync 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. .

Availability

• Available in Mac OS X v10.0 and later.
• Deprecated in Mac OS X v10.5.
• Not available to 64-bit applications.

Declared In

Files.h

PBCloseSync

Closes an open file. (Deprecated in Mac OS X v10.5. Use PBCloseForkSync instead.)

OSErr PBCloseSync (
   ParmBlkPtr paramBlock
);

Parameters

paramBlock

A pointer to a basic File Manager parameter block.

Return Value

A result code. See “Device Manager Result Codes.”

Discussion

The relevant fields of the parameter block are:

• ioCompletion On input, a pointer to a completion routine.

• ioResult On output, the result code of the function.

• ioRefNum On input, a file reference number to the file to close.

The PBCloseSync function writes the contents of the access path buffer specified by the ioRefNum field to the volume and removes the access path.

Special Considerations

Some information stored on the volume won’t be updated until PBFlushVolSync is called.

Do not call PBCloseSync 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. .

Availability

• Available in Mac OS X v10.0 and later.
• Deprecated in Mac OS X v10.5.
• Not available to 64-bit applications.

Declared In

Files.h

PBReadAsync

Reads any number of bytes from an open file. (Deprecated in Mac OS X v10.5. Use PBReadForkAsync instead.)

OSErr PBReadAsync (
   ParmBlkPtr paramBlock
);

Parameters

paramBlock

A pointer to a basic File Manager parameter block.

Return Value

A result code. See “Device Manager Result Codes.”

Discussion

The relevant fields of the parameter block are:

• ioCompletion On input, a pointer to a completion routine.

• ioResult On output, the result code of the function.

• ioRefNum On input, a file reference number for an open file to be read.

• ioBuffer On input, a pointer to a data buffer into which the bytes are read.

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

• ioActCount On output, the number of bytes actually read.

• ioPosMode On input, the positioning mode.

• ioPosOffset On input, the positioning offset. On output, the new position of the mark.

This function attempts to read ioReqCount bytes from the open file whose access path is specified in the ioRefNum field and transfer them to the data buffer pointed to by the ioBuffer field. The position of the mark is specified by ioPosMode and ioPosOffset. If your application tries to read past the logical end-of-file, PBReadAsync reads the data, moves the mark to the end-of-file, and returns eofErr as its function result. Otherwise, PBReadAsync moves the file mark to the byte following the last byte read and returns noErr.

You can specify that PBReadAsync read the file data 1 byte at a time until the requested number of bytes have been read or until the end-of-file is reached. To do so, set bit 7 of the ioPosMode field. Similarly, you can specify that PBReadAsync should stop reading data when it reaches an application-defined newline character. To do so, place the ASCII code of that character into the high-order byte of the ioPosMode field; you must also set bit 7 of that field to enable newline mode.

When reading data in newline mode, PBReadAsync returns the newline character as part of the data read and sets ioActCount to the actual number of bytes placed into the buffer (which includes the newline character).

Special Considerations

In Mac OS 8 and 9, it is possible to call PBReadAsync with a value of 0 in the ioReqCount field. In Mac OS X, PBReadAsync returns a paramErr error if the value in the ioReqCount field is 0.

Availability

• Available in Mac OS X v10.0 and later.
• Deprecated in Mac OS X v10.5.
• Not available to 64-bit applications.

Declared In

Files.h

PBReadSync

Reads any number of bytes from an open file. (Deprecated in Mac OS X v10.5. Use PBReadForkSync instead.)

OSErr PBReadSync (
   ParmBlkPtr paramBlock
);

Parameters

paramBlock

A pointer to a basic File Manager parameter block.

Return Value

A result code. See “Device Manager Result Codes.”

Discussion

The relevant fields of the parameter block are:

• ioCompletion On input, a pointer to a completion routine.

• ioResult On output, the result code of the function.

• ioRefNum On input, a file reference number for an open file to be read.

• ioBuffer On input, a pointer to a data buffer into which the bytes are read.

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

• ioActCount On output, the number of bytes actually read.

• ioPosMode On input, the positioning mode.

• ioPosOffset On input, the positioning offset. On output, the new position of the mark.

This function attempts to read ioReqCount bytes from the open file whose access path is specified in the ioRefNum field and transfer them to the data buffer pointed to by the ioBuffer field. The position of the mark is specified by ioPosMode and ioPosOffset. If your application tries to read past the logical end-of-file, PBReadSync reads the data, moves the mark to the end-of-file, and returns eofErr as its function result. Otherwise, PBReadSync moves the file mark to the byte following the last byte read and returns noErr.

You can specify that PBReadSync read the file data 1 byte at a time until the requested number of bytes have been read or until the end-of-file is reached. To do so, set bit 7 of the ioPosMode field. Similarly, you can specify that PBReadSync should stop reading data when it reaches an application-defined newline character. To do so, place the ASCII code of that character into the high-order byte of the ioPosMode field; you must also set bit 7 of that field to enable newline mode.

When reading data in newline mode, PBReadSync returns the newline character as part of the data read and sets ioActCount to the actual number of bytes placed into the buffer (which includes the newline character).

Special Considerations

In Mac OS 8 and 9, it is possible to call PBReadSync with a value of 0 in the ioReqCount field. In Mac OS X, PBReadSync returns a paramErr error if the value in the ioReqCount field is 0.

Availability

• Available in Mac OS X v10.0 and later.
• Deprecated in Mac OS X v10.5.
• Not available to 64-bit applications.

Declared In

Files.h

PBWaitIOComplete

Keeps the system idle until either an interrupt occurs or the specified timeout value is reached. (Deprecated in Mac OS X v10.5. There is no replacement function.)

OSErr PBWaitIOComplete (
   ParmBlkPtr paramBlock,
   Duration timeout
);

Parameters

paramBlock

A pointer to a basic File Manager parameter block.

timeout

The maximum length of time you want the system to be kept idle.

Return Value

A result code. See “Device Manager Result Codes.” If the timeout value is reached, returns kMPTimeoutErr.

Special Considerations

This function is not implemented in Mac OS X.

Availability

• Available in Mac OS X v10.0 and later.
• Deprecated in Mac OS X v10.5.
• Not available to 64-bit applications.

Declared In

Files.h

PBWriteAsync

Writes any number of bytes to an open file. (Deprecated in Mac OS X v10.5. Use PBWriteForkAsync instead.)

OSErr PBWriteAsync (
   ParmBlkPtr paramBlock
);

Parameters

paramBlock

A pointer to a basic File Manager parameter block.

Return Value

A result code. See “Device Manager Result Codes.”

Discussion

The relevant fields of the parameter block are:

• ioCompletion On input, a pointer to a completion routine.

• ioResult On output, the result code of the function.

• ioRefNum On input, a file reference number for the open file to which to write.

• ioBuffer On input, a pointer to a data buffer containing the bytes to write.

• ioReqCount On input, the number of bytes requested.

• ioActCount On output, the number of bytes actually written.

• ioPosMode On input, the positioning mode.

• ioPosOffset On input, the positioning offset. On output, the new position of the mark.

The PBWriteAsync function takes ioReqCount bytes from the buffer pointed to by ioBuffer and attempts to write them to the open file whose access path is specified by ioRefNum. The position of the mark is specified by ioPosMode and ioPosOffset. If the write operation completes successfully, PBWriteAsync 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, PBWriteAsync moves the logical end-of-file. If you try to write past the physical end-of-file, PBWriteAsync adds one or more clumps to the file and moves the physical end-of-file accordingly.

Availability

• Available in Mac OS X v10.0 and later.
• Deprecated in Mac OS X v10.5.
• Not available to 64-bit applications.

Declared In

Files.h

PBWriteSync

Writes any number of bytes to an open file. (Deprecated in Mac OS X v10.5. Use PBWriteForkSync instead.)

OSErr PBWriteSync (
   ParmBlkPtr paramBlock
);

Parameters

paramBlock

A pointer to a basic File Manager parameter block.

Return Value

A result code. See “Device Manager Result Codes.”

Discussion

The relevant fields of the parameter block are:

• ioCompletion On input, a pointer to a completion routine.

• ioResult On output, the result code of the function.

• ioRefNum On input, a file reference number for the open file to which to write.

• ioBuffer On input, a pointer to a data buffer containing the bytes to write.

• ioReqCount On input, the number of bytes requested.

• ioActCount On output, the number of bytes actually written.

• ioPosMode On input, the positioning mode.

• ioPosOffset On input, the positioning offset. On output, the new position of the mark.

The PBWriteSync function takes ioReqCount bytes from the buffer pointed to by ioBuffer and attempts to write them to the open file whose access path is specified by ioRefNum. The position of the mark is specified by ioPosMode and ioPosOffset. If the write operation completes successfully, PBWriteSync 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, PBWriteSync moves the logical end-of-file. If you try to write past the physical end-of-file, PBWriteSync adds one or more clumps to the file and moves the physical end-of-file accordingly.

Availability

• Available in Mac OS X v10.0 and later.
• Deprecated in Mac OS X v10.5.
• Not available to 64-bit applications.

Declared In

Files.h

---