walk 3.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178
  1. .TH WALK 5
  2. .SH NAME
  3. walk \- descend a directory hierarchy
  4. .SH SYNOPSIS
  5. .ta \w'\fLTwalk 'u
  6. .IR size [4]
  7. .B Twalk
  8. .IR tag [2]
  9. .IR fid [4]
  10. .IR newfid [4]
  11. .IR nwname [2]
  12. .IR nwname *( wname [ s ])
  13. .br
  14. .IR size [4]
  15. .B Rwalk
  16. .IR tag [2]
  17. .IR nwqid [2]
  18. .IR nwqid *( qid [13])
  19. .SH DESCRIPTION
  20. The
  21. .B walk
  22. request carries as arguments an existing
  23. .IR fid
  24. and a proposed
  25. .I newfid
  26. (which must not be in use unless it is the same as
  27. .IR fid )
  28. that the client wishes to associate with
  29. the result of traversing the directory hierarchy
  30. by `walking' the hierarchy using the successive path name
  31. elements
  32. .BR wname .
  33. The
  34. .I fid
  35. must represent a directory unless zero path name elements are specified.
  36. .PP
  37. The
  38. .I fid
  39. must be valid in the current session and must not have been opened for I/O
  40. by an
  41. .B open
  42. or
  43. .B create
  44. message.
  45. If the full sequence of
  46. .B nwname
  47. elements is walked successfully,
  48. .I newfid
  49. will represent the file that results.
  50. If not,
  51. .I newfid
  52. (and
  53. .BR fid )
  54. will be unaffected.
  55. However, if
  56. .I newfid
  57. is in use or otherwise illegal, an
  58. .B Rerror
  59. is returned.
  60. .PP
  61. The name
  62. .RB `` .. ''
  63. (dot-dot) represents the parent directory.
  64. The name
  65. .RB `` . ''
  66. (dot), meaning the current directory, is not used in the protocol.
  67. .PP
  68. It is legal for
  69. .B nwname
  70. to be zero, in which case
  71. .I newfid
  72. will represent the same file as
  73. .I fid
  74. and the
  75. .B walk
  76. will usually succeed; this is equivalent to walking to dot.
  77. The rest of this discussion assumes
  78. .B nwname
  79. is greater than zero.
  80. .PP
  81. The
  82. .B nwname
  83. path name elements
  84. .B wname
  85. are walked in order, ``elementwise''.
  86. For the first elementwise walk
  87. to succeed, the file identified by
  88. .I fid
  89. must be a directory,
  90. and the implied user of the request must have permission
  91. to search the directory (see
  92. .IR intro (5)).
  93. Subsequent elementwise walks have equivalent restrictions
  94. applied to the implicit fid that results from the preceding elementwise walk.
  95. .PP
  96. If the first element cannot be walked for any reason,
  97. .B Rerror
  98. is returned.
  99. Otherwise, the walk will return an
  100. .B Rwalk
  101. message containing
  102. .I nwqid
  103. qids corresponding, in order, to the files that are visited by the
  104. .I nwqid
  105. successful elementwise walks;
  106. .I nwqid
  107. is therefore either
  108. .B nwname
  109. or the index of the first elementwise walk that failed.
  110. The value of
  111. .I nwqid
  112. cannot be zero unless
  113. .B nwname
  114. is zero.
  115. Also,
  116. .I nwqid
  117. will always be less than or equal to
  118. .BR nwname .
  119. Only if it is equal, however, will
  120. .I newfid
  121. be affected, in which case
  122. .I newfid
  123. will represent the file
  124. reached by the final elementwise walk requested in the message.
  125. .PP
  126. A
  127. .B walk
  128. of the name
  129. .RB `` .. ''
  130. in the root directory of a server is equivalent to a walk with no name elements.
  131. .PP
  132. If
  133. .I newfid
  134. is the same as
  135. .IR fid ,
  136. the above discussion applies, with the obvious difference
  137. that if the walk changes the state of
  138. .IR newfid ,
  139. it also changes the state of
  140. .IR fid ;
  141. and if
  142. .I newfid
  143. is unaffected, then
  144. .I fid
  145. is also unaffected.
  146. .PP
  147. To simplify the implementation of the servers, a maximum of sixteen name elements or qids
  148. may be packed in a single message.
  149. This constant is called
  150. .B MAXWELEM
  151. in
  152. .IR fcall (2).
  153. Despite this restriction, the system imposes no limit on the number of elements in a file name,
  154. only the number that may be transmitted in a single message.
  155. .SH ENTRY POINTS
  156. A call to
  157. .IR chdir (2)
  158. causes a
  159. .BR walk .
  160. One or more
  161. .B walk
  162. messages may be generated by
  163. any of the following calls, which evaluate file names:
  164. .IR bind ,
  165. .IR create ,
  166. .IR exec ,
  167. .IR mount ,
  168. .IR open ,
  169. .IR remove ,
  170. .IR stat ,
  171. .IR unmount ,
  172. .IR wstat .
  173. The file name element
  174. .B .
  175. (dot) is interpreted locally and
  176. is not transmitted in
  177. .B walk
  178. messages.