uio(D4) uio(D4)
NAME
uio - 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:
Copyright 1994 Novell, Inc. Page 1
uio(D4) uio(D4)
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:
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
Copyright 1994 Novell, Inc. Page 2
uio(D4) uio(D4)
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
REFERENCES
iovec(D4), physiock(D3), read(D2), uiomove(D3), ureadc(D3),
uwritec(D3), write(D2)
NOTICES
Portability
All processors
Copyright 1994 Novell, Inc. Page 3