xref: /freebsd/share/man/man9/uio.9 (revision 7f3dea244c40159a41ab22da77a434d7c5b5e85a)
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$
27.\" "
28.Dd February 2, 1997
29.Os
30.Dt UIO 9
31.Sh NAME
32.Nm uio ,
33.Nm uiomove
34.Nd device driver IO routines
35.Sh SYNOPSIS
36.Fd #include <sys/types.h>
37.Fd #include <sys/uio.h>
38.Pp
39.Bd -literal
40struct uio {
41	struct	iovec *uio_iov;
42	int	uio_iovcnt;
43	off_t	uio_offset;
44	int	uio_resid;
45	enum	uio_seg uio_segflg;
46	enum	uio_rw uio_rw;
47	struct	proc *uio_procp;
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 IO 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.Em read
67or
68.Em write
69entry will be called with a pointer to a
70.Fa "struct uio"
71being passed.  The transfer request is encoded in this structure.
72The driver itself should use
73.Fn uiomove
74to get at the data in this structure.
75.Pp
76The fields in the uio structure are:
77.Bl -tag -width "uio_iovcntXXXX" -compact
78.It Dv uio_iov
79The array of IO vectors to be processed.  In the case of scatter/gather
80IO, this will be more than one vector.
81.It Dv uio_iovcnt
82The number of IO vectors present.
83.It Dv uio_offset
84The offset into the device.
85.It Dv uio_resid
86The number of bytes to process.
87.It Dv uio_segflg
88One of the following flags:
89.Bl -tag -width "UIO_USERISPACEX" -compact
90.It Dv UIO_USERSPACE
91The IO vector points into a process's address space.
92.It Dv UIO_SYSSPACE
93The IO vector points into the kernel address space.
94.It Dv UIO_USERISPACE
95The IO vector points into the instruction area of a process's address
96space.
97.It Dv UIO_NOCOPY
98Don't copy, already in object.
99.El
100.It Dv uio_rw uio_rw
101The direction of the desired transfer, either
102.Dv UIO_READ ,
103or
104.Dv UIO_WRITE .
105.It Dv uio_procp
106The pointer to a
107.Li struct proc
108for the associated process; used if
109.Dv uio_segflg
110indicates that the transfer is to be made from/to a process's address
111space.
112.El
113.Sh EXAMPLES
114The idea is that the driver maintains a private buffer for its data,
115and processes the request in chunks of maximal the size of this
116buffer.  Note that the buffer handling below is very simplified and
117won't work (the buffer pointer is not being advanced in case of a
118partial read), it's just here to demonstrate the uio handling.
119.Bd -literal
120/* MIN() can be found there: */
121#include <sys/param.h>
122
123#define BUFSIZE 512
124static char buffer[BUFSIZE];
125
126static int data_available;	/* amount of data that can be read */
127
128static int
129fooread(dev_t dev, struct uio *uio, int flag)
130{
131	int rv, amnt;
132
133	while (uio->uio_resid > 0) {
134		if (data_available > 0) {
135			amnt = MIN(uio->uio_resid, data_available);
136			if ((rv = uiomove((caddr_t)buffer, amnt, uio))
137			    != 0)
138				goto error;
139			data_available -= amnt;
140		} else {
141			tsleep(...);	/* wait for a better time */
142		}
143	}
144	return 0;
145error:
146	/* do error cleanup here */
147	return rv;
148}
149
150.Ed
151.Sh RETURN VALUES
152.Fn uiomove
153can return
154.Er EFAULT
155from the invoked
156.Xr copyin 9
157or
158.Xr copyout 9
159in case the transfer was to/from a process's address space.
160.Sh SEE ALSO
161.Xr read 2 ,
162.Xr readv 2 ,
163.Xr write 2 ,
164.Xr writev 2 ,
165.Xr copyin 9 ,
166.Xr copyout 9 ,
167.Xr sleep 9
168.Sh HISTORY
169The uio mechanism appeared in some early version of
170.Ux .
171.Sh AUTHORS
172This man page has been written by
173.ie t J\(:org Wunsch.
174.el Joerg Wunsch.
175