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.

ioctl-streams

Technical documentation

» Table of Contents

» Index