walk.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.