uio(D4DK) —

NAME

uio − scatter/gather I/O request structure

SYNOPSIS

#include <sys/types.h>
#include <sys/file.h>
#include <sys/uio.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(D4DK) structures (base/length pairs) indicating where in user space or kernel space the data are to be read/written.

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(D3DK), ureadc(D3DK), and uwritec(D3DK) functions take care of maintaining the the uio structure. A block driver may also use the physiock(D3DK) 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.

STRUCTURE 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:

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 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:

FNDELAYThe 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.

FNONBLOCKThe 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(D5DK)]. 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.

NOTES

A separate interface does not currently exist for allocating uio(D4DK) and iovec(D4DK) structures when the driver needs to create them itself. Therefore, the driver may either use kmem_zalloc(D3DK) to allocate them, or allocate them statically.