Important: The information in this document is obsolete and should not be used for new development.
PBRead
You can use thePBRead
function to read data from an open driver into a data buffer.
pascal OSErr PBRead(ParmBlkPtr paramBlock, Boolean async);
paramBlock
- A pointer to an
IOParam
structure of the Device Manager parameter block.async
- A Boolean value that indicates whether the request is asynchronous.
--> ioCompletion ProcPtr A pointer to a completion routine. <-- ioResult OSErr The device driver's result code. --> ioVRefNum short The drive number. --> ioRefNum short The driver reference number. --> ioBuffer Ptr A pointer to a data buffer. --> ioReqCount long The requested number of bytes to read. <-- ioActCount long The actual number of bytes read. --> ioPosMode short The positioning mode. <--> ioPosOffset long The positioning offset. DESCRIPTION
Before calling thePBRead
function, your application should allocate a data buffer large enough to hold the data to be read. ThePBRead
function attempts to read the number of bytes indicated by theioReqCount
field and transfer them to the data buffer pointed to by theioBuffer
field. TheioRefNum
field identifies the device driver. After the transfer is complete, theioActCount
field indicates the number of bytes actually read.
For block devices such as disk drivers, the
- WARNING
- Be sure your buffer is large enough to hold the number of bytes specified by the
count
parameter, or this function may corrupt memory.PBRead
function allows you to specify a drive number in theioVRefNum
field and specify a positioning mode and offset in theioPosMode
andioPosOffset
fields. Bits 0 and 1 of theioPosMode field indicate where an operation should begin relative to the physical beginning of the
block-formatted medium. You can use the following constants to test or set the value of these bits:
enum { /* positioning modes */ fsAtMark = 0, /* at current position */ fsFromStart = 1, /* offset from beginning */ fsFromMark = 3 /* offset from current position */ };TheioPosOffset
field specifies the positive or negative byte offset where the data is to be read, relative to the positioning mode. The offset must be a multiple of 512. TheioPosOffset
field is ignored whenioPosMode
is set tofsAtMark
.After the transfer is complete, the
ioPosOffset
field indicates the current position of the block device.The Disk Driver allows you to use the
PBRead
function to verify that data written to a block device matches the data in memory. To do this, callPBRead immediately after writing the data, and add
the read-verify constantrdVerify
to theioPosMode
field of the parameter block. The result codeioErr
is returned if the data does not match.SPECIAL CONSIDERATIONS
Do not call thePBRead
function synchronously at interrupt time. Synchronous requests at interrupt time may block other pending I/O requests and cause the Device Manager to loop indefinitely while it waits for the device driver to complete the interrupted requests.ASSEMBLY-LANGUAGE INFORMATION
The trap macro for thePBRead
function is_Read
(0xA002). Set bit 10 of the trap word to execute this function asynchronously. Set bit 9 to execute it immediately.You must set up register A0 with the address of the parameter block. When
_Read
returns, register D0 contains the result code. Register D0 is the only register affected by this function.
Registers on entry A0 Address of the parameter block
Registers on exit D0 Result code RESULT CODES
noErr 0 No error readErr -19 Driver does not respond to read requests badUnitErr -21 Driver reference number does not match unit table unitEmptyErr -22 Driver reference number specifies a nil
handle in unit tableabortErr -27 Request aborted by KillIO
notOpenErr -28 Driver not open ioErr -36 Data does not match in read-verify mode SEE ALSO
For information about the high-level function for reading from device drivers, see the description of theFSRead
function beginning on page 1-69. For an example of how to read from a device driver using thePBRead
function, see Listing 1-3 on page 1-21.