diff options
| author | rsc <devnull@localhost> | 2005-01-14 03:45:44 +0000 |
|---|---|---|
| committer | rsc <devnull@localhost> | 2005-01-14 03:45:44 +0000 |
| commit | 78e51a8c6678b6e3dff3d619aa786669f531f4bc (patch) | |
| tree | 015e00fde4fc837fd31b705e18d17dc913829388 /man/man9 | |
| parent | 2634795b5f0053bc0ff08e5d7bbc0eda8efea061 (diff) | |
| download | plan9port-78e51a8c6678b6e3dff3d619aa786669f531f4bc.tar.gz plan9port-78e51a8c6678b6e3dff3d619aa786669f531f4bc.tar.bz2 plan9port-78e51a8c6678b6e3dff3d619aa786669f531f4bc.zip | |
checkpoint
Diffstat (limited to 'man/man9')
| -rw-r--r-- | man/man9/attach.html | 107 | ||||
| -rw-r--r-- | man/man9/clunk.html | 66 | ||||
| -rw-r--r-- | man/man9/error.html | 53 | ||||
| -rw-r--r-- | man/man9/flush.html | 98 | ||||
| -rw-r--r-- | man/man9/index.html | 69 | ||||
| -rw-r--r-- | man/man9/intro.html | 344 | ||||
| -rw-r--r-- | man/man9/open.html | 154 | ||||
| -rw-r--r-- | man/man9/read.html | 96 | ||||
| -rw-r--r-- | man/man9/remove.html | 70 | ||||
| -rw-r--r-- | man/man9/stat.html | 258 | ||||
| -rw-r--r-- | man/man9/version.html | 100 | ||||
| -rw-r--r-- | man/man9/walk.html | 119 |
12 files changed, 1534 insertions, 0 deletions
diff --git a/man/man9/attach.html b/man/man9/attach.html new file mode 100644 index 00000000..fda46be2 --- /dev/null +++ b/man/man9/attach.html @@ -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 – 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’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><fcall.h></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’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’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> diff --git a/man/man9/clunk.html b/man/man9/clunk.html new file mode 100644 index 00000000..34aa001f --- /dev/null +++ b/man/man9/clunk.html @@ -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 – 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> diff --git a/man/man9/error.html b/man/man9/error.html new file mode 100644 index 00000000..ed8b9c6c --- /dev/null +++ b/man/man9/error.html @@ -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 – 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−1</font></tt> + bytes; <tt><font size=+1>ERRMAX</font></tt> is defined in <tt><font size=+1><libc.h></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> diff --git a/man/man9/flush.html b/man/man9/flush.html new file mode 100644 index 00000000..20544557 --- /dev/null +++ b/man/man9/flush.html @@ -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 – 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> diff --git a/man/man9/index.html b/man/man9/index.html new file mode 100644 index 00000000..76fb6bdb --- /dev/null +++ b/man/man9/index.html @@ -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 – 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 – 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 – 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 – 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 – 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 – 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 – 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 – 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 – 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 – 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 – 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> diff --git a/man/man9/intro.html b/man/man9/intro.html new file mode 100644 index 00000000..226a94eb --- /dev/null +++ b/man/man9/intro.html @@ -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 – 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 <fcall.h><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><fcall.h></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><fcall.h></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 “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 <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’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’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’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’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’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’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 “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 + <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> diff --git a/man/man9/open.html b/man/man9/open.html new file mode 100644 index 00000000..b893119b --- /dev/null +++ b/man/man9/open.html @@ -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 – 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><libc.h></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 & (~0666 | (dir.perm & 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 & (~0777 | (dir.perm & 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−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’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> diff --git a/man/man9/read.html b/man/man9/read.html new file mode 100644 index 00000000..c524d8de --- /dev/null +++ b/man/man9/read.html @@ -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 – 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> diff --git a/man/man9/remove.html b/man/man9/remove.html new file mode 100644 index 00000000..162db8bc --- /dev/null +++ b/man/man9/remove.html @@ -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 – 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 “phase error.” <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> diff --git a/man/man9/stat.html b/man/man9/stat.html new file mode 100644 index 00000000..eb5c9c4a --- /dev/null +++ b/man/man9/stat.html @@ -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 – 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’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’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’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’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’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’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 “don’t touch” 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 “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 <tt><font size=+1>Rwstat</font></tt> message + is returned. (Consider the message to mean, “make the state of + the file exactly what it claims to be.”) + <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 “(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]...,” 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> diff --git a/man/man9/version.html b/man/man9/version.html new file mode 100644 index 00000000..3d382f6b --- /dev/null +++ b/man/man9/version.html @@ -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 – 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’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 “<tt><font size=+1>9P</font></tt>”. If the server + does not understand the client’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 “<tt><font size=+1>unknown</font></tt>”. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + 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 “<tt><font size=+1>9P2000</font></tt>”. + 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’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 (‘clunked’) + 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> diff --git a/man/man9/walk.html b/man/man9/walk.html new file mode 100644 index 00000000..32a72a9e --- /dev/null +++ b/man/man9/walk.html @@ -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 – 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 ‘walking’ 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 “<tt><font size=+1>..</font></tt>” (dot-dot) represents the parent directory. The name + “<tt><font size=+1>.</font></tt>” (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, “elementwise”. + 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 “<tt><font size=+1>..</font></tt>” 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> |