man(1) Manual page archive


     MSGIO(2)                                                 MSGIO(2)

     NAME
          msgio: getmsg, sendmsg, senderrmsg, getstring, putstring,
          getbytearray, putbytearray, puterror - exchange data on
          delimited and undelimited streams

     SYNOPSIS
          include "msgio.m";
          msgio := load Msgio Msgio->PATH;

          init:         fn();

          getmsg:       fn(fd: ref Sys->FD): array of byte;
          sendmsg:      fn(fd: ref Sys->FD, buf: array of byte, n: int): int;
          senderrmsg:   fn(fd: ref Sys->FD, s: string): int;

          getstring:    fn(fd: ref Sys->FD): (string, string);
          putstring:    fn(fd: ref Sys->FD, s: string): int;
          getbytearray: fn(fd: ref Sys->FD): (array of byte, string);
          putbytearray: fn(fd: ref Sys->FD, a: array of byte, n: int): int;
          puterror:     fn(fd: ref Sys->FD, s: string): int;

     DESCRIPTION
          Msgio provides two complementary sets of functions for the
          exchange of data over a network connection that uses a
          connection-oriented transport protocols.  The connection is
          represented by a file descriptor fd.

          Init must be called before any other operation of the mod-
          ule.

          The first set allows arbitrary data, packed into arrays of
          bytes, to be exchanged on network connections using proto-
          cols such as TCP/IP that do not preserve record boundaries.
          They are used to implement various authentication protocols,
          including auth(6).

          Each data message is transmitted with a five-byte header
          containing a four-character zero-padded decimal count n ter-
          minated by a newline, followed by n bytes of message data.
          An error message has a similar structure, except that the
          first character of the count is replaced by an exclamation
          mark (!); the message data following contains the diagnostic
          string in its UTF-8 encoding (see utf(6)).

          Getmsg reads the next message from fd and returns its data
          content.

          Sendmsg sends the first n bytes of buf as a message on fd,
          and returns n.

     MSGIO(2)                                                 MSGIO(2)

          Senderrmsg sends the error message s.

          The second set of functions provide I/O for strings, byte
          arrays and error strings over network connections that pro-
          vide a record structure for communication (as provided for
          arbitrary networks by ssl(3)).

          Putstring writes string s to fd. It returns the number of
          bytes written, or -1 if an error occurred.  Messages written
          by putstring are truncated to 4096 bytes.

          Getstring reads a string as written by putstring from fd and
          returns a tuple (result,error).  If successful, the error
          string is nil.

          Putbytearray writes the array of bytes a to fd. It returns
          the number of bytes written, or -1 if an error occurred.
          Messages written by putbytearray are truncated to 4096
          bytes.

          Getbytearray reads an array of bytes as written by
          putbytearray from fd and returns a tuple of the form
          (result,error).  If successful, the error string is nil.

          Puterror writes an error string s to fd. It can be used in
          place of putstring or putbytearray to cause a corresponding
          getstring or getbytearray to fail (in the receiving pro-
          cess), forcing them to return the error string s. It may not
          be longer than Sys->ERRMAX bytes.

     SOURCE
          /appl/lib/msgio.b

     DIAGNOSTICS
          The output functions return an int which is -1 if there was
          an I/O error, and a non-negative value otherwise; they also
          set the system error string.  Getmsg returns nil if there
          was an error reading from fd; it sets the system error
          string to reflect the cause.  It also returns nil if an
          error message was received instead of a data message; the
          system error string will contain the error message's diag-
          nostic.  The other input functions (for streams with delim-
          iters) return a tuple that includes a string indicating the
          cause of the error, as the second element of the tuple.

     BUGS
          The module is really intended to retrofit the original
          Inferno authentication protocols into a new regime, and is
          not yet intended for general-purpose use, hence the irregu-
          lar naming and calling conventions, inherited from the orig-
          inal implementation in Keyring.