Legacy Document

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.

-->	ioCompletion	ProcPtr	A pointer to a completion routine.
<--	ioResult	OSErr	The result code of the function.
-->	ioRefNum	Integer	A file reference number.
-->	ioBuffer	Ptr	A pointer to a data buffer.
-->	ioReqCount	LongInt	The number of bytes requested.
<--	ioActCount	LongInt	The number of bytes actually read.
-->	ioPosMode	Integer	The positioning mode.
<->	ioPosOffset	LongInt	The 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

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