[ Previous |
Next |
Contents |
Glossary |
Home |
Search ]
AIX Version 4.3 Base Operating System and Extensions Technical Reference, Volume 1
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>
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 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
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:
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:
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. |
Implementation Specifics
This subroutine is part of Base Operating
System (BOS) Runtime.
Related Information
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.
[ Previous |
Next |
Contents |
Glossary |
Home |
Search ]