glenda.party
term% ls -F
term% cat index.txt
INTRO(5)                      File Formats Manual                     INTRO(5)



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

SYNOPSIS
       #include <fcall.h>

DESCRIPTION
       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 prototypical server is a
       separate  machine  that stores large numbers of user files on permanent
       media; such a machine is called, somewhat confusingly, a  file  server.
       Another possibility for a server is to synthesize files on demand, per‐
       haps 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
       operating on files are translated into requests and responses transmit‐
       ted 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-messages) to the client.  The  combined
       acts  of  transmitting  (receiving) a request of a particular 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 num‐
       ber of bytes in a field is given in brackets after the field name.  The
       two-,  four-,  and  eight-byte fields may hold unsigned integers repre‐
       sented 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 com‐
       ponents,  but  the  protocol has no such restriction.  Plan 9 names may
       contain any printable character (that is, any character  outside  hexa‐
       decimal  00-1F and 80-9F) except slash and blank.)  Messages are trans‐
       ported in byte form to allow for  machine  independence;  fcall(2)  de‐
       scribes  routines that convert to and from this form into a machine-de‐
       pendent C structure.

MESSAGES
              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  iden‐
       tify  the  message.   The  reply to the message will have the same tag.
       Clients must arrange that no two outstanding messages on the same  con‐
       nection 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 describ‐
       ing the reason for failure.

       The nop message request has no obvious effect.  Its main purpose is  in
       debugging  the  connection  between a client and a server.  It is never
       necessary.  A session request initializes 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  re‐
       stricted 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 iden‐
       tifies the user to the server and may specify 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.  Usu‐
       ally, 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 corre‐
       sponding R-messages, but all outstanding T-messages must  specify  dif‐
       ferent tags.  The server may delay the response to a request on one fid
       and respond to later requests on other fids; this is  sometimes  neces‐
       sary,  for  example  when  the client reads from a file that the server
       synthesizes 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 rep‐
       resent two four-byte unsigned integers: first the qid  path,  then  the
       qid  version.  The path is an integer unique among all files in the hi‐
       erarchy.  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.  Directories always have the CHDIR bit (0x80000000)  set  in
       their qid path.  The version is a version number for a file; typically,
       it is incremented every time the file is modified.

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

       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 al‐
       lows 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 li‐
       brary  routines  that  access files are translated by the mount driver,
       mnt(3), into 9P messages.

DIRECTORIES
       Directories are created by create with CHDIR set in the permissions ar‐
       gument  (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 convention directories con‐
       tain no explicit entry for ..  or .  (dot).  The parent of the root di‐
       rectory of a server's tree is itself.

ACCESS PERMISSIONS
       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 re‐
       quest has an implicit user id (copied from the original 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 per‐
       missions: 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 read‐
       ing  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 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.

       The  file  mode contains some additional attributes besides the permis‐
       sions.  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).



                                                                      INTRO(5)