1.\" 2.\" Copyright (c) 1997 Joerg Wunsch 3.\" 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 17.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 18.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 19.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 20.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 21.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 22.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 23.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 24.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25.\" 26.\" $FreeBSD: src/share/man/man9/uio.9,v 1.5.2.4 2001/12/17 11:30:19 ru Exp $ 27.\" $DragonFly: src/share/man/man9/uio.9,v 1.6 2008/11/10 22:59:00 swildner Exp $ 28.\" 29.Dd November 10, 2008 30.Os 31.Dt UIO 9 32.Sh NAME 33.Nm uio , 34.Nm uiomove 35.Nd device driver I/O routines 36.Sh SYNOPSIS 37.In sys/types.h 38.In sys/uio.h 39.Bd -literal 40struct uio { 41 struct iovec *uio_iov; 42 int uio_iovcnt; 43 off_t uio_offset; 44 size_t uio_resid; 45 enum uio_seg uio_segflg; 46 enum uio_rw uio_rw; 47 struct thread *uio_td; 48}; 49.Ed 50.Ft int 51.Fn uiomove "caddr_t buf" "int howmuch" "struct uio *uiop" 52.Sh DESCRIPTION 53The function 54.Fn uiomove 55is used to handle transfer of data between buffers and I/O vectors 56that might possibly also cross the user/kernel space boundary. 57.Pp 58As a result of any 59.Xr read 2 , 60.Xr write 2 , 61.Xr readv 2 , 62or 63.Xr writev 2 64system call that is being passed to a character-device driver, the 65appropriate driver 66.Nm d_read 67or 68.Nm d_write 69entry will be called with a pointer to a 70.Vt "struct dev_read_args" 71or 72.Vt "struct dev_write_args" 73being passed, 74a member of which is a pointer to a 75.Vt "struct uio" . 76The transfer request is encoded in this structure. 77The driver itself should use 78.Fn uiomove 79to get at the data in this structure. 80.Pp 81The fields in the 82.Vt uio 83structure are: 84.Bl -tag -width ".Va uio_iovcnt" 85.It Va uio_iov 86The array of I/O vectors to be processed. 87In the case of scatter/gather 88I/O, this will be more than one vector. 89.It Va uio_iovcnt 90The number of I/O vectors present. 91.It Va uio_offset 92The offset into the device. 93.It Va uio_resid 94The number of bytes to process. 95.It Va uio_segflg 96One of the following flags: 97.Bl -tag -width ".Dv UIO_USERSPACE" 98.It Dv UIO_USERSPACE 99The I/O vector points into a process's address space. 100.It Dv UIO_SYSSPACE 101The I/O vector points into the kernel address space. 102.It Dv UIO_NOCOPY 103Don't copy, already in object. 104.El 105.It Va uio_rw 106The direction of the desired transfer, either 107.Dv UIO_READ , 108or 109.Dv UIO_WRITE . 110.It Va uio_td 111The pointer to a 112.Vt "struct thread" 113for the associated thread; used if 114.Va uio_segflg 115indicates that the transfer is to be made from/to a process's address 116space. 117.El 118.Sh RETURN VALUES 119.Fn uiomove 120can return 121.Er EFAULT 122from the invoked 123.Xr copyin 9 124or 125.Xr copyout 9 126in case the transfer was to/from a process's address space. 127.Sh EXAMPLES 128The idea is that the driver maintains a private buffer for its data, 129and processes the request in chunks of maximal the size of this 130buffer. 131Note that the buffer handling below is very simplified and 132won't work (the buffer pointer is not being advanced in case of a 133partial read), it's just here to demonstrate the 134.Nm 135handling. 136.Bd -literal 137/* MIN() can be found there: */ 138#include <sys/param.h> 139 140#define BUFSIZE 512 141static char buffer[BUFSIZE]; 142 143static int data_available; /* amount of data that can be read */ 144 145static int 146fooread(struct dev_read_args *ap) 147{ 148 cdev_t dev = ap->a_head.a_dev; 149 int rv, amnt; 150 151 while (ap->a_uio->uio_resid > 0) { 152 if (data_available > 0) { 153 amnt = MIN(ap->a_uio->uio_resid, data_available); 154 if ((rv = uiomove((caddr_t)buffer, amnt, ap->a_uio)) 155 != 0) 156 goto error; 157 data_available -= amnt; 158 } else { 159 tsleep(...); /* wait for a better time */ 160 } 161 } 162 return 0; 163error: 164 /* do error cleanup here */ 165 return rv; 166} 167.Ed 168.Sh SEE ALSO 169.Xr read 2 , 170.Xr readv 2 , 171.Xr write 2 , 172.Xr writev 2 , 173.Xr copyin 9 , 174.Xr copyout 9 , 175.Xr physio 9 , 176.Xr sleep 9 177.Sh HISTORY 178The 179.Nm 180mechanism appeared in some early version of 181.Ux . 182.Sh AUTHORS 183This man page was written by 184.An J\(:org Wunsch . 185