Subversion Repositories planix.SVN

.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.