ngeteblk(D3)

NAME
     ngeteblk - get an empty buffer of the specified size

SYNOPSIS
     #include <sys/types.h>
     #include <sys/buf.h>
     #include <sys/ddi.h>
     buf_t *ngeteblk(size_t bsize);

   Arguments
     bsize     Size of the buffer being requested.

DESCRIPTION
     ngeteblk retrieves a buffer [see buf(D4)] of size bsize from the buffer
     cache and returns a pointer to the buffer header.  If a buffer is not
     available, ngeteblk dynamically allocates one.  If memory is not
     immediately available, ngeteblk will sleep until enough memory has been
     freed to allocate the buffer.

   Return Values
     A pointer to the buffer header structure is returned.

USAGE
     When the driver strategy(D2) routine receives a buffer header from the
     kernel, all the necessary members are already initialized.  However, when
     a driver allocates buffers for its own use, it must set up some of the
     members before calling its strategy routine.

     The following list describes the state of these members when the buffer
     header is received from ngeteblk:

          b_flags       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        is set to NODEV and must be initialized by the driver.

          b_bcount      is set to bsize.

          b_un.b_addr   is set to the buffer's virtual address.

          b_blkno       is not initialized by ngeteblk, and must be
                        initialized by the driver

     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.  Or the driver can choose to
     use its own memory for the buffer and only allocate a buffer header with
     getrbuf(D3).

     Note that buffers allocated via ngeteblk must be freed using either
     brelse(D3) or biodone(D3).

   Level
     Base only.

   Synchronization Constraints
     Can sleep.

     Driver-defined basic locks and read/write locks may not be held across
     calls to this function.

     Driver-defined sleep locks may be held across calls to this function.

REFERENCES
     biodone(D3), brelse(D3), buf(D4), geteblk(D3)