.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "<stropts.h>" 0P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" <stropts.h> 
.SH NAME
stropts.h \- STREAMS interface (\fBSTREAMS\fP)
.SH SYNOPSIS
.LP
\fB#include <stropts.h> \fP
.SH DESCRIPTION
.LP
The \fI<stropts.h>\fP header shall define the \fBbandinfo\fP structure
that includes at least the following members:
.sp
.RS
.nf

\fBunsigned char  bi_pri  \fP Priority band. \fB
int            bi_flag \fP Flushing type. \fB
\fP
.fi
.RE
.LP
The \fI<stropts.h>\fP header shall define the \fBstrpeek\fP structure
that includes at least the following members:
.sp
.RS
.nf

\fBstruct strbuf  ctlbuf  \fP The control portion of the message. \fB
struct strbuf  databuf \fP The data portion of the message. \fB
t_uscalar_t    flags   \fP RS_HIPRI or 0. \fB
\fP
.fi
.RE
.LP
The \fI<stropts.h>\fP header shall define the \fBstrbuf\fP structure
that includes at least the following members:
.sp
.RS
.nf

\fBint    maxlen \fP Maximum buffer length. \fB
int    len    \fP Length of data. \fB
char  *buf    \fP Pointer to buffer. \fB
\fP
.fi
.RE
.LP
The \fI<stropts.h>\fP header shall define the \fBstrfdinsert\fP structure
that includes at least the following
members:
.sp
.RS
.nf

\fBstruct strbuf  ctlbuf  \fP The control portion of the message. \fB
struct strbuf  databuf \fP The data portion of the message. \fB
t_uscalar_t    flags   \fP RS_HIPRI or 0. \fB
int            fildes  \fP File descriptor of the other STREAM. \fB
int            offset  \fP Relative location of the stored value. \fB
\fP
.fi
.RE
.LP
The \fI<stropts.h>\fP header shall define the \fBstrioctl\fP structure
that includes at least the following members:
.sp
.RS
.nf

\fBint    ic_cmd    \fP \fIioctl\fP() command. \fB
int    ic_timout \fP Timeout for response. \fB
int    ic_len    \fP Length of data. \fB
char  *ic_dp     \fP Pointer to buffer. \fB
\fP
.fi
.RE
.LP
The \fI<stropts.h>\fP header shall define the \fBstrrecvfd\fP structure
that includes at least the following
members:
.sp
.RS
.nf

\fBint    fda \fP Received file descriptor. \fB
uid_t  uid \fP UID of sender. \fB
gid_t  gid \fP GID of sender. \fB
\fP
.fi
.RE
.LP
The \fBuid_t\fP and \fBgid_t\fP types shall be defined through \fBtypedef\fP
as described in \fI<sys/types.h>\fP .
.LP
The \fI<stropts.h>\fP header shall define the \fBt_scalar_t\fP and
\fBt_uscalar_t\fP types, respectively, as signed and
unsigned opaque types of equal length of at least 32 bits.
.LP
The \fI<stropts.h>\fP header shall define the \fBstr_list\fP structure
that includes at least the following members:
.sp
.RS
.nf

\fBint                sl_nmods   \fP Number of STREAMS module names. \fB
struct str_mlist  *sl_modlist \fP STREAMS module names. \fB
\fP
.fi
.RE
.LP
The \fI<stropts.h>\fP header shall define the \fBstr_mlist\fP structure
that includes at least the following member:
.sp
.RS
.nf

\fBchar  l_name[FMNAMESZ+1] \fP A STREAMS module name. \fB
\fP
.fi
.RE
.LP
At least the following macros shall be defined for use as the \fIrequest\fP
argument to \fIioctl\fP():
.TP 7
I_PUSH
Push a STREAMS module.
.TP 7
I_POP
Pop a STREAMS module.
.TP 7
I_LOOK
Get the top module name.
.TP 7
I_FLUSH
Flush a STREAM.
.TP 7
I_FLUSHBAND
Flush one band of a STREAM.
.TP 7
I_SETSIG
Ask for notification signals.
.TP 7
I_GETSIG
Retrieve current notification signals.
.TP 7
I_FIND
Look for a STREAMS module.
.TP 7
I_PEEK
Peek at the top message on a STREAM.
.TP 7
I_SRDOPT
Set the read mode.
.TP 7
I_GRDOPT
Get the read mode.
.TP 7
I_NREAD
Size the top message.
.TP 7
I_FDINSERT
Send implementation-defined information about another STREAM.
.TP 7
I_STR
Send a STREAMS \fIioctl\fP().
.TP 7
I_SWROPT
Set the write mode.
.TP 7
I_GWROPT
Get the write mode.
.TP 7
I_SENDFD
Pass a file descriptor through a STREAMS pipe.
.TP 7
I_RECVFD
Get a file descriptor sent via I_SENDFD.
.TP 7
I_LIST
Get all the module names on a STREAM.
.TP 7
I_ATMARK
Is the top message "marked''?
.TP 7
I_CKBAND
See if any messages exist in a band.
.TP 7
I_GETBAND
Get the band of the top message on a STREAM.
.TP 7
I_CANPUT
Is a band writable?
.TP 7
I_SETCLTIME
Set close time delay.
.TP 7
I_GETCLTIME
Get close time delay.
.TP 7
I_LINK
Connect two STREAMs.
.TP 7
I_UNLINK
Disconnect two STREAMs.
.TP 7
I_PLINK
Persistently connect two STREAMs.
.TP 7
I_PUNLINK
Dismantle a persistent STREAMS link.
.sp
.LP
At least the following macros shall be defined for use with I_LOOK:
.TP 7
FMNAMESZ
The minimum size in bytes of the buffer referred to by the \fIarg\fP
argument.
.sp
.LP
At least the following macros shall be defined for use with I_FLUSH:
.TP 7
FLUSHR
Flush read queues.
.TP 7
FLUSHW
Flush write queues.
.TP 7
FLUSHRW
Flush read and write queues.
.sp
.LP
At least the following macros shall be defined for use with I_SETSIG:
.TP 7
S_RDNORM
A normal (priority band set to 0) message has arrived at the head
of a STREAM head read queue.
.TP 7
S_RDBAND
A message with a non-zero priority band has arrived at the head of
a STREAM head read queue.
.TP 7
S_INPUT
A message, other than a high-priority message, has arrived at the
head of a STREAM head read queue.
.TP 7
S_HIPRI
A high-priority message is present on a STREAM head read queue.
.TP 7
S_OUTPUT
The write queue for normal data (priority band 0) just below the STREAM
head is no longer full. This notifies the process that
there is room on the queue for sending (or writing) normal data downstream.
.TP 7
S_WRNORM
Equivalent to S_OUTPUT.
.TP 7
S_WRBAND
The write queue for a non-zero priority band just below the STREAM
head is no longer full.
.TP 7
S_MSG
A STREAMS signal message that contains the SIGPOLL signal reaches
the front of the STREAM head read queue.
.TP 7
S_ERROR
Notification of an error condition reaches the STREAM head.
.TP 7
S_HANGUP
Notification of a hangup reaches the STREAM head.
.TP 7
S_BANDURG
When used in conjunction with S_RDBAND, SIGURG is generated instead
of SIGPOLL when a priority message reaches the front of the
STREAM head read queue.
.sp
.LP
At least the following macros shall be defined for use with I_PEEK:
.TP 7
RS_HIPRI
Only look for high-priority messages.
.sp
.LP
At least the following macros shall be defined for use with I_SRDOPT:
.TP 7
RNORM
Byte-STREAM mode, the default.
.TP 7
RMSGD
Message-discard mode.
.TP 7
RMSGN
Message-non-discard mode.
.TP 7
RPROTNORM
Fail \fIread\fP() with [EBADMSG] if a message containing a control
part is at the front
of the STREAM head read queue.
.TP 7
RPROTDAT
Deliver the control part of a message as data when a process issues
a \fIread\fP().
.TP 7
RPROTDIS
Discard the control part of a message, delivering any data part, when
a process issues a \fIread\fP().
.sp
.LP
At least the following macros shall be defined for use with I_SWOPT:
.TP 7
SNDZERO
Send a zero-length message downstream when a \fIwrite\fP() of 0 bytes
occurs.
.sp
.LP
At least the following macros shall be defined for use with I_ATMARK:
.TP 7
ANYMARK
Check if the message is marked.
.TP 7
LASTMARK
Check if the message is the last one marked on the queue.
.sp
.LP
At least the following macros shall be defined for use with I_UNLINK:
.TP 7
MUXID_ALL
Unlink all STREAMs linked to the STREAM associated with \fIfildes\fP.
.sp
.LP
The following macros shall be defined for \fIgetmsg\fP(), \fIgetpmsg\fP(),
\fIputmsg\fP(), and \fIputpmsg\fP():
.TP 7
MSG_ANY
Receive any message.
.TP 7
MSG_BAND
Receive message from specified band.
.TP 7
MSG_HIPRI
Send/receive high-priority message.
.TP 7
MORECTL
More control information is left in message.
.TP 7
MOREDATA
More data is left in message.
.sp
.LP
The \fI<stropts.h>\fP header may make visible all of the symbols from
\fI<unistd.h>\fP.
.LP
The following shall be declared as functions and may also be defined
as macros. Function prototypes shall be provided.
.sp
.RS
.nf

\fBint    isastream(int);
int    getmsg(int, struct strbuf *restrict, struct strbuf *restrict,
           int *restrict);
int    getpmsg(int, struct strbuf *restrict, struct strbuf *restrict,
           int *restrict, int *restrict);
int    ioctl(int, int, ... );
int    putmsg(int, const struct strbuf *, const struct strbuf *, int);
int    putpmsg(int, const struct strbuf *, const struct strbuf *, int,
           int);
int    fattach(int, const char *);
int    fdetach(const char *);
\fP
.fi
.RE
.LP
\fIThe following sections are informative.\fP
.SH APPLICATION USAGE
.LP
None.
.SH RATIONALE
.LP
None.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fI<sys/types.h>\fP, \fI<unistd.h>\fP, the System
Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIclose\fP(), \fIfcntl\fP(),
\fIgetmsg\fP(), \fIioctl\fP(), \fIopen\fP(), \fIpipe\fP(), \fIread\fP(),
\fIpoll\fP(), \fIputmsg\fP(), \fIsignal\fP(), \fIwrite\fP()
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .