STREAM(4)

NAME
stream - I/O control for streams

SYNOPSIS
#include <sys/filio.h>
#include <sys/ttyio.h>

ioctl(fd, code, param)
void *param;

DESCRIPTION
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 disappeared, for example because the process at other end of a pipe has terminated, or a device has hung up, signal SIGPIPE 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; subsequent calls generate SIGPIPE signals.

Processing modules may be inserted into streams. These ioctl(2) calls insert, delete, inspect, and perform operations for stream I/O 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 often null, a pointer to int. The codes are

FIOPUSHLD
    Insert, at the near end of the stream, the line discipline named by the integer to which param points. A census of line discipline modules is given below.

FIOINSLD
    Insert 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.

FIOPOPLD
    Pop (removes) the nearest line discipline module, if param is 0 (null). If param points to an integer, the line discipline at that level is removed. The integer 0 is the same as a null param.

FIOLOOKLD
    Return the number of the topmost line discipline in the stack. If param is not 0 but instead points to an integer, the line discipline at that level is returned in the same integer.

FIOSNDFD
    Send the integer file descriptor pointed to by param to the process on the other end of pipe fd. The code is transmitted directly to the other end of the pipe, untransformed by line disciplines. It cannot be forged by the message line discipline, mesgld(4). The call returns immediately; it does not rendezvous with the matching FIORCVFD.

FIORCVFD
    Deliver a structure pointed to by param:
        struct passfd {
        	int	fd;
        	short	uid;
        	short	gid;
        	short	nice;
        	char	logname[8];
        	char	cap;
        };

    The call blocks until there is something in the stream. If data is present, it returns EIO. If a file descriptor has been sent from the other end of the pipe by FIOSNDFD, FIORCVFD fills in the user and group ID of the sending process, its niceness (see nice(2)), its login name, its capabilities in the form of the field lb_t (see getflab(2)), and a file descriptor for the file being sent; the file is now open in the receiving process. Another use of FIORCVFD is described in connld(4).

FIONREAD
    Store, in the integer pointed to by param, the number of characters that may be read from this stream without possible blocking.

FIOGSRC
    Copy the stream identifier to the SSRCSIZ-byte string pointed to by param.

FIOSSRC
    Copy the SSRCSIZ-byte string pointed to by param into the stream identifier. Capability T_EXTERN is required; see getplab(2). Empty by default, the stream identifier is customarily set on network connections to identify the source. Successful password demands may also be recorded in the stream identifier for the benefit of pwserv(8); see session(1).

TIOCSPGRP
    Make this process the head of a process 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 process 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 opening certain devices. Param must be 0.

TIOCGPGRP
    Store through param a short naming the process group associated with the stream.

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

TIOCNXCL
    Remove the inaccessibility of the stream.

TIOCSBRK
    Generate a message requesting a line break. The message is understood by devices capable of generating it (such as asynchronous character devices) and ignored otherwise.

TIOCFLUSH
    Generate a message causing downstream modules to throw away any queued characters, if possible. It applies to both input and output queues. If the stream serves a device, the flush message may cause further action in the device driver.

TIOCXFLUSH
    Delete all data and messages from input and output queues. No flush message is passed down the stream or to a device driver.

Here is a list of available line discipline modules. Each is an external integer, defined in libc; see intro(3).

tty_ld
    Regular terminal processing; see ttyld(4).

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

cdkp_ld
    Character-mode Datakit universal receiver protocol.

dkp_ld
    Block-mode Datakit universal receiver protocol.

rdk_ld

uxp_ld
    Special Datakit protocols used in connection setup.

buf_ld
    Buffering mechanism; see bufld(4).

mesg_ld
    turns stream control blocks arriving in the read direction into data messages, and written messages into controls. See mesgld(4).

rmesg_ld
    inverse of mesg_ld.

conn_ld
    For making unique connections to servers. See connld(4).

ip_ld

tcp_ld

udp_ld

arp_ld
    Internet protocols; see internet(3).

SEE ALSO
ioctl(2), getstsrc(3)
D. M. Ritchie, `A Stream I/O System' BLTJ, October, 1984
UNIX Programmer's Manual, Seventh Edition, Virtual VAX-11 Version, 1980 (Berkeley)