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: Devices /
Chapter 1 - Device Manager / Device Manager Reference
Device Manager Functions / Communicating With Device Drivers


PBRead

You can use the PBRead 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.
-->ioCompletionProcPtrA pointer to a completion routine.
<--ioResultOSErrThe device driver's result code.
-->ioVRefNumshortThe drive number.
-->ioRefNumshortThe driver reference number.
-->ioBufferPtrA pointer to a data buffer.
-->ioReqCountlongThe requested number of bytes to read.
<--ioActCountlongThe actual number of bytes read.
-->ioPosModeshortThe positioning mode.
<-->ioPosOffsetlongThe positioning offset.

DESCRIPTION
Before calling the PBRead function, your application should allocate a data buffer large enough to hold the data to be read. The PBRead function attempts to read the number of bytes indicated by the ioReqCount field and transfer them to the data buffer pointed to by the ioBuffer field. The ioRefNum field identifies the device driver. After the transfer is complete, the ioActCount field indicates the number of bytes actually read.

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.
For block devices such as disk drivers, the PBRead function allows you to specify a drive number in the ioVRefNum field and specify a positioning mode and offset in the ioPosMode and ioPosOffset fields. Bits 0 and 1 of the ioPosMode 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 */
};
The ioPosOffset 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. The ioPosOffset field is ignored when ioPosMode is set to fsAtMark.

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, call PBRead immediately after writing the data, and add the read-verify constant rdVerify to the ioPosMode field of the parameter block. The result code ioErr is returned if the data does not match.

SPECIAL CONSIDERATIONS
Do not call the PBRead 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 the PBRead 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
A0Address of the parameter block
Registers on exit
D0Result code

RESULT CODES
noErr0No error
readErr-19Driver does not respond to read requests
badUnitErr-21Driver reference number does not match unit table
unitEmptyErr-22Driver reference number specifies a nil handle in unit table
abortErr-27Request aborted by KillIO
notOpenErr-28Driver not open
ioErr-36Data 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 the FSRead function beginning on page 1-69. For an example of how to read from a device driver using the PBRead function, see Listing 1-3 on page 1-21.


Previous Book Contents Book Index Next

© Apple Computer, Inc.
3 JUL 1996