twalk.9p - plan9port - [fork] Plan 9 from user space
(HTM) git clone git://src.adamsgaard.dk/plan9port
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
twalk.9p (3924B)
---
1 .TH WALK 9P
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 (9P)).
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 .MR fcall (3) .
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 .I Fswalk
157 (see
158 .MR 9pclient (3) )
159 generates walk messages.
160 One or more walk messages may be generated by
161 any call that evaluates file names:
162 .IR fsopen ,
163 .IR fsopenfd ,
164 .IR fsdirstat ,
165 .IR fsdirwstat .
166 .\"
167 .\" A call to
168 .\" .IR chdir (2)
169 .\" causes a
170 .\" .BR walk .
171 .\" One or more
172 .\" .B walk
173 .\" messages may be generated by
174 .\" any of the following calls, which evaluate file names:
175 .\" .IR bind ,
176 .\" .IR create ,
177 .\" .IR exec ,
178 .\" .IR mount ,
179 .\" .IR open ,
180 .\" .IR remove ,
181 .\" .IR stat ,
182 .\" .IR unmount ,
183 .\" .IR wstat .
184 .\" The file name element
185 .\" .B .
186 .\" (dot) is interpreted locally and
187 .\" is not transmitted in
188 .\" .B walk
189 .\" messages.