Unix/Linux Go Back    

Plan 9 - man page for 0intro (plan9 section 5)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)

INTRO(5)										 INTRO(5)

       intro - introduction to the Plan 9 File Protocol, 9P

       #include <fcall.h>

       A  Plan	9  server 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
       clients to navigate the hierarchy, and to create, remove, read, and write files.  The pro-
       totypical server is a separate machine that stores large numbers of user files  on  perma-
       nent media; such a machine is called, somewhat confusingly, a file server.  Another possi-
       bility for a server is to synthesize files on demand, perhaps based on information on data
       structures  inside  the	kernel;  the proc(3) kernel device is a part of the Plan 9 kernel
       that does this.	User programs can also act as servers.

       A connection to a server is a bidirectional communication path  from  the  client  to  the
       server.	 There may be a single client or multiple clients sharing the same connection.	A
       server's file tree is attached to a process group's name space by bind(2) and mount calls;
       see  intro(2).  Processes in the group are then clients of the servers: system calls oper-
       ating on files are translated into requests and responses transmitted on the connection to
       the appropriate service.

       The  Plan 9 File Protocol, 9P, is used for messages between clients and servers.  A client
       transmits requests (T-messages) to a server, which subsequently	returns  replies  (R-mes-
       sages)  to  the client.	The combined acts of transmitting (receiving) a request of a par-
       ticular type, and receiving (transmitting) its reply is called a transaction of that type.

       Each message consists of a sequence of bytes.  The first byte is the message type, one  of
       the  constants  in the enumeration in the include file <fcall.h>.  The remaining bytes are
       parameters.  Each parameter consists of a fixed number of bytes (except the data fields of
       write requests or read replies); in the message descriptions below, the number of bytes in
       a field is given in brackets after the field name.  The two-, four-, and eight-byte fields
       may  hold  unsigned  integers  represented  in little-endian order (least significant byte
       first).	Fields that contain names are 28-byte strings (including a  terminal  NUL  (zero)
       byte).	Other  than the NUL terminator, all characters are legal in file names.  (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 and blank.)  Messages are transported in byte form to allow
       for machine independence; fcall(2) describes routines that convert to and from  this  form
       into a machine-dependent C structure.

	      Tnop	tag[2]
	      Rnop	tag[2]

	      Tsession	tag[2] chal[8]
	      Rsession	tag[2] chal[8] authid[28] authdom[48]

	      Rerror	tag[2] ename[64]

	      Tflush	tag[2] oldtag[2]
	      Rflush	tag[2]

	      Tattach	tag[2] fid[2] uid[28] aname[28] ticket[72] auth[13]
	      Rattach	tag[2] fid[2] qid[8] rauth[13]

	      Tclone	tag[2] fid[2] newfid[2]
	      Rclone	tag[2] fid[2]

	      Tclwalk	tag[2] fid[2] newfid[2] name[28]
	      Rclwalk	tag[2] fid[2] qid[8]

	      Twalk	tag[2] fid[2] name[28]
	      Rwalk	tag[2] fid[2] qid[8]

	      Topen	tag[2] fid[2] mode[1]
	      Ropen	tag[2] fid[2] qid[8]

	      Tcreate	tag[2] fid[2] name[28] perm[4] mode[1]
	      Rcreate	tag[2] fid[2] qid[8]

	      Tread	tag[2] fid[2] offset[8] count[2]
	      Rread	tag[2] fid[2] count[2] pad[1] data[count]

	      Twrite	tag[2] fid[2] offset[8] count[2] pad[1] data[count]
	      Rwrite	tag[2] fid[2] count[2]

	      Tclunk	tag[2] fid[2]
	      Rclunk	tag[2] fid[2]

	      Tremove	tag[2] fid[2]
	      Rremove	tag[2] fid[2]

	      Tstat	tag[2] fid[2]
	      Rstat	tag[2] fid[2] stat[116]

	      Twstat	tag[2] fid[2] stat[116]
	      Rwstat	tag[2] fid[2]

       Each  T-message	has  a	tag field, chosen and used by the client to identify the message.
       The reply to the message will have the same tag.  Clients must arrange that  no	two  out-
       standing  messages  on  the  same  connection  have the same tag.  An exception is the tag
       0xFFFF, meaning `no tag': the client can use it, when establishing a connection, to  over-
       ride tag matching in nop and session messages.

       The  type of an R-message will either be one greater than the type of the corresponding T-
       message or Rerror, indicating that the request failed.  In  the	latter	case,  the  ename
       field contains a string describing the reason for failure.

       The  nop message request has no obvious effect.	Its main purpose is in debugging the con-
       nection between a client and a server.  It is never necessary.  A session request initial-
       izes  a	connection and aborts all outstanding I/O on the connection.  The set of messages
       between session requests is called a session.

       Most T-messages contain a fid, a 16-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  stat(2) 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.

       The first fid supplied (in an attach message) will be taken by the server to refer to  the
       root  of the served file tree.  The attach identifies the user to the server and may spec-
       ify a particular file tree served by the server (for those that supply more than one).	A
       walk  message  causes  the server to change the current file associated with a fid to be a
       file in the directory that is the old current file.  Usually, a client maintains a fid for
       the root, and navigates by walks on a fid cloned from the root fid.

       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  on  one fid and respond to later requests on other fids; this is
       sometimes necessary, for example when the client reads from a file that the server synthe-
       sizes from external events such as keyboard characters.

       Replies (R-messages) to attach, walk, open, and create requests convey a qid field back to
       the client.  The qid represents the server's unique  identification  for  the  file  being
       accessed:  two  files  on the same server hierarchy are the same if and only if their qids
       are the same.  (The client may have multiple fids pointing to a single file  on	a  server
       and  hence  having  a  single  qid.)   The  eight-byte  qid fields represent two four-byte
       unsigned integers: first the qid path, then the qid  version.   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  differ-
       ent.   Directories always have the CHDIR bit (0x80000000) set in their qid path.  The ver-
       sion is a version number for a file; typically, it is incremented every time the  file  is

       An  existing  file  can be opened, or a new file may be created in the current (directory)
       file.  I/O of a given number of bytes (limited to 8192) at a given offset on an open  file
       is done by read and write.

       A  client  should  clunk any fid that is no longer needed.  The remove transaction deletes

       The stat transaction retrieves information about the file.  The stat field  in  the  reply
       includes the file's name, access permissions (read, write and execute for owner, group and
       public), access and modification times, and owner and group identifications (see stat(2)).
       The  owner and group identifications are 28-byte names.	The wstat transaction allows some
       of a file's properties to be changed.

       A request can be aborted with a Tflush request.	When  a  server  receives  a  Tflush,  it
       should  not  reply  to the message with tag oldtag (unless it has already replied), and it
       should immediately send an Rflush.  The client should ignore replies with tag oldtag until
       it gets the Rflush, at which point oldtag may be reused.

       Most  programs do not see the 9P protocol directly; instead calls to library routines that
       access files are translated by the mount driver, mnt(3), into 9P messages.

       Directories are created by  create  with  CHDIR	set  in  the  permissions  argument  (see
       stat(5)).   The	members  of  a directory can be found with read(5).  All directories must
       support walks to the directory ..  (dot-dot) meaning parent directory, although by conven-
       tion  directories  contain  no explicit entry for ..  or .  (dot).  The parent of the root
       directory of a server's tree is itself.

       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 group leader who has special privileges (see
       stat(5) and users(6)).  Every file request has an implicit user id (copied from the origi-
       nal attach) and an implicit set of groups (every group of which the user is a member).

       Each file has an associated owner and group id and three sets of permissions: those of the
       owner, those of the group, and those of ``other'' users.  When the owner  attempts  to  do
       something  to a file, the owner, group, and other permissions are consulted, and if any of
       them grant the requested permission, the operation is allowed.  For someone who is not the
       owner, but is a member of the file's group, the group and other permissions are consulted.
       For everyone else, the other permissions are used.  Each set of permissions  says  whether
       reading	is allowed, whether writing is allowed, and whether executing is allowed.  A walk
       in a directory is regarded as executing the directory, not reading  it.	 Permissions  are
       kept  in  the  low-order bits of the file mode: owner read/write/execute permission repre-
       sented 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.

       The  file  mode contains some additional attributes besides the permissions.  If bit 31 is
       set, the file is a directory; if bit 30 is set, the file is append-only (offset is ignored
       in  writes); if bit 29 is set, the file is exclusive-use (only one client may have it open
       at a time).

Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums

All times are GMT -4. The time now is 03:43 PM.