![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to mpx.2 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Research Unix] / researchv10dc / man / manb|
Return to mpx.2 CVS log | Up to [Research Unix] / researchv10dc / man / manb |
1.1 root 1: .TH MPX 2
2: .UC 4
3: .SH NAME
4: mpx \- create and manipulate multiplexed files
5: .SH SYNOPSIS
6: .nf
7: .B mpx(name, access)
8: .B char *name;
9: .PP
10: .B join(fd, xd)
11: .PP
12: .B chan(xd)
13: .PP
14: .B extract(i, xd)
15: .PP
16: .B attach(i, xd)
17: .PP
18: .B detach(i, xd)
19: .PP
20: .B connect(fd, cd, end)
21: .PP
22: .B npgrp(i, xd, pgrp)
23: .PP
24: .B ckill(i, xd, signal)
25: .PP
26: .B #include <sys/mx.h>
27: .B mpxcall(cmd, vec)
28: .B int *vec;
29: .fi
30: .SH DESCRIPTION
31: .PP
32: .B mpxcall(cmd, vec)
33: is the system call shared by the
34: library routines described below.
35: .I Cmd
36: selects a command using values
37: defined in
38: .IR <sys/mx.h> .
39: .I Vec
40: is the address of a
41: structure containing the arguments
42: for the command.
43: .PP
44: .B mpx(name, access)
45: .PP
46: .I Mpx
47: creates and opens the file
48: .I name
49: with access permission
50: .I access
51: (see
52: .IR creat (2))
53: and returns a file descriptor available for
54: reading and writing.
55: A \-1 is returned if the file cannot be created,
56: if
57: .I name
58: already exists, or
59: if the file table or other operating system
60: data structures are full.
61: The file descriptor is required for use
62: with other routines.
63: .PP
64: If
65: .I name
66: is 0,
67: a file descriptor is returned as described
68: but no entry is created in the file system.
69: .PP
70: Once created an mpx file may be opened
71: (see
72: .IR open (2))
73: by any process.
74: This provides a form of interprocess communication
75: whereby a process B can `call' process A
76: by opening an mpx file
77: created by A.
78: To B, the file is ordinary with one exception:
79: the
80: .I connect
81: primitive could be applied to it.
82: Otherwise the functions
83: described below are used only in process A
84: and descendants that inherit the open mpx file.
85: .PP
86: When a process opens an mpx file, the owner of the
87: file receives a control message when the file is next read.
88: The method for `answering'
89: this kind of call involves
90: using
91: .I attach
92: and
93: .I detach
94: as described in more detail below.
95: .PP
96: Once B has opened A's mpx file
97: it is said to have a
98: .I channel
99: to A.
100: A channel is a pair of data streams:
101: in this case, one from B to A and the
102: other from A to B.
103: Several processes may open the same mpx file
104: yielding multiple channels within the one mpx file.
105: By accessing the appropriate channel,
106: A can communicate with B and any others.
107: When A reads (see
108: .IR read (2))
109: from the mpx file
110: data written to A by the other processes appears
111: in A's buffer using a record format
112: described in
113: .IR mpxio (5).
114: When A writes (see
115: .IR write (2))
116: on its mpx file the data must be formatted in a similar way.
117: .PP
118: The following commands
119: are used to manipulate mpx files and channels.
120: .IP
121: .IR join \-
122: adds a new channel on an mpx file to an open file F.
123: I/O on the new channel is I/O on F.
124: .br
125: .IR chan \-
126: creates a new channel.
127: .br
128: .IR extract \-
129: file descriptor maintenance.
130: .br
131: .IR connect \-
132: similar to join except that the open file F is connected
133: to an existing channel.
134: .br
135: .I attach
136: and
137: .IR detach \-
138: used with call protocol.
139: .br
140: .IR npgrp \-
141: manipulates process group numbers so that a channel
142: can act as a control terminal (see
143: .IR tty (4)).
144: .br
145: .IR ckill \-
146: send signal (see
147: .IR signal (2))
148: to process group through channel.
149: .PP
150: A maximum of 15 channels may be connected to an
151: mpx file.
152: They are numbered 0 through 14.
153: .I Join
154: may be used to make one mpx file appear as a channel
155: on another mpx file.
156: A hierarchy or tree of mpx files may be set up in this way.
157: In this case
158: one of the mpx files must be the root of a tree
159: where the other mpx files are interior nodes.
160: The maximum depth of such a tree
161: is 4.
162: .PP
163: An
164: .I index
165: is a 16-bit value
166: that denotes a location
167: in an mpx tree other than the root:
168: the path through mpx `nodes' from the root
169: to the location is expressed as a sequence of
170: 4-bit nibbles.
171: The branch taken at the root is represented by
172: the low-order 4-bits of an index.
173: Each succeeding branch is specified by the next
174: higher-order nibble.
175: If the length of a path to be expressed
176: is less than 4,
177: then the illegal channel number, 15,
178: must be used to terminate the sequence.
179: This is not strictly necessary for the
180: simple case of a tree consisting of
181: only a root node: its channels
182: can be expressed by the numbers
183: 0 through 14.
184: An index
185: .I i
186: and file descriptor
187: .I xd
188: for the root of an mpx tree are
189: required as arguments to most
190: of the commands described below.
191: Indices also serve as channel identifiers
192: in the record formats given in
193: .IR mpxio (5).
194: Since \-1 is not a valid index,
195: it can be returned as a error indication
196: by subroutines that normally return
197: indices.
198: .PP
199: The operating system informs the process managing an mpx file
200: of changes in the status of channels attached to the file
201: by generating messages that
202: are read along with data from the channels.
203: The form and content of these messages is described
204: in
205: .IR mpxio (5).
206: .PP
207: .B join(fd, xd)
208: establishes a connection (channel) between an mpx file
209: and another object.
210: .I Fd
211: is an open file descriptor for a character device
212: or an mpx file and
213: .I xd
214: is the file descriptor of an
215: mpx file.
216: .I Join
217: returns the index for the new channel
218: if the operation succeeds and \-1
219: if it does not.
220: .PP
221: Following join,
222: .I fd
223: may still be used in any system call that would
224: have been meaningful before the join operation.
225: Thus
226: a process can read and write directly to
227: .I fd
228: as well as access it via
229: .I xd.
230: If the number of channels
231: required for a tree of mpx files
232: exceeds the number of open files
233: permitted a process by the operating system,
234: some of the file descriptors can be released using
235: the standard
236: .IR close (2)
237: call.
238: Following a close on an active file descriptor for a channel
239: or internal mpx node,
240: that object may still be accessed through the root of the
241: tree.
242: .PP
243: .B chan(xd)
244: allocates a channel and connects
245: one end of it to the mpx file
246: represented by file descriptor
247: .I xd.
248: .I Chan
249: returns the index of the new channel or
250: a \-1 indicating failure.
251: The
252: .I extract
253: primitive can be used to get a non-multiplexed
254: file descriptor for the free end of a channel
255: created by
256: .I chan.
257: .PP
258: Both
259: .I chan
260: and
261: .I join
262: operate on the mpx file specified by
263: .IR xd .
264: File descriptors for interior nodes of an
265: mpx tree must be preserved or reconstructed with
266: .I extract
267: for use with
268: .I join
269: or
270: .IR chan .
271: For the remaining commands described here,
272: .I xd
273: denotes the file descriptor for the
274: root of an mpx tree.
275: .PP
276: .B extract(i, xd)
277: returns a file descriptor for the object with
278: index
279: .I i
280: on the mpx tree with root file descriptor
281: .I xd.
282: A \-1 is returned by extract if a file descriptor is not available
283: or if the arguments do not refer to an existing
284: channel and mpx file.
285: .PP
286: .B attach(i, xd)
287: .br
288: .BR "detach(i, xd)" .
289: If a process A has created an mpx file represented
290: by file descriptor
291: .I xd,
292: then a process B
293: can open (see
294: .IR open (2))
295: the mpx file.
296: The purpose is to establish a channel between
297: A and B through the mpx file.
298: .I Attach
299: and
300: .I Detach
301: are used by A to respond to
302: such opens.
303: .PP
304: An open request by B fails immediately if a
305: new channel cannot be allocated on the mpx file,
306: if the mpx file does not exist,
307: or if it does exist
308: but there is no process (A)
309: with a multiplexed file descriptor
310: for the mpx file
311: (i.e.
312: .I xd
313: as returned by
314: .IR mpx (2)).
315: Otherwise a channel
316: with index number
317: .I i
318: is allocated.
319: The next time A reads on file descriptor
320: .IR xd ,
321: the WATCH control message
322: (see
323: .IR mpxio (5))
324: will be delivered on channel
325: .I i.
326: A responds to this message with
327: .I attach
328: or
329: .I detach.
330: The former causes the open to complete and
331: return a file descriptor to B.
332: The latter deallocates channel
333: .I i
334: and causes the open to fail.
335: .PP
336: One mpx file may be placed in `listener' mode.
337: This is done by writing
338: .I "ioctl(xd, MXLSTN, 0)"
339: where
340: .I xd
341: is an mpx file descriptor
342: and MXLSTN is defined in
343: .IR /usr/include/sgtty.h .
344: The semantics of listener mode are that
345: all file names discovered by
346: .IR open (2)
347: to have
348: the syntax
349: .I "system!pathname"
350: (see
351: .IR uucp (1))
352: are treated as opens on the mpx file.
353: The operating system sends the listener process
354: an OPEN message (see
355: .IR mpxio (5))
356: which includes the file name being opened.
357: .I Attach
358: and
359: .I detach
360: then apply as described above.
361: .PP
362: .I Detach
363: has two other uses:
364: it closes and releases the resources
365: of any active channel it is applied to,
366: and should be used to respond to
367: a CLOSE message (see
368: .IR mpxio (5))
369: on a channel so the channel may be reused.
370: .PP
371: .BR "connect(fd, cd, end)" .
372: .I Fd
373: is a character file descriptor and
374: .I cd
375: is a file descriptor for a channel,
376: such as might be obtained via
377: .I "extract( chan(xd), xd)"
378: or by
379: .IR open (2)
380: followed by
381: .I attach.
382: .I Connect
383: splices the two streams together.
384: If
385: .I end
386: is negative, only
387: the output of
388: .I fd
389: is spliced to the input of
390: .I cd.
391: If
392: .I end
393: is positive, the output of
394: .I cd
395: is spliced to the input of
396: .I fd.
397: If
398: .I end
399: is zero, then both splices are made.
400: .PP
401: .BR "npgrp(i, xd, pgrp)" .
402: If
403: .I xd
404: is negative
405: .I npgrp
406: applies to the process executing it,
407: otherwise
408: .I i
409: and
410: .I xd
411: are interpreted as a channel index and
412: mpx file descriptor
413: and
414: .I npgrp
415: is applied to the process on the
416: non-multiplexed end of the channel.
417: If
418: .I pgrp
419: is zero, the process group number of the indicated process
420: is set to the process number of that process,
421: otherwise the value of
422: .I pgrp
423: is used as the process group number.
424: .PP
425: .I Npgrp
426: normally returns the new process group number.
427: If
428: .I i
429: and
430: .I xd
431: specify a nonexistent channel,
432: .I npgrp
433: returns \-1.
434: .PP
435: .B ckill(i, xd, signal)
436: sends the specified signal (see
437: .IR signal (2))
438: through the channel specified by
439: .I i
440: and
441: .I xd.
442: If the channel is connected to anything other
443: than a process,
444: .I ckill
445: is a null operation.
446: If there is a process at the other end of the channel,
447: the process group will be interrupted (see
448: .IR signal (2),
449: .IR kill (2)).
450: .I Ckill
451: normally returns
452: .I signal.
453: If
454: .I ch
455: and
456: .I xd
457: specify a nonexistent channel,
458: .I ckill
459: returns \-1.
460: .SH FILES
461: /usr/include/sys/mx.h
462: .br
463: /usr/include/sgtty.h
464: .SH "SEE ALSO"
465: mpxio(5)
466: .SH BUGS
467: .PP
468: Mpx files are an experimental part of the operating
469: system more subject to change and prone to bugs
470: than other parts.
471: .PP
472: Maintenance programs, e.g.
473: .IR icheck (1),
474: diagnose mpx files as an illegal mode.
475: .PP
476: Channels may only be connected to objects in the operating
477: system that are accessible through the line discipline
478: mechanism.
479: .PP
480: Higher performance line disciplines are needed.
481: .PP
482: The maximum tree depth restriction is not really checked.
483: .PP
484: A non-destructive
485: .I disconnect
486: primitive (inverse of
487: .IR connect )
488: is not provided.
489: .PP
490: A non-blocking flow control strategy
491: based on messages defined in
492: .IR mpxio (5)
493: should not be attempted by novices;
494: the enabling
495: .I ioctl
496: command should be protected.
497: .PP
498: The
499: .I join
500: operation could be subsumed by
501: .I connect.
502: A mechanism is needed for moving a channel from one
503: location in an mpx tree to another.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.