DK(3)                                                       DK(3)

     NAME
          dk - Datakit conversations

     SYNOPSIS
          bind #kname /net/dk
          bind #iname /net/dk

          ctlfd = open(".../ctl", ORDWR);
          write(ctlfd, "push dkmux", 10);
          write(ctlfd, "config csc [no]restart name nvc window", n);

     DESCRIPTION
          A Datakit device-either k for the regular Datakit or i for
          the Incon-is a directory containing up to 256 directories,
          one per virtual circuit, named 0 through 255, and a special
          file named clone.  The specifier name matches the Datakit
          device to a physical device that its virtual circuits are
          multiplexed over (see dkmux below).

          Normally, the standard routines dial, hangup, listen, and
          announce (see dial(2)) are used to make, listen for, and
          control calls over any network.  The routines expect the
          following properties of any multiplexed network, not just
          Datakit.

          Opening the clone file is a macro for opening the ctl file
          of an unused virtual circuit.  Reading any ctl file returns
          the name of the virtual circuit directory.  For example,
          reading #k/17/ctl will return the string 17.

          Each virtual circuit directory contains the files:

          ctl       to control the virtual circuit: establish a con-
                    nection, hang it up, etc.

          data      to converse with the remote end (via read and
                    write)

          listen    to listen for calls (after announcing; see below)

          other     information about the conversation

          raddr     the address of the remote end

          ruser     the id of the user at the remote end (when appli-
                    cable)

          To set up and tear down virtual circuits a process writes
          textual commands to the ctl file:

     Page 1                       Plan 9             (printed 12/2/22)

     DK(3)                                                       DK(3)

          connect addr  connect to address addr. If the connection
                        fails, the write returns an error.

          hangup        tear down a connected virtual circuit.

          announce name announce the readiness to accept calls to
                        name.

          accept n      accept the call on virtual circuit n.

          reject n e    reject the call on virtual circuit n with
                        error code e. e must be a number from 0 to 7.

          Once a virtual circuit is set up, a process can converse
          with the remote service by reading and writing the data
          file.  Write boundaries are preserved.

          Accepting calls to name requires the following dance:

          1)   announce name on a virtual circuit.

          2)   open the listen file in that virtual circuit's direc-
               tory.  When a call comes in on a virtual circuit for
               name, the open will return with the file descriptor
               open to the control file of the incoming virtual cir-
               cuit.

          3)   accept or reject the call by writing an accept or
               reject command to the ctl file of the announced virtual
               circuit.

          A dkmux module pushed onto a stream makes that stream a mul-
          tiplexed connection to a Datakit.  The subsequent config
          control message configures the multiplexer and matches it to
          a dk device.  The parameters to the config message are

          csc  the line number of the common signalling channel (must
               be > 0)

          nvc  the number of virtual circuits (optional; default cho-
               sen by Datakit)

          [no]restart
               the word restart or norestart (optional; default is
               restart).  Restart tells the Datakit to forget all pre-
               vious connections and authentications for this machine.

          name The name used in binding dk device.

          window
               the default URP window size for virtual circuits on
               this Datakit line (default is 2048).

     Page 2                       Plan 9             (printed 12/2/22)

     DK(3)                                                       DK(3)

     FILES
          #k/clone
          #k/[0-255]
          #k/[0-255]/data
          #k/[0-255]/ctl
          #k/[0-255]/listen
          #k/[0-255]/ruser
          #k/[0-255]/raddr

     SEE ALSO
          stream(3), dkconfig(8), datakit(3)

     Page 3                       Plan 9             (printed 12/2/22)