geteblk(D3)

NAME
     geteblk - get an empty buffer

SYNOPSIS
     #include <sys/types.h>
     #include <sys/buf.h>
     #include <sys/ddi.h>
     buf_t *geteblk(void);

DESCRIPTION
     geteblk retrieves a buffer [see buf(D4)] from the buffer cache and
     returns a pointer to the buffer header.  If a buffer is not available,
     geteblk sleeps until one is available.

   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 geteblk:

          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 1024.

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

          b_blkno       is not initialized by geteblk, 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 or ngeteblk(D3).  If the driver chooses to
     use its own memory for the buffer, it can allocate a buffer header only
     using getrbuf(D3).
     Buffers allocated via geteblk 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), biowait(D3), brelse(D3), buf(D4), ngeteblk(D3)