The Single UNIX ® Specification, Version 2
Copyright © 1997 The Open Group

 NAME

stropts.h - STREAMS interface

 SYNOPSIS



#include <stropts.h>

 DESCRIPTION

The <stropts.h> header defines the bandinfo structure that includes at least the following members:

unsigned char bi_pri
int           bi_flag

The <stropts.h> header defines the strpeek structure that includes at least the following members:


struct strbuf ctlbuf
struct strbuf databuf
t_uscalar_t   flags

The <stropts.h> header defines the strbuf structure that includes at least the following members:


int           maxlen     maximum buffer length
int           len        length of data
char         *buf        ptr to buffer

The <stropts.h> header defines the strfdinsert structure that includes at least the following members:


struct strbuf ctlbuf
struct strbuf databuf
t_uscalar_t   flags
int           fildes
int           offset

The <stropts.h> header defines the strioctl structure that includes at least the following members:


int           ic_cmd
int           ic_timout
int           ic_len
char         *ic_dp

The <stropts.h> header defines the strrecvfd structure that includes at least the following members:


int           fd
uid_t         uid
gid_t         gid

The uid_t and gid_t types are defined through typedef as described in <sys/types.h>.

The t_uscalar_t type is defined as described in <xti.h> in the referenced Networking Services, Issue 5 specification.

The <stropts.h> header defines the str_list structure that includes at least the following members:


int               sl_nmods
struct str_mlist *sl_modlist

The <stropts.h> header defines the str_mlist structure that includes at least the following member:


char          l_name[FMNAMESZ+1]

At least the following macros are defined for use as the request argument to ioctl():

I_PUSH
Push STREAMS module onto the top of the current STREAM, just below the STREAM head.
I_POP
Remove STREAMS module from just below the STREAM head.
I_LOOK
Retrieve the name of the module just below the STREAM head and place it in a character string. At least the following macros are defined for use as the arg argument:
FMNAMESZ
The minimum size in bytes of the buffer referred to by the arg argument.

I_FLUSH
This request flushes all input and/or output queues, depending on the value of the arg argument. At least the following macros are defined for use as the arg argument:
FLUSHR
Flush read queues.
FLUSHW
Flush write queues.
FLUSHRW
Flush read and write queues.

I_FLUSHBAND
Flush only band specified.

I_SETSIG
Informs the STREAM head that the process wants the SIGPOLL signal issued (see signal() and sigset()) when a particular event has occurred on the STREAM.

The header <stropts.h> defines these possible values for arg when I_SETSIG is specified:

S_RDNORM
A normal (priority band set to 0) message has arrived at the head of a STREAM head read queue.
S_RDBAND
A message with a non-zero priority band has arrived at the head of a STREAM head read queue.
S_INPUT
A message, other than a high-priority message, has arrived at the head of a STREAM head read queue.
S_HIPRI
A high-priority message is present on a STREAM head read queue.
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.
S_WRNORM
Same as S_OUTPUT.
S_WRBAND
The write queue for a non-zero priority band just below the STREAM head is no longer full.
S_MSG
A STREAMS signal message that contains the SIGPOLL signal reaches the front of the STREAM head read queue.
S_ERROR
Notification of an error condition reaches the STREAM head.
S_HANGUP
Notification of a hangup reaches the STREAM head.
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.

I_GETSIG
Returns the events for which the calling process is currently registered to be sent a SIGPOLL signal.

I_FIND
Compares the names of all modules currently present in the STREAM to the name pointed to by arg.

I_PEEK
Allows a process to retrieve the information in the first message on the STREAM head read queue without taking the message off the queue. At least the following macros are defined for use as the arg argument:
RS_HIPRI
Only look for high-priority messages.

I_SRDOPT
Sets the read mode. At least the following macros are defined for use as the arg argument:
RNORM
Byte-STREAM mode, the default.
RMSGD
Message-discard mode.
RMSGN
Message-nondiscard mode.
RPROTNORM
Fail read() with [EBADMSG] if a message containing a control part is at the front of the STREAM head read queue.
RPROTDAT
Deliver the control part of a message as data when a process issues a read().
RPROTDIS
Discard the control part of a message, delivering any data part, when a process issues a read().

I_GRDOPT
Returns the current read mode setting.

I_NREAD
Counts the number of data bytes in data blocks in the first message on the STREAM head read queue.

I_FDINSERT
Creates a message from the specified buffer(s), adds information about another STREAM, and sends the message downstream.

I_STR
Constructs an internal STREAMS ioctl() message and sends that message downstream.

I_SWROPT
Sets the write mode. At least the following macros are defined for use as the arg argument:
SNDZERO
Send a zero-length message downstream when a write() of 0 bytes occurs.

I_GWROPT
Returns the current write mode setting.

I_SENDFD
Requests the STREAM associated with fildes to send a message, containing a file pointer, to the STREAM head at the other end of a STREAMS pipe.

I_RECVFD
Retrieves the file descriptor associated with the message sent by an I_SENDFD ioctl() over a STREAMS pipe.

I_LIST
This request allows the process to list all the module names on the STREAM, up to and including the topmost driver name.

I_ATMARK
This request allows the process to see if the current message on the STREAM head read queue is "marked" by some module downstream. At least the following macros are defined for use as the arg argument:
ANYMARK
Check if the message is marked.
LASTMARK
Check if the message is the last one marked on the queue.

I_CKBAND
Check if the message of a given priority band exists on the STREAM head read queue.

I_GETBAND
Return the priority band of the first message on the STREAM head read queue.

I_CANPUT
Check if a certain band is writable.

I_SETCLTIME
Allows the process to set the time the STREAM head will delay when a STREAM is closing and there is data on the write queues.

I_GETCLTIME
Returns the close time delay.

I_LINK
Connects two STREAMs.

I_UNLINK
Disconnects the two STREAMs. The header defines at least the following value for arg:
MUXID_ALL
Unlink all STREAMs linked to the STREAM associated with fildes.

I_PLINK
Connects two STREAMs with a persistent link.

I_PUNLINK
Disconnects the two STREAMs that were connected with a persistent link.

The following macros are defined for getmsg(), getpmsg(), putmsg() and putpmsg():

MSG_ANY
Receive any message.
MSG_BAND
Receive message from specified band.
MSG_HIPRI
Send/Receive high priority message.
MORECTL
More control information is left in message.
MOREDATA
More data is left in message.

The header <stropts.h> may make visible all of the symbols from <unistd.h>.

The following are declared as functions in the <stropts.h> header and may also be defined as macros. Function prototypes must be provided for use with an ISO C compiler.


int    isastream(int);
int    getmsg(int, struct strbuf *, struct strbuf *, int *);
int    getpmsg(int, struct strbuf *, struct strbuf *, int *, int *);
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 *);

 APPLICATION USAGE

None.

 FUTURE DIRECTIONS

None.

 SEE ALSO

close(), fcntl(), getmsg(), ioctl(), open(), pipe(), read(), poll(), putmsg(), signal(), sigset(), write(), <xti.h>.

UNIX ® is a registered Trademark of The Open Group.
Copyright © 1997 The Open Group
[ Main Index | XSH | XCU | XBD | XCURSES | XNS ]