1.\" $OpenBSD: uiomove.9,v 1.19 2016/03/15 06:49:21 jmc Exp $ 2.\" $NetBSD: uiomove.9,v 1.6 2001/12/26 00:16:30 wiz Exp $ 3.\" 4.\" Copyright (c) 1996 The NetBSD Foundation, Inc. 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 17.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 18.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 19.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 20.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 23.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 24.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 25.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 26.\" POSSIBILITY OF SUCH DAMAGE. 27.\" 28.Dd $Mdocdate: March 15 2016 $ 29.Dt UIOMOVE 9 30.Os 31.Sh NAME 32.Nm uiomove 33.Nd move data described by a struct uio 34.Sh SYNOPSIS 35.In sys/systm.h 36.Ft int 37.Fn uiomove "void *buf" "size_t n" "struct uio *uio" 38.Sh DESCRIPTION 39The 40.Nm 41function copies up to 42.Fa n 43bytes between the kernel-space address pointed 44to by 45.Fa buf 46and the addresses described by 47.Fa uio , 48which may be in user-space or kernel-space. 49.Pp 50The 51.Fa uio 52argument is a pointer to a 53.Fa struct uio 54as defined by 55.In sys/uio.h : 56.Bd -literal 57struct uio { 58 struct iovec *uio_iov; /* pointer to array of iovecs */ 59 int uio_iovcnt; /* number of iovecs in array */ 60 off_t uio_offset; /* offset into file this uio corresponds to */ 61 size_t uio_resid; /* residual i/o count */ 62 enum uio_seg uio_segflg; 63 enum uio_rw uio_rw; 64 struct proc *uio_procp;/* associated process or NULL */ 65}; 66.Ed 67.Pp 68A 69.Fa struct uio 70typically describes data in motion. 71Several of the fields described below reflect that expectation. 72.Bl -tag -width uio_xxxxxx 73.It uio_iov 74Pointer to array of 75.Fa struct iovecs : 76.Bd -literal 77struct iovec { 78 void *iov_base; /* Base address. */ 79 size_t iov_len; /* Length. */ 80}; 81.Ed 82.It uio_iovcnt 83The number of iovecs in the array. 84.It uio_offset 85An offset into the corresponding object. 86.It uio_resid 87The amount of data remaining to be transferred. 88.It uio_segflg 89A flag indicating whether the space described is in user-space 90(UIO_USERSPACE) or kernel-space (UIO_SYSSPACE). 91.It uio_rw 92A flag indicating whether data should be read into the space 93(UIO_READ) or written from the space (UIO_WRITE). 94.It uio_procp 95A pointer to a process whose data area is described by the 96structure, or which is having the I/O done on its behalf if 97the area is in kernel-space. 98.Nm uiomove 99itself does not use this field if the area is in kernel-space, 100but other functions that take a 101.Fa struct uio 102may depend on this information. 103.El 104.Pp 105The value of 106.Fa uio->uio_rw 107controls whether 108.Nm 109copies data from 110.Fa buf 111to 112.Fa uio 113or vice versa. 114.Pp 115The lesser of 116.Fa n 117or 118.Fa uio->uio_resid 119bytes are copied. 120.Pp 121.Nm 122changes fields of the structure pointed to by 123.Fa uio , 124such that 125.Fa uio->uio_resid 126is decremented by the amount of data moved, 127.Fa uio->uio_offset 128is incremented by the same amount, and the array of iovecs is adjusted 129to point that much farther into the region described. 130This allows multiple calls to 131.Nm 132to easily be used to fill or drain the region of data. 133.Sh RETURN VALUES 134.Nm 135returns 0 on success or EFAULT if a bad address is encountered. 136.Sh SEE ALSO 137.Xr copy 9 138