DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 
SVR5

getrbuf(D3)


getrbuf -- get a raw buffer header

Synopsis

   #include <sys/buf.h>
   #include <sys/kmem.h>
   #include <sys/ddi.h>
   

buf_t *getrbuf(intg flag);

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.

Arguments


flag
Indicates whether the caller should sleep for free space.

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 driver is performing raw I/O 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.

On return from getrbuf, the ``b_iodone'' field of the buffer header will be NULL (meaning take the default action on completion). Since the default action does not support driver buffers in the asynchronous case, the driver must change this to the address of a driver-specific I/O completion handler if the buffer will be used for B_ASYNC transfers.

The caller must also initialize the following fields:


b_flags
is set for a syncrhonous 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_addrtype
Is set to BA_KVIRT

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, 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, for DDI versions prior to version 8, 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 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.

Context and synchronization

If flag is set to KM_NOSLEEP, non-blockable, initialization, or interrupt context.

If flag is set to KM_SLEEP, user 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), bioreset(D3), biowait(D3), biowait_sig(D3), buf(D4), freerbuf(D3)
19 June 2005
© 2005 The SCO Group, Inc. All rights reserved.
OpenServer 6 and UnixWare (SVR5) HDK - June 2005