getrbuf(D3DK) —

.IX \f4getrbuf\fP(D3DK)

NAME

getrbuf − get a raw buffer header .IX buffer header

SYNOPSIS

#include <sys/buf.h>
#include <sys/kmem.h>
#include <sys/ddi.h>
buf_t ∗getrbuf(long flag);

ARGUMENTS

flagIndicates whether caller should sleep for free space. If flag is set to KM_SLEEP, the caller will sleep if necessary until memory is available. If flag is set to KM_NOSLEEP, the caller will not sleep, but getrbuf will return NULL if memory is not immediately available.

DESCRIPTION

getrbuf allocates the space for a buffer header [see buf(D4DK)]. It is used when a block driver is performing raw I/O (character interface) and needs to set up a buffer header that is not associated with a system-provided data buffer. The driver provides its own memory for the data buffer.

After allocating the buffer header, the caller must set the b_iodone field to the address of an iodone handler to be invoked when the I/O is complete [see biodone(D3DK)]. The caller must also initialize the following fields:

b_flagsmust be set to indicate the direction of data transfer. Initially, it is set to indicate the transfer is from the user’s buffer to the kernel. The driver must set the B_READ flag if the transfer is from the kernel to the user’s buffer.

b_edevmust be initialized to the proper device number.

b_bcountmust be set to the number of bytes to transfer.

b_un.b_addrmust be set to the virtual address of the caller-supplied buffer.

b_blknomust be set to the block number to be accessed.

b_residmust be set to the same value as b_bcount.

b_bufsizecan be used to remember the size of the data buffer associated with the buffer header.

Typically, block drivers do not allocate buffers. The buffer is allocated by the kernel, and the associated buffer header is used as an argument to the driver strategy routine. However, to implement some special features, such as ioctl(D2DK) commands that perform I/O, the driver may need its own buffer space. The driver can get the buffer space from the system by using geteblk(D3DK) or ngeteblk(D3DK). Or the driver can choose to use its own memory for the buffer and only allocate a buffer header with getrbuf.

RETURN VALUE

Upon successful completion, getrbuf returns a pointer to the allocated buffer header. If KM_NOSLEEP is specified and sufficient memory is not immediately available, getrbuf returns a NULL pointer.

LEVEL

Base only if flag is set to KM_SLEEP. Base or interrupt if flag is set to KM_NOSLEEP.

NOTES

May sleep if flag is set to KM_SLEEP.

Driver-defined basic locks and read/write locks may be held across calls to this function if flag is KM_NOSLEEP, but may not be held if flag is KM_SLEEP.

Driver-defined sleep locks may be held across calls to this function regardless of the value of flag.

Museum