IOCTL(2)

NOME
ioctl - controle de dispositivo

SINOPSE
#include <sys/ioctl.h>

int ioctl(int fd, unsigned long request, ...);

DESCRIÇÃO
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() requests. The argument fd must be an open file descriptor.

The second argument is a device-dependent request 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() request 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() request are located in the file <sys/ioctl.h>. See NOTES.

VALOR DE RETORNO
Usually, on success zero is returned. A few ioctl() requests use the return value as an output parameter and return a nonnegative value on success. On error, -1 is returned, and errno is set appropriately.

ERROS

EBADF
    fd não é um descritor de arquivo válido.

EFAULT
    argp referencia uma área de memória inacessível.

EINVAL
    request ou argp não é válido.

ENOTTY
    fd não está associada com um dispositivo especial de caracter.

ENOTTY
    The specified request does not apply to the kind of object that the file descriptor fd references.

DE ACORDO COM
No single standard. 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).

The ioctl() system call appeared in Version 7 AT&T UNIX.

NOTAS
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.

  Estrutura de ioctl
Os valores do comando Ioctl são constantes de 32 bits. Em princípio, essas constantes são completamente arbitrárias, mas as pessoas tentaram construir alguma estrutura nelas.

A situação antiga do Linux era principalmente de constantes de 16 bits, onde o último byte é um número de série e o(s) byte(s) anterior(es) fornecem um tipo que indica o driver. Às vezes, o número principal era usado: 0x03 para os ioctls HDIO_*, 0x06 para os ioctls LP*. E, às vezes, uma ou mais letras ASCII eram usadas. Por exemplo, TCGETS tem valor 0x00005401, com 0x54 = 'T' indicando o driver do terminal, e CYGETTIMEOUT tem valor 0x00435906, com 0x43 0x59 = 'C''Y' indicando o driver Cyclades.

Posteriormente (0.98p5), mais algumas informações foram incorporadas ao número. Um tem 2 bits de direção (00: nada, 01: escrita, 10: leitura, 11: leitura/escrita) seguidos por 14 bits de tamanho (fornecendo o tamanho do argumento), seguido por um tipo de 8 bits (coletando os ioctls em grupos para uma finalidade comum ou um driver comum) e um número de série de 8 bits.

As macros descrevendo esta estrutura residem em <asm/ioctl.h> e são _IO(type,nr) e {_IOR,_IOW,_IOWR}(type,nr,size). Elas usam sizeof(size), de forma que o tamanho é um nome incorreto aqui: este terceiro argumento é um tipo de dados.

Observe que os bits de tamanho não são confiáveis: em muitos casos, eles estão errados, seja por causa de macros com erros usando sizeof(sizeof(struct)), ou por causa de valores legados.

Assim, parece que a nova estrutura só deu desvantagens: não ajuda na verificação, mas causa valores variáveis para as várias arquiteturas.

VEJA TAMBÉM
execve(2), fcntl(2), ioctl_console(2), ioctl_fat(2), ioctl_ficlonerange(2), ioctl_fideduperange(2), ioctl_fslabel(2), ioctl_getfsmap(2), ioctl_iflags(2), ioctl_ns(2), ioctl_tty(2), ioctl_userfaultfd(2), open(2), sd(4), tty(4)

COLOFÃO
Esta página faz parte da versão 5.10 do projeto Linux man-pages. Uma descrição do projeto, informações sobre relatórios de bugs e a versão mais recente desta página podem ser encontradas em https://www.kernel.org/doc/man-pages/.

TRADUÇÃO
A tradução para português brasileiro desta página man foi criada por André Luiz Fassone <lonely_wolf@ig.com.br> e Ricardo C.O.Freitas <english.quest@best-service.com> Esta tradução é uma documentação livre; leia a Licença Pública Geral GNU Versão 3 (https://www.gnu.org/licenses/gpl-3.0.html) ou posterior para as condições de direitos autorais. Nenhuma responsabilidade é aceita. Se você encontrar algum erro na tradução desta página de manual, envie um e-mail para a lista de discussão de tradutores (debian-l10n-portuguese@lists.debian.org).