Legacy Document

Inside Macintosh: Devices /

Chapter 1 - Device Manager / Device Manager Reference

Device Manager Functions / Communicating With Device Drivers

PBWrite

You can use the PBWrite function to write data from a data buffer to an open driver.

pascal OSErr PBWrite(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 write.
<--	ioActCount	long	The actual number of bytes written.
-->	ioPosMode	short	The positioning mode.
<-->	ioPosOffset	long	The positioning offset.

DESCRIPTION

The PBWrite function attempts to write the number of bytes indicated by the ioReqCount field from the data buffer pointed to by the ioBuffer field to the device driver specified by the ioRefNum field. After the transfer is complete, the ioActCount field indicates the number of bytes actually written.

For block devices such as disk drivers, the PBWrite 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 written, 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 new current position of a block device.

SPECIAL CONSIDERATIONS

Do not call the PBWrite 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 PBWrite function is _Write (0xA003). 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 _Write 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
writErr	-20	Driver does not respond to write requests
badUnitErr	-21	Driver reference number does not match unit table
unitEmptyErr	-22	Driver reference number specifies a nil handle in unit table
abortErr	-27	Request aborted by KillIO
notOpenErr	-28	Driver not open

SEE ALSO

For information about the high-level function for writing to device drivers, see the description of the FSWrite function on page 1-72. For an example of how to write to a device driver using the PBWrite function, see Listing 1-4 on page 1-22.