/share/man/man9/physio.9

  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 January 19, 2012
 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 "struct cdev *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.