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.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE 22.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.\" $FreeBSD$ 31.\" 32.Dd July 8, 2004 33.Dt PHYSIO 9 34.Os 35.Sh NAME 36.Nm physio 37.Nd initiate I/O on raw devices 38.Sh SYNOPSIS 39.In sys/param.h 40.In sys/systm.h 41.In sys/bio.h 42.In sys/buf.h 43.Ft int 44.Fn physio "dev_t dev" "struct uio *uio" "int ioflag" 45.Sh DESCRIPTION 46The 47.Fn physio 48is a helper function typically called from character device 49.Fn read 50and 51.Fn write 52routines to start I/O on a user process buffer. 53The maximum amount of data to transfer with each call 54is determined by 55.Fa dev->si_iosize_max . 56The 57.Fn physio 58call converts the I/O request into a 59.Fn strategy 60request and passes the new request to the driver's 61.Fn strategy 62routine for processing. 63.Pp 64Since 65.Fa uio 66normally describes user space addresses, 67.Fn physio 68needs to lock those pages into memory. 69This is done by calling 70.Fn vmapbuf 71for the appropriate pages. 72.Fn physio 73always awaits the completion of the entire requested transfer before 74returning, unless an error condition is detected earlier. 75.Pp 76A break-down of the arguments follows: 77.Bl -tag -width indent 78.It Fa dev 79The device number identifying the device to interact with. 80.It Fa uio 81The description of the entire transfer as requested by the user process. 82Currently, the results of passing a 83.Fa uio 84structure with the 85.Va uio_segflg 86set to anything other than 87.Dv UIO_USERSPACE 88are undefined. 89.It Fa ioflag 90The ioflag argument from the 91.Fn read 92or 93.Fn write 94function calling 95.Fn physio . 96.El 97.Sh RETURN VALUES 98If successful 99.Fn physio 100returns 0. 101.Er EFAULT 102is returned if the address range described by 103.Fa uio 104is not accessible by the requesting process. 105.Fn physio 106will return any error resulting from calls to the device strategy routine, 107by examining the 108.Dv B_ERROR 109buffer flag and the 110.Va b_error 111field. 112Note that the actual transfer size may be less than requested by 113.Fa uio 114if the device signals an 115.Dq "end of file" 116condition. 117.Sh SEE ALSO 118.Xr read 2 , 119.Xr write 2 120.Sh HISTORY 121The 122.Nm 123manual page is originally from 124.Nx 125with minor changes for applicability with 126.Fx . 127.Pp 128The 129.Nm 130call has been completely re-written for providing higher 131I/O and paging performance. 132