.TH MSGIO 2.SH NAMEmsgio: getmsg, sendmsg, senderrmsg, getstring, putstring, getbytearray, putbytearray, puterror \- exchange data on delimited and undelimited streams.SH SYNOPSIS.EXinclude "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;.EE.SH DESCRIPTION.B Msgioprovides two complementary sets of functions for the exchange of data over a networkconnection that uses a connection-oriented transport protocols.The connection is represented by a file descriptor.IR fd ..PP.B Initmust be called before any other operation of the module..PPThe first set allows arbitrary data, packed into arrays of bytes, to be exchangedon network connections using protocols such as TCP/IP that do not preserverecord boundaries.They are used to implement various authentication protocols, including.IR auth (6)..PPEach data message is transmitted with a five-byte header containing a four-character zero-padded decimal count.I nterminated by a newline, followed by.I nbytes of message data.An error message has a similar structure, except that the first characterof the count is replaced by an exclamation mark.RB ( ! );the message data followingcontains the diagnostic string in its UTF-8 encoding (see.IR utf (6))..PP.B Getmsgreads the next message from.I fdand returns its data content..PP.B Sendmsgsends the first.I nbytes of.I bufas a message on.IR fd ,and returns.IR n ..PP.B Senderrmsgsends the error message.IR s ..PPThe second set of functions provideI/O for strings, byte arrays and error strings over network connections thatprovide a record structure for communication (as provided for arbitrarynetworks by.IR ssl (3))..PP.B Putstringwrites string.I sto.IR fd.It returns the number of bytes written, or -1 if an error occurred.Messages written by.B putstringare truncated to 4096 bytes..PP.B Getstringreads a string as written by.B putstringfrom.IR fdand returns a tuple.RI ( result , error ).If successful, the errorstring is nil..PP.B Putbytearraywrites the array of bytes.I ato.IR fd .It returns the number of bytes written, or -1 if an error occurred.Messages written by.B putbytearrayare truncated to 4096 bytes..PP.B Getbytearrayreads an array of bytes as written by.B putbytearrayfrom.IR fdand returns a tuple of the form.RI ( result , error ).If successful, the error string is nil..PP.B Puterrorwrites an error string.I sto.IR fd .It can be used in place of.B putstringor.B putbytearrayto cause a corresponding.B getstringor.B getbytearrayto fail(in the receiving process),forcing them to return the error string.IR s .It may not be longer than.BR Sys->ERRMAXbytes..SH SOURCE.B /appl/lib/msgio.b.SH DIAGNOSTICSThe output functions return an.B intwhich is -1 if there was an I/O error,and a non-negative value otherwise;they also set the system error string..B Getmsgreturns nil if there was an error reading from.IR fd ;it sets the system error string to reflect the cause.It also returns nilif an error message was received instead of a data message;the system error string will contain the error message's diagnostic.The other input functions (for streams with delimiters)return a tuple that includes a string indicating the cause of theerror, as the second element of the tuple..SH BUGSThe module is really intended to retrofit the original Inferno authenticationprotocols into a new regime, and is not yet intended for general-purpose use,hence the irregular naming and calling conventions, inherited from the original implementation in.BR Keyring .