uio(D4)uio(D4)NAMEuio - scatter/gather I/O request structure
SYNOPSIS
#include <sys/types.h>
#include <sys/file.h>
#include <sys/uio.h>
#include <sys/ddi.h>
DESCRIPTION
The uio structure describes an I/O request that can be broken up into
different data storage areas (scatter/gather I/O). A request is a list
of iovec(D4) structures (base/length pairs) indicating where in user
space or kernel space the data are to be read/written.
USAGE
The contents of the uio structure passed to the driver through the entry
points in section D2 should not be changed directly by the driver. The
uiomove(D3), ureadc(D3), and uwritec(D3) functions take care of
maintaining the uio structure. A block driver may also use the
physiock(D3) function to perform unbuffered I/O. physiock also takes
care of maintaining the uio structure.
A driver that creates its own uio structures for a data transfer is
responsible for zeroing it prior to initializing members accessible to
the driver. The driver must not change the uio structure afterwards; the
functions take care of maintaining the uio structure.
Note that a separate interface does not currently exist for allocating
uio(D4) and iovec(D4) structures when the driver needs to create them
itself. Therefore, the driver may either use kmem_zalloc(D3) to allocate
them, or allocate them statically.
Structure Definitions
The uio structure contains the following members:
iovec_t *uio_iov; /* Pointer to the start of the iovec */
/* array for the uio structure */
int uio_iovcnt; /* The number of iovecs in the array */
off_t uio_offset; /* Offset into file where data are */
/* transferred from or to */
short uio_segflg; /* Identifies the type of I/O transfer */
short uio_fmode; /* File mode flags */
int uio_resid; /* Residual count */
The driver may only set uio structure members to initialize them for a
data transfer for which the driver created the uio structure. The driver
must not otherwise change uio structure members. However, drivers may
read them. The uio structure members available for the driver to test or
set are described below:
Page 1
uio(D4)uio(D4)
uio_iov contains a pointer to the iovec array for the uio structure. If
the driver creates a uio structure for a data transfer, an associated
iovec array must also be created by the driver.
uio_iovcnt contains the number of elements in the iovec array for the uio
structure.
uio_offset contains the starting logical byte address on the device where
the data transfer is to occur. Applicability of this field to the driver
is device-dependent. It applies to randomly accessed devices, but may
not apply to all sequentially accessed devices.
uio_segflg identifies the virtual address space in which the transfer
data areas reside. The value UIO_SYSSPACE indicates the data areas are
within kernel space. The value UIO_USERSPACE indicates one data area is
within kernel space and the other is within the user space of the current
process context.
uio_fmode contains flags describing the file access mode for which the
data transfer is to occur. Valid flags are:
FNDELAY The driver should not wait if the requested data
transfer cannot occur immediately; it should terminate
the request without indicating an error occurred. The
driver's implementation of this flag's implied
semantics are subject to device-dependent
interpretation.
FNONBLOCK The driver should not wait if the requested data
transfer cannot occur immediately; it should terminate
the request, returning the EAGAIN error code as the
completion status [see errnos(D5)]. The driver's
implementation of the implied semantics of this flag
are subject to device-dependent interpretation.
If the driver creates a uio structure for a data transfer, it may set the
flags described above in uio_fmode.
uio_resid indicates the number of bytes that have not been transferred to
or from the data area. If the driver creates a uio structure for a data
transfer, uio_resid is initialized by the driver as the number of bytes
to be transferred. Note that a separate interface does not currently
exist for allocating a uio structure.
REFERENCESiovec(D4), physiock(D3), read(D2), uiomove(D3), ureadc(D3), uwritec(D3),
write(D2)
Page 2
