1 files changed, 186 insertions, 0 deletions
diff --git a/man/5/walk b/man/5/walk
new file mode 100644
index 00000000..135061ce
--- /dev/null
+++ b/man/5/walk
@@ -0,0 +1,186 @@
+.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 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)