[src/uebayasi-xip]: src/share/man/man9 Describe the struct iovec better.

[jruoho <jruoho%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/a2e27669cd0d
branches:  uebayasi-xip
changeset: 751679:a2e27669cd0d
user:      jruoho <jruoho%NetBSD.org@localhost>
date:      Mon Apr 26 07:51:37 2010 +0000

description:
Describe the struct iovec better.

diffstat:

 share/man/man9/uiomove.9 |  154 +++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 154 insertions(+), 0 deletions(-)

diffs (158 lines):

diff -r 245fd64944e1 -r a2e27669cd0d share/man/man9/uiomove.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/uiomove.9  Mon Apr 26 07:51:37 2010 +0000
@@ -0,0 +1,154 @@
+.\"    $NetBSD: uiomove.9,v 1.17.2.2 2010/04/26 07:51:37 jruoho 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 April 26, 2010
+.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"
+.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.
+.Pp
+.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-\*[Gt]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-\*[Gt]uio_resid
+bytes are copied.
+.Pp
+.Fn uiomove
+changes fields of the structure pointed to by
+.Fa uio ,
+such that
+.Va uio-\*[Gt]uio_resid
+is decremented by the amount of data moved,
+.Va uio-\*[Gt]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.
+.Sh RETURN VALUES
+Upon successful completion,
+.Fn uiomove
+returns 0.
+If a bad address is encountered,
+.Er EFAULT
+is returned.
+.Sh SEE ALSO
+.Xr copy 9 ,
+.Xr fetch 9 ,
+.Xr store 9