| .TH WALK 9P |
| .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 (9P)). |
| 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 fcall (3). |
| 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 |
| .I Fswalk |
| (see |
| .IR 9pclient (3)) |
| generates walk messages. |
| One or more walk messages may be generated by |
| any call that evaluates file names: |
| .IR fsopen , |
| .IR fsopenfd , |
| .IR fsdirstat , |
| .IR fsdirwstat . |
| .\" |
| .\" A call to |
| .\" .IR 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: |
| .\" .IR bind , |
| .\" .IR create , |
| .\" .IR exec , |
| .\" .IR mount , |
| .\" .IR open , |
| .\" .IR remove , |
| .\" .IR stat , |
| .\" .IR unmount , |
| .\" .IR wstat . |
| .\" The file name element |
| .\" .B . |
| .\" (dot) is interpreted locally and |
| .\" is not transmitted in |
| .\" .B walk |
| .\" messages. |