uiomove(9r) uiomove(9r)
NAME
uiomove - General: Moves data between user and system virtual space
SYNOPSIS
#include <sys/uio.h>
int uiomove(
caddr_t kern_buf,
int nbytes,
struct uio *uio );
ARGUMENTS
Specifies a pointer to the kernel buffer in system virtual space. Specifies the number of bytes of data to be moved. Specifies a pointer
to a uio structure. This structure describes the current position within a logical user buffer in user virtual space.
DESCRIPTION
The uiomove routine moves data between user and system virtual space. Data can be moved in either direction. Accessibility to the logical
user buffer is verified before the move is made. Accessibility to the kernel buffer is always assumed.
The kernel buffer must always be of sufficient size to accommodate the data. It cannot be less than the number of bytes requested to be
moved. Data corruption or a system panic may result if this condition occurs.
The size of the logical user buffer, as described by the uio structure, may be less than, equal to, or greater than the number of bytes
requested. The number of bytes actually moved is truncated whenever this size is not sufficient to fulfill a request. In all other cases,
only the bytes requested are moved.
Normally there is no need for kernel modules to set up uio structures or worry about their composition or content. The uio structures are
usually set up externally to kernel modules. Their addresses are passed in through the dsent table as arguments to module read and write
routines. The user logical buffers they describe are accessed only by routines external to the module, for example, uiomove. The external
uio structures are quite often updated by such accesses.
The uiomove routine always updates the uio structure to reflect the number of bytes actually moved. The structure continues to describe
the current position within the logical user buffer. The structure members that are subject to change are listed in the SIDE EFFECTS sec-
tion.
NOTES
You can also use the uiomove routine to move data only within system virtual space. In such cases, you still specify a pointer to a uio
structure. However, in these cases, the structure describes a logical buffer in system virtual space.
SIDE EFFECTS
The uiomove routine can update the following members of the uio structure: Specifies the address of the current logical buffer segment.
Specifies the number of remaining logical buffer segments. Specifies the size of the remaining logical buffer. Specifies the current off-
set into the full logical buffer.
The uiomove routine can update the following members of uio_iov (the logical buffer segment descriptor vector): Specifies the address of
the current byte within the current logical buffer segment. Specifies the remaining size of the current segment.
RETURN VALUES
Upon successfully moving the data, the uiomove routine returns the value 0 (zero). This action implies that the user virtual space
described by the uio structure is accessible. Otherwise, uiomove returns the error value EFAULT, indicating an inability to fully access
the user virtual space from within the context of the current process. A partial move may have occurred before the logical user buffer
became inaccessible. The uio structure is appropriately updated to reflect such partial moves.
The EFAULT return value is suitable for placement in the u_error member of the user structure. Following failure of a system call, this
member contains the error code automatically returned in errno to the current process. Kernel module writers should explicitly set this
value when it is returned and disallow the requested operation. This setting lets the current process determine the appropriate reason
(``bad address'') why its request could not be satisfied.
SEE ALSO
Routines: copyin(9r), copyout(9r), fubyte(9r), subyte(9r)
Data Structures: uio(9s)
uiomove(9r)