+.TH MPXIO 5
+.SH NAME
+mpxio \- multiplexed i/o
+.SH SYNOPSIS
+.B #include <sys/mx.h>
+.PP
+.B #include <sgtty.h>
+.SH DESCRIPTION
+Data transfers on
+mpx files
+(see
+.IR mpx (2))
+are multiplexed by
+imposing
+a record structure on the io stream.
+Each record represents data
+from/to
+a particular channel or
+a control or status message associated with a particular channel.
+.PP
+The prototypical data record read from an mpx file is as follows
+.PP
+.in +.5i
+.nf
+struct input_record {
+ short index;
+ short count;
+ short ccount;
+ char data[];
+};
+.PP
+.fi
+where
+.I index
+identifies the channel,
+and
+.I count
+specifies the number of characters in
+.I data.
+If
+.I count
+is zero,
+.I ccount
+gives the size of
+.I data,
+and the record is a control or status message.
+Although
+.I count
+or
+.I ccount
+might be odd,
+the operating system aligns records
+on short (i.e. 16\-bit) boundaries
+by skipping bytes when necessary.
+.PP
+Data written to an mpx file must be formatted as an array
+of record structures defined as follows
+.PP
+.in +.5i
+.nf
+struct output_record {
+ short index;
+ short count;
+ short ccount;
+ char *data;
+};
+.fi
+.PP
+where the data portion of the record is referred
+to indirectly and the other cells have the same interpretation
+as in
+.I input_record.
+.PP
+The
+control messages listed below may be read from
+a multiplexed file descriptor.
+They are presented as two 16-bit integers:
+the first number is the message code
+(defined in
+.IR <sys/mx.h> ),
+the second is an optional parameter meaningful
+only with M_WATCH, M_BLK, and M_SIG.
+.PP
+.in +1i
+.ti -.5i
+M_WATCH \- a process `wants to attach' on this channel.
+The second parameter is the 16-bit
+user-id of the process that executed the open.
+.br
+.ti -.5i
+M_CLOSE \- the channel is closed.
+This message is generated when the last
+file descriptor referencing
+a channel is closed.
+The
+.I detach
+command
+(see
+.IR mpx (2)
+should be used in response to this message.
+.br
+.ti -.5i
+M_EOT \- indicates logical end of file on a channel.
+If the channel is joined to a typewriter,
+EOT (control-d)
+will cause the M_EOT message
+under the conditions specified in
+.IR tty (4)
+for end of file.
+If the channel is attached to a process,
+M_EOT will be generated whenever the process
+writes zero bytes on the channel.
+.br
+.ti -.5i
+M_BLK \- if non-blocking mode has been enabled on an
+mpx file descriptor
+.I xd
+by executing
+.IR "ioctl(xd, MXNBLK, 0)" ,
+write operations on the file are truncated in the kernel
+when internal queues become full.
+This is done on a per-channel basis:
+the parameter
+is a count of the number of characters
+not transferred to the channel on which
+M_BLK is received.
+.br
+.ti -.5i
+M_UBLK \- is generated for a channel
+after M_BLK when the internal queues have
+drained below a threshold.
+.br
+.ti -.5i
+M_SIG \- is generated instead of a normal asynchronous
+signal on channels that are joined to typewriters.
+The parameter is the signal number.
+.in -1i
+.PP
+Two other messages may be generated by the kernel.
+As with other messages, the first
+16-bit quantity is the message code.
+.PP
+.in +1i
+.ti -.5i
+M_OPEN \- is generated in conjunction with
+`listener' mode (see
+.IR mpx (2)).
+The uid of the calling process follows the message code
+as with M_WATCH.
+This is followed by a null-terminated string
+which is the name of the file being opened.
+.br
+.ti -.5i
+M_IOCTL \- is generated for a channel connected
+to a process
+when that process executes the
+.I "ioctl(fd, cmd, &vec)"
+call on the channel file descriptor.
+The M_IOCTL code is followed by
+the
+.I cmd
+argument given to
+.I ioctl
+followed by
+the contents of the structure
+.I vec.
+It is assumed,
+not needing a better compromise at this time,
+that the length of
+.I vec
+is determined by
+.I "sizeof (struct sgttyb)"
+as declared in
+.IR <sgtty.h> .
+.in -1i
+.PP
+Two control messages are understood by the operating system.
+M_EOT may be sent through an mpx file to a channel.
+It is equivalent to propagating a zero-length record
+through the channel;
+i.e. the channel is allowed to drain and the process or
+device at the other end receives a zero-length
+transfer before data starts flowing through the channel again.
+M_IOCTL can also be sent through a channel.
+The format is identical to that described above.
projects / unix-history / commitdiff