HP 3000 Manuals HP 3000 Manuals
ioctl-streams
Provides an interface and control over magnetic tape devices. In the
case of magnetic tape devices, the ioctl() function provides an interface
for issuing various control commands to opened tape devices. The ioctl()
operations can be used to position the magnetic tape, and to determine
the tape device status.
Syntax
int ioctl(fildes, request, arg)
int fildes;
int request;
void *arg;
Parameters
fildes The open file descriptor for the stream that will be used.
request This parameter specifies which command to perform on the
stream. The commands are defined in <sys/stropts.h>. The
different commands that are available are described below.
FIOGNBIO Gets the status of non-blocking i/o. If
non-blocking i/o is enabled, then the integer
whose address is arg is set to 1. If
non-blocking i/o is disabled, then the
integer is set to zero.
FIONBIO Enables or disables non-blocking i/o. If the
integer whose address is arg is not zero,
then non-blocking i/o is enabled. When
non-blocking i/o is enabled, subsequent read
and write requests to the device file are
prevented from blocking whether the request
succeeds or fails. If the integer whose
address is arg is zero, then non-blocking i/o
is disabled.
I_ATMARK Checks to see if the next message is "marked"
by the downstream module. If the earg value
is set to ANYMARK, then the check will be to
see if the message is marked. If the arg
value is set to LASTMARK, then the check will
be to see if the message is the last one that
is marked on the queue. If marked conditions
is satisfied, a 1 is returned; otherwise a
zero is returned.
I_CANPUT Checks if a message can be passed on a
stream. The arg parameter specifies which
priority band to check. If the priority band
is flow controlled, then a zero is returned;
otherwise a 1 is returned.
I_CKBAND Checks if a priority band message is
currently on the stream head read queue. The
^fearg^s parameter specifies the priority
band being checked. If a message is on the
queue, a 1 is returned; otherwise a zero is
returned.
I_FDINSERT Creates a message and sends it downstream.
I_FIFO Converts a stream into a FIFO. Used for
non-System V systems.
I_FIND Checks for a specific module in the stream.
The arg parameter will contain the name of
the module to be searched for. If the module
is present, a 1 is returned; otherwise a zero
is returned.
I_FLUSH Flushes the read and/or write queues of the
stream depending on the value of the arg
parameter.
I_FLUSHBAND Flushes a read and/or write band of messages
depending on the value of the arg parameter.
The band of messages to be flushed is also
defined in the arg structure.
I_GETBAND Gets the priority of the next message on the
stream read queue. The priority is returned
in the arg parameter.
I_GETCLTIME Gets the time delay for closing a stream.
The time value is returned in the arg
parameter.
I_GETSIG Gets the events for which the calling process
has registered to receive a signal. The
events are returned in the arg parameter.
I_GETSTREAMID Gets the stream handle for a C-library file
descriptor. Use for NETWARE.
I_GRDOPT Gets the current read mode setting of the
stream. The integer value is returned in the
arg parameter.
I_GWROPT Gets the current write mode setting of the
stream. The integer value is returned in the
arg parameter.
I_LINK Connects two streams. The descriptor of the
stream referenced by fildes parameter is
connected to the descriptor of the stream
that is referenced in the arg parameter.
I_LIST Gets the list of names of the modules present
on the stream.
I_LOOK Gets the name of the first stream module, and
places in a character string pointed to by
the arg parameter.
I_NREAD Returns the number of bytes in the data block
of the first message on the stream read
queue. The number of bytes is stored in a
location pointed to by the arg parameter.
I_PEEK Allows the user process to "peek"/look at the
first message on the stream read queue. This
information will be stored in a location
pointed to by the arg parameter. If a
message is retrieved, a 1 is returned;
otherwise a zero is returned.
I_PIPE Connects two streams as a pipe. Used for
non-System V systems.
I_PLINK Permanently connects two streams. The
descriptor of the stream referenced by the
fildes is connected to the descriptor of the
stream referenced by the arg parameter. The
latter stream is connected via a persistent
link that can exist even if the first stream
is closed.
I_POP Removes/pops the module just below the stream
head. For this request, the arg parameter
must be set to zero.
I_PUNLINK Disconnects two streams that are connected
via a persistent link.
I_PUSH Pushes the module whose name is pointed to by
the arg parameter onto the stream just below
the stream head.
I_RECVFD Retrieves the file descriptor associated with
the message sent by the I_SENDFD command over
a stream pipe.
I_SENDFD Requests the stream referred to by fildess to
send a message M_PASSFP to the stream head at
the other end of a stream pipe.
I_SETCLTIME Sets the time that the stream head delays
when the stream is closing and the write
queues contain data. The arg parameter
contains a pointer to the number of
milliseconds to delay.
I_SETSIG Tells the stream head that the user process
wants a SIGPOLL signal to be issued by the
kernel for a particular event that can occur
on a stream. This command provides support
for asynchronous processing in streams. The
arg parameter contains information that
specifies the particular events that SIGPOLL
is to be sent for.
I_SRDOPT Sets the read mode of the stream according to
the value of the arg parameter.
I_STR Creates an internaltioctl() message from the
data pointed to by the arg parameter and
sends the message downstream to a module or
driver.
I-SWROPT Sets the stream write mode according to the
value of the arg parameter.
I_UNLINK Disconnects two streams. One descriptor
referenced by the fildes parameter, and the
other descriptor referenced by the arg
parameter.
arg This parameter contains additional information that the
specified request may need to perform its function. This is
usually an integer or a pointer to a structure specific to the
request. See the appropriate request command for an
explanation of the value that the integer will represent in
that context.
Return Values
If the ioctl function completes successfully, the following two
conditions can occur. If a specific condition is met, then a 1 is
returned; if the condition is not met, then a 0 is returned.
If the ioctl function does not complete successfully, then a value of -1
is returned by the function and the global variable errno is set with the
resultant error.
Description
The ioctl() commands can be used to perform control operations on
streams. User processes can use the commands on all streams file types.
When the stream head receives a streams ioctl() function, the request and
the arg parameters are interpreted into an M_IOCTL message. In some
cases, the parameters are passed onto a module or driver in the stream.
The module in a stream can detect errors in the ioctl() function. If an
error is detected, an error message containing the error number is sent
to the stream head. Subsequent calls to functions will fail with the
errno set to this number.
Implementation Considerations
None.
Errors
There are many corresponding errors for each of the request commands
mentioned above. For a list of these errors, and an explanation of the
different error conditions, please refer to the HP-UX Release 9.0 manual.
See Also
ioctl-mag_tape, ioctl-streams, POSIX.1