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)