uiomove(9r)uiomove(9r)NAMEuiomove - 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 mem‐
bers that are subject to change are listed in the SIDE EFFECTS section.
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 struc‐
ture: 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 offset
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)
