WALK(5)                                                   WALK(5)

          walk - descend a directory hierarchy

          size[4] Twalk tag[2] fid[4] newfid[4] nwname[2]
          size[4] Rwalk tag[2] nwqid[2] nwqid*(qid[13])

          The walk request carries as arguments an existing fid and a
          proposed newfid (which must not be in use unless it is the
          same as 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 wname.
          The fid must represent a directory unless zero path name
          elements are specified.

          The fid must be valid in the current session and must not
          have been opened for I/O by an open or create message.  If
          the full sequence of nwname elements is walked successfully,
          newfid will represent the file that results.  If not, newfid
          (and fid) will be unaffected.  However, if newfid is in use
          or otherwise illegal, an Rerror is returned.

          The name ``..''  (dot-dot) represents the parent directory.
          The name ``.''  (dot), meaning the current directory, is not
          used in the protocol.

          It is legal for nwname to be zero, in which case newfid will
          represent the same file as fid and the walk will usually
          succeed; this is equivalent to walking to dot.  The rest of
          this discussion assumes nwname is greater than zero.

          The nwname path name elements wname are walked in order,
          ``elementwise''.  For the first elementwise walk to succeed,
          the file identified by fid must be a directory, and the
          implied user of the request must have permission to search
          the directory (see intro(5)). Subsequent elementwise walks
          have equivalent restrictions applied to the implicit fid
          that results from the preceding elementwise walk.

          If the first element cannot be walked for any reason, Rerror
          is returned.  Otherwise, the walk will return an Rwalk mes-
          sage containing nwqid qids corresponding, in order, to the
          files that are visited by the nwqid successful elementwise
          walks; nwqid is therefore either nwname or the index of the
          first elementwise walk that failed.  The value of nwqid can-
          not be zero unless nwname is zero.  Also, nwqid will always
          be less than or equal to nwname.  Only if it is equal, how-
          ever, will newfid be affected, in which case newfid will

     Page 1                       Plan 9             (printed 7/23/24)

     WALK(5)                                                   WALK(5)

          represent the file reached by the final elementwise walk
          requested in the message.

          A walk of the name ``..''  in the root directory of a server
          is equivalent to a walk with no name elements.

          If newfid is the same as fid, the above discussion applies,
          with the obvious difference that if the walk changes the
          state of newfid, it also changes the state of fid; and if
          newfid is unaffected, then fid is also unaffected.

          To simplify the implementation of the servers, a maximum of
          sixteen name elements or qids may be packed in a single mes-
          sage.  This constant is called MAXWELEM in fcall(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.

          A call to chdir(2) causes a walk.  One or more walk messages
          may be generated by any of the following calls, which evalu-
          ate file names: bind, create, exec, mount, open, remove,
          stat, unmount, wstat. The file name element . (dot) is
          interpreted locally and is not transmitted in walk messages.

     Page 2                       Plan 9             (printed 7/23/24)