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
  46 The
  47 .Fn physio
  48 is a helper function typically called from character device
  49 .Fn read
  50 and
  51 .Fn write
  52 routines to start I/O on a user process buffer.
  53 The maximum amount of data to transfer with each call
  54 is determined by
  55 .Fa dev->si_iosize_max .
  56 The
  57 .Fn physio
  58 call converts the I/O request into a
  59 .Fn strategy
  60 request and passes the new request to the driver's
  61 .Fn strategy
  62 routine for processing.
  63 .Pp
  64 Since
  65 .Fa uio
  66 normally describes user space addresses,
  67 .Fn physio
  68 needs to lock those pages into memory.
  69 This is done by calling
  70 .Fn vmapbuf
  71 for the appropriate pages.
  72 .Fn physio
  73 always awaits the completion of the entire requested transfer before
  74 returning, unless an error condition is detected earlier.
  75 .Pp
  76 A break-down of the arguments follows:
  77 .Bl -tag -width indent
  78 .It Fa dev
  79 The device number identifying the device to interact with.
  80 .It Fa uio
  81 The description of the entire transfer as requested by the user process.
  82 Currently, the results of passing a
  83 .Fa uio
  84 structure with the
  85 .Va uio_segflg
  86 set to anything other than
  87 .Dv UIO_USERSPACE
  88 are undefined.
  89 .It Fa ioflag
  90 The ioflag argument from the
  91 .Fn read
  92 or
  93 .Fn write
  94 function calling
  95 .Fn physio .
  96 .El
  97 .Sh RETURN VALUES
  98 If successful
  99 .Fn physio
 100 returns 0.
 101 .Er EFAULT
 102 is returned if the address range described by
 103 .Fa uio
 104 is not accessible by the requesting process.
 105 .Fn physio
 106 will return any error resulting from calls to the device strategy routine,
 107 by examining the
 108 .Dv B_ERROR
 109 buffer flag and the
 110 .Va b_error
 111 field.
 112 Note that the actual transfer size may be less than requested by
 113 .Fa uio
 114 if the device signals an
 115 .Dq "end of file"
 116 condition.
 117 .Sh SEE ALSO
 118 .Xr read 2 ,
 119 .Xr write 2
 120 .Sh HISTORY
 121 The
 122 .Nm
 123 manual page is originally from
 124 .Nx
 125 with minor changes for applicability with
 126 .Fx .
 127 .Pp
 128 The
 129 .Nm
 130 call has been completely re-written for providing higher
 131 I/O and paging performance.