path: root/man-pages-posix-2017/man0p/stropts.h.0p

'\" et
.TH stropts.h "0P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\"
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.\"
.SH NAME
stropts.h
\(em STREAMS interface (\fBSTREAMS\fP)
.SH SYNOPSIS
.LP
.nf
#include <stropts.h>
.fi
.SH DESCRIPTION
The
.IR <stropts.h> 
header shall define the
.BR bandinfo
structure, which shall include at least the following members:
.sp
.RS 4
.nf

int            bi_flag  \fRFlushing type.\fR
unsigned char  bi_pri   \fRPriority band.\fR
.fi
.P
.RE
.P
The
.IR <stropts.h> 
header shall define the
.BR strpeek
structure, which shall include at least the following members:
.sp
.RS 4
.nf

struct strbuf  ctlbuf   \fRThe control portion of the message.\fR
struct strbuf  databuf  \fRThe data portion of the message.\fR
t_uscalar_t    flags    \fRRS_HIPRI or 0.\fR
.fi
.P
.RE
.P
The
.IR <stropts.h> 
header shall define the
.BR strbuf
structure, which shall include at least the following members:
.sp
.RS 4
.nf

char  *buf     \fRPointer to buffer.\fP
int    len     \fRLength of data.\fP
int    maxlen  \fRMaximum buffer length.\fP
.fi
.P
.RE
.P
The
.IR <stropts.h> 
header shall define the
.BR strfdinsert
structure, which shall include at least the following members:
.sp
.RS 4
.nf

struct strbuf  ctlbuf   \fRThe control portion of the message.\fR
struct strbuf  databuf  \fRThe data portion of the message.\fR
int            fildes   \fRFile descriptor of the other STREAM.\fR
t_uscalar_t    flags    \fRRS_HIPRI or 0.\fR
int            offset   \fRRelative location of the stored value.\fR
.fi
.P
.RE
.P
The
.IR <stropts.h> 
header shall define the
.BR strioctl
structure, which shall include at least the following members:
.sp
.RS 4
.nf

int    ic_cmd     \fIioctl\fR(\|) command.\fR
char  *ic_dp      \fRPointer to buffer.\fR
int    ic_len     \fRLength of data.\fR
int    ic_timout  \fRTimeout for response.\fR
.fi
.P
.RE
.P
The
.IR <stropts.h> 
header shall define the
.BR strrecvfd
structure, which shall include at least the following members:
.sp
.RS 4
.nf

int    fd   \fRReceived file descriptor.\fR
gid_t  gid  \fRGID of sender.\fR
uid_t  uid  \fRUID of sender.\fR
.fi
.P
.RE
.P
The
.IR <stropts.h> 
header shall define the
.BR uid_t
and
.BR gid_t
types through
.BR typedef ,
as described in
.IR <sys/types.h> .
.P
The
.IR <stropts.h> 
header shall define the
.BR t_scalar_t
and
.BR t_uscalar_t
types, respectively, as signed and unsigned opaque types of equal
length of at least 32 bits.
.P
The
.IR <stropts.h> 
header shall define the
.BR str_list
structure, which shall include at least the following members:
.sp
.RS 4
.nf

struct str_mlist  *sl_modlist  \fRSTREAMS module names.\fR
int                sl_nmods    \fRNumber of STREAMS module names.\fR
.fi
.P
.RE
.P
The
.IR <stropts.h> 
header shall define the
.BR str_mlist
structure, which shall include at least the following member:
.sp
.RS 4
.nf

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

int    fattach(int, const char *);
int    fdetach(const char *);
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    isastream(int);
int    putmsg(int, const struct strbuf *, const struct strbuf *, int);
int    putpmsg(int, const struct strbuf *, const struct strbuf *, int,
           int);
.fi
.P
.RE
.LP
.IR "The following sections are informative."
.SH "APPLICATION USAGE"
None.
.SH RATIONALE
None.
.SH "FUTURE DIRECTIONS"
None.
.SH "SEE ALSO"
.IR "\fB<sys_types.h>\fP",
.IR "\fB<unistd.h>\fP"
.P
The System Interfaces volume of POSIX.1\(hy2017,
.IR "\fIclose\fR\^(\|)",
.IR "\fIfattach\fR\^(\|)",
.IR "\fIfcntl\fR\^(\|)",
.IR "\fIfdetach\fR\^(\|)",
.IR "\fIgetmsg\fR\^(\|)",
.IR "\fIioctl\fR\^(\|)",
.IR "\fIisastream\fR\^(\|)",
.IR "\fIopen\fR\^(\|)",
.IR "\fIpipe\fR\^(\|)",
.IR "\fIread\fR\^(\|)",
.IR "\fIpoll\fR\^(\|)",
.IR "\fIputmsg\fR\^(\|)",
.IR "\fIsignal\fR\^(\|)",
.IR "\fIwrite\fR\^(\|)"
.\"
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1-2017, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, 2018 Edition,
Copyright (C) 2018 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 .
.PP
Any typographical or formatting errors that appear
in this page are most likely
to have been introduced during the conversion of the source files to
man page format. To report such errors, see
https://www.kernel.org/doc/man-pages/reporting_bugs.html .