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

checkpoint

Browse source
This commit is contained in:
rsc 2005-01-14 03:45:44 +00:00
parent 2634795b5f
commit 78e51a8c66
314 changed files with 48199 additions and 300 deletions
Download patch file Download diff file Expand all files Collapse all files

107
man/man9/attach.html Normal file
View file

@ -0,0 +1,107 @@
<head>
<title>attach(9P) - Plan 9 from User Space</title>
<meta content="text/html; charset=utf-8" http-equiv=Content-Type>
</head>
<body bgcolor=#ffffff>
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=10><td>
<tr><td width=20><td>
<tr><td width=20><td><b>ATTACH(9P)</b><td align=right><b>ATTACH(9P)</b>
<tr><td width=20><td colspan=2>
<br>
<p><font size=+1><b>NAME </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
attach, auth &ndash; messages to establish a connection<br>
</table>
<p><font size=+1><b>SYNOPSIS </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<i>size</i>[4] <tt><font size=+1>Tauth</font></tt> <i>tag</i>[2] <i>afid</i>[4] <i>uname</i>[<i>s</i>] <i>aname</i>[<i>s</i>]<br>
<i>size</i>[4] <tt><font size=+1>Rauth</font></tt> <i>tag</i>[2] <i>aqid</i>[13]
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>size</i>[4] <tt><font size=+1>Tattach</font></tt> <i>tag</i>[2] <i>fid</i>[4] <i>afid</i>[4] <i>uname</i>[<i>s</i>] <i>aname</i>[<i>s</i>]<br>
<i>size</i>[4] <tt><font size=+1>Rattach</font></tt> <i>tag</i>[2] <i>qid</i>[13]<br>
</table>
<p><font size=+1><b>DESCRIPTION </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
The <tt><font size=+1>attach</font></tt> message serves as a fresh introduction from a user
on the client machine to the server. The message identifies the
user (<i>uname</i>) and may select the file tree to access (<i>aname</i>). The
<i>afid</i> argument specifies a fid previously established by an <tt><font size=+1>auth</font></tt>
message, as described below.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
As a result of the <tt><font size=+1>attach</font></tt> transaction, the client will have a
connection to the root directory of the desired file tree, represented
by <i>fid</i>. An error is returned if <i>fid</i> is already in use. The server&#8217;s
idea of the root of the file tree is represented by the returned
<i>qid</i>.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
If the client does not wish to authenticate the connection, or
knows that authentication is not required, the <i>afid</i> field in the
<tt><font size=+1>attach</font></tt> message should be set to <tt><font size=+1>NOFID</font></tt>, defined as <tt><font size=+1>(u32int)~0</font></tt> in
<tt><font size=+1>&lt;fcall.h&gt;</font></tt>. If the client does wish to authenticate, it must acquire
and validate an <i>afid</i> using an <tt><font size=+1>auth</font></tt> message before
doing the <tt><font size=+1>attach</font></tt>.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The <tt><font size=+1>auth</font></tt> message contains <i>afid</i>, a new fid to be established for
authentication, and the <i>uname</i> and <i>aname</i> that will be those of
the following <tt><font size=+1>attach</font></tt> message. If the server does not require authentication,
it returns <tt><font size=+1>Rerror</font></tt> to the <tt><font size=+1>Tauth</font></tt> message.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
If the server does require authentication, it returns <i>aqid</i> defining
a file of type <tt><font size=+1>QTAUTH</font></tt> (see <i>intro</i>(9P)) that may be read and written
(using <tt><font size=+1>read</font></tt> and <tt><font size=+1>write</font></tt> messages in the usual way) to execute an
authentication protocol. That protocol&#8217;s definition is not part
of 9P itself.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
Once the protocol is complete, the same <i>afid</i> is presented in the
<tt><font size=+1>attach</font></tt> message for the user, granting entry. The same validated
<i>afid</i> may be used for multiple <tt><font size=+1>attach</font></tt> messages with the same <i>uname</i>
and <i>aname</i>.<br>
</table>
<p><font size=+1><b>ENTRY POINTS </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<i>Fsmount</i> and <i>fsauth</i> (see <a href="../man3/9pclient.html"><i>9pclient</i>(3)</a>) generate <tt><font size=+1>attach</font></tt> and <tt><font size=+1>auth</font></tt>
transactions.<br>
</table>
<p><font size=+1><b>SEE ALSO </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<a href="../man3/9pclient.html"><i>9pclient</i>(3)</a>, <i>version</i>(9P), Plan 9&#8217;s <i>authsrv</i>(6)<br>
</table>
<td width=20>
<tr height=20><td>
</table>
<!-- TRAILER -->
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=15><td width=10><td><td width=10>
<tr><td><td>
<center>
<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a>
</center>
</table>
<!-- TRAILER -->
</body></html>

66
man/man9/clunk.html Normal file
View file

@ -0,0 +1,66 @@
<head>
<title>clunk(9P) - Plan 9 from User Space</title>
<meta content="text/html; charset=utf-8" http-equiv=Content-Type>
</head>
<body bgcolor=#ffffff>
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=10><td>
<tr><td width=20><td>
<tr><td width=20><td><b>CLUNK(9P)</b><td align=right><b>CLUNK(9P)</b>
<tr><td width=20><td colspan=2>
<br>
<p><font size=+1><b>NAME </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
clunk &ndash; forget about a fid<br>
</table>
<p><font size=+1><b>SYNOPSIS </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<i>size</i>[4] <tt><font size=+1>Tclunk</font></tt> <i>tag</i>[2] <i>fid</i>[4]<br>
<i>size</i>[4] <tt><font size=+1>Rclunk</font></tt> <i>tag</i>[2]<br>
</table>
<p><font size=+1><b>DESCRIPTION </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
The <tt><font size=+1>clunk</font></tt> request informs the file server that the current file
represented by <i>fid</i> is no longer needed by the client. The actual
file is not removed on the server unless the fid had been opened
with <tt><font size=+1>ORCLOSE</font></tt>.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
Once a fid has been clunked, the same fid can be reused in a new
<tt><font size=+1>walk</font></tt> or <tt><font size=+1>attach</font></tt> request.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
Even if the <tt><font size=+1>clunk</font></tt> returns an error, the <i>fid</i> is no longer valid.<br>
</table>
<p><font size=+1><b>ENTRY POINTS </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<tt><font size=+1>Clunk</font></tt> transactions are generated by <i>fsclose</i> and <i>fsunmount</i> (see
<a href="../man3/9pclient.html"><i>9pclient</i>(3)</a>) and indirectly by other actions such as failed <i>fsopen</i>
calls.<br>
</table>
<td width=20>
<tr height=20><td>
</table>
<!-- TRAILER -->
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=15><td width=10><td><td width=10>
<tr><td><td>
<center>
<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a>
</center>
</table>
<!-- TRAILER -->
</body></html>

53
man/man9/error.html Normal file
View file

@ -0,0 +1,53 @@
<head>
<title>error(9P) - Plan 9 from User Space</title>
<meta content="text/html; charset=utf-8" http-equiv=Content-Type>
</head>
<body bgcolor=#ffffff>
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=10><td>
<tr><td width=20><td>
<tr><td width=20><td><b>ERROR(9P)</b><td align=right><b>ERROR(9P)</b>
<tr><td width=20><td colspan=2>
<br>
<p><font size=+1><b>NAME </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
error &ndash; return an error<br>
</table>
<p><font size=+1><b>SYNOPSIS </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<i>size</i>[4] <tt><font size=+1>Rerror</font></tt> <i>tag</i>[2] <i>ename</i>[<i>s</i>]<br>
</table>
<p><font size=+1><b>DESCRIPTION </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
The <tt><font size=+1>Rerror</font></tt> message (there is no <tt><font size=+1>Terror</font></tt>) 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.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
By convention, clients may truncate error messages after <tt><font size=+1>ERRMAX&#8722;1</font></tt>
bytes; <tt><font size=+1>ERRMAX</font></tt> is defined in <tt><font size=+1>&lt;libc.h&gt;</font></tt>.<br>
</table>
<td width=20>
<tr height=20><td>
</table>
<!-- TRAILER -->
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=15><td width=10><td><td width=10>
<tr><td><td>
<center>
<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a>
</center>
</table>
<!-- TRAILER -->
</body></html>

98
man/man9/flush.html Normal file
View file

@ -0,0 +1,98 @@
<head>
<title>flush(9P) - Plan 9 from User Space</title>
<meta content="text/html; charset=utf-8" http-equiv=Content-Type>
</head>
<body bgcolor=#ffffff>
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=10><td>
<tr><td width=20><td>
<tr><td width=20><td><b>FLUSH(9P)</b><td align=right><b>FLUSH(9P)</b>
<tr><td width=20><td colspan=2>
<br>
<p><font size=+1><b>NAME </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
flush &ndash; abort a message<br>
</table>
<p><font size=+1><b>SYNOPSIS </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<i>size</i>[4] <tt><font size=+1>Tflush</font></tt> <i>tag</i>[2] <i>oldtag</i>[2]<br>
<i>size</i>[4] <tt><font size=+1>Rflush</font></tt> <i>tag</i>[2]<br>
</table>
<p><font size=+1><b>DESCRIPTION </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
When the response to a request is no longer needed, such as when
a user interrupts a process doing a <i>read</i>(9p), a <tt><font size=+1>Tflush</font></tt> request
is sent to the server to purge the pending response. The message
being flushed is identified by <i>oldtag</i>. The semantics of <tt><font size=+1>flush</font></tt>
depends on messages arriving in order.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The server should answer the <tt><font size=+1>flush</font></tt> message immediately. If it
recognizes <i>oldtag</i> 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 <tt><font size=+1>Rflush</font></tt> echoing the <i>tag</i> (not <i>oldtag</i>)
of the <tt><font size=+1>Tflush</font></tt> message. A <tt><font size=+1>Tflush</font></tt> can never be
responded to by an <tt><font size=+1>Rerror</font></tt> message.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The server may respond to the pending request before responding
to the <tt><font size=+1>Tflush</font></tt>. It is possible for a client to send multiple <tt><font size=+1>Tflush</font></tt>
messages for a particular pending request. Each subsequent <tt><font size=+1>Tflush</font></tt>
must contain as <i>oldtag</i> the tag of the pending request (not a previous
<tt><font size=+1>Tflush</font></tt>). Should multiple <tt><font size=+1>Tflush</font></tt>es be
received for a pending request, they must be answered in order.
A <tt><font size=+1>Rflush</font></tt> for any of the multiple <tt><font size=+1>Tflush</font></tt>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.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
When the client sends a <tt><font size=+1>Tflush</font></tt>, it must wait to receive the corresponding
<tt><font size=+1>Rflush</font></tt> before reusing <i>oldtag</i> for subsequent messages. If a response
to the flushed request is received before the <tt><font size=+1>Rflush</font></tt>, 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, <tt><font size=+1>Tcreate</font></tt> may have created a
file and <tt><font size=+1>Twalk</font></tt> may have allocated a fid. If no response is received
before the <tt><font size=+1>Rflush</font></tt>, the flushed transaction is considered to have
been canceled, and should be treated as though it had never been
sent.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
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 <tt><font size=+1>Tflush</font></tt>, and flushing
an invalid tag.<br>
</table>
<p><font size=+1><b>ENTRY POINTS </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
The <a href="../man3/9pclient.html"><i>9pclient</i>(3)</a> library does not generate <tt><font size=+1>flush</font></tt> transactions..
<a href="../man4/9pserve.html"><i>9pserve</i>(4)</a> generates <tt><font size=+1>flush</font></tt> transactions to cancel transactions
pending when a client hangs up.<br>
</table>
<td width=20>
<tr height=20><td>
</table>
<!-- TRAILER -->
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=15><td width=10><td><td width=10>
<tr><td><td>
<center>
<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a>
</center>
</table>
<!-- TRAILER -->
</body></html>

69
man/man9/index.html Normal file
View file

@ -0,0 +1,69 @@
<html>
<head>
<title>Manual Section 9 - Plan 9 from User Space</title>
</head>
<body>
<table width=100%>
<tr><td width=20><td>
<center>
<table border=0 cellspacing=0 cellpadding=0 width=100%>
<tr height=1><td width=200><td>
<tr><td colspan=2>
<center>
<b>Manual Section 9 - Plan 9 from User Space</b>
</center>
<tr height=10><td>
<tr><td valign=top><a href="intro.html">intro(9P)</a><td>intro &ndash; introduction to the Plan 9 File Protocol, 9P
<tr height=1><td>
<tr height=1><td colspan=2 bgcolor=#cccccc>
<tr height=1><td>
<tr><td valign=top><a href="attach.html">attach(9P)</a><td>attach, auth &ndash; messages to establish a connection
<tr height=1><td>
<tr height=1><td colspan=2 bgcolor=#cccccc>
<tr height=1><td>
<tr><td valign=top><a href="clunk.html">clunk(9P)</a><td>clunk &ndash; forget about a fid
<tr height=1><td>
<tr height=1><td colspan=2 bgcolor=#cccccc>
<tr height=1><td>
<tr><td valign=top><a href="error.html">error(9P)</a><td>error &ndash; return an error
<tr height=1><td>
<tr height=1><td colspan=2 bgcolor=#cccccc>
<tr height=1><td>
<tr><td valign=top><a href="flush.html">flush(9P)</a><td>flush &ndash; abort a message
<tr height=1><td>
<tr height=1><td colspan=2 bgcolor=#cccccc>
<tr height=1><td>
<tr><td valign=top><a href="open.html">open(9P)</a><td>open, create &ndash; prepare a fid for I/O on an existing or new file
<tr height=1><td>
<tr height=1><td colspan=2 bgcolor=#cccccc>
<tr height=1><td>
<tr><td valign=top><a href="read.html">read(9P)</a><td>read, write &ndash; transfer data from and to a file
<tr height=1><td>
<tr height=1><td colspan=2 bgcolor=#cccccc>
<tr height=1><td>
<tr><td valign=top><a href="remove.html">remove(9P)</a><td>remove &ndash; remove a file from a server
<tr height=1><td>
<tr height=1><td colspan=2 bgcolor=#cccccc>
<tr height=1><td>
<tr><td valign=top><a href="stat.html">stat(9P)</a><td>stat, wstat &ndash; inquire or change file attributes
<tr height=1><td>
<tr height=1><td colspan=2 bgcolor=#cccccc>
<tr height=1><td>
<tr><td valign=top><a href="version.html">version(9P)</a><td>version &ndash; negotiate protocol version
<tr height=1><td>
<tr height=1><td colspan=2 bgcolor=#cccccc>
<tr height=1><td>
<tr><td valign=top><a href="walk.html">walk(9P)</a><td>walk &ndash; descend a directory hierarchy
</table>
</center>
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=15><td width=10><td><td width=10>
<tr><td><td>
<center>
<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a>
</center>
</table>
<td width=20>
</table>
</body>
</html>

344
man/man9/intro.html Normal file
View file

@ -0,0 +1,344 @@
<head>
<title>intro(9P) - Plan 9 from User Space</title>
<meta content="text/html; charset=utf-8" http-equiv=Content-Type>
</head>
<body bgcolor=#ffffff>
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=10><td>
<tr><td width=20><td>
<tr><td width=20><td><b>INTRO(9P)</b><td align=right><b>INTRO(9P)</b>
<tr><td width=20><td colspan=2>
<br>
<p><font size=+1><b>NAME </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
intro &ndash; introduction to the Plan 9 File Protocol, 9P<br>
</table>
<p><font size=+1><b>SYNOPSIS </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<tt><font size=+1>#include &lt;fcall.h&gt;<br>
</font></tt>
</table>
<p><font size=+1><b>DESCRIPTION </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
A Plan 9 <i>server</i> is an agent that provides one or more hierarchical
file systems -- file trees -- that may be accessed by Plan 9 processes.
A server responds to requests by <i>clients</i> 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 server</i>. Another possibility for a server is
to synthesize files on demand, perhaps based on information on
data structures maintained in memory; the <a href="../man4/plumber.html"><i>plumber</i>(4)</a> server is
an example of such a server.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
A <i>connection</i> 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.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The <i>Plan 9 File Protocol</i>, 9P, is used for messages between <i>clients</i>
and <i>servers</i>. A client transmits <i>requests</i> (<i>T-messages</i>) to a server,
which subsequently returns <i>replies</i> (<i>R-messages</i>) 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</i> of that type.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
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, <i>n</i>, followed by <i>n</i> bytes of data. Text strings are
represented this way, with the text itself stored as a UTF-8 encoded
sequence of Unicode characters (see <a href="../man7/utf.html"><i>utf</i>(7)</a>). Text strings in 9P
messages are not NUL-terminated: <i>n</i> counts the bytes of UTF-8 data,
which include no final zero byte. The NUL character is illegal
in all text strings in 9P, and is therefore excluded from file
names, user names, and so on.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
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 <tt><font size=+1>&lt;fcall.h&gt;</font></tt>.
The next two bytes are an identifying <i>tag</i>, 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 <i>parameter</i>[<i>n</i>]
where <i>n</i> is not a constant represents a variable-length parameter:
<i>n</i>[2] followed by <i>n</i> bytes of data forming the <i>parameter</i>. The
notation <i>string</i>[<i>s</i>] (using a literal <i>s</i> character) is shorthand
for <i>s</i>[2] followed by <i>s</i> 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; <a href="../man3/fcall.html"><i>fcall</i>(3)</a> describes routines
that convert to and from this form into a machine-dependent C
structure.<br>
</table>
<p><font size=+1><b>MESSAGES </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<i>size</i>[4] <tt><font size=+1>Tversion</font></tt> <i>tag</i>[2] <i>msize</i>[4] <i>version</i>[<i>s</i>]<br>
<i>size</i>[4] <tt><font size=+1>Rversion</font></tt> <i>tag</i>[2] <i>msize</i>[4] <i>version</i>[<i>s</i>]<br>
<i>size</i>[4] <tt><font size=+1>Tauth</font></tt> <i>tag</i>[2] <i>afid</i>[4] <i>uname</i>[<i>s</i>] <i>aname</i>[<i>s</i>]<br>
<i>size</i>[4] <tt><font size=+1>Rauth</font></tt> <i>tag</i>[2] <i>aqid</i>[13]<br>
<i>size</i>[4] <tt><font size=+1>Rerror</font></tt> <i>tag</i>[2] <i>ename</i>[<i>s</i>]<br>
<i>size</i>[4] <tt><font size=+1>Tflush</font></tt> <i>tag</i>[2] <i>oldtag</i>[2]<br>
<i>size</i>[4] <tt><font size=+1>Rflush</font></tt> <i>tag</i>[2]<br>
<i>size</i>[4] <tt><font size=+1>Tattach</font></tt> <i>tag</i>[2] <i>fid</i>[4] <i>afid</i>[4] <i>uname</i>[<i>s</i>] <i>aname</i>[<i>s</i>]<br>
<i>size</i>[4] <tt><font size=+1>Rattach</font></tt> <i>tag</i>[2] <i>qid</i>[13]<br>
<i>size</i>[4] <tt><font size=+1>Twalk</font></tt> <i>tag</i>[2] <i>fid</i>[4] <i>newfid</i>[4] <i>nwname</i>[2] <i>nwname</i>*(<i>wname</i>[<i>s</i>])<br>
<i>size</i>[4] <tt><font size=+1>Rwalk</font></tt> <i>tag</i>[2] <i>nwqid</i>[2] <i>nwqid</i>*(<i>wqid</i>[13])<br>
<i>size</i>[4] <tt><font size=+1>Topen</font></tt> <i>tag</i>[2] <i>fid</i>[4] <i>mode</i>[1]<br>
<i>size</i>[4] <tt><font size=+1>Ropen</font></tt> <i>tag</i>[2] <i>qid</i>[13] <i>iounit</i>[4]<br>
<i>size</i>[4] <tt><font size=+1>Topenfd</font></tt> <i>tag</i>[2] <i>fid</i>[4] <i>mode</i>[1]<br>
<i>size</i>[4] <tt><font size=+1>Ropenfd</font></tt> <i>tag</i>[2] <i>qid</i>[13] <i>iounit</i>[4] <i>unixfd</i>[4]<br>
<i>size</i>[4] <tt><font size=+1>Tcreate</font></tt> <i>tag</i>[2] <i>fid</i>[4] <i>name</i>[<i>s</i>] <i>perm</i>[4] <i>mode</i>[1]<br>
<i>size</i>[4] <tt><font size=+1>Rcreate</font></tt> <i>tag</i>[2] <i>qid</i>[13] <i>iounit</i>[4]<br>
<i>size</i>[4] <tt><font size=+1>Tread</font></tt> <i>tag</i>[2] <i>fid</i>[4] <i>offset</i>[8] <i>count</i>[4]<br>
<i>size</i>[4] <tt><font size=+1>Rread</font></tt> <i>tag</i>[2] <i>count</i>[4] <i>data</i>[<i>count</i>]<br>
<i>size</i>[4] <tt><font size=+1>Twrite</font></tt> <i>tag</i>[2] <i>fid</i>[4] <i>offset</i>[8] <i>count</i>[4] <i>data</i>[<i>count</i>]<br>
<i>size</i>[4] <tt><font size=+1>Rwrite</font></tt> <i>tag</i>[2] <i>count</i>[4]<br>
<i>size</i>[4] <tt><font size=+1>Tclunk</font></tt> <i>tag</i>[2] <i>fid</i>[4]<br>
<i>size</i>[4] <tt><font size=+1>Rclunk</font></tt> <i>tag</i>[2]<br>
<i>size</i>[4] <tt><font size=+1>Tremove</font></tt> <i>tag</i>[2] <i>fid</i>[4]<br>
<i>size</i>[4] <tt><font size=+1>Rremove</font></tt> <i>tag</i>[2]<br>
<i>size</i>[4] <tt><font size=+1>Tstat</font></tt> <i>tag</i>[2] <i>fid</i>[4]<br>
<i>size</i>[4] <tt><font size=+1>Rstat</font></tt> <i>tag</i>[2] <i>stat</i>[<i>n</i>]<br>
<i>size</i>[4] <tt><font size=+1>Twstat</font></tt> <i>tag</i>[2] <i>fid</i>[4] <i>stat</i>[<i>n</i>]<br>
<i>size</i>[4] <tt><font size=+1>Rwstat</font></tt> <i>tag</i>[2]
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</table>
Each T-message has a <i>tag</i> 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 <tt><font size=+1>NOTAG</font></tt>, defined as <tt><font size=+1>(ushort)~0</font></tt> in <tt><font size=+1>&lt;fcall.h&gt;</font></tt>: the
client can use it, when establishing a connection, to override
tag matching in <tt><font size=+1>version</font></tt> messages.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The type of an R-message will either be one greater than the type
of the corresponding T-message or <tt><font size=+1>Rerror</font></tt>, indicating that the
request failed. In the latter case, the <i>ename</i> field contains a
string describing the reason for failure.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The <tt><font size=+1>version</font></tt> 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 <tt><font size=+1>version</font></tt> requests
is called a <i>session</i>.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
Most T-messages contain a <i>fid</i>, a 32-bit unsigned integer that
the client uses to identify a &#8220;current file&#8221; 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 <a href="../man3/stat.html"><i>stat</i>(3)</a> calls, and so on -- all files being
manipulated by the operating system -- 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.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The fid supplied in an <tt><font size=+1>attach</font></tt> message will be taken by the server
to refer to the root of the served file tree. The <tt><font size=+1>attach</font></tt> identifies
the user to the server and may specify a particular file tree
served by the server (for those that supply more than one).
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
Permission to attach to the service is proven by providing a special
fid, called <tt><font size=+1>afid</font></tt>, in the <tt><font size=+1>attach</font></tt> message. This <tt><font size=+1>afid</font></tt> is established
by exchanging <tt><font size=+1>auth</font></tt> messages and subsequently manipulated using
<tt><font size=+1>read</font></tt> and <tt><font size=+1>write</font></tt> messages to exchange authentication information
not defined explicitly by 9P. Once the
authentication protocol is complete, the <tt><font size=+1>afid</font></tt> is presented in
the <tt><font size=+1>attach</font></tt> to permit the user to access the service.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
A <tt><font size=+1>walk</font></tt> 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. <tt><font size=+1>Walk</font></tt> returns a new fid that
refers to the resulting file. Usually, a client maintains a fid
for the root, and navigates by <tt><font size=+1>walks</font></tt> from the root fid.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
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.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
Replies (R-messages) to <tt><font size=+1>auth</font></tt>, <tt><font size=+1>attach</font></tt>, <tt><font size=+1>walk</font></tt>, <tt><font size=+1>open</font></tt>, and <tt><font size=+1>create</font></tt> requests
convey a <i>qid</i> field back to the client. The qid represents the
server&#8217;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 <i>version</i>,
then the eight-byte qid <i>path</i>. 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.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
An existing file can be <tt><font size=+1>opened</font></tt>, or a new file may be <tt><font size=+1>created</font></tt> in
the current (directory) file. I/O of a given number of bytes at
a given offset on an open file is done by <tt><font size=+1>read</font></tt> and <tt><font size=+1>write</font></tt>.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
A client should <tt><font size=+1>clunk</font></tt> any fid that is no longer needed. The <tt><font size=+1>remove</font></tt>
transaction deletes files.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<tt><font size=+1>Openfd</font></tt> 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 <i>openfd</i>(9p) and <a href="../man3/9pclient.html"><i>9pclient</i>(3)</a> for details.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The <tt><font size=+1>stat</font></tt> transaction retrieves information about the file. The
<i>stat</i> field in the reply includes the file&#8217;s name, access permissions
(read, write and execute for owner, group and public), access
and modification times, and owner and group identifications (see
<a href="../man3/stat.html"><i>stat</i>(3)</a>). The owner and group identifications are textual
names. The <tt><font size=+1>wstat</font></tt> transaction allows some of a file&#8217;s properties
to be changed.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
A request can be aborted with a flush request. When a server receives
a <tt><font size=+1>Tflush</font></tt>, it should not reply to the message with tag <i>oldtag</i> (unless
it has already replied), and it should immediately send an <tt><font size=+1>Rflush</font></tt>.
The client must wait until it gets the <tt><font size=+1>Rflush</font></tt> (even if the reply
to the original message arrives in the interim),
at which point <i>oldtag</i> may be reused.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
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 <tt><font size=+1>Rstat</font></tt> of the file or <tt><font size=+1>Rread</font></tt> 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
<tt><font size=+1>Rerror</font></tt> message should be truncated if necessary, since the string
is only advisory and in some sense arbitrary.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
Most programs do not see the 9P protocol directly; on Plan 9,
calls to library routines that access files are translated by
the kernel&#8217;s mount driver into 9P messages.<br>
<p><font size=+1><b>Unix </b></font><br>
On Unix, 9P services are posted as Unix domain sockets in a well-known
directory (see <a href="../man3/getns.html"><i>getns</i>(3)</a> and <a href="../man4/9pserve.html"><i>9pserve</i>(4)</a>). Clients connect to these
servers using a 9P client library (see <a href="../man3/9pclient.html"><i>9pclient</i>(3)</a>).<br>
</table>
<p><font size=+1><b>DIRECTORIES </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
Directories are created by <tt><font size=+1>create</font></tt> with <tt><font size=+1>DMDIR</font></tt> set in the permissions
argument (see <i>stat</i>(9P)). The members of a directory can be found
with <i>read</i>(9P). All directories must support <tt><font size=+1>walks</font></tt> to the directory
<tt><font size=+1>..</font></tt> (dot-dot) meaning parent directory, although by convention
directories contain no explicit entry for <tt><font size=+1>..</font></tt> or <tt><font size=+1>.
</font></tt>(dot). The parent of the root directory of a server&#8217;s tree is
itself.<br>
</table>
<p><font size=+1><b>ACCESS PERMISSIONS </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
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.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
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</i> who has special privileges (see <i>stat</i>(9P) and Plan
9&#8217;s <i>users</i>(6)). Every file request has an implicit user id (copied
from the original <tt><font size=+1>attach</font></tt>) and an implicit set of groups (every
group of which the user is a member).
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
Each file has an associated <i>owner</i> and <i>group</i> id and three sets
of permissions: those of the owner, those of the group, and those
of &#8220;other&#8221; 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&#8217;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
<tt><font size=+1>walk</font></tt> in a directory is regarded as executing the directory, not
reading it. Permissions are kept in the low-order bits of the
file <i>mode</i>: 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.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The file <i>mode</i> contains some additional attributes besides the
permissions. If bit 31 (<tt><font size=+1>DMDIR</font></tt>) is set, the file is a directory;
if bit 30 (<tt><font size=+1>DMAPPEND</font></tt>) is set, the file is append-only (offset is
ignored in writes); if bit 29 (<tt><font size=+1>DMEXCL</font></tt>) is set, the file is exclusive-use
(only one client may have it open at a time); if bit 27 (<tt><font size=+1>DMAUTH</font></tt>)
is
set, the file is an authentication file established by <tt><font size=+1>auth</font></tt> messages;
if bit 26 (<tt><font size=+1>DMTMP</font></tt>) 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: <tt><font size=+1>QTDIR</font></tt>, <tt><font size=+1>QTAPPEND</font></tt>, <tt><font size=+1>QTEXCL</font></tt>,
(skipping one bit) <tt><font size=+1>QTAUTH</font></tt>, and <tt><font size=+1>QTTMP</font></tt>. The name <tt><font size=+1>QTFILE</font></tt>, defined
to be zero, identifies the value of the type for a plain file.<br>
</table>
<td width=20>
<tr height=20><td>
</table>
<!-- TRAILER -->
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=15><td width=10><td><td width=10>
<tr><td><td>
<center>
<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a>
</center>
</table>
<!-- TRAILER -->
</body></html>

154
man/man9/open.html Normal file
View file

@ -0,0 +1,154 @@
<head>
<title>open(9P) - Plan 9 from User Space</title>
<meta content="text/html; charset=utf-8" http-equiv=Content-Type>
</head>
<body bgcolor=#ffffff>
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=10><td>
<tr><td width=20><td>
<tr><td width=20><td><b>OPEN(9P)</b><td align=right><b>OPEN(9P)</b>
<tr><td width=20><td colspan=2>
<br>
<p><font size=+1><b>NAME </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
open, create &ndash; prepare a fid for I/O on an existing or new file<br>
</table>
<p><font size=+1><b>SYNOPSIS </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<i>size</i>[4] <tt><font size=+1>Topen</font></tt> <i>tag</i>[2] <i>fid</i>[4] <i>mode</i>[1]<br>
<i>size</i>[4] <tt><font size=+1>Ropen</font></tt> <i>tag</i>[2] <i>qid</i>[13] <i>iounit</i>[4]
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>size</i>[4] <tt><font size=+1>Tcreate</font></tt> <i>tag</i>[2] <i>fid</i>[4] <i>name</i>[<i>s</i>] <i>perm</i>[4] <i>mode</i>[1]<br>
<i>size</i>[4] <tt><font size=+1>Rcreate</font></tt> <i>tag</i>[2] <i>qid</i>[13] <i>iounit</i>[4]<br>
</table>
<p><font size=+1><b>DESCRIPTION </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
The <tt><font size=+1>open</font></tt> request asks the file server to check permissions and
prepare a fid for I/O with subsequent <tt><font size=+1>read</font></tt> and <tt><font size=+1>write</font></tt> messages.
The <i>mode</i> field determines the type of I/O: 0 (called <tt><font size=+1>OREAD</font></tt> in
<tt><font size=+1>&lt;libc.h&gt;</font></tt>), 1 (<tt><font size=+1>OWRITE</font></tt>), 2 (<tt><font size=+1>ORDWR</font></tt>), and 3 (<tt><font size=+1>OEXEC</font></tt>) mean <i>read access,
write access, read and write access,</i> and <i>execute
access,</i> to be checked against the permissions for the file. In
addition, if <i>mode</i> has the <tt><font size=+1>OTRUNC</font></tt> (<tt><font size=+1>0x10</font></tt>) bit set, the file is to
be truncated, which requires write permission (if the file is
append-only, and permission is granted, the <tt><font size=+1>open</font></tt> succeeds but
the file will not be truncated); if the <i>mode</i> has the <tt><font size=+1>ORCLOSE</font></tt> (<tt><font size=+1>0x40</font></tt>)
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</i> 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 <i>stat</i>(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</i> has been clunked. All these
permissions are checked at the time of the <tt><font size=+1>open</font></tt> request; subsequent
changes to the permissions of files do not affect the ability
to read, write, or remove an open file.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The <tt><font size=+1>create</font></tt> request asks the file server to create a new file with
the <i>name</i> supplied, in the directory (<i>dir</i>) represented by <i>fid</i>,
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 <i>dir</i>, and the permissions are the value of
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<tt><font size=+1>perm &amp; (~0666 | (dir.perm &amp; 0666)) <br>
</font></tt>
</table>
</table>
if a regular file is being created and<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<tt><font size=+1>perm &amp; (~0777 | (dir.perm &amp; 0777)) <br>
</font></tt>
</table>
</table>
if a directory is being created. This means, for example, that
if the <tt><font size=+1>create</font></tt> allows read permission to others, but the containing
directory does not, then the created file will not allow others
to read the file.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
Finally, the newly created file is opened according to <i>mode</i>, and
<i>fid</i> will represent the newly opened file. <i>Mode</i> is not checked
against the permissions in <i>perm</i>. The <i>qid</i> for the new file is returned
with the <tt><font size=+1>create</font></tt> reply message.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
Directories are created by setting the <tt><font size=+1>DMDIR</font></tt> bit (<tt><font size=+1>0x80000000</font></tt>)
in the <i>perm</i>.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The names <tt><font size=+1>.</font></tt> and <tt><font size=+1>..</font></tt> are special; it is illegal to create files
with these names.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
It is an error for either of these messages if the fid is already
the product of a successful <tt><font size=+1>open</font></tt> or <tt><font size=+1>create</font></tt> message.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
An attempt to <tt><font size=+1>create</font></tt> a file in a directory where the given <i>name</i>
already exists will be rejected; in this case, the <i>fscreate</i> call
(see <a href="../man3/9pclient.html"><i>9pclient</i>(3)</a>) uses <tt><font size=+1>open</font></tt> with truncation. The algorithm used
by the <i>create</i> system call is: first walk to the directory to contain
the file. If that fails, return an error. Next <tt><font size=+1>walk</font></tt> to the
specified file. If the <tt><font size=+1>walk</font></tt> succeeds, send a request to <tt><font size=+1>open</font></tt> and
truncate the file and return the result, successful or not. If
the <tt><font size=+1>walk</font></tt> 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 <tt><font size=+1>walk</font></tt> and <tt><font size=+1>open</font></tt> again.
</table>
<p><font size=+1><b>ENTRY POINTS </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<i>Fsopen</i> and <i>fscreate</i> (see <a href="../man3/9pclient.html"><i>9pclient</i>(3)</a>) both generate <tt><font size=+1>open</font></tt> messages;
only <i>fscreate</i> generates a <tt><font size=+1>create</font></tt> message. The <tt><font size=+1>iounit</font></tt> associated
with an open file may be discovered by calling <i>fsiounit</i>.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
For programs that need atomic file creation, without the race
that exists in the <tt><font size=+1>open&#8722;create</font></tt> sequence described above, <i>fscreate</i>
does the following. If the <tt><font size=+1>OEXCL</font></tt> (<tt><font size=+1>0x1000</font></tt>) bit is set in the <i>mode</i>
for a <i>fscreate</i> call, the <tt><font size=+1>open</font></tt> message is not sent; the kernel
issues only the <tt><font size=+1>create</font></tt>. Thus, if the file exists, <i>fscreate
</i>will draw an error, but if it doesn&#8217;t and the <i>fscreate</i> call succeeds,
the process issuing the <i>fscreate</i> is guaranteed to be the one that
created the file.<br>
</table>
<td width=20>
<tr height=20><td>
</table>
<!-- TRAILER -->
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=15><td width=10><td><td width=10>
<tr><td><td>
<center>
<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a>
</center>
</table>
<!-- TRAILER -->
</body></html>

96
man/man9/read.html Normal file
View file

@ -0,0 +1,96 @@
<head>
<title>read(9P) - Plan 9 from User Space</title>
<meta content="text/html; charset=utf-8" http-equiv=Content-Type>
</head>
<body bgcolor=#ffffff>
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=10><td>
<tr><td width=20><td>
<tr><td width=20><td><b>READ(9P)</b><td align=right><b>READ(9P)</b>
<tr><td width=20><td colspan=2>
<br>
<p><font size=+1><b>NAME </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
read, write &ndash; transfer data from and to a file<br>
</table>
<p><font size=+1><b>SYNOPSIS </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<i>size</i>[4] <tt><font size=+1>Tread</font></tt> <i>tag</i>[2] <i>fid</i>[4] <i>offset</i>[8] <i>count</i>[4]<br>
<i>size</i>[4] <tt><font size=+1>Rread</font></tt> <i>tag</i>[2] <i>count</i>[4] <i>data</i>[<i>count</i>]
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>size</i>[4] <tt><font size=+1>Twrite</font></tt> <i>tag</i>[2] <i>fid</i>[4] <i>offset</i>[8] <i>count</i>[4] <i>data</i>[<i>count</i>]<br>
<i>size</i>[4] <tt><font size=+1>Rwrite</font></tt> <i>tag</i>[2] <i>count</i>[4]<br>
</table>
<p><font size=+1><b>DESCRIPTION </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
The <tt><font size=+1>read</font></tt> request asks for <i>count</i> bytes of data from the file identified
by <i>fid</i>, which must be opened for reading, starting <i>offset</i> bytes
after the beginning of the file. The bytes are returned with the
<tt><font size=+1>read</font></tt> reply message.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The <i>count</i> field in the reply indicates the number of bytes returned.
This may be less than the requested amount. If the <i>offset</i> field
is greater than or equal to the number of bytes in the file, a
count of zero will be returned.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
For directories, <tt><font size=+1>read</font></tt> returns an integral number of directory
entries exactly as in <tt><font size=+1>stat</font></tt> (see <i>stat</i>(9P)), one for each member
of the directory. The <tt><font size=+1>read</font></tt> request message must have <tt><font size=+1>offset</font></tt> equal
to zero or the value of <tt><font size=+1>offset</font></tt> in the previous <tt><font size=+1>read</font></tt> on the directory,
plus the number of bytes returned in the previous
<tt><font size=+1>read</font></tt>. In other words, seeking other than to the beginning is illegal
in a directory.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The <tt><font size=+1>write</font></tt> request asks that <i>count</i> bytes of data be recorded in
the file identified by <i>fid</i>, which must be opened for writing,
starting <i>offset</i> 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 <i>offset</i>. Directories may not be written.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The <tt><font size=+1>write</font></tt> reply records the number of bytes actually written.
It is usually an error if this is not the same as requested.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
Because 9P implementations may limit the size of individual messages,
more than one message may be produced by a single <i>read</i> or <i>write</i>
call. The <i>iounit</i> field returned by <i>open</i>(9P), if non-zero, reports
the maximum size that is guaranteed to be transferred atomically.<br>
</table>
<p><font size=+1><b>ENTRY POINTS </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<i>Fsread</i> and <i>fswrite</i> (see <a href="../man3/9pclient.html"><i>9pclient</i>(3)</a>) generate the corresponding
messages. Because they take an offset parameter, the <i>fspread</i> and
<i>fspwrite</i> calls correspond more directly to the 9P messages. Although
<i>fsseek</i> affects the offset, it does not generate a message.<br>
</table>
<td width=20>
<tr height=20><td>
</table>
<!-- TRAILER -->
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=15><td width=10><td><td width=10>
<tr><td><td>
<center>
<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a>
</center>
</table>
<!-- TRAILER -->
</body></html>

70
man/man9/remove.html Normal file
View file

@ -0,0 +1,70 @@
<head>
<title>remove(9P) - Plan 9 from User Space</title>
<meta content="text/html; charset=utf-8" http-equiv=Content-Type>
</head>
<body bgcolor=#ffffff>
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=10><td>
<tr><td width=20><td>
<tr><td width=20><td><b>REMOVE(9P)</b><td align=right><b>REMOVE(9P)</b>
<tr><td width=20><td colspan=2>
<br>
<p><font size=+1><b>NAME </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
remove &ndash; remove a file from a server<br>
</table>
<p><font size=+1><b>SYNOPSIS </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<i>size</i>[4] <tt><font size=+1>Tremove</font></tt> <i>tag</i>[2] <i>fid</i>[4]<br>
<i>size</i>[4] <tt><font size=+1>Rremove</font></tt> <i>tag</i>[2]<br>
</table>
<p><font size=+1><b>DESCRIPTION </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
The <tt><font size=+1>remove</font></tt> request asks the file server both to remove the file
represented by <i>fid</i> and to <tt><font size=+1>clunk</font></tt> the <i>fid</i>, even if the remove fails.
This request will fail if the client does not have write permission
in the parent directory.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
It is correct to consider <tt><font size=+1>remove</font></tt> to be a <tt><font size=+1>clunk</font></tt> with the side effect
of removing the file if permissions allow.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
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 &#8220;phase error.&#8221; <i>U9fs</i>
follows the semantics of the underlying Unix file system, so other
fids typically remain usable.<br>
</table>
<p><font size=+1><b>ENTRY POINTS </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<i>Fsremove</i> (see <a href="../man3/9pclient.html"><i>9pclient</i>(3)</a>) generates <tt><font size=+1>remove</font></tt> messages.<br>
</table>
<td width=20>
<tr height=20><td>
</table>
<!-- TRAILER -->
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=15><td width=10><td><td width=10>
<tr><td><td>
<center>
<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a>
</center>
</table>
<!-- TRAILER -->
</body></html>

258
man/man9/stat.html Normal file
View file

@ -0,0 +1,258 @@
<head>
<title>stat(9P) - Plan 9 from User Space</title>
<meta content="text/html; charset=utf-8" http-equiv=Content-Type>
</head>
<body bgcolor=#ffffff>
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=10><td>
<tr><td width=20><td>
<tr><td width=20><td><b>STAT(9P)</b><td align=right><b>STAT(9P)</b>
<tr><td width=20><td colspan=2>
<br>
<p><font size=+1><b>NAME </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
stat, wstat &ndash; inquire or change file attributes<br>
</table>
<p><font size=+1><b>SYNOPSIS </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<i>size</i>[4] <tt><font size=+1>Tstat</font></tt> <i>tag</i>[2] <i>fid</i>[4]<br>
<i>size</i>[4] <tt><font size=+1>Rstat</font></tt> <i>tag</i>[2] <i>stat</i>[<i>n</i>]
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>size</i>[4] <tt><font size=+1>Twstat</font></tt> <i>tag</i>[2] <i>fid</i>[4] <i>stat</i>[<i>n</i>]<br>
<i>size</i>[4] <tt><font size=+1>Rwstat</font></tt> <i>tag</i>[2]<br>
</table>
<p><font size=+1><b>DESCRIPTION </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
The <tt><font size=+1>stat</font></tt> transaction inquires about the file identified by <i>fid</i>.
The reply will contain a machine-independent <i>directory entry</i>,
<i>stat</i>, laid out as follows:<br>
<i>size</i>[2]total byte count of the following data<br>
<i>type</i>[2]<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
for kernel use<br>
</table>
<i>dev</i>[4]for kernel use<br>
<i>qid.type</i>[1]<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
the type of the file (directory, etc.), represented as a bit vector
corresponding to the high 8 bits of the file&#8217;s mode word.<br>
</table>
<i>qid.vers</i>[4]<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
version number for given path<br>
</table>
<i>qid.path</i>[8]<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
the file server&#8217;s unique identification for the file<br>
</table>
<i>mode</i>[4]<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
permissions and flags<br>
</table>
<i>atime</i>[4]<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
last access time<br>
</table>
<i>mtime</i>[4]<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
last modification time<br>
</table>
<i>length</i>[8]<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
length of file in bytes<br>
</table>
<i>name</i>[ s ]<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
file name; must be <tt><font size=+1>/</font></tt> if the file is the root directory of the
server<br>
</table>
<i>uid</i>[ s ]<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
owner name<br>
</table>
<i>gid</i>[ s ]<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
group name<br>
</table>
<i>muid</i>[ s ]<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
name of the user who last modified the file
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</table>
Integers in this encoding are in little-endian order (least significant
byte first). The <i>convM2D</i> and <i>convD2M</i> routines (see <a href="../man3/fcall.html"><i>fcall</i>(3)</a>) convert
between directory entries and a C structure called a <tt><font size=+1>Dir</font></tt>.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The <i>mode</i> contains permission bits as described in <i>intro</i>(9P) and
the following: <tt><font size=+1>0x80000000</font></tt> (<tt><font size=+1>DMDIR</font></tt>, this file is a directory), <tt><font size=+1>0x40000000</font></tt>
(<tt><font size=+1>DMAPPEND</font></tt>, append only), <tt><font size=+1>0x20000000</font></tt> (<tt><font size=+1>DMEXCL</font></tt>, exclusive use), <tt><font size=+1>0x04000000</font></tt>
(<tt><font size=+1>DMTMP</font></tt>, temporary); these are echoed in <tt><font size=+1>Qid.type</font></tt>. Writes to append-only
files always
place their data at the end of the file; the <i>offset</i> in the <tt><font size=+1>write</font></tt>
message is ignored, as is the <tt><font size=+1>OTRUNC</font></tt> 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&#8217;s <i>fossil</i>(4)).
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The two time fields are measured in seconds since the epoch (Jan
1 00:00 1970 GMT). The <i>mtime</i> field reflects the time of the last
change of content (except when later changed by <tt><font size=+1>wstat</font></tt>). For a
plain file, <i>mtime</i> is the time of the most recent <tt><font size=+1>create</font></tt>, <tt><font size=+1>open</font></tt>
with truncation, or <tt><font size=+1>write</font></tt>; for a directory it is the time of
the most recent <tt><font size=+1>remove</font></tt>, <tt><font size=+1>create</font></tt>, or <tt><font size=+1>wstat</font></tt> of a file in the directory.
Similarly, the <i>atime</i> field records the last <tt><font size=+1>read</font></tt> of the contents;
also it is set whenever <i>mtime</i> is set. In addition, for a directory,
it is set by an <tt><font size=+1>attach</font></tt>, <tt><font size=+1>walk</font></tt>, or <tt><font size=+1>create</font></tt>, all whether successful
or not.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The <i>muid</i> field names the user whose actions most recently changed
the <i>mtime</i> of the file.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The <i>length</i> records the number of bytes in the file. Directories
and most files representing devices have a conventional length
of 0.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The <tt><font size=+1>stat</font></tt> request requires no special permissions.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The <tt><font size=+1>wstat</font></tt> request can change some of the file status information.
The <i>name</i> 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</i> 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</i> and <i>mtime</i> can be changed by the owner
of the file or the group leader of the file&#8217;s current group. The
directory bit cannot be changed by a <tt><font size=+1>wstat</font></tt>; the other
defined permission and mode bits can. The <i>gid</i> can be changed:
by the owner if also a member of the new group; or by the group
leader of the file&#8217;s current group if also leader of the new group
(see <i>intro</i>(9P) for more information about permissions, users,
and groups). None of the other data can be altered by a
<tt><font size=+1>wstat</font></tt> 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&#8217;s <i>fsconfig</i>(8).)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
Either all the changes in <tt><font size=+1>wstat</font></tt> request happen, or none of them
does: if the request succeeds, all changes were made; if it fails,
none were.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
A <tt><font size=+1>wstat</font></tt> request can avoid modifying some properties of the file
by providing explicit &#8220;don&#8217;t touch&#8221; values in the <tt><font size=+1>stat</font></tt> 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</i> the elements of the directory entry in a <tt><font size=+1>Twstat
</font></tt>message are &#8220;don&#8217;t touch&#8221; 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 <tt><font size=+1>Rwstat</font></tt> message
is returned. (Consider the message to mean, &#8220;make the state of
the file exactly what it claims to be.&#8221;)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
A <i>read</i> of a directory yields an integral number of directory entries
in the machine independent encoding given above (see <i>read</i>(9P)).
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
Note that since the <tt><font size=+1>stat</font></tt> information is sent as a 9P variable-length
datum, it is limited to a maximum of 65535 bytes.<br>
</table>
<p><font size=+1><b>ENTRY POINTS </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<tt><font size=+1>Stat</font></tt> messages are generated by <i>fsdirfstat</i> and <i>fsdirstat</i> (see <a href="../man3/9pclient.html"><i>9pclient</i>(3)</a>).
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<tt><font size=+1>Wstat</font></tt> messages are generated by <i>fsdirfwstat</i> and <i>fsdirwstat</i>.<br>
</table>
<p><font size=+1><b>BUGS </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
To make the contents of a directory, such as returned by <i>read</i>(9P),
easy to parse, each directory entry begins with a size field.
For consistency, the entries in <tt><font size=+1>Twstat</font></tt> and <tt><font size=+1>Rstat</font></tt> messages also
contain their size, which means the size appears twice. For example,
the <tt><font size=+1>Rstat</font></tt> message is formatted as &#8220;(4+1+2+2+<i>n</i>)[4]
<tt><font size=+1>Rstat</font></tt> <i>tag</i>[2] <i>n</i>[2] (<i>n</i>-2)[2] <i>type</i>[2] <i>dev</i>[4]...,&#8221; where <i>n</i> is the
value returned by <tt><font size=+1>convD2M</font></tt>.<br>
</table>
<td width=20>
<tr height=20><td>
</table>
<!-- TRAILER -->
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=15><td width=10><td><td width=10>
<tr><td><td>
<center>
<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a>
</center>
</table>
<!-- TRAILER -->
</body></html>

100
man/man9/version.html Normal file
View file

@ -0,0 +1,100 @@
<head>
<title>version(9P) - Plan 9 from User Space</title>
<meta content="text/html; charset=utf-8" http-equiv=Content-Type>
</head>
<body bgcolor=#ffffff>
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=10><td>
<tr><td width=20><td>
<tr><td width=20><td><b>VERSION(9P)</b><td align=right><b>VERSION(9P)</b>
<tr><td width=20><td colspan=2>
<br>
<p><font size=+1><b>NAME </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
version &ndash; negotiate protocol version<br>
</table>
<p><font size=+1><b>SYNOPSIS </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<i>size</i>[4] <tt><font size=+1>Tversion</font></tt> <i>tag</i>[2] <i>msize</i>[4] <i>version</i>[<i>s</i>]<br>
<i>size</i>[4] <tt><font size=+1>Rversion</font></tt> <i>tag</i>[2] <i>msize</i>[4] <i>version</i>[<i>s</i>]<br>
</table>
<p><font size=+1><b>DESCRIPTION </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
The <tt><font size=+1>version</font></tt> request negotiates the protocol version and message
size to be used on the connection and initializes the connection
for I/O. <tt><font size=+1>Tversion</font></tt> must be the first message sent on the 9P connection,
and the client cannot issue any further requests until it has
received the <tt><font size=+1>Rversion</font></tt> reply. The <i>tag</i> should be
<tt><font size=+1>NOTAG</font></tt> (value <tt><font size=+1>(ushort)~0</font></tt>) for a <tt><font size=+1>version</font></tt> message.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The client suggests a maximum message size, <tt><font size=+1>msize</font></tt>, 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 <tt><font size=+1>size</font></tt> field and extending through the message,
but excludes enveloping transport protocols. The
server responds with its own maximum, <tt><font size=+1>msize</font></tt>, which must be less
than or equal to the client&#8217;s value. Thenceforth, both sides of
the connection must honor this limit.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The <tt><font size=+1>version</font></tt> string identifies the level of the protocol. The string
must always begin with the two characters &#8220;<tt><font size=+1>9P</font></tt>&#8221;. If the server
does not understand the client&#8217;s version string, it should respond
with an <tt><font size=+1>Rversion</font></tt> message (not <tt><font size=+1>Rerror</font></tt>) with the <tt><font size=+1>version</font></tt> string
the 7 characters &#8220;<tt><font size=+1>unknown</font></tt>&#8221;.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The server may respond with the client&#8217;s version string, or a
version string identifying an earlier defined protocol version.
Currently, the only defined version is the 6 characters &#8220;<tt><font size=+1>9P2000</font></tt>&#8221;.
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 <tt><font size=+1>9P</font></tt><i>nnnn</i>, where <i>nnnn</i> is less than or equal to the digits sent
by the client.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The client and server will use the protocol version defined by
the server&#8217;s response for all subsequent communication on the
connection.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
A successful <tt><font size=+1>version</font></tt> request initializes the connection. All outstanding
I/O on the connection is aborted; all active fids are freed (&#8216;clunked&#8217;)
automatically. The set of messages between <tt><font size=+1>version</font></tt> requests is
called a <i>session</i>.<br>
</table>
<p><font size=+1><b>ENTRY POINTS </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<i>Fsversion</i> (see <a href="../man3/9pclient.html"><i>9pclient</i>(3)</a>) generates <tt><font size=+1>version</font></tt> messages; it is
called automatically by <i>fsmount</i>.<br>
</table>
<td width=20>
<tr height=20><td>
</table>
<!-- TRAILER -->
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=15><td width=10><td><td width=10>
<tr><td><td>
<center>
<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a>
</center>
</table>
<!-- TRAILER -->
</body></html>

119
man/man9/walk.html Normal file
View file

@ -0,0 +1,119 @@
<head>
<title>walk(9P) - Plan 9 from User Space</title>
<meta content="text/html; charset=utf-8" http-equiv=Content-Type>
</head>
<body bgcolor=#ffffff>
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=10><td>
<tr><td width=20><td>
<tr><td width=20><td><b>WALK(9P)</b><td align=right><b>WALK(9P)</b>
<tr><td width=20><td colspan=2>
<br>
<p><font size=+1><b>NAME </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
walk &ndash; descend a directory hierarchy<br>
</table>
<p><font size=+1><b>SYNOPSIS </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<i>size</i>[4] <tt><font size=+1>Twalk</font></tt> <i>tag</i>[2] <i>fid</i>[4] <i>newfid</i>[4] <i>nwname</i>[2] <i>nwname</i>*(<i>wname</i>[<i>s</i>])<br>
<i>size</i>[4] <tt><font size=+1>Rwalk</font></tt> <i>tag</i>[2] <i>nwqid</i>[2] <i>nwqid</i>*(<i>qid</i>[13])<br>
</table>
<p><font size=+1><b>DESCRIPTION </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
The <tt><font size=+1>walk</font></tt> request carries as arguments an existing <i>fid</i> and a proposed
<i>newfid</i> (which must not be in use unless it is the same as <i>fid</i>)
that the client wishes to associate with the result of traversing
the directory hierarchy by &#8216;walking&#8217; the hierarchy using the successive
path name elements <tt><font size=+1>wname</font></tt>. The <i>fid</i> must represent
a directory unless zero path name elements are specified.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The <i>fid</i> must be valid in the current session and must not have
been opened for I/O by an <tt><font size=+1>open</font></tt> or <tt><font size=+1>create</font></tt> message. If the full
sequence of <tt><font size=+1>nwname</font></tt> elements is walked successfully, <i>newfid</i> will
represent the file that results. If not, <i>newfid</i> (and <tt><font size=+1>fid</font></tt>) will
be unaffected. However, if <i>newfid</i> is in use or otherwise illegal,
an <tt><font size=+1>Rerror</font></tt> is returned.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The name &#8220;<tt><font size=+1>..</font></tt>&#8221; (dot-dot) represents the parent directory. The name
&#8220;<tt><font size=+1>.</font></tt>&#8221; (dot), meaning the current directory, is not used in the protocol.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
It is legal for <tt><font size=+1>nwname</font></tt> to be zero, in which case <i>newfid</i> will represent
the same file as <i>fid</i> and the <tt><font size=+1>walk</font></tt> will usually succeed; this is
equivalent to walking to dot. The rest of this discussion assumes
<tt><font size=+1>nwname</font></tt> is greater than zero.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The <tt><font size=+1>nwname</font></tt> path name elements <tt><font size=+1>wname</font></tt> are walked in order, &#8220;elementwise&#8221;.
For the first elementwise walk to succeed, the file identified
by <i>fid</i> must be a directory, and the implied user of the request
must have permission to search the directory (see <i>intro</i>(9P)).
Subsequent elementwise walks have equivalent
restrictions applied to the implicit fid that results from the
preceding elementwise walk.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
If the first element cannot be walked for any reason, <tt><font size=+1>Rerror</font></tt> is
returned. Otherwise, the walk will return an <tt><font size=+1>Rwalk</font></tt> message containing
<i>nwqid</i> qids corresponding, in order, to the files that are visited
by the <i>nwqid</i> successful elementwise walks; <i>nwqid</i> is therefore
either <tt><font size=+1>nwname</font></tt> or the index of the first elementwise
walk that failed. The value of <i>nwqid</i> cannot be zero unless <tt><font size=+1>nwname</font></tt>
is zero. Also, <i>nwqid</i> will always be less than or equal to <tt><font size=+1>nwname</font></tt>.
Only if it is equal, however, will <i>newfid</i> be affected, in which
case <i>newfid</i> will represent the file reached by the final elementwise
walk requested in the message.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
A <tt><font size=+1>walk</font></tt> of the name &#8220;<tt><font size=+1>..</font></tt>&#8221; in the root directory of a server is equivalent
to a walk with no name elements.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
If <i>newfid</i> is the same as <i>fid</i>, the above discussion applies, with
the obvious difference that if the walk changes the state of <i>newfid</i>,
it also changes the state of <i>fid</i>; and if <i>newfid</i> is unaffected,
then <i>fid</i> is also unaffected.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
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 <tt><font size=+1>MAXWELEM</font></tt> in <a href="../man3/fcall.html"><i>fcall</i>(3)</a>. 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.<br>
</table>
<p><font size=+1><b>ENTRY POINTS </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<i>Fswalk</i> (see <a href="../man3/9pclient.html"><i>9pclient</i>(3)</a>) generates walk messages. One or more
walk messages may be generated by any call that evaluates file
names: <i>fsopen</i>, <i>fsopenfd</i>, <i>fsdirstat</i>, <i>fsdirwstat</i>.<br>
</table>
<td width=20>
<tr height=20><td>
</table>
<!-- TRAILER -->
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=15><td width=10><td><td width=10>
<tr><td><td>
<center>
<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a>
</center>
</table>
<!-- TRAILER -->
</body></html>