OpenSS7
SS7 for the
Common Man
© Copyright 1997-2007 OpenSS7 Corporation All Rights Reserved.
Last modified: Mon, 28 Apr 2008 12:53:43 GMT
Home TopIndex FirstPrev Next LastMore Download Info FAQ Mail  Home -> Documentation -> Man Pages -> Manpage of STREAMIO
Quick Links

Download

SCTP

SIGTRAN

SS7

Hardware

STREAMS

Asterisk

Related

Package

Manual

FAQ

Man Pages

Applications

SS7 Stack

ISDN Stack

SIGTRAN Stack

VoIP Stack

MG Stack

SS7/ISDN Devices

IP Transport

Embedded Systems

OS

Documentation

FAQ

SIGTRAN

Design

Conformance

Performance

References

Man Pages

Manuals

Papers

Home

Overview

Status

Documentation

Resources

About

News

Manpage of STREAMIO

Description: Manual Page

Keywords: ss7 ss7/ip ss7 over ip ss7 mtp ss7 sccp ss7 tcap sigtran mtp sccp tcap openss7 acb56 linux telephony pstn linux telephony linux nebs linux compactpci


STREAMIO

Section: The OpenSS7 Project Protocols (7)
Updated: Mon, 01 Sep 2014 11:10:13 GMT
Index Return to Main Contents

NAME

streamio - STREAMS ioctl commands

SYNOPSIS

#include <sys/types.h>
#include <stropts.h>

int retval = ioctl (int fd, int command , ... /* arg */);

DESCRIPTION

STREAMS
I/O control commands are ioctl commands that are defined to operate on all STREAMS character special devices. All of these commands are interpreted by the stream head. Some commands are passed to the STREAMS module or driver.

STREAMS I/O control commands are invoked using the normal ioctl(2s) system call, but are defined only for STREAMS character special files.

fd
is an open file descriptor for a STREAMS character special file.
command
is the STREAMS I/O control function that the caller requests be performed.
arg
provides additional information required by the particular I/O command. Specific command and arg are described below.

IOCTLS

I_ATMARK

Checks whether the next messages on the stream head read queue is marked. arg is an integer value indicating which messages to check as follows:

ANYMARK
check whether the next message on the stream head read queue is marked.
LASTMARK
check whether the next message on the stream head read queue is the last marked message (i.e. it is not followed by a another marked message).

Marked messages are messages that have the MSGMARK flag set in the message b_flag field.

Upon success, I_ATMARK returns (0) to indicate that the stream head read queue does not meet the mark criteria, or (1) to indicate that it meets the mark criteria. Upon failure, I_ATMARK returns -1 and sets errno(3) to an appropriate error number as follows:

[EINVAL]
arg is invalid.

Solaris®[1] also uses the MSGNEXTMARK and MSGNOTNEXTMARK flags on the message blocks; but their use is undocumented. AIX®[2] indicates that it is permissible for arg to be the inclusive OR of the ANYMARK and LASTMARK flags. HP-UX®[3] indicates that if both ANYMARK and LASTMARK are set, ANYMARK supersedes LASTMARK. UnixWare®[4] indicates that the bitwise-OR of ANYMARK and LASTMARK is allowed and that, if both are set, ANYMARK supersedes LASTMARK.

I_CANPUT

Checks whether messages can be written to the queue band specified by arg. arg is an integer which contains the queue band to test for flow control.

Linux Fast-STREAMS adds the extension that arg can also be one of the following values:

ANYBAND
instead of testing a specified band, tests whether any (existing) band is writable.

Upon success, retval is false (0) if the queue band arg is flow controlled, true (1) if the queue band is not flow controlled. Upon failure, retval is -1 and errno(3) is set to one of the following errors numbers:

[EINVAL]
arg is outside the range 0 to 255 and does not represent a valid priority band.

Any of the errors returned by putpmsg(2s) may be returned in errno. Any error received in an M_ERROR(9) message indicating a write error for the stream will be returned in errno. (See also ERRORS below.)

I_CKBAND

Checks whether messages can be read from the queue band specified by arg. arg is an integer which contains the queue band to test for an available message. Upon success, I_CKBAND returns false (0) if there is no message for the specified queue band arg available, and true (1) if a message for the specified queue band arg is available to be read with read(2) or getmsg(2). Upon failure, I_CKBAND returns -1 and errno(3) is set to one of the following error numbers:

[EINVAL]
arg contains a priority band outside the range 0 - 255.

Any of the errors returned by getpmsg(2s) may be returned in errno. Any error received in an M_ERROR(9) message indicating a read error for the stream will be returned in errno. (See also ERRORS below.)

I_FDINSERT

This command performs similar to putmsg(2), however, it performs the additional function of inserting the bottom read queue pointer associated with a specified file descriptor in the resulting message. This ioctl is often used to accepting incoming connections on tpi(7) based protocols.

arg is a pointer to a strfdinsert structure that is formatted as follows:

struct strfdinsert {
    struct strbuf ctlbuf;
    struct strbuf databuf;
    ulong flags;
    int fildes;
    int offset;
};

ctlbuf
describes the control part of the message, and is formated the same as the strbuf structure pointed to by ctlptr as an argument to putmsg(2). The len field of this strbuf structure must be large enough to accept the translated file descriptor. Unlike putmsg(2) this message must contain a control part.
databuf
describes the data part of the message, formatted the same as the strbuf structure pointed to by datptr as an argument to putmsg(2). Unlike putmsg(2) if the len field of this strbuf structure is zero, it indicates that no data part is to be sent with the message. (For putmsg(2), a len field of zero (0) would indicate to send a zero-length data part message.)
flags
provides the options flags formatted the same as the flags argument to putmsg(2).
fildes
is the file descriptor of a stream to be translated to a read queue pointer and placed into the control part of the message.
offset
is the offset into the control part to place the read queue pointer associated with fildes. This offset must leave sufficient room in the control part of the message to permit the read queue pointer to be overwritten without exceeding the bounds of the control part.

Upon success, I_FDINSERT returns zero (0). Upon failure, I_FDINSERT returns -1 and sets errno(3) to one of the following error numbers:

[EFAULT]
arg, ctlbuf, databuf, ctlbuf.buf or databuf.buf points outside the caller's valid address space.
[ENOSR]
a buffer for the resulting message could not be allocated.
[EINVAL]
fildes is invalid, or offset is invalid, or flags is invalid.

Any of the errors returned by putpmsg(2s) may be returned in errno. Any error received in an M_ERROR(9) message indicating a write error for the stream will be returned in errno. (See also ERRORS below.)

I_FIND

Checks whether the specified module is currently present in the stream specified by fd.

arg is a pointer to a string which provides the name of the module to find.

Upon success, I_FIND returns true (1) if the module is present in the stream under the name arg, and returns false (0) if the module is not present in the stream. Upon failure, I_FIND returns -1 and sets errno(3) to an appropriate error number as follows:

[EFAULT]
arg points to a string which exceeds the callers valid address space.

I_FLUSHBAND

Flushes the stream for a specified band. arg points to a bandinfo structure formatted as follows:

struct bandinfo {
        unsigned char bi_pri;
        int bi_flag;
};

bi_pri specifies the priority of the band to flush. bi_flag specifies which queues to flush and has one of the following values:

FLUSHR
flush the read queues.
FLUSHW
flush the write queues.
FLUSHRW
flush the read and write queues.

Note that on a bare STREAMS-based pipe(4), specifying FLUSHR will flush the read queues at both ends of the pipe, and FLUSHW will flush the write queues at both ends of the pipe. FLUSHRW will still flush both queues. This is expected behaviour for bare STREAMS-based pipes (that is, pipes that have no modules pushed on either end). For the I_FLUSH command to flush the proper queues in modules pushed on a STREAMS-based pipe, pipemod(4) must be pushed onto one end of the pipe before pushing any other modules. Pushing pipemod(4) will also reverse the effect that FLUSHR and FLUSHW have on the opposite STREAM head: FLUSHR flushes the near read queue and the far write queue, FLUSHW flushes the near write queue and the far read queue. See pipemod(4) for details.

Upon success, I_FLUSHBAND returns zero (0). Upon failure, I_FLUSHBAND returns -1 and sets errno(3) to an appropriate error number as follows:

[EFAULT]
arg points outside the caller's valid address space.
[EINVAL]
bi_flag contains invalid flags other than FLUSHR, FLUSHW or FLUSHRW.
[ENOSR]
the M_FLUSH(9) message could not be allocated.

(See also ERRORS below.)

I_FLUSH

Flushes the stream.

arg is an integer containing one of the following flags:

FLUSHR
flush the read queues.
FLUSHW
flush the write queues.
FLUSHRW
flush both the read and write queues.

Note that on a bare STREAMS-based pipe(4), specifying FLUSHR will flush the read queues at both ends of the pipe, and FLUSHW will flush the write queues at both ends of the pipe. FLUSHRW will still flush both queues. This is expected behaviour for bare STREAMS-based pipes (that is, pipes that have no modules pushed on either end). For the I_FLUSH command to flush the proper queues in modules pushed on a STREAMS-based pipe, pipemod(4) must be pushed onto one end of the pipe before pushing any other modules. Pushing pipemod(4) will also reverse the effect that FLUSHR and FLUSHW have on the opposite STREAM head: FLUSHR flushes the near read queue and the far write queue, FLUSHW flushes the near write queue and the far read queue. See pipemod(4) for details.

Upon success, I_FLUSH returns zero (0). Upon failure, I_FLUSH returns -1 and sets errno(3) to an appropriate error number as follows:

[EINVAL]
arg contains invalid flags other than FLUSHR, FLUSHW or FLUSHRW.
[ENOSR]
the M_FLUSH(9) message could not be allocated.

(See also ERRORS below.)

I_GETBAND

Gets the priority band associated with the next message on the stream head read queue. arg is a pointer to an integer to receive the band number. Upon success, I_GETBAND returns (0) and places the band associated with the next message on the stream head read queue into the integer pointed to by arg. Upon failure, I_GETBAND returns -1 and sets errno(3) to an appropriate error number as follows:

[EFAULT]
arg points outside the caller's valid address space.
[ENODATA]
there is no message on the stream head read queue.

Any of the errors returned by getpmsg(2s) may be returned in errno. Any error received in an M_ERROR(9) message indicating a read error for the stream will be returned in errno. (See also ERRORS below.)

I_GETCLTIME

Gets the close delay time (in milliseconds) associated with the stream head. arg points to an int to receive the delay.

Upon success, I_GETCLTIME returns zero (0) and the close delay time in the int pointed to by arg. Upon failure, I_GETCLTIME returns -1 and sets errno(3) to an appropriate error number as follows:

[EFAULT]
arg points outside the caller's valid address space.

I_GETSIG

Gets a bitmask of the events for which the calling process is registered to be sent a SIGPOLL signal. arg points to an integer into which will be returned the bit mask. The bit mask returned in the integer pointed to by arg will contain a bitwise OR of one or more of the following flags:

S_INPUT
any message but high priority on read queue.
S_HIPRI
high priority message on read queue.
S_OUTPUT
write queue is no longer full.
S_MSG
signal message at front of read queue.
S_ERROR
error message arrived at stream head.
S_HANGUP
hangup message arrived at stream head.
S_RDNORM
normal message on read queue
S_WRNORM
same as S_OUTPUT.
S_RDBAND
out of band message on read queue.
S_WRBAND
can write out of band message.
S_BANDURG
modifier to S_RDBAND, to generate SIGURG instead of SIGPOLL.
S_ALL
all flags.

Upon success, I_GETSIG returns (0) and the event bit mask in the integer pointed to by arg. Upon failure, I_GETSIG returns -1 and sets errno(3) to an appropriate error number as follows:

[EFAULT]
arg points outside the caller's valid address space.
[EINVAL]
the calling process is not registered to receive a SIGPOLL signal.

I_SRDOPT

Sets the read(2s) options flags for the stream head. These flags alter the behaviour of the read(2s) call when called for fd. arg is an integer value containing the read options flags which may be one flag from the mode group as follows:

RNORM
byte-stream mode. This is the default read mode. This is the normal byte-stream mode where message boundaries are ignored. read(2s) and readv(2s) returns data until the read count has been satisfied or a zero length message is received.
RMSGN
message non-discard mode. The read(2s) or readv(2s) will return when either the count is satisfied, a zero length message is received, or a message boundary is encountered. If there is any data left in a message after the read count has been satisfied, the message is placed back on the stream head read queue. The data will be read on a subsequent read(2s) or readv(2s) call.
RMSGD
message discard mode. Similar to RMSGN mode, above, but data that remains in a message after the read count has been satisfied is discarded.
RFILL
message fill mode. Similar to RNORM but requests that the stream head fill a buffer completely before returning to the application. This is used in conjunction with a cooperating module and M_READ(9) messages.

bitwise OR'ed with one flag from the protocol group as follows:

RPROTNORM
fail read when control part present. Fail read(2s) with [EBADMSG] if a message containing a control part is at the front of the stream head read queue. Otherwise, the message is read as normal. This is the default setting for new stream heads. This setting is used with the timod(4) module requiring the use of the tirdwr(4) module for use with the xti(3) library[5].
RPROTDAT
deliver control part of a message as data. The control part of the message is prepended to the data part. This may be useful for specialized libraries or at the user's option with timod(4) or sockmod(4) modules.
RPROTDIS
discard control part of message, delivering any data part. The control part of the message is discarded and the data part is processed. This setting is used with the sockmod(4) module, or at the user's option with other modules or drivers.

Note: Although all modes terminate the read on a zero-length message, POSIX requires that zero only be returned from read when the requested length is zero or an end of file (M_HANGUP(9)) has occurred. Therefore, LfS[6] only returns on a zero-length message if some data has been read already.

I_GRDOPT

Gets the read options flags for the stream head. arg is a pointer to an integer to receive the stream head read options. The integer pointed to by arg will return one flag from the following mode flags:

RNORM
byte-stream mode. This is the default read mode.
RMSGN
message non-discard mode.
RMSGD
message discard mode.
RFILL
message fill mode.

bitwise OR'ed with one flag from the following protocol flags:

RPROTNORM
fail read when control part present.
RPROTDAT
deliver control part of a message as data.
RPROTDIS
discard control part of message, delivering any data part.

Upon success, I_GRDOPT returns zero (0) and the read options flags in the integer pointed to by arg. Upon failure, I_GRDOPT returns -1 and sets errno(3) to an appropriate error number as follows:

[EFAULT]
arg points outside the caller's valid address space.

I_SWROPT

Sets the write(2s) options flags for the stream head. These flags alter the behaviour of the write(2) and putmsg(2) calls when called for fd. arg is an integer value containing the write options flags which may be one or more flags from the following:

SNDZERO
send a zero-length message downstream when a write of zero bytes occurs.
SNDPIPE
send SIGPIPE on write(2s) and putmsg(2) if the stream head has received a write error (M_ERROR(9)) message.
SNDHOLD
hold messages briefly in an attempt to coalesce smaller transmissions into larger ones.

I_GWROPT

Gets the write options flags for the stream head. arg is a pointer to an integer to receive the stream head write options. The integer pointed to by arg will return zero or more flags from the following flags: (These flags alter the operations of write(2) and putmsg(2) on a STREAMS character special file.)

SNDZERO
send a zero-length message downstream when a write of zero bytes occurs.
SNDPIPE
send SIGPIPE on write(2s) and putmsg(2) if the stream head has received a write error (M_ERROR(9)) message.
SNDHOLD
hold messages briefly in an attempt to coalesce smaller transmissions into larger ones.

Upon success, I_GWROPT returns zero (0) and the write options flags in the integer pointed to by arg. Upon failure, I_GWROPT returns -1 and sets errno(3) to an appropriate error number as follows:

[EFAULT]
arg pointed outside the caller's valid address space.

I_SERROPT

Sets the error options flags for the stream head. These flags alter the behavior of system calls in response to the receipt of an M_ERROR(9) message at the stream head when called for fd. arg is an integer value containing the error option flags which may be one flag controlling the read error behaviour from the following:

RERRNORM
specifies that read errors are treated as normal and persist until they are cleared with a subsequent M_ERROR(9) message indicating a read error of zero (0), or until the stream is closed. This is the default.
RERRNONPERSIST
specifies that read errors are treated as non-persistent. Once the read error is delivered to a system call, it is cleared automatically.

and one flag controlling the write error behaviour from the following:

WERRNORM
specifies that write errors are treated as normal and persist until they are cleared with a subsequent M_ERROR(9) message indicating a write error of zero (0), or until the stream is closed. This is the default.
WERRNONPERSIST
specifies that write errors are treated as non-persistent. Once the write error is delivered to a system call, it is cleared automatically.

Upon success, I_SERROPT returns zero (0) and the error options flags are set according to the value in arg. Upon failure, I_SERROPT returns -1 and sets errno(3) to an appropriate error number as follows:

[EINVAL]
the flags specified in arg are invalid.

I_GERROPT

Gets ther error options flags for the stream head. arg is a pointer to an integer to receive the stream head error options. The integer pointed to by arg will return one flag from the following flags: (These flags alter the operations of read errors in return to system calls.)

RERRNORM
indicates that read errors are treated as normal and persist until they are cleared with a subsequent M_ERROR(9) message indicating a read error of zero (0), or until the stream is closed. This is the default.
RERRNONPERSIST
indicates that read errors are treated as non-persistent. Once the read error is delivered to a system call, it is cleared automatically.

and one flag from the following flags: (These flags alter the operations of the write errors in return to system calls.)

WERRNORM
indicates that write errors are treated as normal and persist until they are cleared with a subsequent M_ERROR(9) message indicating a write error of zero (0), or until the stream is closed. This is the default.
WERRNONPERSIST
indicates that write errors are treated as non-persistent. Once the write error is delivered to a system call, it is cleared automatically.

Upon success, I_GERROPT returns the error options flags in the integer pointed to by arg. Upon failure, I_GERROPT returns -1 and sets errno(3) to an appropriate error number as follows:

[EFAULT]
arg points outside the user's valid address space.

I_LINK

Links one Stream under the multiplexing driver on stream fd. arg is the integer file descriptor of the stream to link under fd.

This call is passed as an I_STR ioctl using an M_IOCTL(9) down the stream head write queue to be processed by the multiplexing driver on fd. I_LINK will block until an acknowledgement is received from the driver, the call times out waiting for an acknowledgement, the call is interrupted while blocked by a signal, or the receipt of hangup or error message.

Upon success, I_LINK returns a positive integer representing the multiplex identifier of the lower stream. This value can be subsequently used in a I_UNLINK command. Upon failure, I_LINK returns -1 and sets errno(3) to an appropriate error number as follows:

[EBADF]
arg is not a valid open file descriptor.
[ETIME]
the command timed out before receiving an acknowledgement.
[ENOSR]
a buffer for the ioctl message could not be allocated.
[EINVAL]
fd received an error message.
[EIO]
the stream specified by fd is closing.
[ENXIO]
the stream specified by fd received a hangup.
[EINVAL]
fd has no lower multiplexing driver definition.
[EINVAL]
arg is already linked under a multiplexer or is not a STREAMS character special file.

In addition, any error received in an error message will be returned in errno. Also, any error returned by the module or driver in an ioctl positive or negative acknowledgement message will also be returned in errno.

I_LIST

List all of the modules pushed on the stream specified by fd. arg is a pointer to a str_list structure to place the module names as follows:

struct str_list {
    int sl_nmods;
    struct str_mlist *sl_modlist;
};

sl_nmods indicates the number of str_mlist structures the array pointed to by sl_modlist. sl_modlist points to a list of str_mlist structures formatted as follows:

struct str_mlist {
    char l_name[FMNAMESZ + 1];
};

If arg is NULL, I_LIST will return a positive integer retval indicating the number of modules, including the driver, on stream fd. This can be used to determine the number of module and driver names before passing the str_list structure.

I_LIST only lists sl_nmods number of modules and drivers starting with the module below the stream head. If there is an insufficient number of members in the sl_modlist array to hold all of the names, I_LIST will success, but will return only the number of names in the space provided.

Upon success, I_LIST returns zero (0) and the module and driver names in the passed in str_list and str_mlist structures, or, when arg is NULL, returns a positive integer indicating the number of modules plus the driver on the stream fd. Upon failure, I_LIST returns -1 and sets errno(3) to an appropriate error number as follows:

[EFAULT]
arg or str_mlist points outside the caller's valid address space.
[EINVAL]
sl_nmods is less than 1, or, str_mlist is NULL.

I_LOOK

Gets the name of the first module beneath the stream head. arg is a pointer to a character string buffer to accept the name. This buffer must be at least (FNAMESZ + 1) in length.

Upon success, I_LOOK copies the name of the module beneath the stream head to the buffer pointed to by arg. Upon failure, I_LOOK returns -1 and sets errno(3) to an appropriate error number as follows:

[EFAULT]
arg pointed outside the caller's valid address space.
[EINVAL]
there is no module beneath the stream head.

I_NREAD

Gets the number of unread data bytes contained in M_DATA(9) message blocks in the first message on the stream head read queue. arg points to an integer to contain the number of unread bytes.

Upon success, I_NREAD returns zero (0) or a positive integer indicating the number of messages on the stream head read queue. Upon failure, I_NREAD returns -1 and sets errno(3) to an appropriate error number as follows:

[EFAULT]
arg points outside the caller's valid address space.

I_PEEK

Peeks at the next message on the stream head read queue without removing the message from the queue. arg is a pointer to a strpeek structure formatted as follows:

struct strpeek {
    struct strbuf ctlbuf;
    struct strbuf databuf;
    long flags;
};

ctlbuf
describes the control part of the message, and is formatted the same as the strbuf structure pointed to by ctlptr as an argument to getmsg(2). If there is no control part, the maxlen field of this strbuf should be zero (0).
databuf
describes the data part of the message, and is formatted the same as the strbuf structure pointed to by datptr as an argument to getmsg(2). If there is no data part, the maxlen field of this strbuf should be zero (0).
flags
provides the read flags and is formatted the same as the flags argument to getmsg(2).

Upon success, I_PEEK returns zero (0) if there was no message on the stream head read queue, and returns one (1) and the retrieved message in the structure pointed to by arg, if there was a message on the stream head read queue. Upon failure, I_PEEK returns -1 and sets errno(3) to an appropriate error message as follows:

[EFAULT]
arg, ctlbuf.buf or databuf.buf point outside the caller's valid address space.

In addition, I_PEEK can return any errno(3) returned by getmsg(2). See getmsg(2).

I_PLINK

Links on stream under the multiplexing driver on stream fd. arg is the integer file descriptor of the stream to link under fd.

This call is passed as an I_STR ioctl using an M_IOCTL(9) down the stream head write queue to be processed by the multiplexing driver on fd. I_PLINK will block until an acknowledgement is received from the driver, the call times out waiting for an acknowledgement, the call is interrupted while blocked by a signal, or the receipt of hangup or error message.

Upon success, I_PLINK returns a positive integer representing the multiplex identifier of the lower stream. This value can be subsequently used in a I_PUNLINK command. Upon failure, I_PLINK returns -1 and sets errno(3) to an appropriate error number as follows:

[EBADF]
arg is not a valid open file descriptor.
[ETIME]
the command timed out before receiving an acknowledgement.
[ENOSR]
a buffer for the ioctl message could not be allocated.
[EINVAL]
fd received an error message.
[EIO]
the stream specified by fd is closing.
[ENXIO]
the stream specified by fd received a hangup.
[EINVAL]
fd has no lower multiplexing driver definition.
[EINVAL]
arg is already linked under a multiplexer or is not a STREAMS character special file.

In addition, any error received in an error message will be returned in errno. Also, any error returned by the module or driver in an ioctl positive or negative acknowledgement message will also be returned in errno.

I_POP

Pops the STREAMS module just beneath the stream head from fd. arg is ignored.

Upon success, I_POP pops the moudule beneath the stream head by calling qdetach(9) and returns (0). Upon failure, I_POP returns -1 and sets errno(3) to an appropriate error number as follows:

[EIO]
the stream specified by fd is closing.
[ENXIO]
the stream specified by fd received a hangup.
[EINVAL]
there was no module beneath the stream head.
[EPERM]
an anchor was placed with I_ANCHOR and an attempt is being made by a non-privileged process to pop beneath the anchor position.

See qdetach(9) for more information.

I_PUNLINK

Unlink a stream from under a multiplexing driver that was previously linked with I_PLINK. arg is the multiplexer identifier of the linked stream, or, MUXID_ALL indicating that all linked streams are requested to be unlinked.

When MUXID_ALL is specified, all streams previously linked under the multiplexing driver with I_PLINK will be unlinked.

This call is passed as an I_STR ioctl using an M_IOCTL(9) down the stream head write queue to be processed by the multiplexing driver on fd. I_PUNLINK will block until an acknowledgement is received from the driver, the call times out waiting for an acknowledgement, the call is interrupted while blocked by a signal, or the receipt of hangup or error message.

Upon success, I_PUNLINK returns zero (0) and unlinks the specified stream(s). Upon failure, I_PUNLINK returns -1 and sets errno(3) to an appropriate error number as follows:

[EIO]
the stream specified by fd is closing.
[ENXIO]
the stream specified by fd received a hangup.
[EINVAL]
arg is invalid.
[ETIME]
the call timed out waiting for a response from the driver.
[ERESTARTSYS]
a signal arrived before the operation could begin.
[EINTR]
a signal arrived before the operation could complete.
[ENOSR], [EAGAIN]
could not allocate the buffer for the ioctl message.

In addition, any error received in a error message will be returned in errno. Also, any error returned by the module or driver in a ioctl positive or negative acknowledgement message will also be returned in errno.

I_PUSH

Pushes a STREAMS module by name on the stream specified by fd. arg is a pointer to a string that contains the name of the module to push.

Upon success, I_PUSH pushes the named module and returns zero (0). Upon failure, I_PUSH returns -1 and sets errno(3) to an appropriate error number as follows:

[EFAULT]
arg points outside the caller's valid address space.
[EIO]
the stream specified by fd is closing.
[ENXIO]
the stream specified by fd received a hangup.
[ENXIO]
the open procedure of the pushed module failed.
[EINVAL]
the module name pointed to by arg is invalid.
[ENOSR]
fd has reached its maximum push count. No more modules can be pushed on the stream.
[ENOMEM]
memory allocation for the queue pair for the pushed module failed.
[ENOPKG]
the module has no qopen routine.

In addition, any error returned by the module's qopen(9) function may be returned by I_PUSH. See qattach(9) and qopen(9) for more information.

I_ANCHOR

Requests that an anchor be placed at the position beneath the stream head. When an anchor is placed, modules beneath the anchor point can no longer be popped from the stream by non-privileged processing using I_POP. Modules can still be pushed and popped above the anchor by non-privileged processes. If an anchor already exists, the anchor is moved. arg is ignored and should be set to zero (0).

Upon success, I_ANCHOR places the anchor and returns zero. Upon failure, I_ANCHOR returns -1 and sets errno(3) to an appropriate error number as follows:

[EINVAL]
fd specifies a pipe.

I_RECVFD

arg is a pointer to a strrecvfd structure formatted as follows:

struct strrecvfd {
    int fd;
    uid_t uid;
    gid_t gid;
    ...
};

In the strrecfd structure, fd is the file descriptor received, and uid and gid are the credentials associated with the file descriptor.

Upon success, I_RECVFD returns zero (0) and the completed strrecvfd structure. Upon failure, I_RECVFD returns -1 and sets errno(3) to an appropriate error number as follows:

[EFAULT]
arg points outside the caller's valid address space.
[EPIPE]
fd refers to a pipe and the other end of the pipe is closed.
[EIO]
fd is a valid, open, file descriptor, but the stream is closing.
[ENXIO]
fd refers to a stream that has received a hangup.
[EBADF]
fd is not a stream.
[EAGAIN]
no file descriptor message (M_PASSFP(9)) is waiting.
[ENFILE]
no remaining file descriptors could be allocated for the receiving process.
[EBADMSG]
the message on the top of the stream head read queue is not a passed file descriptor (M_PASSFD(9)) message.

I_SENDFD

Sends a file descriptor to the other end of a pipe. arg is the integer file descriptor to send.

Upon success, I_SENDFD returns (0). Upon failure, I_SENDFD returns -1 and sets errno(3) to an appropriate error number as follows:

[EINVAL]
fd is not a STREAMS based pipe.
[EIO]
fd is a valid, open, file descriptor, but the stream is closing.
[ENXIO]
fd refers to a stream that has received a hangup.
[EPIPE]
fd refers to a pipe, but the other end of the pipe is closed.
[EBADF]
arg is not a valid file descriptor.
[ENOSR]
a buffer could not be allocated to send the file descriptor.
[EAGAIN]
the read queue at the other end of the pipe is full.

I_SETCLTIME

Sets the closing delay time for the stream head. arg points to an int that specifies the delay time in milliseconds.

Upon success, I_SETCLTIME returns zero (0) and sets the close delay time for fd. Upon failure, I_SETCLTIME returns -1 and sets errno(3) to an appropriate error number as follows:

[EINVAL]
arg is outside the valid range 0 to 300,000 milliseconds.

I_SETSIG

Sets the mask of events for which the stream head will send the calling process a SIGPOLL or SIGURG signal. arg is an integer value contains one or more of the following event flags:

S_INPUT
any message but high priority on read queue.
S_HIPRI
high priority message on read queue.
S_OUTPUT
write queue is no longer full.
S_MSG
signal message at front of read queue.
S_ERROR
error message arrived at stream head.
S_HANGUP
hangup message arrived at stream head.
S_RDNORM
normal message on read queue
S_WRNORM
same as S_OUTPUT.
S_RDBAND
out of band message on read queue.
S_WRBAND
can write out of band message.
S_BANDURG
modifier to S_RDBAND, to generate SIGURG instead of SIGPOLL.
S_ALL
all flags.

I_STR

Generates an internal STREAMS ioctl message and places it on the stream head's write queue for processing by the module or driver and returns the response. arg is a pointer to a strioctl structure formatted as follows:

struct strioctl {
    int ic_cmd;
    int ic_timout;
    int ic_len;
    char *ic_dp;
};

ic_cmd
is the command to issue. The command can by any of the commands listed here that are handled by the module or driver (e.g. I_LINK) or any other ioctl command understood by a module or driver on the stream fd.
ic_timout
is the period of time to wait for an acknowledgement in milliseconds, or -1 indicating that there is no timeout.
ic_len
is the length of the argument data pointed to by ic_dp.
ic_dp
is a pointer to the argument data of length ic_len bytes.

I_STR generates an M_IOCTL(9) message an passes it downstream to the module or driver and blocks until a positive or negative acknowledgement is received, the command times out, an hangup or error message is received by the stream head, or a signal is received.

Upon success, I_STR returns the return value specified in the positive or negative acknowledgement message. Upon failure, I_STR returns -1 and sets errno(3) to an appropriate error number as follows:

[EFAULT]
arg or ic_dp point outside the caller's valid address space.
[EINVAL]
ic_len is less than 0.
[EINVAL]
ic_len is greater than the maximum size of the data part of a message.
[EINVAL]
ic_timout is less than -1.
[ETIME], [EAGAIN]
the operation timed out waiting for an acknowledgement.
[ERESTARTSYS]
a signal arrived before the operation could begin.
[EINTR]
a signal arrived before the operation could complete.
[EIO]
the stream specified by fd is closing.
[ENXIO]
the stream specified by fd received a hangup.
[ENOSR]
a buffer for the ioctl message could not be allocated.

In addition, I_STR can return any errno(3) placed in an error message received by the stream head, or placed in the positive or negative acknowledgement message by the module or driver.

I_UNLINK

Unlink a stream from under a multiplexing driver that was previously linked with I_LINK. arg is the multiplexer identifier of the linked stream, or, MUXID_ALL indicating that all linked streams are requested to be unlinked.

When MUXID_ALL is specified, all streams previously linked under the multiplexing driver with I_LINK for the specified control stream, fd, will be unlinked.

This call is passed as an I_STR ioctl using an M_IOCTL(9) down the stream head write queue to be processed by the multiplexing driver on fd. I_UNLINK will block until an acknowledgement is received from the driver, the call times out waiting for an acknowledgement, the call is interrupted while blocked by a signal, or the receipt of hangup or error message.

Upon success, I_UNLINK returns zero (0) and unlinks the specified stream(s). Upon failure, I_UNLINK returns -1 and sets errno(3) to an appropriate error number as follows:

[EIO]
the stream specified by fd is closing.
[ENXIO]
the stream specified by fd received a hangup.
[EINVAL]
arg is invalid, or fd is a pipe or FIFO.
[ETIME]
the call timed out waiting for a response from the driver.
[ERESTARTSYS]
a signal arrived before the operation could begin.
[EINTR]
a signal arrived before the operation could complete.
[ENOSR], [EAGAIN]
could not allocate the buffer for the ioctl message.

In addition, any error received in a error message will be returned in errno. Also, any error returned by the module or driver in a ioctl positive or negative acknowledgement message will also be returned in errno.

RETURN VALUE

Upon success, ioctl() returns zero (0) or a positive integer. Upon failure, ioctl() returns -1 and sets errno(3) to an appropriate error number.

ERRORS

When ioctl() fails, it returns -1 and sets errno(3) to one of the following errors:

[EFAULT]
arg or a member of arg, points to an address that is outside the caller's valid address space.
[EINVAL]
fd, command, arg or a member of arg is invalid.
[EBADF]
fd is not a valid open file descriptor.
[ENOSTR]
fd is not a stream special character device.
[EOPNOTSUPP]
fd does not support the requested operation.
[EIO]
fd refers to stream that is closing.
[ENOTTY]
fd does not refer to a STREAMS device that accepts I/O controls.
[ENODEV]
fd refers to a STREAMS device that does not support the ioctl(2s) system call.
[ENXIO]
fd refers to stream that has received a hangup.
[ENXIO]
the I/O control command cannot be performed by this particular sub-device.
[EPIPE]
fd refers to a pipe and the other end of the pipe is closed.
[ESTRPIPE]
fd refers to a STREAMS-based pipe and a write operation was attempted with no readers at the other end, or a read operation was attempted, the pipe is empty, and there are no readers at the other end. (This error is returned by strread(9) and strwrite(9) internally and should not be exposed to the user. Instead, a [EPIPE] should be generated.)
[EINVAL]
fd refers to a stream that is linked under a multiplexing driver. If a stream is linked under a multiplexing driver, all ioctl(2s) commands other than I_UNLINK or I_PUNLINK will return [EINVAL].
[ERESTARTSYS]
a signal was received before the operation could begin.
[EINTR]
a signal was recievied before the operation could complete.
[EAGAIN], [EWOULDBLOCK]
the file is set for asynchronous I/O and the operation would block.
[ETIME]
the operation timed out awaiting an acknowledgement or response from the driver.
[ENOSR]
a message block could not be allocated during the operation and the operation is not permitted to block.

Any error delivered to the stream head in an M_ERROR(9) message can be returned in errno(3).

Where the command is passed to the module or driver, or the command results in the call to a module or driver open or close procedures, or link or unlink procedures, the error number returned by the module or driver open or close procedure can be returned in errno(3).

Any error returned in an M_IOCNAK(9) message from the driver in response to a I_STR ioctl can be returned in errno(3).

NOTICES

STREAMS ioctl() calls are complex and there is much conflicting documentation in specific areas of behaviour. Not all bugs are bugs and not all features are features.

SEE ALSO

close(2), fcntl(2), getmsg(2), ioctl(2s), open(2s), open(2s), poll(2s), putmsg(2), read(2s), signal(2), signal(5), write(2s), qopen(9), qclose(9), qattach(9), qdetach(9).

STREAMS(9) input-output control commands are also documented individually in the following manual pages: I_ATMARK(7), I_CANPUT(7), I_CKBAND(7), I_FATTACH(7), I_FDETACH(7), I_FDINSERT(7), I_FIND(7), I_FLUSH(7), I_FLUSHBAND(7), I_GETBAND(7), I_GETCLTIME(7), I_GETPMSG(7), I_GETSIG(7), I_GRDOPT(7), I_GWROPT(7), I_ISASTREAM(7), I_LINK(7), I_LIST(7), I_LOOK(7), I_NREAD(7), I_PEEK(7), I_PIPE(7), I_PLINK(7), I_POP(7), I_PUNLINK(7), I_PUSH(7), I_PUTPMSG(7), I_RECVFD(7), I_SENDFD(7), I_SETCLTIME(7), I_SETSIG(7), I_SRDOPT(7), I_STR(7), I_SWROPT(7), I_UNLINK(7).

The OpenSS7 Project also supports some Solaris® specific STREAMS(9) input-output controls for compatibility with Solaris®. These are documented in separate manual pages as follows: I_SERROPT(7), I_GERROPT(7), I_ANCHOR(7), I_ESETSIG(7), I_EGETSIG(7).

If your GNU/Linux distribution is equipped with OpenGroup POSIX/SUSv3 manual pages, see also ioctl(3p).

BUGS

streamio has no known bugs.

STREAMS ioctl() calls are complex and there is much conflicting documentation in specific areas of behaviour. Not all bugs are bugs and not all features are features.

COMPATIBILITY

streamio is compatible with SVR 4.2[7], Solaris®, UnixWare® and LiS[8], with the following portability considerations:

---
Linux Fast-STREAMS supports the RFILL read mode. This read mode is AIX®[9] specific.
---
Linux Fast-STREAMS provides ioctls that are used to implement this system call.
---
Linux Fast-STREAMS recognizes some Solaris®-specific and LiS-specific IO control numbers for compatibility.
---
The numbering of standard input-output control commands for STREAMS(9) is split between SVR 4.2-style[7] implementations and OSF/1.2-style[10] style implementations. The OpenGroup SUS/POSIX specifications specify the input-output control names, but not the numbering. Specific intput-output control numbers that differ between SVR 4.2 and OSF/1.2 are: I_SWROPT(7), I_GWROPT(7), I_LIST(7), I_FLUSHBAND(7), I_CKBAND(7), I_GETBAND(7), I_ATMARK(7), I_SETCLTIME(7), I_GETCLTIME(7), I_CANPUT(7).
(If we were smart, we would change the numbering in <sys/stropts.h> depending upon the processor for which the package is compiled to match the particular UNIX® vendor's numbering scheme.)
---
Two standard input-output control commands,--- I_PLINK(7) and I_PUNLINK(7), differ in numbering between SVR 3[11], and SVR 4[12].
---
AIX® HP-UX®, and UnixWare® document that, when command is I_SETCLTIME, arg is a pointer to an integer timeout value. Solaris® documents that, when command is I_SETCLTIME, arg is a long timeout value. LiS follows Solaris®. SUSv2[13] documents that, when command is I_SETCLTIME, arg is a pointer to an integer timeout value. Solaris® can be seen in strace(8) output to pass a pointer instead of a value. This means that Solaris® documentation is erroneous, and LiS implementation is wrong.
Portable STREAMS(9) libraries and applications programs will use The OpenSS7 Project instead of LiS.

CONFORMANCE

SVID[14], XID[15], SUSv2[13], SUSv3[16], POSIX.

Conformance is tested using the test-streams(8) test case executable and the The OpenSS7 Project autotest test suite.

HISTORY

ioctl() for STREAMS first appeared in SVR 3[11].

REFERENCES

[1]
Solaris® 8, Solaris 8 Docmentation, 2001, (Santa Clara, California), Sun Microsystems, Inc., Sun. <http://docs.sun.com/>
[2]
AIX® 5L Version 5.1, AIX 5L Version 5.1 Documentation, 2001, (Boulder, Colorado), Internatonal Business Machines Corp., IBM. <http://publibn.boulder.ibm.com/>
[3]
HP-UX® 11i v2, HP-UX 11i v2 Documentation, 2001, (Palo Alto, California), Hewlett-Packard Company, HP. <http://docs.hp.com/>
[4]
UnixWare® 7.1.3, UnixWare 7.1.3 (OpenUnix 8) Documentation, 2002, (Lindon, Utah), Caldera International, Inc., Caldera. <http://uw713doc.sco.com/>
[5]
Magic Garden, The Magic Garden Explained: The Internals of UNIX® System V Release 4 / An Open Systems Design, 1994, (Australia), B. Goodheart, J. Cox, Prentice Hall. [ISBN 0-13-098138-9] 525.
[6]
streams-0.9.2, Linux Fast-STREAMS (LfS) 0.9.2 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[7]
SVR 4.2, UNIX® System V Release 4.2 Programmer's Manual, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[8]
LIS 2.18, Linux STREAMS (LiS) 2.18.6 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[9]
AIX® 5L Version 5.1, AIX Communications Programming Concepts, 2001, (Boulder, Colorado), Internatonal Business Machines Corp., IBM. "Differences Between Portable Streams Environment and V.4 STREAMS" <http://publibn.boulder.ibm.com/>
[10]
Digital® UNIX (OSF/1.2), Digital UNIX Documentation Library, 2003, (Palo Alto, California), Digital Equipment Corporation, Hewlett-Packard Company. <http://www.true64unix.compaq.com/docs/>
[11]
SVR 3, UNIX® System V Release 3 Programmer's Manual, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[12]
SVR 4, UNIX® System V Release 4 Programmer's Manual, 1990, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[13]
SUS Version 2, Single UNIX Specification, OpenGroup, Open Group Publication. <http://www.opengroup.org/onlinepubs/>
[14]
SVID, System V, Interface Definition, Fourth Edition.
[15]
XBD Issue 5, X/Open System Interface Definitions, Issue 5, OpenGroup, Open Group Publication. <http://www.opengroup.org/onlinepubs/>
[16]
SUS Version 3, Single UNIX Specification, OpenGroup, Open Group Publication. <http://www.opengroup.org/onlinepubs/>

TRADEMARKS

OpenSS7tm
is a trademark of OpenSS7 Corporation.
Linux®
is a registered trademark of Linus Torvalds.
UNIX®
is a registered trademark of The Open Group.
Solaris®
is a registered trademark of Sun Microsystems.

Other trademarks are the property of their respective owners.

IDENTIFICATION

The OpenSS7 Project: Package OpenSS7 version 0.9.2 released Mon, 01 Sep 2014 11:10:13 GMT.

Copyright©1997-2008OpenSS7 Corp.
All Rights Reserved.
(See roff source for permission notice.)



Index

NAME
SYNOPSIS
DESCRIPTION
IOCTLS
I_ATMARK
I_CANPUT
I_CKBAND
I_FDINSERT
I_FIND
I_FLUSHBAND
I_FLUSH
I_GETBAND
I_GETCLTIME
I_GETSIG
I_SRDOPT
I_GRDOPT
I_SWROPT
I_GWROPT
I_SERROPT
I_GERROPT
I_LINK
I_LIST
I_LOOK
I_NREAD
I_PEEK
I_PLINK
I_POP
I_PUNLINK
I_PUSH
I_ANCHOR
I_RECVFD
I_SENDFD
I_SETCLTIME
I_SETSIG
I_STR
I_UNLINK
RETURN VALUE
ERRORS
NOTICES
SEE ALSO
BUGS
COMPATIBILITY
CONFORMANCE
HISTORY
REFERENCES
TRADEMARKS
IDENTIFICATION

This document was created by man2html, using the manual pages.
Time: 11:10:12 GMT, September 01, 2014
OpenSS7
SS7 for the
Common Man
Home TopIndex FirstPrev Next LastMore Download Info FAQ Mail  Home -> Documentation -> Man Pages -> Manpage of STREAMIO
Last modified: Mon, 28 Apr 2008 12:53:43 GMT
© Copyright 1997-2007 OpenSS7 Corporation All Rights Reserved.