manual page distributed with 4.1BSD

[unix-history] / usr / src / old / man / mpxio.5

.\"	@(#)mpxio.5	4.1 (Berkeley) %G%
.\"
.TH MPXIO 5 
.AT 3
.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
.TP "\w'M_WATCH  'u"
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.
.TP
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.
.TP
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.
.TP
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.
.TP
M_UBLK
is generated for a channel
after M_BLK when the internal queues have
drained below a threshold.
.TP
M_SIG
is generated instead of a normal asynchronous
signal on channels that are joined to typewriters.
The parameter is the signal number.
.PP
Two other messages may be generated by the kernel.
As with other messages, the first
16-bit quantity is the message code.
.br
.TP "\w'M_IOCTL  'u"
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.
.TP
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_IOANS can also be sent through a channel to reply to a M_IOCTL.
The format is identical to that received from M_IOCTL.
.SH SEE ALSO
mpx(2)