streamio.7

7号信令功能代码,为开源代码

.B SNDPIPE
send
.B SIGPIPE
on
.BR write (2)
and
.BR putmsg (2)
if the stream head has received a write error
.BR "" ( M_ERROR )
message.
.PP
Upon success,
.B I_GWROPT
returns zero (0) and the write options flags in the integer pointed to by
.IR arg .
Upon failure,
.B I_GWROPT
returns -1 and sets
.I errno
to an appropriate error number as follows:
.TP 12
.RB [ EFAULT ]
.I arg
pointed outside the caller's valid address space.
.SS I_LINK
.PP
.PP
Links on stream under the multiplexing driver on stream
.IR fd .
.I arg
is the integer file descriptor of the stream to link under
.IR fd .
.PP
This call is passed as an
.B I_STR
ioctl using an
.B M_IOCTL
down the stream head write queue to be processed by the multiplexing driver on
.IR fd .
.B I_LINK
will block until an acknowledgment 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.
.PP
Upon success,
.B I_LINK
returns a positive integer representing the multiplex identifier of the lower
stream.  This value can be subsequently used in a
.B I_UNLINK
command.
Upon failure,
.B I_LINK
returns -1 and sets
.I errno
to an appropriate error number as follows:
.PP
.TP 12
.RB [ EBADF ]
.I arg
is not a valid open file descriptor.
.TP 12
.RB [ ETIME ]
the command timed out before receiving an acknowledgment.
.TP 12
.RB [ ENOSR ]
a buffer for the ioctl message could not be allocated.
.TP 12
.RB [ EINVAL ]
.I fd
received an error message.
.TP 12
.RB [ ENXIO ]
.I fd
received a hangup or is closing.
.TP 12
.RB [ EINVAL ]
.I fd
has no lower multiplexing driver definition.
.TP 12
.RB [ EINVAL ]
.I arg
is already linked under a multiplexor or is not a STREAMS character special
file.
.PP
In addition, any error received in an error message will be returned in
.IR errno .
Also, any error returned by the module or driver in an ioctl positive or
negative acknowledgement message will also be returned in
.IR errno .
.SS I_LIST
.PP
.PP
List all of the modules pushed on the stream specified by
.IR fd .
.I arg
is a pointer to a
.B str_list
structure to place the module names as follows:
.sp
.nf
\fC\s-1\
struct str_list {
    int sl_nmods;
    struct str_mlist *sl_modlist;
};
\fR\s+1
.fi
.PP
.I sl_nmods
indicates the number of
.B str_mlist
structures the array pointed to by
.IR sl_modlist .
.I sl_modlist
points to a list of
.B str_mlist
structures formatted as follows:
.sp
.nf
\fC\s-1\
struct str_mlist {
    char l_name[FMNAMESZ + 1];
};
\fR\s+1
.fi
.PP
If
.I arg
is
.BR NULL ,
.B I_LIST
will return a positive integer
.I retval
indicating the number of modules, including the driver, on stream
.IR fd .
This can be used to determine the number of module and driver names before
passing the
.B str_list
structure.
.PP
.B I_LIST
only lists
.I sl_nmods
number of modules and drivers starting with the module below the stream head.
If there is an insuffient number of members in the
.I sl_modlist
array to hold all of the names,
.B I_LIST
will success, but will return only the number of names in the space provided.
.PP
Upon success,
.B I_LIST
returns zero (0) and the module and driver names in the passed in
.B str_list " and " str_mlist
structures, or, when
.I arg
is
.BR NULL ,
returns a positive integer indicating the number of modules plus the driver on
the stream
.IR fd.
Upon failure,
.B I_LIST
returns -1 and sets
.I errno
to an appropriate error number as follows:
.TP 12
.RB [ EFAULT ]
.IR arg " or " str_mlist
points outside the caller's valid address space.
.TP 12
.RB [ EINVAL ]
.I sl_nmods
is less than 1, or,
.I str_mlist
is
.BR NULL .
.PP
See
.IR "\*(lqBUGS\*(rq" ,
below.
.SS I_LOOK
.PP
.PP
Gets the name of the first module beneath the stream head.
.I arg
is a pointer to a character string buffer to accept the name.
This buffer must be at least
.B (FNAMESZ + 1)
in length.
.PP
Upon success,
.B I_LOOK
copies the name of the module beneath the stream head to tbe buffer pointed to
by
.IR arg .
Upon failure,
.B I_LOOK
returns -1 and sets
.I errno
to an appropriate error number as follows:
.TP 12
.RB [ EFAULT ]
.I arg
pointed outside the caller's valid address space.
.TP 12
.RB [ EINVAL ]
there is no module beneath the stream head.
.SS I_NREAD
.PP
.PP
Gets the number of unread data bytes contained in
.B M_DATA
message blocks in the first messsage on the stream head read queue.
.I arg
points to an integer to contain the number of unread bytes.
.PP
Upon success,
.B I_NREAD
returns zero (0) or a positive integer indicating the number of messages on
the stream head read queue.
Upon failure,
.B I_NREAD
returns -1 and sets
.I errno
to an appropriate error number as follows:
.TP 12
.RB [ EFAULT ]
.I arg
points outside the caller's valid address space.
.HP 12
.B Note:
.B LiS
.[
LiS
.]
uses
.BR qsize "(9) and " msgdsize (9)
to provide this command.
.SS I_PEEK
.PP
.PP
Peeks at the next message on the stream head read queue without removing the
message from the queue.
.I arg
is a pointer to a
.B strpeek
structure formatted as follows:
.sp
.nf
\fC\s-1\
struct strpeek {
    struct strbuf ctlbuf;
    struct strbuf databuf;
    long flags;
};
\fR\s+1
.fi
.PP
.I ctlbuf
describes the control part of the message, and is formatted the same as the
.B strbuf
structure pointed to by
.I ctlptr
as an argument to
.BR getmsg (2).
If there is no control part,
the
.I maxlen
field of this
.B strbuf
should be zero (0).
.I databuf
describes the data part of the message, and is formatted the same as the
.B strbuf
structure pointed to by
.I datptr
as an argument to
.BR getmsg (2).
If there is no data part,
the
.I maxlen
field of this
.B strbuf
should be zero (0).
.PP
.I flags
provides the read flags and is formatted the same as the
.I flags
argument to
.BR getmsg (2).
.PP
Upon success,
.B 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
.IR arg ,
if there was a message on the stream head read queue.
Upon failure,
.B I_PEEK
returns -1 and sets
.I errno
to an appropriate error message as follows:
.TP 12
.RB [ EFAULT ]
.IR arg ", " ctlbuf.buf " or " databuf.buf
point outside the caller's valid address space.
.PP
In addition,
.B I_PEEK
can return any
.I errno
returned by
.BR getmsg (2).
See
.BR getmsg (2).
.SS I_PLINK
.PP
.PP
Links on stream under the multiplexing driver on stream
.IR fd .
.I arg
is the integer file descriptor of the stream to link under
.IR fd .
.PP
This call is passed as an
.B I_STR
ioctl using an
.B M_IOCTL
down the stream head write queue to be processed by the multiplexing driver on
.IR fd .
.B I_PLINK
will block until an acknowledgment 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.
.PP
Upon success,
.B I_PLINK
returns a positive integer representing the multiplex identifier of the lower
stream.  This value can be subsequently used in a
.B I_PUNLINK
command.
Upon failure,
.B I_PLINK
returns -1 and sets
.I errno
to an appropriate error number as follows:
.PP
.TP 12
.RB [ EBADF ]
.I arg
is not a valid open file descriptor.
.TP 12
.RB [ ETIME ]
the command timed out before receiving an acknowledgment.
.TP 12
.RB [ ENOSR ]
a buffer for the ioctl message could not be allocated.
.TP 12
.RB [ EINVAL ]
.I fd
received an error message.
.TP 12
.RB [ ENXIO ]
.I fd
received a hangup or is closing.
.TP 12
.RB [ EINVAL ]
.I fd
has no lower multiplexing driver definition.
.TP 12
.RB [ EINVAL ]
.I arg
is already linked under a multiplexor or is not a STREAMS character special
file.
.PP
In addition, any error received in an error message will be returned in
.IR errno .
Also, any error returned by the module or driver in an ioctl positive or
negative acknowledgement message will also be returned in
.IR errno .
.PP
.SS I_POP
.PP
.PP
Pops the STREAMS module just beneath the stream head from
.IR fd .
.I arg
is ignored.
.PP
Upon success,
.B I_POP
pops the moudule beneath the stream head by calling
.BR qdetach (9)
and
returns (0).
Upon failure,
.B I_POP
returns -1 and sets
.I errno
to an appropriate error number as follows:
.TP 12
.RB [ ENXIO ]
.I fd
received a hangup or is closing.
.TP 12
.RB [ EINVAL ]
there was no module beneath the stream head.
.PP
See
.BR qdetach (9)
for more information.
.SS I_PUNLINK
.PP
.PP
Unlink a stream from under a multiplexing driver that was previously linked
with
.BR I_PLINK .
.I arg
is the multiplexor identifier of the linked stream, or,
.B MUXID_ALL
indicating that all linked streams are requested to be unlinked.
.PP
This call is passed as an
.B I_STR
ioctl using an
.B M_IOCTL
down the stream head write queue to be processed by the multiplexing driver on
.IR fd .
.B 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.
.PP
Upon success,
.B I_PUNLINK
returns zero (0) and unlinks the specified stream(s).
Upon failure,
.B I_PUNLINK
returns -1 and sets
.I errno
to an appropriate error number as follows:
.TP 12
.RB [ ENXIO ]
.I fd
received a hangup or is closing.
.TP 12
.RB [ EINVAL ]
.I arg
is invalid.
.TP 12
.RB [ ETIME ]
the call timed out waiting for a response from the driver.
.TP 12
.RB [ EINTR ]
the call was interrupted by a signal.
.TP 12
.RB [ ENOSR "], [" EAGAIN ]
could not allocate the buffer for the ioctl message.
.PP
In addition, any error received in a error message will be returned
in
.IR errno .
Also, any error returned by the module or driver in a ioctl positive or
negative acknowledgement message will also be returned in
.SS I_PUSH
.PP
.PP
Pushes a STREAMS module by name on the stream specified by
.IR fd .
.I arg
is a pointer to a string that contains the name of the module to push.
.PP
Upon success,
.B I_PUSH
pushes the named module and returns zero (0).
Upon failure,
.B I_PUSH
returns -1 and sets
.T errno
to an appropriate error number as follows:
.TP 12
.RB [ EFAULT ]
.I arg
points outside the caller's valid address space.
.TP 12
.RB [ EXNXIO ]
the stream specified by
.I fd
has received a hangup or is closing.
.TP 12
.RB [ EINVAL ]
the module name pointed to by
.I arg
is invalid.
.TP 12
.RB [ ENOSR ]
.I fd
has reached its maximum push count.  No more modules can be pushed on the
stream.
.TP 12
.RB [ ENOMEM ]
memory allocation for the queue pair for the pushed module failed.
.TP 12
.RB [ ENOPKG ]
the module has no qopen routine.
.PP
In addition, any error returned by the module's
.BR qopen (9)
function may be returned by
.BR I_PUSH .
See
.BR qattach (9)
and
.BR qopen (9)
for more information.
.SS I_RECVFD
.PP
.PP
.I arg
is a pointer to a
.B strrecvfd
structure formatted as follows:
.sp
.nf
\fC\s-1\
struct strrecvfd {
    int fd;
    uid_t uid;
    gid_t gid;
    ...
};
\fR\s+1
.fi
.PP
In the
.B strrecfd
structure,
.I fd
is the filedescriptor received, and
.IR uid " and " gid
are the credentials associated with the file descriptor.
.PP
Upon success,
.B I_RECVFD
returns zero (0) and the completed
.B strrecvfd
structure.
Upon failure,
.B I_RECVFD
returns -1 and sets
.I errno
to an appropriate error number as follows:
.PP
.TP 12
.RB [ EFAULT ]
.I arg
points outside the caller's valid address space.
.TP 12
.RB [ ENXIO ]
.I fd
received a hangup message or is closing.
.TP 12
.RB [ EBADF ]
.I fd
is not a stream.
.TP 12
.RB [ EAGAIN ]
no file descriptor message
.BR "" ( M_PASSFP )
is waiting.
.TP 12
.RB [ ENFILE ]
no remaining file descriptors could be allocated for the receiving process.
.TP 12
.RB [ EBADMSG ]
the message on the top of the stream head read queue is not a passed file
descriptor
.BR "" ( M_PASSFD )
message.
.SS I_SENDFD
.PP
.PP
Sends a file descriptor to the other end of a pipe.
.I arg
is the integer file descriptor to send.
.PP
Upon success,
.B I_SENDFD
returns (0).
Upon failure,
.B I_SENDFD
returns -1 and sets
.I errno
to an appropriate error number as follows:
.TP 12
.RB [ EBADF ]
.I arg
is not a valid file descriptor.
.TP 12
.RB [ EPIPE ]
.TP 12
.RB [ ENOSR ]
a buffer could not be allocated to send the file descriptor.
.TP 12
.RB [ ENOMEM ]
a file descriptor could not be allocated for the receiving end.
.SS I_SETCLTIME
.PP
.PP
Sets the closing delay time for the stream head.
.I arg
is a
.B long
value which specifies the delay time in milliseconds.
.PP
Upon success,
.B I_SETTLTIME
returns zero (0) and sets the close delay time for
.BR fd .
Upon failure,
.B I_SETTLTIME
returns -1 and sets
.T errno
to an appropriate error number as follows:
.TP 12
.RB [ EINVAL ]
.I arg
is outside the valid range 0 to 300,000 milliseconds.
.SS I_SETSIG
.PP
.PP
Sets the mask of events for which the stream head will send the calling
process a
.B SIGPOLL
or
.B SIGURG
signal.
.I arg
is an integer value containins one or more of the following event flags:
.TP 12
.B S_INPUT
any message but high priority on read queue.
.TP 12
.B S_HIPRI
high priority message on read queue.
.TP 12
.B S_OUTPUT
write queue is no longer full.
.TP 12
.B S_MSG
signal message at front of read queue.
.TP 12
.B S_ERROR
error message arrived at stream head.
.TP 12
.B S_HANGUP
hangup message arrived at stream head.
.TP 12
.B S_RDNORM
normal message on read queue
.TP 12
.B S_WRNORM
same as
.BR S_OUTPUT .
.TP 12
.B S_RDBAND
out of band message on read queue.