getrbuf(D3) getrbuf(D3)
NAME
getrbuf - get a raw buffer header
SYNOPSIS
#include <sys/buf.h>
#include <sys/kmem.h>
#include <sys/ddi.h>
buf_t *getrbuf(long flag);
Arguments
flag Indicates whether the caller should sleep for
free space.
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.
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 block driver is performing raw I/O
(character interface) 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 Must be modified to indicate the direction of
data transfer. Initially, it 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
Copyright 1994 Novell, Inc. Page 1
getrbuf(D3) getrbuf(D3)
buffer.
b_edev Must be initialized to the proper device number.
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, 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(D3). Or the driver can choose to use
its own memory for the buffer and only allocate a buffer
header with getrbuf.
Level
Base only if flag is set to KM_SLEEP.
Base or Interrupt if flag is set to KM_NOSLEEP.
Synchronization Constraints
May sleep if flag is set to KM_SLEEP.
Driver-defined basic locks and read/write locks may be held
across calls to this function if flag is KM_NOSLEEP, but may
not be held if flag is KM_SLEEP.
Driver-defined sleep locks may be held across calls to this
function regardless of the value of flag.
REFERENCES
biodone(D3), bioreset(D3), biowait(D3), biowait_sig(D3),
buf(D4), freerbuf(D3)
Copyright 1994 Novell, Inc. Page 2
getrbuf(D3) getrbuf(D3)
NOTICES
Portability
All processors
Applicability
ddi: 1, 2, 3, 4, 5, 5mp, 6, 6mp, 7, 7mp
Copyright 1994 Novell, Inc. Page 3