Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

Previous Book Contents Book Index Next

Inside Macintosh: Files /
Chapter 2 - File Manager / File Manager Reference
Low-Level File Access Routines / Reading, Writing, and Closing Files


PBRead

You can use the PBRead function to read any number of bytes from an open file.

FUNCTION PBRead (paramBlock: ParmBlkPtr; async: Boolean): OSErr;
paramBlock
A pointer to a basic File Manager parameter block.
async
A Boolean value that specifies asynchronous (TRUE) or synchronous (FALSE) execution.
-->ioCompletionProcPtrA pointer to a completion routine.
<--ioResultOSErrThe result code of the function.
-->ioRefNumIntegerA file reference number.
-->ioBufferPtrA pointer to a data buffer.
-->ioReqCountLongIntThe number of bytes requested.
<--ioActCountLongIntThe number of bytes actually read.
-->ioPosModeIntegerThe positioning mode.
<->ioPosOffsetLongIntThe positioning offset.

DESCRIPTION
The PBRead 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, PBRead reads the data, moves the mark to the end-of-file, and returns eofErr as its function result. Otherwise, PBRead moves the file mark to the byte following the last byte read and returns noErr. After the read is completed, the mark is returned in ioPosOffset, and the number of bytes actually read into the buffer is returned in ioActCount.

You can specify that PBRead 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 PBRead 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.

Note
When reading data in newline mode, PBRead 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).
ASSEMBLY-LANGUAGE INFORMATION
The trap macro for PBRead is _Read.

RESULT CODES
noErr0No error
ioErr-36I/O error
fnOpnErr-38File not open
eofErr-39Logical end-of-file reached
posErr-40Attempt to position mark before start of file
fLckdErr-45File is locked
paramErr-50Negative ioReqCount
rfNumErr-51Bad reference number
afpAccessDenied-5000User does not have the correct access to the file

Previous Book Contents Book Index Next

© Apple Computer, Inc.
2 JUL 1996