streamio.7

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

.TP 12
.B S_WRBAND
can write out of band message.
.TP 12
.B S_BANDURG
modifier to
.BR S_RDBAND ,
to generate
.B SIGURG
instead of
.BR SIGPOLL .
.TP 12
.B S_ALL
all flags.
.SS I_SRDOPT
.PP
.PP
Sets the
.BR read (2)
options flags for the stream head.
These flags alter the behavior of the
.BR read (2)
call when called for
.IR fd .
.I arg
is an integer value containing the read options flags which may be one flag
from the mode group as follows:
.TP 12
.B RNORM
byte-stream mode.  This is the default read mode.
.TP 12
.B RMSGD
message discard mode.
.TP 12
.B RMSGN
message non-discard mode.
.PP
bitwise OR'ed with one flag from the protocol group as follows:
.TP 12
.B RPROTNORM
fail
.BR read (2)
with
.RB [ EBADMSG ]
if a message containing a control part is at the front of the stream head
read queue.
.TP 12
.B RPROTDAT
deliver control part of a message as data.
.TP 12
.B RPROTDIS
discard control part of message, delivering any data part.
.SS I_STR
.PP
.PP
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.
.I arg
is a pointer to a
.B strioctl
structure formatted as follows:
.sp
.nf
\fC\s-1\
struct strioctl {
    int ic_cmd;
    int ic_timout;
    int ic_len;
    char *ic_dp;
};
\s+1\fR
.fi
.PP
.I 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.
.BR I_LINK )
or any other ioctl command understood by a module or driver on the stream
.IR fd .
.I ic_timout
is the period of time to wait for an acknowledgement in milliseconds, or
-1 indicating that there is no timeout.
.I ic_len
is the length of the argument data pointed to by
.IR ic_dp .
.I ic_dp
is a pointer to the argument data of length
.I ic_len
bytes.
.PP
.B I_STR
generates an
.B M_IOCTL
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.
.PP
Upon success,
.B I_STR
returns the return value sepcified in the positive or negative acknowledgement
message.
Upon failure,
.B I_STR
returns -1 and sets
.I errno
to an appropriate error number as follows:
.TP 12
.RB [ EFAULT ]
.IR arg " or " ic_dp
point outside the caller's valid address space.
.TP 12
.RB [ EINVAL ]
.I ic_len
is less than 0.
.TP 12
.RB [ EINVAL ]
.I ic_len
is greater than the maximum size of the data part of a message.
.TP 12
.RB [ EINVAL ]
.I ic_timout
is less than -1.
.TP 12
.RB [ ETIME "], [" EAGAIN ]
the operation timed out waiting for an acknowledgement.
.TP 12
.RB [ EINTR ]
the oepration was interrupted by a signal.
.TP 12
.RB [ ENXIO ]
.I fd
received a hangup or is closing.
.TP 12
.RB [ ENOSR ]
a buffer for the ioctl message could not be allocated.
.PP
In addition,
.B I_STR
can return any
.I errno
placed in an error message received by the stream head, or
placed in the positive or negative acknowledgement message by the module or
driver.
.SS I_SWROPT
.PP
.PP
Sets the
.BR write (2)
options flags for the strem head.
These flags alter the behavior of the
.BR write "(2) and " putmsg (2)
calls when called for
.IR fd .
.I arg
is an integer value containing the write options flags which may be one or
more flags from the following:
.TP 12
.B SNDZERO
send a zero-length message downstream when a write of zero bytes occurs.
.TP 12
.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.
.SS I_UNLINK
.PP
.PP
Unlink a stream from under a multiplexing driver that was previously linked
with
.BR I_LINK .
.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_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.
.PP
Upon success,
.B I_UNLINK
returns zero (0) and unlinks the specified stream(s).
Upon failure,
.B I_UNLINK
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, or
.I fd
is a pipe or FIFO.
.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
.IR errno .
.SH "RETURN VALUE"
.PP
.PP
Upon success,
.B ioctl()
returns zero (0) or a positive integer.
Upon failure,
.B ioctl()
returns -1 and sets
.I errno
to an appropriate error number.
.SH ERRORS
.PP
.PP
When
.B ioctl()
fails, it returns -1 and sets
.I errno
to one of the following errors:
.TP 12
.RB [ ENXIO ]
.I fd
has received a hangup or is closing.
.TP 12
.RB [ EFAULT ]
.I arg
or a member of
.IR arg ,
points to an address that is outside the caller's valid address space.
.TP 12
.RB [ EINVAL ]
.IR fd ", " command ", " arg " or a member of " arg
is invalid.
.TP 12
.RB [ ENOSR ]
a buffer could not be allocated for the call.
.TP 12
.RB [ ETIME "], [" EAGAIN ]
timed out waiting for an acknowledgment.
.TP 12
.RB [ EINTR ]
interrupted by a signal.
.PP
In addition, any error delivered to the stream head in an error message can be
returned in
.IR errno .
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 can be returned
in
.IR errno .
.SH CAVEATS
.PP
.PP
STREAMS
.B ioctl()
calls are complex and there is much conflicting documentation in specific
areas of behavior.  Not all bugs are bugs and not all features are features.
.SH BUGS
.PP
.SS I_ATMARK
.PP
.PP
.B LiS
fails silently (returns success) if there is no queue associated with the
stream head.
.SS I_CANPUT
.PP
.PP
.B LiS
uses
.BR bcanput (9)
to test for flow control once
.I arg
is validated.
.BR bcanput (9)
has the problem that it will return false (0) when an internal error occurs.
See the
.BR bcanput (9)
man page for more information.
.SS I_CKBAND
.PP
.B LiS
uses
.BR strqget (9)
to get the
.B QCOUNT
associated with the band specified by
.IR arg .
.BR strqget (9)
returns
.RB [ EINVAL ]
when the specified priority band does not exist.  Therefore,
.B I_CKBAND
will return
.RB [ EINVAL ]
when it should return false (0) indicating that there is no message for the
band.  See
.B QCOUNT
description in the
.BR strqget (9)
man page for more information.
.SS I_FDINSERT
.PP
.PP
.B LiS
incorrectly returns
.RB [ ENODEV ]
instead of
.RB [ ENXIO ]
when
.I fd
is linked under a multiplexor.
.PP
.B LiS
incorrectly returns
.RB [ EAGAIN ]
when
.B RS_HIPRI
is set in
.IR flags ,
and the stream is flow controlled.
It should deliver the message in this case.
.PP
.B LiS
incorrectly returns
.RB [ EINVAL ]
when
.I fd
or
.I fildes
has received an error message.  It should return the write error of the error
message in the case of
.IR fd .
.PP
.B LiS
incorrectly returns
.RB [ ENOSR ]
instead of
.RB [ ENODEV ]
when there is no queue under the stream head.
.PP
.B LiS
incorrectly returns
.RB [ ENOSTR ]
instead of
.RB [ EINVAL ]
when
.I fildes
is not a STREAMS character special file.
.PP
.B LiS
incorrectly returns
.RB [ ENODEV ]
instead of
.RB [ ENXIO ]
when a hangup was received on
.I fd
or
.I fd
is closing.
.PP
.B LiS
does not check whether
.I fildes
has received a hangup or is closing.  It should return return
.RB [ ENXIO ]
in that case.
.SS I_FIND
.PP
.PP
.B LiS
verifies read on
.I arg
for a string sized
.BR "(FNNAMESZ + 1)" .
If the name string pointed to by
.I arg
is shorter than
.B FNAMESZ
and terminates on a page boundary,
.B I_FIND
will fail with error number
.RB [ EFAULT ]
even though the provided module name is valid and resides completely within
the caller's address space.  A workaround for this is for the caller to
always allocate
.B (FNAMESZ + 1)
sized buffers to hold the module name.  There is no excuse for this bug as
.B Linux
provides one byte look-ahead verify on the kernel function
.BR strncpy_from_user ()
which is in fact called by
.B LiS
when processing
.BR I_FIND .
.PP
.B LiS
allocates memory to hold the passed in string.  The maximum size of this
string is 8 or 16 bytes.  This is not too much to place on the stack.
.B LiS
should not allocate memory for this and should never return
.RB [ ENOMEM ]
in response to
.BR I_FIND .
.SS I_FLUSH
.PP
.PP
.B LiS
incorrectly returns
.RB [ ENOMEM ]
when it cannot allocate a message block for
the
.B M_FLUSH
message.  The correct error number is
.RB [ ENOSR ].
.PP
.B LiS
uses
.BR putnext (9)
internally to send the
.B M_FLUSH
message.
.BR putnext (9)
can fail silently
under a number of conditions detailed in the
.BR putnext (9)
man page.  One of
those conditions is that
.BR qprocsoff (9)
has been called on the stream.
.SS I_FLUSHBAND
.PP
.PP
Rather than returning
.RB [ EINVAL "], " LiS
masks
.I bi_flag
with
.B FLUSHRW
to force validity.  This is a bug.   For example,
.B I_FLUSHBAND
can be called with
.I bi_flag
=
.B 0xffffffff
and
.B LiS
would threat this as
.BR FLUSHRW .
.PP
Rather than returning
.RB [ EINVAL "], " LiS
masks
.I bi_pri
with
.B 0xff
to force validity.  This is a bug.  For example,
.B I_FLUSHBAND
can be called with
.I bi_pri
=
.B 257
and
.B LiS
would flush band
.BR 1 .
.PP
.B LiS
incorrectly returns
.RB [ ENOMEM ]
when it cannot allocate a message block for the
.B M_FLUSH
message.   The correct error number is
.RB [ ENOSR ].
.PP
.B LiS
usesc 
.BR putnext (9)
to send the
.B M_FLUSH
message.
.BR putnext (9)
can fail silently under a number of con- ditions detailed in the
.BR putnext (9)
man page.  One of those conditions is that
.BR qprocsoff (9)
has been called on the stream.
.SS I_GETCLTIME
.PP
.PP
UN*X documentation shows that
.I arg
is a pointer to a
.BR long .
In
.B LiS
.I arg
is a pointer to an
.BR int .
This has an impact on architectures where a
.B long
is not the same as an
.BR int .
.SS I_RECVFD
.PP
.PP
.B LiS
does not block waiting for a passed file descriptor message to appear on the
stream head read queue if the stream indicated by
.I fd
is set for blocking operation.  It should.
.PP
.B LiS
will return
.RB [ EAGAIN ]
where it should return
.RB [ EBADMSG ].
.PP
.B LiS
does not check for hangup on the pipe.
.SS I_SETCLTIME
.PP
.PP
UN*X documentation shows that
.I arg
is a pointer to a
.BR long .
In
.B LiS
.I arg
is a pointer to an
.BR int .
This has an impact on architectures where a
.B long
is not the same as an
.BR int .
.SS I_LINK
.PP
.PP
.B LiS
returns
.RB [ ENOMEM ]
instead of
.RB [ ENOSR "] or [" EAGAIN ]
when it cannot allocate a buffer for the call.
.SS I_LIST
.PP
.PP
.B LiS I_LIST
fails silently (returns zero (0)) if there is no queue associated
with the stream head.
.SS I_LOOK
.PP
.PP
.B LiS
verifies write on
.I arg
for a string sized
.BR (FNAMESZ + 1) .
If the name string of the module under the stream head is shorter than
.B (FNAMESZ + 1)
and
.I arg
terminates on a page boundary,
.B I_LOOK
will return with error number
.RB [ EFAULT ]
even though the provided buffer is valid and resides as far as is necessary
completely within the caller's address space.  A workaround for this is for
the caller to always allocate
.B (FNAMESZ + 1)
sized buffers to hold the module name.  There is no excuse for this bug as
.B Linux
provides one byte look-ahead verify on the kernel function
.BR strncpy_to_user ()
which is in fact called by
.B LiS
when processing
.BR I_LOOK .
.SS I_PLINK
.PP
.PP
.B LiS
returns
.RB [ ENOMEM ]
instead of
.RB [ ENOSR "] or [" EAGAIN ]
when it cannot allocate a buffer for the call.
.SS I_PUNLINK
.PP
.PP
.B LiS
returns
.RB [ ENOMEM "] instead of [" ENOSR "] or [" EAGAIN ]
when it cannot allocate a buffer for the call.
.SS I_UNLINK
.PP
.PP
.B LiS
returns
.RB [ ENOMEM "] instead of [" ENOSR "] or [" EAGAIN ]
when it cannot allocate a buffer for the call.
.SH "SEE ALSO"
.PP
.BR close (2),
.BR fcntl (2),
.BR getmsg (2),
.BR ioctl (2),
.BR open (2),
.BR open (2s),
.BR poll (2),
.BR putmsg (2),
.BR read (2),
.BR signal (2),
.BR signal (2),
.BR write (2),
.BR qopen (9),
.BR qclose (9),
.BR qattach (9),
.BR qdetach (9).
.SH VERSIONS
.PP
.PP
This manpage was written for
.B LiS\c
.
.[
LiS
.]
.PP
.B ioctl()
for STREAMS first appeared in SVR 3.0.
.[
svr3
.]
.[
$LIST$
.]
.TA