Performs control functions associated with open file descriptors.
Standard C Library (libc.a)
BSD Library (libbsd.a)
int ioctl (FileDescriptor,
int FileDescriptor, Command;
void * Argument;
int ioctlx (FileDescriptor, Command, Argument, Ext
int FileDescriptor , Command ;
int ioct132 (FileDescriptor, Command
int FileDescriptor, Command;
unsigned int Argument;
int ioct132x (FileDescriptor, Command
, Argument, Ext)
int FileDescriptor, Command;
unsigned int Argument;
unsigned int Ext;
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.
|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.|
A number of file input/output
(FIO) ioctl commands are available to enable the ioctl subroutine
to function similar to the fcntl subroutine:
|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:
|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.
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.
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:
|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.|
This subroutine is part of Base Operating System (BOS) Runtime.
The ddioctl device driver entry point and the fp_ioctl kernel service in AIX 5L Version 5.1 Technical Reference: Kernel and Subsystems.
The Special Files Overview in AIX 5L Version 5.1 Files Reference.
The Input and Output Handling Programmer's Overview, the tty Subsystem Overview, in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.
The Sockets Overview and Understanding Socket Data Transfer in AIX 5L Version 5.1 Communications Programming Concepts.