Legacy Document

Inside Macintosh: Devices /

Chapter 1 - Device Manager / Device Manager Reference

Device Manager Functions / Opening and Closing Device Drivers

PBOpen

You can use the PBOpen function to open a closed device driver or to determine the driver reference number of an open device driver.

pascal OSErr PBOpen(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. You must set this field to false because device drivers cannot be opened asynchronously.

<--	ioResult	OSErr	The device driver's result code.
-->	ioNamePtr	StringPtr	A pointer to the driver name.
<--	ioRefNum	short	The driver reference number.
-->	ioPermssn	char	Read/write permission.

DESCRIPTION

The PBOpen function opens the device driver specified by the ioNamePtr field and returns its driver reference number in the ioRefNum field. To avoid replacing an open driver, the Device Manager searches the drivers that are already installed in the unit table before searching driver resources. If the specified driver is already open, this function simply returns the driver reference number.

If the driver is not already open, the Device Manager calls the GetNamedResource function using the specified name and the resource type 'DRVR'. If the resource is found, the resource ID defines the unit number of the driver, which determines the location in the unit table where the Device Manager stores the handle to the driver's device control entry (DCE).

After loading the driver resource into memory, the Device Manager creates a DCE for the driver, copies the flags from the driver header to the dCtlFlags field, and places the driver reference number in the dCtlRefNum field.

You specify the access permission for the device driver by placing one of the following constants in the ioPermssn field of the parameter block:

enum {
   /* access permissions */
   fsCurPerm         = 0,        /* retain current permission */
   fsRdPerm          = 1,        /* allow reads only */
   fsWrPerm          = 2,        /* allow writes only */
   fsRdWrPerm        = 3         /* allow reads and writes */
};

If the driver returns a negative result in register D0, the Device Manager returns the result code in the ioResult parameter and does not open the driver.

SPECIAL CONSIDERATIONS

Because another driver might already be installed in the unit table at the location determined by the driver's resource ID, you should first search for an unused location in the unit table and renumber the driver resource accordingly before calling this function. See Listing 1-1 on page 1-18 for an example.

The PBOpen function may move memory; you should not call it at interrupt time.

ASSEMBLY-LANGUAGE INFORMATION

The trap macro for the PBOpen function is _Open (0xA000). You must set up register A0 with the address of the parameter block. When _Open 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
badUnitErr	-21	Driver reference number does not match unit table
unitEmptyErr	-22	Driver reference number specifies a nil handle in unit table
openErr	-23	Requested read/write permission does not match driver's open permission
dInstErr	-26	Driver resource not found

SEE ALSO

For information about the high-level function for opening device drivers, see the description of the OpenDriver function on page 1-60. For information about the
low-level function for opening device drivers that serve devices on expansion cards, see the next section, which describes the OpenSlot function. For an example of opening a device driver, see Listing 1-1 on page 1-18.