ioctl

Performs a variety of control functions on a STREAMS, BSD Socket, and pipe file descriptors

Local Servers:blocking
Remote Servers:N/A
Classification:UNIX (nonstandard)
NetWare Server:3.12, 3.2, 4.x, 5.x, 6.x
Platform:NLM
Service:Operating System I/O

Syntax

  #include <sys/ioctl.h> 
  #include <stropts.h>  
   
  int ioctl  (  
     int    filedes,   
     int    command,   
     void  *arg);
  

Parameters

filedes
(IN) Specifies a descriptor returned from the open, pipe, sopen, socket, etc., functions.
command
(IN) Specifies the control function to be performed.
arg
(IN/OUT) Points to an additional argument to be used or points to an argument returned by ioctl (depending on the control function performed).

Return Values

Upon successful completion, the value returned depends upon the control function (command argument) but must be a nonnegative integer. Otherwise, errno indicates the occurring error.

Remarks

See spxc_rw.c for sample code.

For Stream files, ioctl performs the following control operations:

FIOGETNBIO

Supported for TCP, UDP, ICMP, RAWIP sockets. Returns the nonblocking status of the socket. The status is returned in the third parameter of ioctl as a value and result parameter. A nonzero value indicates the flag is SET, and a zero value indicates the flag is CLEAR.

FIONBIO

Supported for TCP, UDP, ICMP, RAWIP sockets. Sets and clears the nonblocking flag for the sockets, depending on the value of the third parameter that is passed to ioctl. A nonzero value indicates the flag is SET, and a zero value indicates the flag is CLEAR.

FIONREAD

Supported for TCP, UDP, ICMP, RAWIP sockets. Returns the number of bytes that are currently in the socket receive buffer. The value is returned in the third parameter of ioctl.

I_FDINSERT

Creates a message from user-specified buffers, adds information about another Stream and sends the message downstream. The message contains a control part and an optional data part. On failure, errno is set.

I_FIND

Compares the names of all modules currently present in the Stream to the name pointed to by the arg parameter, and returns a value of 1 if the named module is present in the Stream. It returns a value of 0 if the named module is not present. On failure, errno is set.

I_FLUSH

Flushes all input and/or output queues, depending on the value of the arg parameter :

 

FLSHR

Flush read queues.

 

FLUSHW

Flush write queues.

 

FLUSHRW

Flush read and write queues.

I_GETSIG

Returns the events for which the calling process is currently registered to be sent a SIGPOLL signal. The events are returned as a bit mask pointed to by the arg parameter, where the events are those specified in the description of I_SETSIG. On failure, errno is set.

I_GRDOPT

Returns the current read mode setting in an int pointed to by the arg parameter. On failure, errno is set.

I_LINK

Connects two Streams, where the filedes parameter contains the file descriptor of the Stream connected to the multiplexing driver, and the arg parameter is the file descriptor of the Stream connected to another driver. The Stream designated by the arg parameter is connected below the multiplexing driver. I_LINK requires the multiplexing driver to send an acknowledgment message to the stream-head regarding the linking operation. It returns a multiplexer ID number (an identifier used to disconnect the multiplexer) on success, and a value of -1 on failure. On failure, errno is set.

I_LOOK

Retrieves the name of the module just below the stream-head of the Stream pointed to by the filedes parameter, and places it in a NULL-terminated character string pointed to by the arg parameter. On failure, errno is set.

I_NREAD

Counts the number of data bytes in data blocks in the first message on the stream-head read queue, and places this value in the location pointed to by the arg parameter. The return value for the command is the number of messages on the stream-head read queue. On failure, errno is set.

For a pipe file, counts the number of data bytes left to read on the descriptor before the read function blocks.

I_NWRITE

Counts the number of data bytes that may be written on a pipe descriptor before the write function blocks. Similar to I_NREAD. For example, err=ioctl(pipeFD, I_NWRITE, &pending);.

I_PEEK

Allows a user to retrieve the information in the first message on the stream-head read queue without taking the message off the queue. The arg parameter points to a strpeek structure. I_PEEK returns a value of 1 if a message was retrieved, and returns a value of 0 if no message was found on the stream-head read queue.

I_POP

Removes the module just below the stream-head of the Stream pointed to by the filedes parameter. The arg parameter should be 0 in an I_POP request. On failure, errno is set.

I_PUSH

Pushes the module whose name is pointed to by the arg parameter onto the top of the current Stream, just below the stream-head. It then calls the open routine of the newly pushed module. On failure, errno is set.

I_RECVFD

Retrieves the file descriptor associated with the message sent by an I_SENDFD ioctl over a stream pipe. The arg parameter points to a data buffer large enough to hold the strrecvfd structure. If the message at the stream-head is a message sent by an I_SEND descriptor, a new user file descriptor is allocated for the file pointer contained in the message. The new file descriptor is placed in the fd field of the strrecvfd structure. The structure is copied into the user data buffer pointed to by the arg parameter. On failure, errno is set.

I_SENDFD

Requests the Stream associated with the file descriptor to send a message, containing a file pointer, to the stream-head at the other end of a stream pipe. The arg parameter must point to a file descriptor. I_SENDFD converts the arg parameter into the corresponding system file pointer. It allocates a message block and inserts the file pointer in the block. The user ID and group ID associated with the sending process are also inserted. This message is placed directly on the read queue for the stream-head at the other end of the stream pipe to which it is connected. On failure, errno is set.

I_SETBUF

Exchanges the buffer currently underlying the pipe for one of a different size. The pipe becomes empty and cleared with respect to data read or written. For example, err=ioctl(pipeFD, I_SETBUF, 8192);.

I_SETSIG

Informs the stream-head that the user wants the kernel to issue the SIGPOLL signal when a particular event has occurred on the Stream associated with the filedes parameter. I_SETSIG supports an asynchronous processing capability in STREAMS. The value of the arg parameter is a bit mask that specifies the events for which the user should be signaled. It is the bitwise OR of any combination of the following constants:

 

S_INPUT

Nonpriority message has arrived.

 

S_HIPRI

Priority message is present.

 

S_OUTPUT

The write queue is no longer full. There is room for sending (or writing) data downstream.

 

S_MSG

Stream signal message containing the SIGPOLL signal has reached the front of the stream-head read queue. On failure, errno is set.

I_SRDOPT

Sets the read mode using the arg parameter. Legal values for the arg parameter are:

 

RNORM

Byte-stream mode (the default)

 

RMSGD

Message-discard mode

 

RMSGN

Message-nondiscard mode

I_STR

Constructs an internal Stream ioctl message from the data pointed to by the arg parameter and sends that message downstream. I_STR blocks until the system responds with either a positive or negative acknowledgment message or until the request times out after some period of time. If the request fails, errno is set.

I_UNLINK

Disconnects the two Streams specified by the filedes and arg parameters. The filedes parameter is the file descriptor of the Stream connected to the multiplexing driver. The descriptor must correspond to the Stream on which the ioctl I_LINK command was issued to link the Stream below the multiplexing driver. The arg parameter is the multiplexer ID number that was returned by the I_LINK call. If the arg parameter is -1, all Streams which were linked to the filedes parameter are disconnected. As in I_LINK, it requires the multiplexing driver to acknowledge the unlink. On failure, errno is set.

SIOCATMARK

Supported for TCP sockets. Returns a nonzero value if the socket's read pointer is currently at the out-of-band mark. A zero value indicates the read pointer is not at the out-of-band mark. The value is returned in the third parameter of ioctl.

SIOCDGRAMSIZE

Supported for RAWIP sockets (NetWare specific). Returns the size of the datagram to be sent, in bytes. The value is returned in the third parameter of ioctl.

See Also

pipe, poll, open, read, write