root/kern/include/uio.h

INCLUDED FROM

   1 /*
   2  * Copyright (c) 2000, 2001, 2002, 2003, 2004, 2005, 2008, 2009
   3  *      The President and Fellows of Harvard College.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  * 1. Redistributions of source code must retain the above copyright
   9  *    notice, this list of conditions and the following disclaimer.
  10  * 2. Redistributions in binary form must reproduce the above copyright
  11  *    notice, this list of conditions and the following disclaimer in the
  12  *    documentation and/or other materials provided with the distribution.
  13  * 3. Neither the name of the University nor the names of its contributors
  14  *    may be used to endorse or promote products derived from this software
  15  *    without specific prior written permission.
  16  *
  17  * THIS SOFTWARE IS PROVIDED BY THE UNIVERSITY AND CONTRIBUTORS ``AS IS'' AND
  18  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20  * ARE DISCLAIMED.  IN NO EVENT SHALL THE UNIVERSITY OR CONTRIBUTORS BE LIABLE
  21  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  23  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  24  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  25  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  26  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27  * SUCH DAMAGE.
  28  */
  30 #ifndef _UIO_H_
  31 #define _UIO_H_
  33 /*
  34  * Like BSD uio, but simplified a bit. (In BSD, there can be more than one
  35  * iovec in a uio.)
  36  *
  37  * struct iovec is in <kern/iovec.h>.
  38  */
  40 #include <kern/iovec.h>
  42 /* Direction. */
  43 enum uio_rw {
UIO_READ,                       /* From kernel to uio_seg */
UIO_WRITE,                      /* From uio_seg to kernel */
  46 };
  48 /* Source/destination. */
  49 enum uio_seg {
UIO_USERISPACE,                 /* User process code. */
UIO_USERSPACE,                  /* User process data. */
UIO_SYSSPACE,                   /* Kernel. */
  53 };
  55 struct uio {
  56         struct iovec     *uio_iov;      /* Data blocks */
  57         unsigned          uio_iovcnt;   /* Number of iovecs */
off_t             uio_offset;   /* Desired offset into object */
size_t            uio_resid;    /* Remaining amt of data to xfer */
  60         enum uio_seg      uio_segflg;   /* What kind of pointer we have */
  61         enum uio_rw       uio_rw;       /* Whether op is a read or write */
  62         struct addrspace *uio_space;    /* Address space for user pointer */
  63 };
  66 /*
  67  * Copy data from a kernel buffer to a data region defined by a uio struct,
  68  * updating the uio struct's offset and resid fields. May alter the iovec
  69  * fields as well.
  70  *
  71  * Before calling this, you should
  72  *   (1) set up uio_iov to point to the buffer(s) you want to transfer
  73  *       to, and set uio_iovcnt to the number of such buffers;
  74  *   (2) initialize uio_offset as desired;
  75  *   (3) initialize uio_resid to the total amount of data that can be 
  76  *       transferred through this uio;
  77  *   (4) set up uio_seg and uio_rw correctly;
  78  *   (5) if uio_seg is UIO_SYSSPACE, set uio_space to NULL; otherwise,
  79  *       initialize uio_space to the address space in which the buffer
  80  *       should be found.
  81  *
  82  * After calling, 
  83  *   (1) the contents of uio_iov and uio_iovcnt may be altered and
  84  *       should not be interpreted;
  85  *   (2) uio_offset will have been incremented by the amount transferred;
  86  *   (3) uio_resid will have been decremented by the amount transferred;
  87  *   (4) uio_segflg, uio_rw, and uio_space will be unchanged.
  88  *
  89  * uiomove() may be called repeatedly on the same uio to transfer
  90  * additional data until the available buffer space the uio refers to
  91  * is exhausted.
  92  *
  93  * Note that the actual value of uio_offset is not interpreted. It is
  94  * provided to allow for easier file seek pointer management.
  95  *
  96  * When uiomove is called, the address space presently in context must
  97  * be the same as the one recorded in uio_space. This is an important
  98  * sanity check if I/O has been queued.
  99  */
 100 int uiomove(void *kbuffer, size_t len, struct uio *uio);
 102 /*
 103  * Like uiomove, but sends zeros.
 104  */
 105 int uiomovezeros(size_t len, struct uio *uio);
 107 /*
 108  * Initialize a uio suitable for I/O from a kernel buffer.
 109  *
 110  * Usage example;
 111  *      char buf[128];
 112  *      struct iovec iov;
 113  *      struct uio myuio;
 114  *
 115  *      uio_kinit(&iov, &myuio, buf, sizeof(buf), 0, UIO_READ);
 116  *      result = VOP_READ(vn, &myuio);
 117  *      ...
 118  */
 119 void uio_kinit(struct iovec *, struct uio *,
 120                void *kbuf, size_t len, off_t pos, enum uio_rw rw);
 123 #endif /* _UIO_H_ */