diff options
author | rsc <devnull@localhost> | 2005-01-03 06:40:20 +0000 |
---|---|---|
committer | rsc <devnull@localhost> | 2005-01-03 06:40:20 +0000 |
commit | 058b0118a52061ad57694c01fc8763b22b789c4d (patch) | |
tree | 6685f04dea5ed68edaa34998c976aed34c55fe94 /man/man9/walk.9p | |
parent | 2600337aa704efbeba8201e88147a764b4fd2b90 (diff) | |
download | plan9port-058b0118a52061ad57694c01fc8763b22b789c4d.tar.gz plan9port-058b0118a52061ad57694c01fc8763b22b789c4d.tar.bz2 plan9port-058b0118a52061ad57694c01fc8763b22b789c4d.zip |
Some man pages.
Diffstat (limited to 'man/man9/walk.9p')
-rw-r--r-- | man/man9/walk.9p | 189 |
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. |