178 lines
3.5 KiB
Text
178 lines
3.5 KiB
Text
.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.
|