IOCTL(2) — SYSTEM CALLS

NAME

ioctl − control device

SYNOPSIS

int ioctl(des, request, arg)
int des, request;
caddr_t arg;

DESCRIPTION

ioctl() performs a special function on the object referred to by the open descriptor des. The set of functions that may be performed depends on the object that des refers to. For example, many operating characteristics of character special files (for instance, terminals) may be controlled with ioctl() requests. The writeups in section 4 discuss how ioctl() applies to various objects.

The request codes for particular functions are specified in include files specific to objects or to families of objects; the writeups in section 4 indicate which include files specify which requests.

For most ioctl() functions, arg is a pointer to data to be used by the function or to be filled in by the function. Other functions may ignore arg or may treat it directly as a data item; they may, for example, be passed an int value.

RETURN VALUE

If an error has occurred, a value of −1 is returned and errno is set to indicate the error.

If no error has occurred, a value of 0 is returned by most functions. Some specialized functions may return non-zero values on success; see the description of the function in the writeup for the object.

ERRORS

ioctl() will fail if one or more of the following are true:

EBADF des is not a valid descriptor.

ENOTTY The specified request does not apply to the kind of object to which the descriptor des refers.

EINVAL request or arg is not valid.

EFAULT request requires a data transfer to or from a buffer pointed to by arg, but some part of the buffer is outside the process’s allocated space.

ioctl() will also fail if the object on which the function is being performed detects an error. In this case, an error code specific to the object and the function will be returned.

Museum