ioctl, ioctlx, ioctl32, or ioctl32x Subroutine

Purpose

Performs control functions associated with open file descriptors.

Library

Standard C Library (libc.a)

BSD Library (libbsd.a)

Syntax

#include <sys/ioctl.h> #include <sys/types.h> #include <unistd.h> #include <stropts.h>

int ioctl (FileDescriptor,  Command, Argument) int  FileDescriptor,  Command; void * Argument;

int ioctlx (FileDescriptor, Command, Argument, Ext ) int FileDescriptor , Command ; void *Argument; int  Ext;

int ioct132 (FileDescriptor, Command , Argument) int FileDescriptor, Command; unsigned int Argument;

int ioct132x (FileDescriptor, Command , Argument, Ext) int FileDescriptor, Command; unsigned int Argument; unsigned int Ext;

Description

The ioctl subroutine performs a variety of control operations on the object associated with the specified open file descriptor. This function is typically used with character or block special files, sockets, or generic device support such as the termio general terminal interface.

The control operation provided by this function call is specific to the object being addressed, as are the data type and contents of the Argument parameter. The ioctlx form of this function can be used to pass an additional extension parameter to objects supporting it. The ioct132 and ioct132x forms of this function behave in the same way as ioctl and ioctlx, but allow 64-bit applications to call the ioctl routine for an object that does not normally work with 64-bit applications.

Performing an ioctl function on a file descriptor associated with an ordinary file results in an error being returned.

Parameters

Item Description
FileDescriptor Specifies the open file descriptor for which the control operation is to be performed.
Command Specifies the control function to be performed. The value of this parameter depends on which object is specified by the FileDescriptor parameter.
Argument Specifies additional information required by the function requested in the Command parameter. The data type of this parameter (a void pointer) is object-specific, and is typically used to point to an object device-specific data structure. However, in some device-specific instances, this parameter is used as an integer.
Ext Specifies an extension parameter used with the ioctlx subroutine. This parameter is passed on to the object associated with the specified open file descriptor. Although normally of type int, this parameter can be used as a pointer to a device-specific structure for some devices.

File Input/Output (FIO) ioctl Command Values

A number of file input/output (FIO) ioctl commands are available to enable the ioctl subroutine to function similar to the fcntl subroutine:

Item Description
FIOCLEX and FIONCLEX Manipulate the close-on-exec flag to determine if a file descriptor should be closed as part of the normal processing of the exec subroutine. If the flag is set, the file descriptor is closed. If the flag is clear, the file descriptor is left open.

The following code sample illustrates the use of the fcntl subroutine to set and clear the close-on-exec flag:

/* set the close-on-exec flag for fd1 */
fcntl(fd1,F_SETFD,FD_CLOEXEC);
/* clear the close-on-exec flag for fd2 */
fcntl(fd2,F_SETFD,0);

Although the fcntl subroutine is normally used to set the close-on-exec flag, the ioctl subroutine may be used if the application program is linked with the Berkeley Compatibility Library (libbsd.a) or the Berkeley Thread Safe Library (libbsd_r.a) (4.2.1 and later versions). The following ioctl code fragment is equivalent to the preceding fcntl fragment:

/* set the close-on-exec flag for fd1 */
ioctl(fd1,FIOCLEX,0);
/* clear the close-on-exec flag for fd2 */
ioctl(fd2,FIONCLEX,0);

The third parameter to the ioctl subroutine is not used for the FIOCLEX and FIONCLEX ioctl commands.
FIONBIO Enables nonblocking I/O. The effect is similar to setting the O_NONBLOCK flag with the fcntl subroutine. The third parameter to the ioctl subroutine for this command is a pointer to an integer that indicates whether nonblocking I/O is being enabled or disabled. A value of 0 disables non-blocking I/O. Any nonzero value enables nonblocking I/O. A sample code fragment follows: 
int flag;
/* enable NBIO for fd1 */
flag = 1;
ioctl(fd1,FIONBIO,&flag);
/* disable NBIO for fd2 */
flag = 0;
ioctl(fd2,FIONBIO,&flag);
FIONREAD Determines the number of bytes that are immediately available to be read on a file descriptor. The third parameter to the ioctl subroutine for this command is a pointer to an integer variable where the byte count is to be returned. The following sample code illustrates the proper use of the FIONREAD ioctl command: 
int nbytes;
ioctl(fd,FIONREAD,&nbytes);
FIOASYNC Enables a simple form of asynchronous I/O notification. This command causes the kernel to send SIGIO signal to a process or a process group when I/O is possible. Only sockets, ttys, and pseudo-ttys implement this functionality.

The third parameter of the ioctl subroutine for this command is a pointer to an integer variable that indicates whether the asynchronous I/O notification should be enabled or disabled. A value of 0 disables I/O notification; any nonzero value enables I/O notification. A sample code segment follows:

int flag;
/* enable ASYNC on fd1 */
flag = 1;
ioctl(fd, FIOASYNC,&flag);
/* disable ASYNC on fd2 */
flag = 0;
ioctl(fd,FIOASYNC,&flag);
FIOSETOWN Sets the recipient of the SIGIO signals when asynchronous I/O notification (FIOASYNC) is enabled. The third parameter to the ioctl subroutine for this command is a pointer to an integer that contains the recipient identifier. If the value of the integer pointed to by the third parameter is negative, the value is assumed to be a process group identifier. If the value is positive, it is assumed to be a process identifier.

Sockets support both process groups and individual process recipients, while ttys and psuedo-ttys support only process groups. Attempts to specify an individual process as the recipient will be converted to the process group to which the process belongs. The following code example illustrates how to set the recipient identifier:

int owner;
owner = -getpgrp();
ioctl(fd,FIOSETOWN,&owner);
Note: In this example, the asynchronous I/O signals are being enabled on a process group basis. Therefore, the value passed through the owner parameter must be a negative number.

The following code sample illustrates enabling asynchronous I/O signals to an individual process:

int owner;
owner = getpid();
ioctl(fd,FIOSETOWN,&owner);
FIOGETOWN Determines the current recipient of the asynchronous I/O signals of an object that has asynchronous I/O notification (FIOASYNC) enabled. The third parameter to the ioctl subroutine for this command is a pointer to an integer used to return the owner ID. For example: 
int owner;
ioctl(fd,FIOGETOWN,&owner);

If the owner of the asynchronous I/O capability is a process group, the value returned in the reference parameter is negative. If the owner is an individual process, the value is positive.

Return Values

If the ioctl subroutine fails, a value of -1 is returned. The errno global variable is set to indicate the error.

The ioctl subroutine fails if one or more of the following are true:

Item Description
EBADF The FileDescriptor parameter is not a valid open file descriptor.
EFAULT The Argument or Ext parameter is used to point to data outside of the process address space.
EINTR A signal was caught during the ioctl or ioctlx subroutine and the process had not enabled re-startable subroutines for the signal.
EINTR A signal was caught during the ioctl , ioctlx , ioctl32 , or ioct132x subroutine and the process had not enabled re-startable subroutines for the signal.
EINVAL The Command or Argument parameter is not valid for the specified object.
ENOTTY The FileDescriptor parameter is not associated with an object that accepts control functions.
ENODEV The FileDescriptor parameter is associated with a valid character or block special file, but the supporting device driver does not support the ioctl function.
ENXIO The FileDescriptor parameter is associated with a valid character or block special file, but the supporting device driver is not in the configured state.

Object-specific error codes are defined in the documentation for associated objects.