1MPX(2)                        System Calls Manual                       MPX(2)
2
3
4

NAME

6       mpx - create and manipulate multiplexed files
7

SYNOPSIS

9       mpx(name, access) char *name;
10
11       join(fd, xd)
12
13       chan(xd)
14
15       extract(i, xd)
16
17       attach(i, xd)
18
19       detach(i, xd)
20
21       connect(fd, cd, end)
22
23       npgrp(i, xd, pgrp)
24
25       ckill(i, xd, signal)
26
27       #include <sys/mx.h>
28       mpxcall(cmd, vec)
29       int *vec;
30

DESCRIPTION

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
37       mpx(name, access)
38
39       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
45       If name designates a null string, a  file  descriptor  is  returned  as
46       described but no entry is created in the file system.
47
48       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
55       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
60       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
70       The following commands are used to manipulate mpx files and channels.
71
72              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
84       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
91       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
106       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
111       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
117       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
127       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
133       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
139       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
144       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
151       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
161       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
170       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
174       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
182       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
189       Npgrp normally returns the new process group number.  If i and xd spec‐
190       ify  a nonexistant channel, npgrp returns -1.
191
192       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

FILES

200       /usr/include/sys/mx.h
201       /usr/include/sgtty.h
202

SEE ALSO

204       mpxio(5)
205

BUGS

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
220
221
222                                                                        MPX(2)
Impressum