SVR5

ngeteblk(D3)

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);

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.

Arguments

bsize: Size of the buffer being requested.

Return values

A pointer to the buffer header structure is returned.

Usage

When the driver strategy(D2) (DDI versions before version 8) or biostart(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 for a synchronous write transfer from main memory to the device. The druver must turn on the B_READ flag to transfer from the device to main memory. The driver may also turn on the B_ASYNC flag and set the b_iodone member for a synchronous transfer. the user's buffer.
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
b_blkoff
b_addrtype: is set to BA_KVIRT
b_bufsize: is set to bsize
b_iodone: is set to NULL

Typically, drivers do not allocate buffers. A buffer is allocated by the kernel, and the associated buffer header is used as an argument to the driver's biostart(D2) or strategy(D2) 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 the ngetenlk( ) function. Or the driver can choose to use its own memory for the buffer and allocate just a buffer header with the getrbuf(D3) function.

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

Context and synchronization

User or blockable context.

Hardware applicability

All

Version applicability

ddi: 1, 2, 3, 4, 5, 5mp, 6, 6mp, 7, 7mp, 7.1, 7.1mp, 8, 8mp

References

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