term% cat index.txt MPX(2) System Calls Manual MPX(2)
NAME
mpx - create and manipulate multiplexed files
SYNOPSIS
mpx(name, access) char *name;
join(fd, xd)
chan(xd)
extract(i, xd)
attach(i, xd)
detach(i, xd)
connect(fd, cd, end)
npgrp(i, xd, pgrp)
ckill(i, xd, signal)
#include <sys/mx.h>
mpxcall(cmd, vec)
int *vec;
DESCRIPTION
mpxcall(cmd, vec) is the system call shared by the library routines de‐
scribed below. Cmd selects a command using values defined in
<sys/mx.h>. Vec is the address of a structure containing the arguments
for the command.
mpx(name, access)
Mpx creates and opens the file name with access permission access (see
creat(2)) and returns a file descriptor available for reading and writ‐
ing. A -1 is returned if the file cannot be created, if name already
exists, or if the file table or other operating system data structures
are full. The file descriptor is required for use with other routines.
If name designates a null string, a file descriptor is returned as de‐
scribed but no entry is created in the file system.
Once created an mpx file may be opened (see open(2)) by any process.
This provides a form of interprocess communication whereby a process B
can `call' process A by opening an mpx file created by A. To B, the
file is ordinary with one exception: the connect primitive could be ap‐
plied to it. Otherwise the functions described below are used only in
process A and descendants that inherit the open mpx file.
When a process opens an mpx file, the owner of the file receives a con‐
trol message when the file is next read. The method for `answering'
this kind of call involves using attach and detach as described in more
detail below.
Once B has opened A's mpx file it is said to have a channel to A. A
channel is a pair of data streams: in this case, one from B to A and
the other from A to B. Several processes may open the same mpx file
yielding multiple channels within the one mpx file. By accessing the
appropriate channel, A can communicate with B and any others. When A
reads (see read(2)) from the mpx file data written to A by the other
processes appears in A's buffer using a record format described in
mpxio(5). When A writes (see write(2)) on its mpx file the data must
be formatted in a similar way.
The following commands are used to manipulate mpx files and channels.
join- adds a new channel on an mpx file to an open file F. I/O
on the new channel is I/O on F.
chan- creates a new channel.
extract- file descriptor maintenance.
connect- similar to join except that the open file F is con‐
nected to an existing channel.
attach and detach- used with call protocol.
npgrp- manipulates process group numbers so that a channel can
act as a control terminal (see tty(4)).
ckill- send signal (see signal(2)) to process group through
channel.
A maximum of 15 channels may be connected to an mpx file. They are
numbered 0 through 14. Join may be used to make one mpx file appear as
a channel on another mpx file. A hierarchy or tree of mpx files may be
set up in this way. In this case one of the mpx files must be the root
of a tree where the other mpx files are interior nodes. The maximum
depth of such a tree is 4.
An index is a 16-bit value that denotes a location in an mpx tree other
than the root: the path through mpx `nodes' from the root to the loca‐
tion is expressed as a sequence of 4-bit nibbles. The branch taken at
the root is represented by the low-order 4-bits of an index. Each suc‐
ceeding branch is specified by the next higher-order nibble. If the
length of a path to be expressed is less than 4, then the illegal chan‐
nel number, 15, must be used to terminate the sequence. This is not
strictly necessary for the simple case of a tree consisting of only a
root node: its channels can be expressed by the numbers 0 through 14.
An index i and file descriptor xd for the root of an mpx tree are re‐
quired as arguments to most of the commands described below. Indices
also serve as channel identifiers in the record formats given in
mpxio(5). Since -1 is not a valid index, it can be returned as a error
indication by subroutines that normally return indices.
The operating system informs the process managing an mpx file of
changes in the status of channels attached to the file by generating
messages that are read along with data from the channels. The form and
content of these messages is described in mpxio(5).
join(fd, xd) establishes a connection (channel) between an mpx file and
another object. Fd is an open file descriptor for a character device
or an mpx file and xd is the file descriptor of an mpx file. Join re‐
turns the index for the new channel if the operation succeeds and -1 if
it does not.
Following join, fd may still be used in any system call that would
have been meaningful before the join operation. Thus a process can
read and write directly to fd as well as access it via xd. If the num‐
ber of channels required for a tree of mpx files exceeds the number of
open files permitted a process by the operating system, some of the
file descriptors can be released using the standard close(2) call.
Following a close on an active file descriptor for a channel or inter‐
nal mpx node, that object may still be accessed through the root of the
tree.
chan(xd) allocates a channel and connects one end of it to the mpx file
represented by file descriptor xd. Chan returns the index of the new
channel or a -1 indicating failure. The extract primitive can be used
to get a non-multiplexed file descriptor for the free end of a channel
created by chan.
Both chan and join operate on the mpx file specified by xd. File de‐
scriptors for interior nodes of an mpx tree must be preserved or recon‐
structed with extract for use with join or chan. For the remaining
commands described here, xd denotes the file descriptor for the root of
an mpx tree.
Extract(i, xd) returns a file descriptor for the object with index i on
the mpx tree with root file descriptor xd. A -1 is returned by extract
if a file descriptor is not available or if the arguments do not refer
to an existing channel and mpx file.
attach(i, xd)
detach(i, xd). If a process A has created an mpx file represented by
file descriptor xd, then a process B can open (see open(2)) the mpx
file. The purpose is to establish a channel between A and B through
the mpx file. Attach and Detach are used by A to respond to such
opens.
An open request by B fails immediately if a new channel cannot be allo‐
cated on the mpx file, if the mpx file does not exist, or if it does
exist but there is no process (A) with a multiplexed file descriptor
for the mpx file (i.e. xd as returned by mpx(2)). Otherwise a channel
with index number i is allocated. The next time A reads on file de‐
scriptor xd, the WATCH control message (see mpxio(5)) will be delivered
on channel i. A responds to this message with attach or detach. The
former causes the open to complete and return a file descriptor to B.
The latter deallocates channel i and causes the open to fail.
One mpx file may be placed in `listener' mode. This is done by writing
ioctl(xd, MXLSTN, 0) where xd is an mpx file descriptor and MXLSTN is
defined in /usr/include/sgtty.h. The semantics of listener mode are
that all file names discovered by open(2) to have the syntax sys‐
tem!pathname (see uucp(1)) are treated as opens on the mpx file. The
operating system sends the listener process an OPEN message (see
mpxio(5)) which includes the file name being opened. Attach and detach
then apply as described above.
Detach has two other uses: it closes and releases the resources of any
active channel it is applied to, and should be used to respond to a
CLOSE message (see mpxio(5)) on a channel so the channel may be reused.
connect(fd, cd, end). Fd is a character file descriptor and cd is a
file descriptor for a channel, such as might be obtained via extract(
chan(xd), xd) or by open(2) followed by attach. Connect splices the
two streams together. If end is negative, only the output of fd is
spliced to the input of cd. If end is positive, the output of cd is
spliced to the input of fd. If end is zero, then both splices are
made.
npgrp(i, xd, pgrp). If xd is negative npgrp applies to the process ex‐
ecuting it, otherwise i and xd are interpreted as a channel index and
mpx file descriptor and npgrp is applied to the process on the non-mul‐
tiplexed end of the channel. If pgrp is zero, the process group number
of the indicated process is set to the process number of that process,
otherwise the value of pgrp is used as the process group number.
Npgrp normally returns the new process group number. If i and xd spec‐
ify a nonexistant channel, npgrp returns -1.
ckill(i, xd, signal) sends the specified signal (see signal(2)) through
the channel specified by i and xd. If the channel is connected to any‐
thing other than a process, ckill is a null operation. If there is a
process at the other end of the channel, the process group will be in‐
terrupted (see signal(2), kill(2)). Ckill normally returns signal. If
ch and xd specify a nonexistent channel, ckill returns -1.
FILES
/usr/include/sys/mx.h
/usr/include/sgtty.h
SEE ALSO
mpxio(5)
BUGS
Mpx files are an experimental part of the operating system more subject
to change and prone to bugs than other parts. Maintenance programs,
e.g. icheck(1), diagnose mpx files as an illegal mode. Channels may
only be connected to objects in the operating system that are accessi‐
ble through the line discipline mechanism. Higher performace line dis‐
ciplines are needed. The maximum tree depth restriction is not really
checked. A non-destructive disconnect primitive (inverse of connect)
is not provided. A non-blocking flow control strategy based on mes‐
sages defined in mpxio(5) should not be attempted by novices; the en‐
abling ioctl command should be protected. The join operation could be
subsumed by connect. A mechanism is needed for moving a channel from
one location in an mpx tree to another.
MPX(2)