ref: df03eca7e7cbfadf1cf8c8c5a94390eaa5013a8b
dir: /man/5/walk/
.TH WALK 5 .SH NAME walk \- descend a directory hierarchy .SH SYNOPSIS .ta \w'\fLTwalk 'u .IR size [4] .B Twalk .IR tag [2] .IR fid [4] .IR newfid [4] .IR nwname [2] .IR nwname *( wname [ s ]) .br .IR size [4] .B Rwalk .IR tag [2] .IR nwqid [2] .IR nwqid *( qid [13]) .SH DESCRIPTION The .B walk request carries as arguments an existing .IR fid and a proposed .I newfid (which must not be in use unless it is the same as .IR fid ) that the client wishes to associate with the result of traversing the directory hierarchy by `walking' the hierarchy using the successive path name elements .BR wname . The .I fid must represent a directory unless zero path name elements are specified. .PP The .I fid must be valid in the current session and must not have been opened for I/O by an .B open or .B create message. If the full sequence of .B nwname elements is walked successfully, .I newfid will represent the file that results. If not, .I newfid (and .BR fid ) will be unaffected. However, if .I newfid is in use or otherwise illegal, an .B Rerror is returned. .PP The name .RB `` .. '' (dot-dot) represents the parent directory. The name .RB `` . '' (dot), meaning the current directory, is not used in the protocol. .PP It is legal for .B nwname to be zero, in which case .I newfid will represent the same file as .I fid and the .B walk will usually succeed; this is equivalent to walking to dot. The rest of this discussion assumes .B nwname is greater than zero. .PP The .B nwname path name elements .B wname are walked in order, ``elementwise''. For the first elementwise walk to succeed, the file identified by .I fid must be a directory, and the implied user of the request must have permission to search the directory (see .IR intro (5)). Subsequent elementwise walks have equivalent restrictions applied to the implicit fid that results from the preceding elementwise walk. .PP If the first element cannot be walked for any reason, .B Rerror is returned. Otherwise, the walk will return an .B Rwalk message containing .I nwqid qids corresponding, in order, to the files that are visited by the .I nwqid successful elementwise walks; .I nwqid is therefore either .B nwname or the index of the first elementwise walk that failed. The value of .I nwqid cannot be zero unless .B nwname is zero. Also, .I nwqid will always be less than or equal to .BR nwname . Only if it is equal, however, will .I newfid be affected, in which case .I newfid will represent the file reached by the final elementwise walk requested in the message. .PP A .B walk of the name .RB `` .. '' in the root directory of a server is equivalent to a walk with no name elements. .PP If .I newfid is the same as .IR fid , the above discussion applies, with the obvious difference that if the walk changes the state of .IR newfid , it also changes the state of .IR fid ; and if .I newfid is unaffected, then .I fid is also unaffected. .PP To simplify the implementation of the servers, a maximum of sixteen name elements or qids may be packed in a single message. This constant is called .B MAXWELEM in .IR styx (2) and .IR styx (10.2). Despite this restriction, the system imposes no limit on the number of elements in a file name, only the number that may be transmitted in a single message. .SH ENTRY POINTS A call to .IR sys-chdir (2) causes a .BR walk . One or more .B walk messages may be generated by any of the following calls, which evaluate file names: .BR bind , .BR create , .BR mount , .BR open , .BR remove , .BR stat , .BR unmount , .BR wstat . The file name element .B . (dot) is interpreted locally and is not transmitted in .B walk messages. .SH SEE ALSO .IR sys-bind (2), .IR sys-chdir (2), .IR sys-open (2), .IR sys-remove (2), .IR sys-stat (2), .IR intro (5)