diff options
Diffstat (limited to 'static/netbsd/man9/uiomove.9')
| -rw-r--r-- | static/netbsd/man9/uiomove.9 | 182 |
1 files changed, 182 insertions, 0 deletions
diff --git a/static/netbsd/man9/uiomove.9 b/static/netbsd/man9/uiomove.9 new file mode 100644 index 00000000..ad386450 --- /dev/null +++ b/static/netbsd/man9/uiomove.9 @@ -0,0 +1,182 @@ +.\" $NetBSD: uiomove.9,v 1.21 2023/05/22 14:07:24 riastradh Exp $ +.\" +.\" Copyright (c) 1996 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 9, 2023 +.Dt UIOMOVE 9 +.Os +.Sh NAME +.Nm uiomove +.Nd move data described by a struct uio +.Sh SYNOPSIS +.In sys/systm.h +.Ft int +.Fn uiomove "void *buf" "size_t n" "struct uio *uio" +.Ft int +.Fn uiopeek "void *buf" "size_t n" "struct uio *uio" +.Ft void +.Fn uioskip "void *buf" "size_t n" "struct uio *uio" +.Sh DESCRIPTION +The +.Fn uiomove +function copies up to +.Fa n +bytes between the kernel-space address pointed +to by +.Fa buf +and the addresses described by +.Fa uio , +which may be in user-space or kernel-space. +.Pp +The +.Fa uio +argument is a pointer to a +.Va struct uio +as defined by +.In sys/uio.h : +.Bd -literal -offset indent +struct uio { + struct iovec *uio_iov; + int uio_iovcnt; + off_t uio_offset; + size_t uio_resid; + enum uio_rw uio_rw; + struct vmspace *uio_vmspace; +}; +.Ed +.Pp +A +.Va struct uio +typically describes data in motion. +Several of the fields described below reflect that expectation. +.Bl -tag -width "uio_vmspace " +.It Va uio_iov +Pointer to array of +.Tn I/O +vectors to be processed. +The +.Va struct iovec +is defined to be: +.Bd -literal -offset indent +struct iovec { + void *iov_base; + size_t iov_len; +}; +.Ed +.Pp +The members in the +.Va struct iovec +should only be initialized. +These are: +.Bl -tag -width "*iov_base " -offset indent +.It Va iov_base +The address for a range of memory to or from which data is transferred. +.It Va iov_len +The number of bytes of data to be transferred to +or from the range of memory starting at +.Va iov_base . +.El +.It Va uio_iovcnt +The number of +.Tn I/O +vectors in the +.Va uio_iov +array. +.It Va uio_offset +An offset into the corresponding object. +.It Va uio_resid +The amount of space described by the structure; notionally, the amount +of data remaining to be transferred. +.It Va uio_rw +A flag indicating whether data should be read into the space +(UIO_READ) or written from the space (UIO_WRITE). +.It Va uio_vmspace +A pointer to the address space which is being transferred to or from. +.El +.Pp +The value of +.Va uio->uio_rw +controls whether +.Fn uiomove +copies data from +.Fa buf +to +.Fa uio +or vice versa. +.Pp +The lesser of +.Fa n +or +.Va uio->uio_resid +bytes are copied. +.Pp +.Fn uiomove +changes fields of the structure pointed to by +.Fa uio , +such that +.Va uio->uio_resid +is decremented by the amount of data moved, +.Va uio->uio_offset +is incremented by the same amount, and the array of iovecs is adjusted +to point that much farther into the region described. +This allows multiple calls to +.Fn uiomove +to easily be used to fill or drain the region of data. +.Pp +The +.Fn uiopeek +function copies up to +.Fa n +bytes of data without updating +.Fa uio ; +the +.Fn uioskip +function updates +.Fa uio +without copying any data, and is guaranteed never to sleep or fault +even if the buffers are in userspace and memory access via +.Fn uiomove +or +.Fn uiopeek +would trigger paging. +A successful +.Fn uiomove buf n uio +call is equivalent to a successful +.Fn uiopeek buf n uio +followed by +.Fn uioskip n uio . +.Sh RETURN VALUES +Upon successful completion, +.Fn uiomove +and +.Fn uiopeek +return 0. +If a bad address is encountered, +.Er EFAULT +is returned. +.Sh SEE ALSO +.Xr copy 9 , +.Xr ufetch 9 , +.Xr ustore 9 |