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