MPX(2) 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 described below. Cmd selects a command using values defined in <sys/mx.h>. Vec is the address of a struc- ture 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 avail- able for reading and writing. 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 described 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 applied to it. MPX(2) MPX(2) 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 control 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 chan- nels 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 connected 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 location 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 succeeding 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 channel 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 MPX(2) MPX(2) expressed by the numbers 0 through 14. An index i and file descriptor xd for the root of an mpx tree are required 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 returns 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 number 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 descrip- tors can be released using the standard close(2) call. Fol- lowing a close on an active file descriptor for a channel or internal 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 descriptors for interior nodes of an mpx tree must be preserved or reconstructed 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 MPX(2) MPX(2) 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 can- not be allocated 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 descriptor 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 system!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 executing 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-multiplexed 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, other- wise the value of pgrp is used as the process group number. Npgrp normally returns the new process group number. If i and xd specify a nonexistant channel, npgrp returns -1. ckill(i, xd, signal) sends the specified signal (see MPX(2) MPX(2) signal(2)) through the channel specified by i and xd. If the channel is connected to anything 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 interrupted (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 accessible through the line discipline mechanism. Higher performace line disciplines 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 messages defined in mpxio(5) should not be attempted by novices; the enabling ioctl com- mand should be protected. The join operation could be sub- sumed by connect. A mechanism is needed for moving a channel from one location in an mpx tree to another.