1MPX(2) System Calls Manual MPX(2)
2
6 mpx - create and manipulate multiplexed files
7
9 mpx(name, access) char *name;
10 join(fd, xd)
12 chan(xd)
14 extract(i, xd)
16 attach(i, xd)
18 detach(i, xd)
20 connect(fd, cd, end)
22 npgrp(i, xd, pgrp)
24 ckill(i, xd, signal)
26 #include <sys/mx.h>
28 mpxcall(cmd, vec)
29 int *vec;
30
32 mpxcall(cmd, vec) is the system call shared by the library routines
33 described below. Cmd selects a command using values defined in
34 <sys/mx.h>. Vec is the address of a structure containing the arguments
35 for the command.
36 mpx(name, access)
38 Mpx creates and opens the file name with access permission access (see
40 creat(2)) and returns a file descriptor available for reading and writ‐
41 ing. A -1 is returned if the file cannot be created, if name already
42 exists, or if the file table or other operating system data structures
43 are full. The file descriptor is required for use with other routines.
44 If name designates a null string, a file descriptor is returned as
46 described but no entry is created in the file system.
47 Once created an mpx file may be opened (see open(2)) by any process.
49 This provides a form of interprocess communication whereby a process B
50 can `call' process A by opening an mpx file created by A. To B, the
51 file is ordinary with one exception: the connect primitive could be
52 applied to it. Otherwise the functions described below are used only
53 in process A and descendants that inherit the open mpx file.
54 When a process opens an mpx file, the owner of the file receives a con‐
56 trol message when the file is next read. The method for `answering'
57 this kind of call involves using attach and detach as described in more
58 detail below.
59 Once B has opened A's mpx file it is said to have a channel to A. A
61 channel is a pair of data streams: in this case, one from B to A and
62 the other from A to B. Several processes may open the same mpx file
63 yielding multiple channels within the one mpx file. By accessing the
64 appropriate channel, A can communicate with B and any others. When A
65 reads (see read(2)) from the mpx file data written to A by the other
66 processes appears in A's buffer using a record format described in
67 mpxio(5). When A writes (see write(2)) on its mpx file the data must
68 be formatted in a similar way.
69 The following commands are used to manipulate mpx files and channels.
71 join- adds a new channel on an mpx file to an open file F. I/O
73 on the new channel is I/O on F.
74 chan- creates a new channel.
75 extract- file descriptor maintenance.
76 connect- similar to join except that the open file F is con‐
77 nected to an existing channel.
78 attach and detach- used with call protocol.
79 npgrp- manipulates process group numbers so that a channel can
80 act as a control terminal (see tty(4)).
81 ckill- send signal (see signal(2)) to process group through
82 channel.
83 A maximum of 15 channels may be connected to an mpx file. They are
85 numbered 0 through 14. Join may be used to make one mpx file appear as
86 a channel on another mpx file. A hierarchy or tree of mpx files may be
87 set up in this way. In this case one of the mpx files must be the root
88 of a tree where the other mpx files are interior nodes. The maximum
89 depth of such a tree is 4.
90 An index is a 16-bit value that denotes a location in an mpx tree other
92 than the root: the path through mpx `nodes' from the root to the loca‐
93 tion is expressed as a sequence of 4-bit nibbles. The branch taken at
94 the root is represented by the low-order 4-bits of an index. Each suc‐
95 ceeding branch is specified by the next higher-order nibble. If the
96 length of a path to be expressed is less than 4, then the illegal chan‐
97 nel number, 15, must be used to terminate the sequence. This is not
98 strictly necessary for the simple case of a tree consisting of only a
99 root node: its channels can be expressed by the numbers 0 through 14.
100 An index i and file descriptor xd for the root of an mpx tree are
101 required as arguments to most of the commands described below. Indices
102 also serve as channel identifiers in the record formats given in
103 mpxio(5). Since -1 is not a valid index, it can be returned as a error
104 indication by subroutines that normally return indices.
105 The operating system informs the process managing an mpx file of
107 changes in the status of channels attached to the file by generating
108 messages that are read along with data from the channels. The form and
109 content of these messages is described in mpxio(5).
110 join(fd, xd) establishes a connection (channel) between an mpx file and
112 another object. Fd is an open file descriptor for a character device
113 or an mpx file and xd is the file descriptor of an mpx file. Join
114 returns the index for the new channel if the operation succeeds and -1
115 if it does not.
116 Following join, fd may still be used in any system call that would
118 have been meaningful before the join operation. Thus a process can
119 read and write directly to fd as well as access it via xd. If the num‐
120 ber of channels required for a tree of mpx files exceeds the number of
121 open files permitted a process by the operating system, some of the
122 file descriptors can be released using the standard close(2) call.
123 Following a close on an active file descriptor for a channel or inter‐
124 nal mpx node, that object may still be accessed through the root of the
125 tree.
126 chan(xd) allocates a channel and connects one end of it to the mpx file
128 represented by file descriptor xd. Chan returns the index of the new
129 channel or a -1 indicating failure. The extract primitive can be used
130 to get a non-multiplexed file descriptor for the free end of a channel
131 created by chan.
132 Both chan and join operate on the mpx file specified by xd. File
134 descriptors for interior nodes of an mpx tree must be preserved or
135 reconstructed with extract for use with join or chan. For the remain‐
136 ing commands described here, xd denotes the file descriptor for the
137 root of an mpx tree.
138 Extract(i, xd) returns a file descriptor for the object with index i on
140 the mpx tree with root file descriptor xd. A -1 is returned by extract
141 if a file descriptor is not available or if the arguments do not refer
142 to an existing channel and mpx file.
143 attach(i, xd)
145 detach(i, xd). If a process A has created an mpx file represented by
146 file descriptor xd, then a process B can open (see open(2)) the mpx
147 file. The purpose is to establish a channel between A and B through
148 the mpx file. Attach and Detach are used by A to respond to such
149 opens.
150 An open request by B fails immediately if a new channel cannot be allo‐
152 cated on the mpx file, if the mpx file does not exist, or if it does
153 exist but there is no process (A) with a multiplexed file descriptor
154 for the mpx file (i.e. xd as returned by mpx(2)). Otherwise a channel
155 with index number i is allocated. The next time A reads on file
156 descriptor xd, the WATCH control message (see mpxio(5)) will be deliv‐
157 ered on channel i. A responds to this message with attach or detach.
158 The former causes the open to complete and return a file descriptor to
159 B. The latter deallocates channel i and causes the open to fail.
160 One mpx file may be placed in `listener' mode. This is done by writing
162 ioctl(xd, MXLSTN, 0) where xd is an mpx file descriptor and MXLSTN is
163 defined in /usr/include/sgtty.h. The semantics of listener mode are
164 that all file names discovered by open(2) to have the syntax sys‐
165 tem!pathname (see uucp(1)) are treated as opens on the mpx file. The
166 operating system sends the listener process an OPEN message (see
167 mpxio(5)) which includes the file name being opened. Attach and detach
168 then apply as described above.
169 Detach has two other uses: it closes and releases the resources of any
171 active channel it is applied to, and should be used to respond to a
172 CLOSE message (see mpxio(5)) on a channel so the channel may be reused.
173 connect(fd, cd, end). Fd is a character file descriptor and cd is a
175 file descriptor for a channel, such as might be obtained via extract(
176 chan(xd), xd) or by open(2) followed by attach. Connect splices the
177 two streams together. If end is negative, only the output of fd is
178 spliced to the input of cd. If end is positive, the output of cd is
179 spliced to the input of fd. If end is zero, then both splices are
180 made.
181 npgrp(i, xd, pgrp). If xd is negative npgrp applies to the process
183 executing it, otherwise i and xd are interpreted as a channel index and
184 mpx file descriptor and npgrp is applied to the process on the non-mul‐
185 tiplexed end of the channel. If pgrp is zero, the process group number
186 of the indicated process is set to the process number of that process,
187 otherwise the value of pgrp is used as the process group number.
188 Npgrp normally returns the new process group number. If i and xd spec‐
190 ify a nonexistant channel, npgrp returns -1.
191 ckill(i, xd, signal) sends the specified signal (see signal(2)) through
193 the channel specified by i and xd. If the channel is connected to any‐
194 thing other than a process, ckill is a null operation. If there is a
195 process at the other end of the channel, the process group will be
196 interrupted (see signal(2), kill(2)). Ckill normally returns signal.
197 If ch and xd specify a nonexistent channel, ckill returns -1.
198
200 /usr/include/sys/mx.h
201 /usr/include/sgtty.h
202
204 mpxio(5)
205
207 Mpx files are an experimental part of the operating system more subject
208 to change and prone to bugs than other parts. Maintenance programs,
209 e.g. icheck(1), diagnose mpx files as an illegal mode. Channels may
210 only be connected to objects in the operating system that are accessi‐
211 ble through the line discipline mechanism. Higher performace line dis‐
212 ciplines are needed. The maximum tree depth restriction is not really
213 checked. A non-destructive disconnect primitive (inverse of connect)
214 is not provided. A non-blocking flow control strategy based on mes‐
215 sages defined in mpxio(5) should not be attempted by novices; the
216 enabling ioctl command should be protected. The join operation could
217 be subsumed by connect. A mechanism is needed for moving a channel
218 from one location in an mpx tree to another.
219 MPX(2)