/share/man/man9/vnode.9

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

  1. .\" Copyright (c) 1996 Doug Rabson
  2. .\"
  3. .\" All rights reserved.
  4. .\"
  5. .\" This program is free software.
  6. .\"
  7. .\" Redistribution and use in source and binary forms, with or without
  8. .\" modification, are permitted provided that the following conditions
  9. .\" are met:
  10. .\" 1. Redistributions of source code must retain the above copyright
  11. .\" notice, this list of conditions and the following disclaimer.
  12. .\" 2. Redistributions in binary form must reproduce the above copyright
  13. .\" notice, this list of conditions and the following disclaimer in the
  14. .\" documentation and/or other materials provided with the distribution.
  15. .\"
  16. .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
  17. .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  18. .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  19. .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
  20. .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  21. .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  22. .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  23. .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  24. .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  25. .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26. .\"
  27. .\" $FreeBSD$
  28. .\"
  29. .Dd February 13, 2010
  30. .Dt VNODE 9
  31. .Os
  32. .Sh NAME
  33. .Nm vnode
  34. .Nd internal representation of a file or directory
  35. .Sh SYNOPSIS
  36. .In sys/param.h
  37. .In sys/vnode.h
  38. .Sh DESCRIPTION
  39. The vnode is the focus of all file activity in
  40. .Ux .
  41. A vnode is described by
  42. .Vt "struct vnode" .
  43. There is a
  44. unique vnode allocated for each active file, each current directory,
  45. each mounted-on file, text file, and the root.
  46. .Pp
  47. Each vnode has three reference counts,
  48. .Va v_usecount ,
  49. .Va v_holdcnt
  50. and
  51. .Va v_writecount .
  52. The first is the number of clients within the kernel which are
  53. using this vnode.
  54. This count is maintained by
  55. .Xr vref 9 ,
  56. .Xr vrele 9
  57. and
  58. .Xr vput 9 .
  59. The second is the number of clients within the kernel who veto
  60. the recycling of this vnode.
  61. This count is
  62. maintained by
  63. .Xr vhold 9
  64. and
  65. .Xr vdrop 9 .
  66. When both the
  67. .Va v_usecount
  68. and the
  69. .Va v_holdcnt
  70. of a vnode reaches zero then the vnode will be put on the freelist
  71. and may be reused for another file, possibly in another file system.
  72. The transition to and from the freelist is handled by
  73. .Xr getnewvnode 9 ,
  74. .Xr vfree 9
  75. and
  76. .Xr vbusy 9 .
  77. The third is a count of the number of clients which are writing into
  78. the file.
  79. It is maintained by the
  80. .Xr open 2
  81. and
  82. .Xr close 2
  83. system calls.
  84. .Pp
  85. Any call which returns a vnode (e.g.\&
  86. .Xr vget 9 ,
  87. .Xr VOP_LOOKUP 9
  88. etc.)
  89. will increase the
  90. .Va v_usecount
  91. of the vnode by one.
  92. When the caller is finished with the vnode, it
  93. should release this reference by calling
  94. .Xr vrele 9
  95. (or
  96. .Xr vput 9
  97. if the vnode is locked).
  98. .Pp
  99. Other commonly used members of the vnode structure are
  100. .Va v_id
  101. which is used to maintain consistency in the name cache,
  102. .Va v_mount
  103. which points at the file system which owns the vnode,
  104. .Va v_type
  105. which contains the type of object the vnode represents and
  106. .Va v_data
  107. which is used by file systems to store file system specific data with
  108. the vnode.
  109. The
  110. .Va v_op
  111. field is used by the
  112. .Dv VOP_*
  113. macros to call functions in the file system which implement the vnode's
  114. functionality.
  115. .Sh VNODE TYPES
  116. .Bl -tag -width VSOCK
  117. .It Dv VNON
  118. No type.
  119. .It Dv VREG
  120. A regular file; may be with or without VM object backing.
  121. If you want to make sure this get a backing object, call
  122. .Fn vnode_create_vobject .
  123. .It Dv VDIR
  124. A directory.
  125. .It Dv VBLK
  126. A block device; may be with or without VM object backing.
  127. If you want to make sure this get a backing object, call
  128. .Fn vnode_create_vobject .
  129. .It Dv VCHR
  130. A character device.
  131. .It Dv VLNK
  132. A symbolic link.
  133. .It Dv VSOCK
  134. A socket.
  135. Advisory locking will not work on this.
  136. .It Dv VFIFO
  137. A FIFO (named pipe).
  138. Advisory locking will not work on this.
  139. .It Dv VBAD
  140. Indicates that the vnode has been reclaimed.
  141. .El
  142. .Sh IMPLEMENTATION NOTES
  143. VFIFO uses the "struct fileops" from
  144. .Pa /sys/kern/sys_pipe.c .
  145. VSOCK uses the "struct fileops" from
  146. .Pa /sys/kern/sys_socket.c .
  147. Everything else uses the one from
  148. .Pa /sys/kern/vfs_vnops.c .
  149. .Pp
  150. The VFIFO/VSOCK code, which is why "struct fileops" is used at all, is
  151. an artifact of an incomplete integration of the VFS code into the
  152. kernel.
  153. .Pp
  154. Calls to
  155. .Xr malloc 9
  156. or
  157. .Xr free 9
  158. when holding a
  159. .Nm
  160. interlock, will cause a LOR (Lock Order Reversal) due to the
  161. intertwining of VM Objects and Vnodes.
  162. .Sh SEE ALSO
  163. .Xr malloc 9 ,
  164. .Xr VOP_ACCESS 9 ,
  165. .Xr VOP_ACLCHECK 9 ,
  166. .Xr VOP_ADVLOCK 9 ,
  167. .Xr VOP_ATTRIB 9 ,
  168. .Xr VOP_BWRITE 9 ,
  169. .Xr VOP_CREATE 9 ,
  170. .Xr VOP_FSYNC 9 ,
  171. .Xr VOP_GETACL 9 ,
  172. .Xr VOP_GETEXTATTR 9 ,
  173. .Xr VOP_GETPAGES 9 ,
  174. .Xr VOP_GETVOBJECT 9 ,
  175. .Xr VOP_INACTIVE 9 ,
  176. .Xr VOP_IOCTL 9 ,
  177. .Xr VOP_LINK 9 ,
  178. .Xr VOP_LISTEXTATTR 9 ,
  179. .Xr VOP_LOCK 9 ,
  180. .Xr VOP_LOOKUP 9 ,
  181. .Xr VOP_OPENCLOSE 9 ,
  182. .Xr VOP_PATHCONF 9 ,
  183. .Xr VOP_PRINT 9 ,
  184. .Xr VOP_RDWR 9 ,
  185. .Xr VOP_READDIR 9 ,
  186. .Xr VOP_READLINK 9 ,
  187. .Xr VOP_REALLOCBLKS 9 ,
  188. .Xr VOP_REMOVE 9 ,
  189. .Xr VOP_RENAME 9 ,
  190. .Xr VOP_REVOKE 9 ,
  191. .Xr VOP_SETACL 9 ,
  192. .Xr VOP_SETEXTATTR 9 ,
  193. .Xr VOP_STRATEGY 9 ,
  194. .Xr VOP_VPTOCNP 9 ,
  195. .Xr VOP_VPTOFH 9 ,
  196. .Xr VFS 9
  197. .Sh AUTHORS
  198. This manual page was written by
  199. .An Doug Rabson .