getrbuf(D3)

NAME
     getrbuf - 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.

DESCRIPTION
     getrbuf 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.

USAGE
     getrbuf 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.
     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.

REFERENCES
     biodone(D3), biowait(D3), buf(D4), freerbuf(D3).