o5r/plan9port
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Some man pages.

Browse source
This commit is contained in:
rsc 2005-01-03 06:40:20 +00:00
parent 2600337aa7
commit 058b0118a5
214 changed files with 17112 additions and 1999 deletions
Download patch file Download diff file Expand all files Collapse all files

630
man/man9/0intro.9p Normal file
View file

@ -0,0 +1,630 @@
.TH INTRO 9P
.SH NAME
intro \- introduction to the Plan 9 File Protocol, 9P
.SH SYNOPSIS
.B #include <fcall.h>
.SH DESCRIPTION
A Plan 9
.I server
is an agent that provides one or more hierarchical file systems
\(em file trees \(em
that may be accessed by Plan 9 processes.
A server responds to requests by
.I clients
to navigate the hierarchy,
and to create, remove, read, and write files.
The prototypical server is a separate machine that stores
large numbers of user files on permanent media;
such a machine is called, somewhat confusingly, a
.I file
.IR server .
Another possibility for a server is to synthesize
files on demand, perhaps based on information on data structures
maintained in memory; the
.IR plumber (4)
server is an example of such a server.
.PP
A
.I connection
to a server is a bidirectional communication path from the client to the server.
There may be a single client or
multiple clients sharing the same connection.
.PP
The
.IR "Plan 9 File Protocol" ,
9P, is used for messages between
.I clients
and
.IR servers .
A client transmits
.I requests
.RI ( T-messages )
to a server, which
subsequently returns
.I replies
.RI ( R-messages )
to the client.
The combined acts of transmitting (receiving) a request of a particular type,
and receiving (transmitting)
its reply is called a
.I transaction
of that type.
.PP
Each message consists of a sequence of bytes.
Two-, four-, and eight-byte fields hold unsigned
integers represented in little-endian order
(least significant byte first).
Data items of larger or variable lengths are represented
by a two-byte field specifying a count,
.IR n ,
followed by
.I n
bytes of data.
Text strings are represented this way,
with the text itself stored as a UTF-8
encoded sequence of Unicode characters (see
.IR utf (7)).
Text strings in 9P messages are not
.SM NUL\c
-terminated:
.I n
counts the bytes of UTF-8 data, which include no final zero byte.
The
.SM NUL
character is illegal in all text strings in 9P, and is therefore
excluded from file names, user names, and so on.
.PP
Each 9P message begins with a four-byte size field
specifying the length in bytes of the complete message including
the four bytes of the size field itself.
The next byte is the message type, one of the constants
in the enumeration in the include file
.BR <fcall.h> .
The next two bytes are an identifying
.IR tag ,
described below.
The remaining bytes are parameters of different sizes.
In the message descriptions, the number of bytes in a field
is given in brackets after the field name.
The notation
.IR parameter [ n ]
where
.I n
is not a constant represents a variable-length parameter:
.IR n [2]
followed by
.I n
bytes of data forming the
.IR parameter .
The notation
.IR string [ s ]
(using a literal
.I s
character)
is shorthand for
.IR s [2]
followed by
.I s
bytes of UTF-8 text.
(Systems may choose to reduce the set of legal characters
to reduce syntactic problems,
for example to remove slashes from name components,
but the protocol has no such restriction.
Plan 9 names may contain any printable character (that is, any character
outside hexadecimal 00-1F and 80-9F)
except slash.)
Messages are transported in byte form to allow for machine independence;
.IR fcall (3)
describes routines that convert to and from this form into a machine-dependent
C structure.
.SH MESSAGES
.ta \w'\fLTsession 'u
.IP
.ne 2v
.IR size [4]
.B Tversion
.IR tag [2]
.IR msize [4]
.IR version [ s ]
.br
.IR size [4]
.B Rversion
.IR tag [2]
.IR msize [4]
.IR version [ s ]
.IP
.ne 2v
.IR size [4]
.B Tauth
.IR tag [2]
.IR afid [4]
.IR uname [ s ]
.IR aname [ s ]
.br
.br
.IR size [4]
.B Rauth
.IR tag [2]
.IR aqid [13]
.IP
.ne 2v
.IR size [4]
.B Rerror
.IR tag [2]
.IR ename [ s ]
.IP
.ne 2v
.IR size [4]
.B Tflush
.IR tag [2]
.IR oldtag [2]
.br
.IR size [4]
.B Rflush
.IR tag [2]
.IP
.ne 2v
.IR size [4]
.B Tattach
.IR tag [2]
.IR fid [4]
.IR afid [4]
.IR uname [ s ]
.IR aname [ s ]
.br
.IR size [4]
.B Rattach
.IR tag [2]
.IR qid [13]
.IP
.ne 2v
.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 *( wqid [13])
.IP
.ne 2v
.IR size [4]
.B Topen
.IR tag [2]
.IR fid [4]
.IR mode [1]
.br
.IR size [4]
.B Ropen
.IR tag [2]
.IR qid [13]
.IR iounit [4]
.IP
.ne 2v
.IR size [4]
.B Topenfd
.IR tag [2]
.IR fid [4]
.IR mode [1]
.br
.IR size [4]
.B Ropenfd
.IR tag [2]
.IR qid [13]
.IR iounit [4]
.IR unixfd [4]
.IP
.ne 2v
.IR size [4]
.B Tcreate
.IR tag [2]
.IR fid [4]
.IR name [ s ]
.IR perm [4]
.IR mode [1]
.br
.IR size [4]
.B Rcreate
.IR tag [2]
.IR qid [13]
.IR iounit [4]
.IP
.ne 2v
.IR size [4]
.B Tread
.IR tag [2]
.IR fid [4]
.IR offset [8]
.IR count [4]
.br
.IR size [4]
.B Rread
.IR tag [2]
.IR count [4]
.IR data [ count ]
.IP
.ne 2v
.IR size [4]
.B Twrite
.IR tag [2]
.IR fid [4]
.IR offset [8]
.IR count [4]
.IR data [ count ]
.br
.IR size [4]
.B Rwrite
.IR tag [2]
.IR count [4]
.IP
.ne 2v
.IR size [4]
.B Tclunk
.IR tag [2]
.IR fid [4]
.br
.IR size [4]
.B Rclunk
.IR tag [2]
.IP
.ne 2v
.IR size [4]
.B Tremove
.IR tag [2]
.IR fid [4]
.br
.IR size [4]
.B Rremove
.IR tag [2]
.IP
.ne 2v
.IR size [4]
.B Tstat
.IR tag [2]
.IR fid [4]
.br
.IR size [4]
.B Rstat
.IR tag [2]
.IR stat [ n ]
.IP
.ne 2v
.IR size [4]
.B Twstat
.IR tag [2]
.IR fid [4]
.IR stat [ n ]
.br
.IR size [4]
.B Rwstat
.IR tag [2]
.PP
Each T-message has a
.I tag
field, chosen and used by the client to identify the message.
The reply to the message will have the same tag.
Clients must arrange that no two outstanding messages
on the same connection have the same tag.
An exception is the tag
.BR NOTAG ,
defined as
.B (ushort)~0
in
.BR <fcall.h> :
the client can use it, when establishing a connection,
to
override tag matching in
.B version
messages.
.PP
The type of an R-message will either be one greater than the type
of the corresponding T-message or
.BR Rerror ,
indicating that the request failed.
In the latter case, the
.I ename
field contains a string describing the reason for failure.
.PP
The
.B version
message identifies the version of the protocol and indicates
the maximum message size the system is prepared to handle.
It also initializes the connection and
aborts all outstanding I/O on the connection.
The set of messages between
.B version
requests is called a
.IR session .
.PP
Most T-messages contain a
.IR fid ,
a 32-bit unsigned integer that the client uses to identify
a ``current file'' on the server.
Fids are somewhat like file descriptors in a user process,
but they are not restricted to files open for I/O:
directories being examined, files being accessed by
.IR stat (3)
calls, and so on \(em all files being manipulated by the operating
system \(em are identified by fids.
Fids are chosen by the client.
All requests on a connection share the same fid space;
when several clients share a connection,
the agent managing the sharing must arrange
that no two clients choose the same fid.
.PP
The fid supplied in an
.B attach
message
will be taken by the server to refer to the root of the served file tree.
The
.B attach
identifies the user
to the server and may specify a particular file tree served
by the server (for those that supply more than one).
.PP
Permission to attach to the service is proven by providing a special fid, called
.BR afid ,
in the
.B attach
message. This
.B afid
is established by exchanging
.B auth
messages and subsequently manipulated using
.B read
and
.B write
messages to exchange authentication information not defined explicitly by 9P.
Once the authentication protocol is complete, the
.B afid
is presented in the
.B attach
to permit the user to access the service.
.PP
A
.B walk
message causes the server to change the current file associated
with a fid to be a file in the directory that is the old current file, or one of
its subdirectories.
.B Walk
returns a new fid that refers to the resulting file.
Usually, a client maintains a fid for the root,
and navigates by
.B walks
from the root fid.
.PP
A client can send multiple T-messages without waiting for the corresponding
R-messages, but all outstanding T-messages must specify different tags.
The server may delay the response to a request
and respond to later ones;
this is sometimes necessary, for example when the client reads
from a file that the server synthesizes from external events
such as keyboard characters.
.PP
Replies (R-messages) to
.BR auth ,
.BR attach ,
.BR walk ,
.BR open ,
and
.B create
requests convey a
.I qid
field back to the client.
The qid represents the server's unique identification for the
file being accessed:
two files on the same server hierarchy are the same if and only if their qids
are the same.
(The client may have multiple fids pointing to a single file on a server
and hence having a single qid.)
The thirteen-byte qid fields hold a one-byte type,
specifying whether the file is a directory, append-only file, etc.,
and two unsigned integers:
first the four-byte qid
.IR version ,
then the eight-byte qid
.IR path .
The path is an integer unique among all files in the hierarchy.
If a file is deleted and recreated with the
same name in the same directory, the old and new path components of the qids
should be different.
The version is a version number for a file;
typically, it is incremented every time the file is modified.
.PP
An existing file can be
.BR opened ,
or a new file may be
.B created
in the current (directory) file.
I/O of a given number of bytes
at a given offset
on an open file is done by
.B read
and
.BR write .
.PP
A client should
.B clunk
any fid that is no longer needed.
The
.B remove
transaction deletes files.
.PP
.B Openfd
is an extension used by Unix utilities to allow traditional Unix programs
to have their input or output attached to fids on 9P servers.
See
.IR openfd (9p)
and
.IR 9pclient (3)
for details.
.PP
The
.B stat
transaction retrieves information about the file.
The
.I stat
field in the reply includes the file's
name,
access permissions (read, write and execute for owner, group and public),
access and modification times, and
owner and group identifications
(see
.IR stat (3)).
The owner and group identifications are textual names.
The
.B wstat
transaction allows some of a file's properties
to be changed.
.PP
A request can be aborted with a
flush
request.
When a server receives a
.BR Tflush ,
it should not reply to the message with tag
.I oldtag
(unless it has already replied),
and it should immediately send an
.BR Rflush .
The client must wait
until it gets the
.B Rflush
(even if the reply to the original message arrives in the interim),
at which point
.I oldtag
may be reused.
.PP
Because the message size is negotiable and some elements of the
protocol are variable length, it is possible (although unlikely) to have
a situation where a valid message is too large to fit within the negotiated size.
For example, a very long file name may cause a
.B Rstat
of the file or
.B Rread
of its directory entry to be too large to send.
In most such cases, the server should generate an error rather than
modify the data to fit, such as by truncating the file name.
The exception is that a long error string in an
.B Rerror
message should be truncated if necessary, since the string is only
advisory and in some sense arbitrary.
.PP
Most programs do not see the 9P protocol directly;
on Plan 9, calls to library
routines that access files are
translated by the kernel's mount driver
into 9P messages.
.SS Unix
On Unix, 9P services are posted as Unix domain sockets in a
well-known directory (see
.IR getns (3)
and
.IR 9pserve (4)).
Clients connect to these servers using a 9P client library
(see
.IR 9pclient (3)).
.SH DIRECTORIES
Directories are created by
.B create
with
.B DMDIR
set in the permissions argument (see
.IR stat (9P)).
The members of a directory can be found with
.IR read (9P).
All directories must support
.B walks
to the directory
.B ..
(dot-dot)
meaning parent directory, although by convention directories
contain no explicit entry for
.B ..
or
.B .
(dot).
The parent of the root directory of a server's tree is itself.
.SH "ACCESS PERMISSIONS"
This section describes the access permission conventions
implemented by most Plan 9 file servers. These conventions
are not enforced by the protocol and may differ between servers,
especially servers built on top of foreign operating systems.
.PP
Each file server maintains a set of user and group names.
Each user can be a member of any number of groups.
Each group has a
.I group leader
who has special privileges (see
.IR stat (9P)
and
Plan 9's \fIusers\fR(6)).
Every file request has an implicit user id (copied from the original
.BR attach )
and an implicit set of groups (every group of which the user is a member).
.PP
Each file has an associated
.I owner
and
.I group
id and
three sets of permissions:
those of the owner, those of the group, and those of ``other'' users.
When the owner attempts to do something to a file, the owner, group,
and other permissions are consulted, and if any of them grant
the requested permission, the operation is allowed.
For someone who is not the owner, but is a member of the file's group,
the group and other permissions are consulted.
For everyone else, the other permissions are used.
Each set of permissions says whether reading is allowed,
whether writing is allowed, and whether executing is allowed.
A
.B walk
in a directory is regarded as executing the directory,
not reading it.
Permissions are kept in the low-order bits of the file
.IR mode :
owner read/write/execute permission represented as 1 in bits 8, 7, and 6
respectively (using 0 to number the low order).
The group permissions are in bits 5, 4, and 3,
and the other permissions are in bits 2, 1, and 0.
.PP
The file
.I mode
contains some additional attributes besides the permissions.
If bit 31
.RB ( DMDIR )
is set, the file is a directory;
if bit 30
.RB ( DMAPPEND )
is set, the file is append-only (offset is ignored in writes);
if bit 29
.RB ( DMEXCL )
is set, the file is exclusive-use (only one client may have it
open at a time);
if bit 27
.RB ( DMAUTH )
is set, the file is an authentication file established by
.B auth
messages;
if bit 26
.RB ( DMTMP )
is set, the contents of the file (or directory) are not included in nightly archives.
(Bit 28 is skipped for historical reasons.)
These bits are reproduced, from the top bit down, in the type byte of the Qid:
.BR QTDIR ,
.BR QTAPPEND ,
.BR QTEXCL ,
(skipping one bit)
.BR QTAUTH ,
and
.BR QTTMP .
The name
.BR QTFILE ,
defined to be zero,
identifies the value of the type for a plain file.

16
man/man9/INDEX Normal file
View file

@ -0,0 +1,16 @@
0intro 0intro.9p
intro 0intro.9p
attach attach.9p
auth attach.9p
clunk clunk.9p
error error.9p
flush flush.9p
create open.9p
open open.9p
read read.9p
write read.9p
remove remove.9p
stat stat.9p
wstat stat.9p
version version.9p
walk walk.9p

168
man/man9/attach.9p Normal file
View file

@ -0,0 +1,168 @@
.TH ATTACH 9P
.SH NAME
attach, auth \- messages to establish a connection
.SH SYNOPSIS
.ta \w'\fLTauth 'u
.IR size [4]
.B Tauth
.IR tag [2]
.IR afid [4]
.IR uname [ s ]
.IR aname [ s ]
.br
.IR size [4]
.B Rauth
.IR tag [2]
.IR aqid [13]
.PP
.IR size [4]
.B Tattach
.IR tag [2]
.IR fid [4]
.IR afid [4]
.IR uname [ s ]
.IR aname [ s ]
.br
.IR size [4]
.B Rattach
.IR tag [2]
.IR qid [13]
.SH DESCRIPTION
.PP
The
.B attach
message serves as a fresh introduction from a user on
the client machine to the server.
The message identifies the user
.RI ( uname )
and may select
the file tree to access
.RI ( aname ).
The
.I afid
argument specifies a fid previously established by an
.B auth
message, as described below.
.PP
As a result of the
.B attach
transaction, the client will have a connection to the root
directory of the desired file tree,
represented by
.IR fid .
An error is returned if
.I fid
is already in use.
The server's idea of the root of the file tree is represented by the returned
.IR qid .
.PP
If the client does not wish to authenticate the connection, or knows that
authentication is not required, the
.I afid
field in the
.B attach
message should be set to
.BR NOFID ,
defined as
.B (u32int)~0
in
.BR <fcall.h> .
If the client does wish to authenticate, it must acquire and validate an
.I afid
using an
.B auth
message before doing the
.BR attach .
.PP
The
.B auth
message contains
.IR afid ,
a new fid to be established for authentication, and the
.I uname
and
.I aname
that will be those of the following
.B attach
message.
If the server does not require authentication, it returns
.B Rerror
to the
.B Tauth
message.
.PP
If the server does require authentication, it returns
.I aqid
defining a file of type
.B QTAUTH
(see
.IR intro (9P))
that may be read and written (using
.B read
and
.B write
messages in the usual way) to execute an authentication protocol.
That protocol's definition is not part of 9P itself.
.PP
Once the protocol is complete, the same
.I afid
is presented in the
.B attach
message for the user, granting entry.
The same validated
.I afid
may be used for multiple
.B attach
messages with the same
.I uname
and
.IR aname .
.SH ENTRY POINTS
.I Fsmount
and
.I fsauth
(see
.IR 9pclient (3))
generate
.B attach
and
.B auth
transactions.
.\" An
.\" .B attach
.\" transaction will be generated for kernel devices
.\" (see
.\" .IR intro (3))
.\" when a system call evaluates a file name
.\" beginning with
.\" .LR # .
.\" .IR Pipe (2)
.\" generates an attach on the kernel device
.\" .IR pipe (3).
.\" The
.\" .I mount
.\" system call
.\" (see
.\" .IR bind (2))
.\" generates an
.\" .B attach
.\" message to the remote file server.
.\" When the kernel boots, an
.\" .I attach
.\" is made to the root device,
.\" .IR root (3),
.\" and then an
.\" .B attach
.\" is made to the requested file server machine.
.\" .PP
.\" An
.\" .B auth
.\" transaction is generated by the
.\" .IR fauth (2)
.\" system call or by the first
.\" .B mount
.\" system call on an uninitialized connection.
.SH SEE ALSO
.IR 9pclient (3),
.IR version (9P),
Plan 9's \fIauthsrv\fR(6)

55
man/man9/clunk.9p Normal file
View file

@ -0,0 +1,55 @@
.TH CLUNK 9P
.SH NAME
clunk \- forget about a fid
.SH SYNOPSIS
.ta \w'\fLTclunk 'u
.IR size [4]
.B Tclunk
.IR tag [2]
.IR fid [4]
.br
.IR size [4]
.B Rclunk
.IR tag [2]
.SH DESCRIPTION
The
.B clunk
request informs the file server
that the current file represented by
.I fid
is no longer needed by the client.
The actual file is not removed on the server unless the fid had been opened with
.BR ORCLOSE .
.PP
Once a fid has been clunked,
the same fid can be reused in a new
.B walk
or
.B attach
request.
.PP
Even if the
.B clunk
returns an error, the
.I fid
is no longer valid.
.SH ENTRY POINTS
.B Clunk
transactions are
generated by
.I fsclose
and
.I fsunmount
(see
.IR 9pclient (3))
and indirectly by other actions such as failed
.I fsopen
calls.
.\"
.\" A
.\" .B clunk
.\" message is generated by
.\" .I close
.\" and indirectly by other actions such as failed
.\" .I open
.\" calls.

28
man/man9/error.9p Normal file
View file

@ -0,0 +1,28 @@
.TH ERROR 9P
.SH NAME
error \- return an error
.SH SYNOPSIS
.ta \w'\fLRerror 'u
.IR size [4]
.B Rerror
.IR tag [2]
.IR ename [ s ]
.SH DESCRIPTION
The
.B Rerror
message
(there is no
.BR Terror )
is used to return an error string
describing the
failure of a transaction.
It replaces the corresponding reply message
that would accompany a successful call; its tag is that
of the failing request.
.PP
By convention, clients may truncate error messages after
.B ERRMAX-1
bytes;
.B ERRMAX
is defined in
.BR <libc.h> .

109
man/man9/flush.9p Normal file
View file

@ -0,0 +1,109 @@
.TH FLUSH 9P
.SH NAME
flush \- abort a message
.SH SYNOPSIS
.ta \w'\fLTflush 'u
.IR size [4]
.B Tflush
.IR tag [2]
.IR oldtag [2]
.br
.IR size [4]
.B Rflush
.IR tag [2]
.SH DESCRIPTION
When the response to a request is no longer needed, such as when
a user interrupts a process doing a
.IR read (9p),
a
.B Tflush
request is sent to the server to purge the pending response.
The message being flushed is identified by
.IR oldtag .
The semantics of
.B flush
depends on messages arriving in order.
.PP
The server should answer the
.B flush
message immediately.
If it recognizes
.I oldtag
as the tag of a pending transaction, it should abort any pending response
and discard that tag.
In either case, it should respond with an
.B Rflush
echoing the
.I tag
(not
.IR oldtag )
of the
.B Tflush
message.
A
.B Tflush
can never be responded to by an
.B Rerror
message.
.PP
The server may respond to the pending request before
responding to the
.BR Tflush .
It is possible for a client to send multiple
.B Tflush
messages for a particular pending request. Each
subsequent
.B Tflush
must contain as
.I oldtag
the tag of the pending request (not a previous
.BR Tflush ).
Should multiple
.BR Tflush es
be received for a pending request, they must be answered in
order. A
.B Rflush
for any of the multiple
.BR Tflush es
implies an answer for all previous ones. Therefore, should
a server receive a request and then multiple flushes for that
request, it need respond only to the last flush.
.PP
When the client sends a
.BR Tflush ,
it must wait to receive the corresponding
.B Rflush
before reusing
.I oldtag
for subsequent messages.
If a response to the flushed request is received before the
.BR Rflush ,
the client must honor the response
as if it had not been flushed,
since the completed request may signify a state change in the server.
For instance,
.B Tcreate
may have created a file and
.B Twalk
may have allocated a fid.
If no response is received before the
.BR Rflush ,
the flushed transaction is considered to have been canceled,
and should be treated as though it had never been sent.
.PP
Several exceptional conditions are handled correctly by the above specification:
sending multiple flushes for a single tag,
flushing after a transaction is completed,
flushing a
.BR Tflush ,
and flushing an invalid tag.
.SH ENTRY POINTS
The
.IR 9pclient (3)
library does not generate
.B flush
transactions..
.IR 9pserve (4)
generates
.B flush
transactions to cancel transactions pending when a client hangs up.

249
man/man9/open.9p Normal file
View file

@ -0,0 +1,249 @@
.TH OPEN 9P
.SH NAME
open, create \- prepare a fid for I/O on an existing or new file
.SH SYNOPSIS
.ta \w'\fLTcreate 'u
.IR size [4]
.B Topen
.IR tag [2]
.IR fid [4]
.IR mode [1]
.br
.IR size [4]
.B Ropen
.IR tag [2]
.IR qid [13]
.IR iounit [4]
.PP
.IR size [4]
.B Tcreate
.IR tag [2]
.IR fid [4]
.IR name [ s ]
.IR perm [4]
.IR mode [1]
.br
.IR size [4]
.B Rcreate
.IR tag [2]
.IR qid [13]
.IR iounit [4]
.SH DESCRIPTION
The
.B open
request asks the file server to check permissions and
prepare a fid for I/O with subsequent
.B read
and
.B write
messages.
The
.I mode
field determines the type of I/O:
0
(called
.BR OREAD
in
.BR <libc.h> ),
1
.RB ( OWRITE ),
2
.RB ( ORDWR ),
and 3
.RB ( OEXEC )
mean
.I
read access, write access, read and write access,
and
.I
execute access,
to be checked against the permissions for the file.
In addition, if
.I mode
has the
.B OTRUNC
.RB ( 0x10 )
bit set,
the file is to be truncated, which requires write permission
(if
the file is append-only, and permission is granted, the
.B open
succeeds but the file will not be truncated);
if the
.I mode
has the
.B ORCLOSE
.RB ( 0x40 )
bit set, the file is to be removed when the fid
is clunked, which requires permission to remove the file from its directory.
All other bits in
.I mode
should be zero.
It is illegal to write a directory, truncate it, or attempt to remove it on close.
If the file is marked for exclusive use (see
.IR stat (9P)),
only one client can have the file open at any time.
That is, after such a file has been opened,
further opens will fail until
.I fid
has been clunked.
All these permissions are checked at the time of the
.B open
request; subsequent changes to the permissions of files do not affect
the ability to read, write, or remove an open file.
.PP
The
.B create
request asks the file server to create a new file
with the
.I name
supplied, in the directory
.RI ( dir )
represented by
.IR fid ,
and requires write permission in the directory.
The owner of the file is the implied user id of the request,
the group of the file is the same as
.IR dir ,
and the permissions are the value of
.ce
.B "perm & (~0666 | (dir.perm & 0666))"
if a regular file is being created and
.ce
.B "perm & (~0777 | (dir.perm & 0777))"
if a directory is being created.
This means, for example, that if the
.B create
allows read permission to others, but the containing directory
does not, then the created file will not allow others to read the file.
.PP
Finally, the newly created file is opened according to
.IR mode ,
and
.I fid
will represent the newly opened file.
.I Mode
is not checked against the permissions in
.IR perm .
The
.I qid
for the new file is returned with the
.B create
reply message.
.PP
Directories are created by setting the
.B DMDIR
bit
.RB ( 0x80000000 )
in the
.IR perm .
.PP
The names
.B .
and
.B ..
are special; it is illegal to create files with these names.
.PP
It is an error for either of these messages if the fid
is already the product of a successful
.B open
or
.B create
message.
.PP
An attempt to
.B create
a file in a directory where the given
.I name
already exists will be rejected;
in this case, the
.I fscreate
call
(see
.IR 9pclient (3))
uses
.B open
with truncation.
The algorithm used by the
.IR create
system call
is:
first walk to the directory to contain the file.
If that fails, return an error.
Next
.B walk
to the specified file.
If the
.B walk
succeeds, send a request to
.B open
and truncate the file and return the result, successful or not.
If the
.B walk
fails, send a create message.
If that fails, it may be because the file was created by another
process after the previous walk failed, so (once) try the
.B walk
and
.B open
again.
.\" .PP
.\" For the behavior of
.\" .I create
.\" on a union directory, see
.\" .IR bind (2).
.\" .PP
.\" The
.\" .B iounit
.\" field returned by
.\" .B open
.\" and
.\" .B create
.\" may be zero.
.\" If it is not, it is the maximum number of bytes that are guaranteed to
.\" be read from or written to the file without breaking the I/O transfer
.\" into multiple 9P messages; see
.\" .IR read (9P).
.SH ENTRY POINTS
.I Fsopen
and
.I fscreate
(see
.IR 9pclient (3))
both generate
.B open
messages; only
.I fscreate
generates a
.B create
message.
The
.B iounit
associated with an open file may be discovered by calling
.IR fsiounit .
.PP
For programs that need atomic file creation, without the race
that exists in the
.B open-create
sequence described above,
.IR fscreate
does the following.
If the
.B OEXCL
.RB ( 0x1000 )
bit is set in the
.I mode
for a
.I fscreate
call,
the
.B open
message is not sent; the kernel issues only the
.BR create .
Thus, if the file exists,
.I fscreate
will draw an error, but if it doesn't and the
.I fscreate
call succeeds, the process issuing the
.I fscreate
is guaranteed to be the one that created the file.

126
man/man9/read.9p Normal file
View file

@ -0,0 +1,126 @@
.TH READ 9P
.SH NAME
read, write \- transfer data from and to a file
.SH SYNOPSIS
.ta \w'\fLTwrite 'u
.IR size [4]
.B Tread
.IR tag [2]
.IR fid [4]
.IR offset [8]
.IR count [4]
.br
.IR size [4]
.B Rread
.IR tag [2]
.IR count [4]
.IR data [ count ]
.PP
.IR size [4]
.B Twrite
.IR tag [2]
.IR fid [4]
.IR offset [8]
.IR count [4]
.IR data [ count ]
.br
.IR size [4]
.B Rwrite
.IR tag [2]
.IR count [4]
.SH DESCRIPTION
The
.B read
request
asks for
.I count
bytes of data
from the file identified by
.IR fid ,
which must be opened for reading,
starting
.I offset
bytes after the beginning of the file.
The bytes are returned with the
.B read
reply message.
.PP
The
.I count
field in the reply indicates the number of bytes returned.
This may be less than the requested amount.
If the
.I offset
field is greater than or equal to the number of bytes in the file,
a count of zero will be returned.
.PP
For directories,
.B read
returns an integral number of
directory entries exactly as in
.B stat
(see
.IR stat (9P)),
one for each member of the directory.
The
.B read
request message must have
.B offset
equal to zero or the value of
.B offset
in the previous
.B read
on the directory, plus the number of bytes
returned in the previous
.BR read .
In other words, seeking other than to the beginning
is illegal in a directory.
.PP
The
.B write
request asks that
.I count
bytes of data be recorded in the file identified by
.IR fid ,
which must be opened for writing, starting
.I offset
bytes after the beginning of the file.
If the file is append-only,
the data will be placed at the end of the file regardless of
.IR offset .
Directories may not be written.
.PP
The
.B write
reply records the number of bytes actually written.
It is usually an error
if this is not the same as requested.
.PP
Because 9P implementations may limit the size of individual
messages,
more than one message may be produced by a single
.I read
or
.I write
call.
The
.I iounit
field returned by
.IR open (9P),
if non-zero, reports the maximum size that is guaranteed
to be transferred atomically.
.SH ENTRY POINTS
.I Fsread
and
.I fswrite
(see
.IR 9pclient (3))
generate the corresponding messages.
Because they take an offset parameter, the
.I fspread
and
.I fspwrite
calls correspond more directly to the 9P messages.
Although
.I fsseek
affects the offset, it does not generate a message.

51
man/man9/remove.9p Normal file
View file

@ -0,0 +1,51 @@
.TH REMOVE 9P
.SH NAME
remove \- remove a file from a server
.SH SYNOPSIS
.ta \w'\fLTremove 'u
.IR size [4]
.B Tremove
.IR tag [2]
.IR fid [4]
.br
.IR size [4]
.B Rremove
.IR tag [2]
.SH DESCRIPTION
The
.B remove
request asks the file server both to remove the file represented by
.I fid
and to
.B clunk
the
.IR fid ,
even if the remove fails.
This request will fail if the client does not have write permission
in the parent directory.
.PP
It is correct to consider
.B remove
to be a
.B clunk
with the side effect of removing the file if permissions allow.
.PP
If a file has been opened as multiple fids,
possibly on different connections,
and one fid is used to remove the file,
whether the other fids continue to provide access to the file
is implementation-defined.
The Plan 9 file servers
remove the file immediately: attempts to use the other fids
will yield a
``phase error.''
.IR U9fs
follows the semantics of the underlying Unix file system,
so other fids typically remain usable.
.SH ENTRY POINTS
.I Fsremove
(see
.IR 9pclient (3))
generates
.B remove
messages.

297
man/man9/stat.9p Normal file
View file

@ -0,0 +1,297 @@
.TH STAT 9P
.SH NAME
stat, wstat \- inquire or change file attributes
.SH SYNOPSIS
.ta \w'\fLTwstat 'u
.IR size [4]
.B Tstat
.IR tag [2]
.IR fid [4]
.br
.IR size [4]
.B Rstat
.IR tag [2]
.IR stat [ n ]
.PP
.IR size [4]
.B Twstat
.IR tag [2]
.IR fid [4]
.IR stat [ n ]
.br
.IR size [4]
.B Rwstat
.IR tag [2]
.SH DESCRIPTION
The
.B stat
transaction inquires about the file
identified by
.IR fid .
The reply will contain a
machine-independent
.I directory
.IR entry ,
.IR stat ,
laid out as follows:
.TP
.I size\f1[2]\fP
total byte count of the following data
.TP
.I type\f1[2]\fP
for kernel use
.TP
.I dev\f1[4]\fP
for kernel use
.TP
.I qid.type\f1[1]\fP
the type of the file (directory, etc.), represented as a bit vector
corresponding to the high 8 bits of the file's mode word.
.TP
.I qid.vers\f1[4]\fP
version number for given path
.TP
.I qid.path\f1[8]\fP
the file server's unique identification for the file
.TP
.I mode\f1[4]\fP
permissions and flags
.TP
.I atime\f1[4]\fP
last access time
.TP
.I mtime\f1[4]\fP
last modification time
.TP
.I length\f1[8]\fP
length of file in bytes
.TP
.I name\f1[ s ]\fP
file name; must be
.B /
if the file is the root directory of the server
.TP
.I uid\f1[ s ]\fP
owner name
.TP
.I gid\f1[ s ]\fP
group name
.TP
.I muid\f1[ s ]\fP
name of the user who last modified the file
.PD
.PP
Integers in this encoding are in little-endian order (least
significant byte first).
The
.I convM2D
and
.I convD2M
routines (see
.IR fcall (3))
convert between directory entries and a C structure called a
.BR Dir .
.PP
The
.I mode
contains permission bits as described in
.IR intro (9P)
and the following:
.B 0x80000000
.RB ( DMDIR ,
this file is a directory),
.B 0x40000000
.RB ( DMAPPEND ,
append only),
.B 0x20000000
.RB ( DMEXCL ,
exclusive use),
.B 0x04000000
.RB ( DMTMP ,
temporary);
these are echoed in
.BR Qid.type .
Writes to append-only files always place their data at the
end of the file; the
.I offset
in the
.B write
message is ignored, as is the
.B OTRUNC
bit in an open.
Exclusive use files may be open for I/O by only one fid at a time
across all clients of the server. If a second open is attempted,
it draws an error. Servers may implement a timeout on the lock
on an exclusive use file: if the fid holding the file open has
been unused for an extended period (of order at least minutes),
it is reasonable to break the lock and deny the initial fid
further I/O.
Temporary files are not included in nightly archives
(see Plan 9's \fIfossil\fR(4)).
.PP
The two time fields are measured in seconds since the epoch
(Jan 1 00:00 1970 GMT).
The
.I mtime
field reflects the time of the last change of content (except when later changed by
.BR wstat ).
For a plain file,
.I mtime
is the time of the most recent
.BR create ,
.B open
with truncation,
or
.BR write ;
for a directory it is the time of the most recent
.BR remove ,
.BR create ,
or
.B wstat
of a file in the directory.
Similarly, the
.I atime
field records the last
.B read
of the contents;
also it is set whenever
.I mtime
is set.
In addition, for a directory, it is set by
an
.BR attach ,
.BR walk ,
or
.BR create ,
all whether successful or not.
.PP
The
.I muid
field names the user whose actions most recently changed the
.I mtime
of the file.
.PP
The
.I length
records the number of bytes in the file.
Directories and most files representing devices have a conventional
length of 0.
.PP
The
.B stat
request requires no special permissions.
.PP
The
.B wstat
request can change some of the file status information.
The
.I name
can be changed by anyone with write permission in the parent directory;
it is an error to change the name to that of an existing file.
The
.I length
can be changed (affecting the actual length of the file) by anyone with
write permission on the file.
It is an error to attempt to set the length of a directory to a non-zero value,
and servers may decide to reject length changes for other reasons.
The
.I mode
and
.I mtime
can be changed by the owner of the file or the group leader of the file's current
group.
The directory bit cannot be changed by a
.BR wstat ;
the other defined permission and mode bits can.
The
.I gid
can be changed: by the owner if also a member of the new group; or
by the group leader of the file's current group
if also leader of the new group
(see
.IR intro (9P)
for more information about permissions, users, and groups).
None of the other data can be altered by a
.B wstat
and attempts to change them will trigger an error.
In particular,
it is illegal to attempt to change the owner of a file.
(These conditions may be
relaxed when establishing the initial state of a file server; see
Plan 9's \fIfsconfig\fR(8).)
.PP
Either all the changes in
.B wstat
request happen, or none of them does: if the request succeeds,
all changes were made; if it fails, none were.
.PP
A
.B wstat
request can avoid modifying some properties of the file
by providing explicit ``don't touch'' values in the
.B stat
data that is sent: zero-length strings for text values and
the maximum unsigned value of appropriate size
for integral values.
As a special case, if
.I all
the elements of the directory entry in a
.B Twstat
message are ``don't touch'' values, the server may interpret it
as a request to guarantee that the contents of the associated
file are committed to stable storage before the
.B Rwstat
message is returned.
(Consider the message to mean, ``make the state of the file
exactly what it claims to be.'')
.PP
A
.I read
of a directory yields an integral number of directory entries in
the machine independent encoding given above
(see
.IR read (9P)).
.PP
Note that since the
.B stat
information is sent as a 9P variable-length datum, it is limited to a maximum of
65535 bytes.
.SH ENTRY POINTS
.B Stat
messages are generated by
.I fsdirfstat
and
.IR fsdirstat
(see
.IR 9pclient (3)).
.PP
.B Wstat
messages are generated by
.I fsdirfwstat
and
.IR fsdirwstat .
.SH BUGS
To make the contents of a directory, such as returned by
.IR read (9P),
easy to parse, each
directory entry begins with a size field.
For consistency, the entries in
.B Twstat
and
.B Rstat
messages also contain
their size, which means the size appears twice.
For example, the
.B Rstat
message is formatted as
.RI ``(4+1+2+2+ n )[4]
.B Rstat
.IR tag [2]
.IR n [2]
.RI ( n -2)[2]
.IR type [2]
.IR dev [4]...,''
where
.I n
is the value returned by
.BR convD2M .

99
man/man9/version.9p Normal file
View file

@ -0,0 +1,99 @@
.TH VERSION 9P
.SH NAME
version \- negotiate protocol version
.SH SYNOPSIS
.ta \w'\fLTversion 'u
.IR size [4]
.B Tversion
.IR tag [2]
.IR msize [4]
.IR version [ s ]
.br
.IR size [4]
.B Rversion
.IR tag [2]
.IR msize [4]
.IR version [ s ]
.SH DESCRIPTION
The
.B version
request negotiates the protocol version and message size
to be used on the connection and initializes the connection for I/O.
.B Tversion
must be the first message sent on the 9P connection,
and the client cannot issue any further requests until it has received the
.B Rversion
reply.
The
.I tag
should be
.B NOTAG
(value
.BR (ushort)~0 )
for a
.B version
message.
.PP
The client suggests a maximum message size,
.BR msize ,
that is the maximum length, in bytes,
it will ever generate or expect to receive in a single 9P message.
This count includes all 9P protocol data, starting from the
.B size
field and extending through the message,
but excludes enveloping transport protocols.
The server responds with its own maximum,
.BR msize ,
which must be less than or equal to the client's value.
Thenceforth, both sides of the connection must honor this limit.
.PP
The
.B version
string identifies the level of the protocol.
The string must always begin with the two characters
.RB `` 9P ''.
If the server does not understand the client's version string,
it should respond with an
.B Rversion
message (not
.BR Rerror )
with the
.B version
string the 7 characters
.RB `` unknown ''.
.PP
The server may respond with the client's version string,
or a version string identifying
an earlier defined protocol version.
Currently, the only defined version is the 6 characters
.RB `` 9P2000 ''.
Version strings are defined such that, if the client string contains
one or more period characters, the initial substring up to but not including
any single period in the version string defines a version of the protocol.
After stripping any such period-separated suffix, the server is allowed to respond
with a string of the form
.BI 9P nnnn\f1,
where
.I nnnn
is less than or equal to the digits sent by the client.
.PP
The client and server will use the protocol version defined by the
server's response for all subsequent communication on the connection.
.PP
A successful
.B version
request initializes the connection.
All outstanding I/O on the connection is aborted; all active fids are freed (`clunked') automatically.
The set of messages between
.B version
requests is called a
.IR session .
.SH ENTRY POINTS
.I Fsversion
(see
.IR 9pclient (3))
generates
.B version
messages;
it is called automatically by
.IR fsmount .

189
man/man9/walk.9p Normal file
View file

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