10564b1175
groff 1.23.0 added .MR to its -man macro package. The NEWS file states
that the inclusion of the macro "was prompted by its introduction to
Plan 9 from User Space's troff in August 2020." From d32deab it seems
that the name for Plan 9 from User Space's implementation was suggested
by groff maintainer G. Brandon Robinson.
Not sure if the intention was to make these definitions compatible, but
it would be nice if they were.
Currently, Plan 9 from User Space's .MR expects its second argument to
be parenthesized. groff's .MR does not. This results in extra
parentheses appearing in manual references when viewing Plan 9 from User
Space's manual pages on a system using groff.
190 lines
3.8 KiB
Plaintext
190 lines
3.8 KiB
Plaintext
.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
|
|
.MR 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
|
|
.MR 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.
|