ATTACH(5)                                               ATTACH(5)

     NAME
          attach, auth - messages to establish a connection

     SYNOPSIS
          size[4] Tauth tag[2] afid[4] uname[s] aname[s]
          size[4] Rauth tag[2] aqid[13]

          size[4] Tattach tag[2] fid[4] afid[4] uname[s] aname[s]
          size[4] Rattach tag[2] qid[13]

     DESCRIPTION
          The attach message serves as a fresh introduction from a
          user on the client machine to the server.  The message iden-
          tifies the user (uname) and may select the file tree to
          access (aname).  The afid argument specifies a fid previ-
          ously established by an auth message, as described below.

          As a result of the attach transaction, the client will have
          a connection to the root directory of the desired file tree,
          represented by fid. An error is returned if fid is already
          in use.  The server's idea of the root of the file tree is
          represented by the returned qid.

          If the client does not wish to authenticate the connection,
          or knows that authentication is not required, the afid field
          in the attach message should be set to NOFID, defined as
          (u32int)~0 in <fcall.h>.  If the client does wish to authen-
          ticate, it must acquire and validate an afid using an auth
          message before doing the attach.

          The auth message contains afid, a new fid to be established
          for authentication, and the uname and aname that will be
          those of the following attach message.  If the server does
          not require authentication, it returns Rerror to the Tauth
          message.

          If the server does require authentication, it returns aqid
          defining a file of type QTAUTH (see intro(5)) that may be
          read and written (using read and write messages in the usual
          way) to execute an authentication protocol.  That protocol's
          definition is not part of Styx itself.

          Once the protocol is complete, the same afid is presented in
          the attach message for the user, granting entry.  The same
          validated afid may be used for multiple attach messages with
          the same uname and aname.

     ENTRY POINTS
          An attach transaction will be generated for kernel devices
          (see intro(3)) when a system call evaluates a file name

     Page 1                       Plan 9            (printed 10/31/24)

     ATTACH(5)                                               ATTACH(5)

          beginning with `#'.  Sys-pipe(2) generates an attach on the
          kernel device pipe(3). The mount call (see sys-bind(2)) gen-
          erates an attach message to the remote file server.  When
          the kernel boots, an attach is made to the root device,
          root(3), and then an attach is made to the requested file
          server machine.

          An auth transaction is generated by the fauth(2) system call
          or by the first mount system call on an uninitialized con-
          nection.

     SEE ALSO
          sys-bind(2), sys-fauth(2), intro(3), root(3), version(5)

     Page 2                       Plan 9            (printed 10/31/24)