getrbuf(D3)getrbuf(D3)NAMEgetrbuf - get a raw buffer header
SYNOPSIS
#include <sys/buf.h>
#include <sys/kmem.h>
#include <sys/ddi.h>
buf_t *getrbuf(long flag);
Arguments
flag Indicates whether the caller should sleep for free space.
DESCRIPTIONgetrbuf allocates the space for a buffer header (see buf(D4)). 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.
Return Values
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.
USAGEgetrbuf 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(D3)). The caller must also initialize the
following fields:
b_flags Must be modified 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_edev Must be initialized to the proper device number.
b_bcount Must be set to the number of bytes to transfer.
b_un.b_addr Must be set to the virtual address of the caller-supplied
buffer.
b_blkno Must be set to the block number to be accessed.
Page 1
getrbuf(D3)getrbuf(D3)
b_resid Must be set to the same value as b_bcount.
b_bufsize Can 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(D2) 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(D3) or ngeteblk(D3). Or the driver can
choose to use its own memory for the buffer and only allocate a buffer
header with getrbuf.
Level
Base only if flag is set to KM_SLEEP.
Base or Interrupt if flag is set to KM_NOSLEEP.
Synchronization Constraints
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.
REFERENCESbiodone(D3), biowait(D3), buf(D4), freerbuf(D3).
Page 2
