uio(D4)
uio --
virtual memory scatter/gather I/O request structure
Syntax
#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
that is 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 structure
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 and iovec structures
when the driver needs to create them itself.
Therefore, the driver may either use the
kmem_zalloc(D3)
routine to allocate them,
or allocate them statically.
Structure definitions
The uio structure contains the following members:
iovec_t *uio_iov;
int uio_iovcnt;
short uio_segflg;
int uio_resid;
short uio_fmode;
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(D4)
array for the uio structure.
If the driver creates a uio
structure for a data transfer,
the driver must also create
an associated iovec array.
uio_iovcnt
-
contains the number of elements in the iovec
array for the uio structure.
uio_segflg
-
identifies the virtual address space in which the
transfer data areas reside.
The following values are valid:
UIO_SYSSPACE-
indicates
that the data areas are within kernel space.
UIO_USERSPACE-
indicates one data area is within kernel space
and the other is within the user space
of the current process context.
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.
This member is usually updated by the
uiomove(D3),
ureadc(D3),
and
uwritec(D3)
functions.
uio_fmode
-
contains flags describing the file access mode for
which the data transfer is to occur.
Valid flags are:
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 this flag in uio_fmode
.
Applicable hardware
All
Version applicability
ddi:
1, 2, 3, 4, 5, 5mp, 6, 6mp, 7, 7mp, 7.1, 7.1mp, 8, 8mp
Differences between versions
DDI versions prior to version 8
also support the following member for the
uio structure:
off_t uio_offset;
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.
For DDI 8 drivers,
this member is replaced by the
b_blkno
and b_blkoff
members of the
buf(D4)
structure to accomodate large file support. See
``Large device support'' in HDK Technical Reference.
For DDI versions prior to version 8,
the uio_fmode
member
also supports the following flag:
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.
References
iovec(D4),
open(D2),
physiock(D3),
read(D2),
uiomove(D3),
ureadc(D3),
uwritec(D3),
write(D2)
``Large device support'' in HDK Technical Reference
19 June 2005
© 2005 The SCO Group, Inc. All rights reserved.
OpenServer 6 and UnixWare (SVR5) HDK - June 2005