# ioctl

## NAME



           ioctl - control device
    


## LIBRARY



           Standard C library (_libc_ , _-lc_)
    


## SYNOPSIS



           **#include <sys/ioctl.h>**
    
           **int ioctl(int** _fd_**, unsigned long** _op_**, ...);** /* glibc, BSD */
           **int ioctl(int** _fd_**, int** _op_**, ...);** /* musl, other UNIX */
    


## DESCRIPTION



           The **ioctl**() system call manipulates the underlying device
           parameters of special files.  In particular, many operating
           characteristics of character special files (e.g., terminals) may
           be controlled with **ioctl**() operations.  The argument _fd_ must be an
           open file descriptor.
    
           The second argument is a device-dependent operation code.  The
           third argument is an untyped pointer to memory.  It's
           traditionally **char ***_argp_ (from the days before **void *** was valid
           C), and will be so named for this discussion.
    
           An **ioctl**() _op_ has encoded in it whether the argument is an _in_
           parameter or _out_ parameter, and the size of the argument _argp_ in
           bytes.  Macros and defines used in specifying an **ioctl**() _op_ are
           located in the file _< sys/ioctl.h>_.  See NOTES.
    


## RETURN VALUE



           Usually, on success zero is returned.  A few **ioctl**() operations
           use the return value as an output parameter and return a
           nonnegative value on success.  On error, -1 is returned, and _errno_
           is set to indicate the error.
    


## ERRORS



           **EBADF** _fd_ is not a valid file descriptor.
    
           **EFAULT** _argp_ references an inaccessible memory area.
    
           **EINVAL** _op_ or _argp_ is not valid.
    
           **ENOTTY** _fd_ is not associated with a character special device.
    
           **ENOTTY** The specified operation does not apply to the kind of
                  object that the file descriptor _fd_ references.
    


## VERSIONS



           Arguments, returns, and semantics of **ioctl**() vary according to the
           device driver in question (the call is used as a catch-all for
           operations that don't cleanly fit the UNIX stream I/O model).
    


## STANDARDS



           None.
    


## NOTES



           In order to use this call, one needs an open file descriptor.
           Often the open(2) call has unwanted side effects, that can be
           avoided under Linux by giving it the **O_NONBLOCK** flag.
    
       **ioctl structure**
           Ioctl _op_ values are 32-bit constants.  In principle these
           constants are completely arbitrary, but people have tried to build
           some structure into them.
    
           The old Linux situation was that of mostly 16-bit constants, where
           the last byte is a serial number, and the preceding byte(s) give a
           type indicating the driver.  Sometimes the major number was used:
           0x03 for the **HDIO_*** ioctls, 0x06 for the **LP*** ioctls.  And
           sometimes one or more ASCII letters were used.  For example,
           **TCGETS** has value 0x00005401, with 0x54 = 'T' indicating the
           terminal driver, and **CYGETTIMEOUT** has value 0x00435906, with 0x43
           0x59 = 'C' 'Y' indicating the cyclades driver.
    
           Later (0.98p5) some more information was built into the number.
           One has 2 direction bits (00: none, 01: write, 10: read, 11:
           read/write) followed by 14 size bits (giving the size of the
           argument), followed by an 8-bit type (collecting the ioctls in
           groups for a common purpose or a common driver), and an 8-bit
           serial number.
    
           The macros describing this structure live in _< asm/ioctl.h>_ and are
           **_IO(type,nr)** and **{_IOR,_IOW,_IOWR}(type,nr,size)**.  They use
           _sizeof(size)_ so that size is a misnomer here: this third argument
           is a data type.
    
           Note that the size bits are very unreliable: in lots of cases they
           are wrong, either because of buggy macros using
           _sizeof(sizeof(struct))_ , or because of legacy values.
    
           Thus, it seems that the new structure only gave disadvantages: it
           does not help in checking, but it causes varying values for the
           various architectures.
    


* * *