diff options
Diffstat (limited to 'man/man9/intro.html')
| -rw-r--r-- | man/man9/intro.html | 344 |
1 files changed, 0 insertions, 344 deletions
diff --git a/man/man9/intro.html b/man/man9/intro.html deleted file mode 100644 index 226a94eb..00000000 --- a/man/man9/intro.html +++ /dev/null @@ -1,344 +0,0 @@ -<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> |