STREAM(4)                                               STREAM(4)

          stream - stream I/O control calls

          #include <sys/ioctl.h>
          ioctl(fd, code, param)
          union universe *param;

          A stream is a connection between two processes, or between a
          process and a device.  It is referred to by a file
          descriptor, and ordinary read and write calls apply.  When a
          write(2) call is given on a stream whose other end has dis-
          appeared, for example because the process at other end of a
          pipe has terminated, or a device has hung up, a SIGPIPE sig-
          nal is generated; if the signal is ignored, the write call
          returns error EPIPE.  The first several (currently 64)
          read(2) calls on such a disconnected streams return 0; sub-
          sequent calls generate SIGPIPE signals.

          Processing modules may be inserted into streams.  These
          ioctl calls insert, delete, inspect, and perform operations
          for stream IO modules.  They apply to the file descriptor of
          any open stream object: terminal, network connection, pipe.
          The param argument is a general pointer which, for these
          calls, is usually null or a pointer to int.  The codes are

                inserts, at the near end of the stream, the line dis-
                cipline named by the integer to which param points.  A
                census of line discipline modules is given below.

                inserts a named line discipline at a given level in a
                stack of such modules on the stream.  Param points to
                a structure containing two short integers respectively
                naming the line discipline and the level.  A level of
                0 could be accomplished by FIOPUSHLD.  This call is
                under construction and may not be available yet.

                pops (removes) the nearest line discipline module, if
                param is null.  If it points to an integer, the line
                discipline at that level is removed.  The integer 0
                corresponds to a null param, and (as with FIOINSLD)
                the non-null case may not be handled yet.

                returns the number of the topmost line discipline in
                the stack.  If param is not null but instead points to

     STREAM(4)                                               STREAM(4)

                an integer, the line discipline at that level is
                returned in the same integer.  As with push and pop,
                the non-null case may not be handled yet.

                sends the integer file descriptor pointed to by param
                to the process on the other end of the pipe whose file
                descriptor is fd.

                delivers a structure pointed to by param:

                struct passfd {
                       union {
                              int    fd;
                       } f;
                       short  uid;
                       short  gid;
                       short  nice;
                       short  fill;

                The call blocks until there is something in the
                stream.  If data is present, it returns EIO.  If the
                FIOSNDFD call has sent a file descriptor to the other
                end of the pipe, this call fills in the user and group
                ID of the sending process, its niceness (priority),
                and a file descriptor for the file being sent; this
                file is now open in the calling process.

                stores, in the integer pointed to by param, the number
                of characters that may be read from this stream with-
                out possible blocking.

                with null param makes this process the head of a pro-
                cess group and makes this stream its control stream.
                When signals, such as hangup, interrupt, and quit,
                arrive at a control stream, they are sent to its pro-
                cess group.  Child processes inherit the process group
                of their parent.  Process groups are created only by
                explicit use of this call, and not implicitly by open-
                ing certain devices.  If param is not null, it points
                to an integer nominating a process group to receive
                signals from this stream.

                stores through param an integer naming the process
                group associated with the stream.


     STREAM(4)                                               STREAM(4)

                marks this stream as inaccessible except by the
                super-user or by processes in the group associated
                with this stream.

                removes the inaccessibility of the stream.

                generates a message requesting a line break.  The mes-
                sage is understood by devices capable of generating it
                (such as asynchronous character devices) and ignored

                generates a message causing downstream modules to
                throw away any queued characters, if possible.  It
                applies to both input and output queues.

          Here is a list of available line discipline modules.  The
          magic numbers are collected in the standard library, and are
          accessible under the following names:

                Terminal processing according to standard Seventh Edi-
                tion rules; see ttyld(4).

                Terminal processing according to (modified) Berkeley
                `new tty' rules; see Berkeley Users Manual.

                Character-mode Datakit URP protocol.

                Block-mode Datakit URP protocol.

                Special Datakit protocol used in connection setup.

          pk_ld Packet-driver protocol (obsolete).

                Buffering mechanism; see bufld(4).

          mesg_ld, rmesg_ld
                Mesg_ld turns stream control blocks arriving in the
                read direction into data messages, and written mes-
                sages into controls.  rmesg_ld does the opposite.  See
                mesg (4).

                Helps debug stream line discipline modules.

     STREAM(4)                                               STREAM(4)

                For making unique connections to servers.  See

          ip_ld, tcp_ld, udp_ld, arp_ld
                Internet protocols; see inet(3).

          D. M. Ritchie, `A Stream I/O System' BLTJ, October, 1984

          -1 is returned for errors.