1 files changed, 189 insertions, 0 deletions
diff --git a/man/man9/walk.9p b/man/man9/walk.9p
new file mode 100644
index 00000000..49777f21
--- /dev/null
+++ b/man/man9/walk.9p
@@ -0,0 +1,189 @@
+.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.