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