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