Return to mpx.2 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / old / man

Annotation of 43BSDReno/old/man/mpx.2, revision 1.1

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.