Performs control functions associated with open file descriptors.
Standard C Library (libc.a)
BSD Library (libbsd.a)
int ioct132 (FileDescriptor, Command
int FileDescriptor, Command;
unsigned int Argument;
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 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
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.
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 Technical Reference: Kernel and Subsystems.
The Special Files Overview in AIX Version 4.3 Files Reference.
The Input and Output Handling Programmer's Overview, the tty Subsystem Overview, in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.
The Sockets Overview and Understanding Socket Data Transfer in AIX Version 4.3 Communications Programming Concepts.