KEYRING-GETMSG(2)KEYRING-GETMSG(2)NAME
keyring: getmsg, sendmsg, senderrmsg - send and receive messages on
undelimited streams
SYNOPSIS
include "keyring.m";
keyring := load Keyring Keyring->PATH;
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;
DESCRIPTION
These functions allow arbitrary data, packed into arrays of bytes, to
be exchanged on network connections using connection-oriented transport
protocols that do not preserve record boundaries (eg, TCP/IP without
ssl(3)). They are used to implement various authentication protocols,
including auth(6), as implemented by keyring-auth(2).
Each data message is transmitted with a five-byte header containing a
four-character zero-padded decimal count n terminated 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 diag‐
nostic 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.
Senderrmsg sends the error message s.
SOURCE
/libinterp/keyring.c
DIAGNOSTICS
Sendmsg and senderrmsg return -1 if there was an error writing to fd;
they 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 mes‐
sage's diagnostic.
KEYRING-GETMSG(2)
