xref: /dragonfly/share/man/man9/physio.9 (revision 38a690d7)
1.\"	$NetBSD: physio.9,v 1.2 1996/11/11 00:05:12 lukem Exp $
2.\"
3.\" Copyright (c) 1996 The NetBSD Foundation, Inc.
4.\" All rights reserved.
5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Paul Kranenburg.
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright
13.\"    notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\"    notice, this list of conditions and the following disclaimer in the
16.\"    documentation and/or other materials provided with the distribution.
17.\" 3. All advertising materials mentioning features or use of this software
18.\"    must display the following acknowledgement:
19.\"        This product includes software developed by the NetBSD
20.\"        Foundation, Inc. and its contributors.
21.\" 4. Neither the name of The NetBSD Foundation nor the names of its
22.\"    contributors may be used to endorse or promote products derived
23.\"    from this software without specific prior written permission.
24.\"
25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
28.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
29.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
35.\" POSSIBILITY OF SUCH DAMAGE.
36.\"
37.\" $FreeBSD: src/share/man/man9/physio.9,v 1.6.2.4 2001/12/17 11:30:18 ru Exp $
38.\" $DragonFly: src/share/man/man9/physio.9,v 1.2 2003/06/17 04:37:01 dillon Exp $
39.\"
40.Dd June 15, 1996
41.Dt PHYSIO 9
42.Os
43.Sh NAME
44.Nm physio
45.Nd initiate I/O on raw devices
46.Sh SYNOPSIS
47.In sys/param.h
48.In sys/systm.h
49.In sys/buf.h
50.Ft int
51.Fn physio "dev_t dev" "struct uio *uio" "int ioflag"
52.Sh DESCRIPTION
53The
54.Fn physio
55is a helper function typically called from character device read and write
56routines to start I/O on a user process buffer.
57It calls back on the
58provided
59.Fa strategy
60routine one or more times to complete the transfer described by
61.Fa uio .
62The maximum amount of data to transfer with each call to
63.Fa strategy
64is determined by the
65.Fa minphys
66routine.
67Since
68.Fa uio
69normally describes user space addresses,
70.Fn physio
71needs to lock the process into memory.  This is done by setting the
72.Dv P_PHYSIO
73flag on the process.
74.Fn physio
75always awaits the completion of the entire requested transfer before
76returning, unless an error condition is detected earlier.
77In all cases,
78the buffer passed in
79.Fa bp
80is locked (marked as
81.Dq busy )
82for the duration of the entire transfer.
83.Pp
84A break-down of the arguments follows:
85.Bl -tag -width indent
86.It Fa strategy
87The device strategy routine to call for each chunk of data to initiate
88device I/O.
89.It Fa bp
90The buffer to use with the strategy routine.
91The buffer flags will have
92.Dv B_BUSY ,
93and
94.Dv B_PHYS
95set when passed to the strategy routine.
96If
97.Dv NULL ,
98a buffer is allocated from a system pool.
99.It Fa dev
100The device number identifying the device to interact with.
101.It Fa flags
102Direction of transfer; the only valid settings are
103.Dv B_READ
104or
105.Dv B_WRITE .
106.It Fa minphys
107A device specific routine called to determine the maximum transfer size
108that the device's strategy routine can handle.
109.It Fa uio
110The description of the entire transfer as requested by the user process.
111Currently, the results of passing a
112.Fa uio
113structure with the
114.Sq uio_segflg
115set to anything other than
116.Dv UIO_USERSPACE ,
117are undefined.
118.El
119.Sh RETURN VALUES
120If successful
121.Fn physio
122returns 0.
123.Er EFAULT
124is returned if the address range described by
125.Fa uio
126is not accessible by the requesting process.
127.Fn physio
128will return any error resulting from calls to the device strategy routine,
129by examining the
130.Dv B_ERROR
131buffer flag and the
132.Va b_error
133field.
134Note that the actual transfer size may be less than requested by
135.Fa uio
136if the device signals an
137.Dq end of file
138condition.
139.Sh SEE ALSO
140.Xr read 2 ,
141.Xr write 2
142