Return to mpx.2 CVS log

Up to [Research Unix] / researchv10dc / man / manb

Annotation of researchv10dc/man/manb/mpx.2, revision 1.1

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.