harvey/sys/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 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.
.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:
.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.