/share/man/man9/physio.9

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 131 lines · 131 code · 0 blank · 0 comment · 0 complexity · e9a08c834b2d1da6b84dd12d8bf2872e MD5 · raw file

  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.