mirror of https://github.com/mkerrisk/man-pages
400 lines
9.1 KiB
Plaintext
400 lines
9.1 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "<stropts.h>" P 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 .
|