'\" rt.\" -*- nroff -*-.\".\" @(#) streamio.2,v 1.1.4.1 2004/01/12 23:45:04 brian Exp.\".\" =========================================================================.\".\" Copyright (C) 2001-2004  OpenSS7 Corporation <www.openss7.com>.\".\" All Rights Reserved..\".\" Permission is granted to make and distribute verbatim copies of this.\" manual provided the copyright notice and this permission notice are.\" preserved on all copies..\".\" Permission is granted to copy and distribute modified versions of this.\" manual under the conditions for verbatim copying, provided that the.\" entire resulting derived work is distributed under the terms of a.\" permission notice identical to this one.\" .\" Since the Linux kernel and libraries are constantly changing, this.\" manual page may be incorrect or out-of-date.  The author(s) assume no.\" responsibility for errors or omissions, or for damages resulting from.\" the use of the information contained herein.  The author(s) may not.\" have taken the same level of care in the production of this manual,.\" which is licensed free of charge, as they might when working.\" professionally..\" .\" Formatted or processed versions of this manual, if unaccompanied by.\" the source, must acknowledge the copyright and authors of this work..\".\" =========================================================================.\".\" Modified 2004/01/12 23:45:04 by brian.\".\" =========================================================================.so lis.macros.R1bracket-label "\fR[\fB" "\fR]" "\fR, \fB"no-default-databasedatabase lis.refsaccumulatemove-punctuationabbreviate Ajoin-authors ", " ", " " and "et-al " et al" 2 3abbreviate-label-ranges ".."sort-adjacent-labels.R2.\".\".TH STREAMIO 2 "2004/01/12 23:45:04" "LiS-2_16_18-8" "Linux STREAMS".SH NAME.B streamio\- STREAMS ioctl commands .SH SYNOPSIS   .PP.B #include <sys/types.h>.br.B #include <stropts.h>.HP.BI "int " retval " = ioctl (int " fd ", int " command " , ... /* " arg " */);".SH DESCRIPTION.PP.PPSTREAMS I/O control commands are ioctl commands that are defined to operate onall STREAMS character special devices.  All of these commands are interpretedby the stream head.  Some commands are passed to the STREAMS module or driver..PPSTREAMS I/O control commands are invoked using the normal.BR ioctl (2)system call, but are defined only for STREAMS character special files..PP.I fdis an open file descriptor for a STREAMS character special file..PP.I commandis the STREAMS I/O control function that the caller requests be performed..PP.I argprovides additional information required by the particular I/O.IR command .Specific.IR command " and " argare described below..SH IOCTLS.PP.SS I_ATMARK.PP.PPChecks whether the next messages on the stream head read queue is marked..I argis an integer value indicating which messages to check as follows:.TP 12.B ANYMARKcheck whether the next message on the stream head read queue is marked..TP 12.B LASTMARKcheck whether the next message on the stream head read queue is the lastmarked message (i.e. it is not followed by a another marked message)..PPMarked messages are messages that have the.B MSGMARKflag set in the message.I b_flagfield..PPUpon success,.I I_ATMARKreturns (0) to indicate that the stream head read queue does not meet themark criteria, or (1) to indicate that it meets the mark criteria.Upon failure,.I I_ATMARKreturns -1 and sets.I errnoto an appropriate error number as follows:.TP 12.RB [ EINVAL ].I argis invalid..SS I_CANPUT.PP.PPChecks whether messages can be written to the queue band specified by.IR arg ..I argis an integer which contains the queue band to test for flow control.Upon success,.I retvalis false (0) if the queue band.I argis flow controlled,true (1) if the queue band is not flow controlled.Upon failure,.I retvalis -1 and.I errnois set to one of the following errors numbers:.TP 12.RB [ EINVAL ]integer.I argis outside the range 0 to 255 and does not represent a valid priority band..SS I_CKBAND.PP.PPChecks whether messages cna be read from the queue band specified by.IR arg ..I argis an integer which contains the queue band to test for an available message.Upon success,.B I_CKBANDreturns false (0) if there is no message for the specified queue band.I argavailable, and true (1) if a message for the specified queue band.I argis available to be read with.BR read "(2) or " getmsg (2).Upon failure,.B I_CKBANDreturns -1 and.I errnois set to one of the following error numbers:.TP 12.RB [ EINVAL ].I argcontains a priority band outside the range 0 - 255..TP 12.RB [ EINVAL ]the priority band does not exist.  (See.IR "\*(lqBUGS\*(rq" ,below.).SS I_FDINSERT.PP.PPThis command performs similar to.BR putmsg (2),however, it performs the additional function of inserting the read queuepointer associated with a specified file descriptor in the resulting message.This ioctl is often used to accepting incoming connections on.BR tpi (7)based protocols..PP.I argis a pointer to a.B strfdinsertstructure that is formatted as follows:.sp.nf\fC\s-1\struct strfdinsert {    struct strbuf ctlbuf;    struct strbuf databuf;    ulong flags;    int fildes;    int offset;};\s+1\fR.fi.PP.I ctlbufdescribes the control part of the message, and is formated the same as the.B strbufstructure pointed to by.I ctlptras an argument to.BR putmsg (2).The.I lenfield of this.B strbufstructure must be large enough to accept the translated file descriptor.Unlike.BR putmsg (2)this message must contain a control part..PP.I databufdescribes the data part of the message, formatted the same as the.B strbufstructure pointed to by.I datptras an argument to.BR putmsg (2).Unlike.BR putmsg (2)if the.I lenfield of this.B strbufstructure is zero, it indicates that no data part is to be sent with themessage.(For.BR putmsg (2),a.I lenfield of zero (0) would indicate to send a zero-length data part message.).PP.I flagsprovides the options flags formatted the same as the.I flagsargument to.BR putmsg (2)..PP.I fildesis the file descriptor of a stream to be translated to a read queue pointer andplaced into the control part of the message..PP.I offsetis the offset into the control part to place the read queue pointer associatedwith.IR fildes .This.I offsetmust leave sufficient room in the control part of the message to permit theread queue pointer to be overwritten without exceeding the bounds of thecontrol part..PPUpon succes,.B I_FDINSERTreturns zero (0).Upon failure,.B I_FDINSERTreturns -1 and sets.I errnoto one of the following error numbers:.TP 12.RB [ ENOSR ]a buffer for the resulting message could not be allocated..TP 12.RB [ EFAULT ].IR arg ", " ctlbuf ", " databuf ", " ctlbuf.buf " or " databuf.bufpoints outside the caller's valid address space..TP 12.RB [ EINVAL ].I fildesis invalid, or.I offsetis invalid, or.I flagsis invalid.(See.IR "\*(lqBUGS\*(rq" ,below.).TP 12.RB [ EINTR ]interrupted by a signal..TP 12.RB [ ENXIO ].I fdreceived a hangup or is closing.(See.IR "\*(lqBUGS\*(rq" ,below.).TP 12.RB [ ERANGE ]The.I lenof the data part of the message is outside the range.I q_minpszto.I q_maxpszinclusive for the topmost STREAMS module or driver under the stream head, or,the.I lenof the control or data part is larger than the maximum sized control or datamessage for the STREAMS subsystem..TP 12.RB [ EAGAIN ]the stream head is set for asynchronous operation.BR "" ( O_NONBLOCK " or " O_NDELAYwas set using.BR open "(2) or " fcntl (2)),the stream head was flow controlled and.I flagsindicated a normal priority message.(See.IR "\*(lqBUGS\*(rq" ,below.).PPIn addition, any error received in an error message will be returned in.IR errno ..SS I_FIND.PP.PPChecks whether the specified module is currently present in the streamspecified by.IR fd ..PP.I argis a pointer to a string which provides the name of the module to find..PPUpon success,.B I_FINDreturns true (1) if the module is present in the stream under the name.IR arg ,and returns false (0) if the module is not present in the stream.Upon failure,.B I_FINDreturns -1 and sets.I errnoto an appropriate error number as follows:.TP 12.RB [ EFAULT ].I argpoints to a string which exceeds the callers valid address space.(See.IR "\*(lqBUGS\*(rq" ,below.).TP 12.RB [ EINVAL ].I argpoints to an invalid module name..TP 12.RB [ ENOMEM ]memory could not be allocated tohold the string pointed to by.IR arg .(See.IR "\*(lqBUGS\*(rq" ,below.).TP 12.RB [ ENAMETOOLONG ].I argcontains a string that is greater than.B (FMNAMESZ + 1)in length..SS I_FLUSH.PP.PPFlushes the stream..PP.I argis an integer containing one of the following flags:.TP 12.B FLUSHRflush the read queues..TP 12.B FLUSHWflush the write queues..TP 12.B FLUSHRWflush both the read and write queues..PPUpon success,.B I_FLUSHreturns zero (0).Upon failure,.B I_FLUSHreturns -1 and sets.I errnoto an appropriate error number as follows:.TP 12.RB [ ENXIO ]the stream head specified by.I fdis closing or has received a hangup..TP 12.RB [ EINVAL ].I argcontains invalid flags other than.BR FLUSHR ", " FLUSHW " or " FLUSHRW ..TP 12.RB [ ENOMEM ]the.B M_FLUSHmessage could not be allocated.(See.IR "\*(lqBUGS\*(rq" ,below.).PPIn addition,.B I_FLUSHcan fail silently.(See.IR "\*(lqBUGS\*(rq" ,below.).SS I_FLUSHBAND.PP.PPFlushes the stream for a specified band..I argis a.B bandinfostructure formatted as follows:.sp.nf\fC\s-1\struct bandinfo {	unsigned char bi_pri;	int bi_flag;};\fR\s+1.fi.PP.I bi_prispecifies the priority of the band to flush..PP.I bi_flagspecifies which queues to flush and has one of the following values:.TP 12.B FLUSHRflush the read queues..TP 12.B FLUSHWflush the write queues..TP 12.B FLUSHRWflush the read and write queues..PPUpon success,.B I_FLUSHBANDreturns zero (0).Upon failure,.B I_FLUSHBANDreturns -1 and sets.I errnoto an appropriate error number as follows:.TP 12.RB [ ENXIO ]the stream head specified by.I fdis closing or has received a hangup..TP 12.RB [ EINVAL ].I bi_flagcontains invalid flags other than.BR FLUSHR ", " FLUSHW " or " FLUSHRW ..TP 12.RB [ ENOMEM ]the.B M_FLUSHmessage could not be allocated.(See.IR "\*(lqBUGS\*(rq" ,below.).PPIn addition,.B I_FLUSHBANDcan fail silently.(See.IR "\*(lqBUGS\*(rq" ,below.).SS I_GETBAND.PP.PPGets the priority band associated with the next message on the stream head read queue..I argis a pointer to an integer to receive the band number.Upon success,.B I_GETBANDreturns (0) and places the band associated with the next message on the streamhead read queue into the integer pointed to by.IR arg .Upon failure,.B I_GETBANDreturns -1 and sets.I errnoto an appropriate error number as follows:.TP 12.RB [ EFAULT ].I argpoints outside the caller's valid address space..TP 12.RB [ ENODATA ]there is no message on the stream head read queue..SS I_GETCLTIME.PP.PPGets the close delay time (in milliseconds) associated with the stream head..I argpoints to a.B long(see.IR "\*(lqBUGS\*(rq" ,below)to receive the delay..PPUpon success,.B I_GETCLTIMEreturns zero (0) and the close delay time in the.B longpointed to by.IR arg .Upon failure,.B I_GETCLTIMEreturns -1 and sets.I errnoto an appropriate error number as follows:.TP 12.RB [ EFAULT ].I argpoints outside the caller's valid address space..SS I_GETSIG.PP.PPGets a bitmask of the events for which the calling process is registeredto be sent a.B SIGPOLLsignal..I argpoints to an integer into which will be returned the bitmask.The bitmask returned in the integer pointed to by.I argwill contain a bitwise OR of one or more of the following flags:.TP 12.B S_INPUTany message but high priority on read queue..TP 12.B S_HIPRIhigh priority message on read queue..TP 12.B S_OUTPUTwrite queue is no longer full..TP 12.B S_MSGsignal message at front of read queue..TP 12.B S_ERRORerror message arrived at stream head..TP 12.B S_HANGUPhangup message arrived at stream head..TP 12.B S_RDNORMnormal message on read queue.TP 12.B S_WRNORMsame as.BR S_OUTPUT ..TP 12.B S_RDBANDout of band message on read queue..TP 12.B S_WRBANDcan write out of band message..TP 12.B S_BANDURGmodifier to.BR S_RDBAND ,to generate.B SIGURGinstead of.BR SIGPOLL ..TP 12.B S_ALLall flags..PPUpon success,.B I_GETSIGreturns (0) and the event bitmask in the integer pointed to by.IR arg .Upon failure,.B I_GETSIGreturns -1 and sets.I errnoto an appropriate error number as follows:.TP 12.RB [ EFAULT ].I argpoints outside the caller's valid address space..TP 12.RB [ EINVAL ]the calling process is not registered to receive a.B SIGPOLLsignal..SS I_GRDOPT.PP.PPGets the read options flags for the stream head..I argis a pointer to an integer to receive the stream head read options.The integer pointed to by.I argwill return one flag from the following mode flags:.TP 12.B RNORMbyte-stream mode.  This is the default read mode..TP 12.B RMSGDmessage discard mode..TP 12.B RMSGNmessage non-discard mode..PPbitwise OR'ed with one flag from the following protocol flags:.TP 12.B RPROTNORMfail.BR read (2)with.RB [ EBADMSG ]if a message containing a control part is at the front of the stream headread queue..TP 12.B RPROTDATdeliver control part of a message as data..TP 12.B RPROTDISdiscard control part of message, delivering any data part..PPUpon success,.B I_GRDOPTreturns zero (0) and the read options flags in the integer pointed to by.IR arg .Upon failure,.B I_GRDOPTreturns -1 and sets.I errnoto an appropriate error number as follows:.TP 12.RB [ EFAULT ].I argpoints outside the caller's valid address space..SS I_GWROPT.PP.PPGets the write options flags for the stream head..I argis a pointer to an integer to receive the stream head write options.  Theinteger pointed to by.I argwill return zero or more flags from the following flags:(These flags alter the operations of.BR write "(2) and " putmsg (2)on a STREAMS character special file.).TP 12.B SNDZEROsend a zero-length message downstream when a write of zero bytes occurs..TP 12