ioctl(2)

NOM
ioctl – Contrôler les périphériques

BIBLIOTHÈQUE
Bibliothèque C standard (libc, -lc)

SYNOPSIS
#include <sys/ioctl.h>

int ioctl(int desc_fic, unsigned long opération, ...);  /* glibc, BSD */
int ioctl(int desc_fic, int opération, ...);            /* musl, autres UNIX */

DESCRIPTION
L'appel système ioctl() modifie le comportement des périphériques sous-jacents des fichiers spéciaux. En particulier, de nombreuses caractéristiques des fichiers spéciaux en mode caractère (par exemple des terminaux) peuvent être contrôlées avec des opérations ioctl(). L'argument desc_fic doit être un descripteur de fichier ouvert.

Le second argument est le code de l’opération dépendant du périphérique. Le troisième argument est un pointeur non typé. Il est traditionnellement défini en char *argp (cela date de l'époque avant que void * soit du C valable), et sera ainsi nommé dans le reste de cette page.

Une opération ioctl() encapsule le fait que l'argument est un paramètre d'entrée ou de sortie ainsi que la taille de l'argument argp en octets. Les macros et définitions décrivant une opération ioctl() se trouvent dans le fichier <sys/ioctl.h>. Voir NOTES.

VALEUR RENVOYÉE
En général, ioctl renvoie 0 s'il réussit. Certaines opérations ioctl utilisent la valeur de retour comme paramètre de sortie et renvoient une valeur non négative si elles réussissent. En cas d'échec, -1 est renvoyé et errno est positionnée pour indiquer l'erreur.

ERREURS

EBADF
    fd n'est pas un descripteur de fichier valable.

EFAULT
    argp pointe en dehors de l'espace d'adressage valable.

EINVAL
    L’opération ou l'argument argp ne sont pas valables.

ENOTTY
    desc_fic n'est pas associé avec un fichier spécial en mode caractère.

ENOTTY
    L’opération indiquée ne s'applique pas au type d'objet associé avec le descripteur desc_fic.

VERSIONS
Les arguments, les valeurs de retour et la sémantique de ioctl() varient en fonction du pilote de périphérique concerné (cet appel système est utilisé pour encapsuler les opérations qui ne se conforment pas bien au modèle UNIX des entrées/sorties par flux).

NORMES
Aucun.

HISTORIQUE
Version 7 AT&T UNIX has
ioctl(int fd, int op, struct sgttyb *argp);
où struct sgttyb a historiquement été utilisé par stty(2) et gtty(2) et est polymorphe pour le type d’opération (tel qu’un void * le serait s’il était disponible).

SysIII documente arg sans aucun type.

4.3BSD a
ioctl(int desc_fic, unsigned long opération, char *argp);
avec char * intégré de façon similaire pour void *.

SysVr4 a
int ioctl(int fd, int op, ...  /* arg */);

NOTES
Pour utiliser cet appel, on a besoin d'un descripteur de fichier ouvert. Souvent, l'appel open(2) a des effets de bord non désirés, qui peuvent être évités sous Linux en lui passant le drapeau O_NONBLOCK.

  Structure ioctl
Les valeurs d’opération ioctl sont des constantes 32 bits. En principe, ces constantes sont totalement arbitraires, mais des gens ont essayé de construire une certaine structure avec elles.

Avant, sous Linux, il y avait principalement des constantes de 16 bits, où le dernier octet est un numéro de série et le(s) précédent(s) octet(s) donne(nt) un type indiquant le pilote. Parfois, le nombre majeur était utilisé : 0x03 pour les ioctls HDIO_*, 0x06 pour les ioctls LP*, et parfois, une ou plusieurs lettres ASCII étaient utilisées. Par exemple, TCGETS a une valeur de 0x00005401, avec 0x54 = 'T' indiquant le pilote du terminal, et CYGETTIMEOUT a une valeur de 0x00435906, avec 0x43 0x59 = 'C' 'Y' indiquant le pilote Cyclades.

Plus tard (0.98p5), des informations supplémentaires ont été intégrées dans le numéro. L'une a deux bits de direction (00 : aucun, 01 : écriture, 10 : lecture, 11 : lecture/écriture), suivis de 14 bits de taille (donnant la taille de l'argument), suivis d'un autre de type de 8 bits (récupérant les ioctls dans des groupes pour une utilisation générique ou un pilote commun) et d’un numéro de série de 8 bits.

Les macros décrivant cette structure se trouvent dans <asm/ioctl.h>. Il s'agit de _IO(type,nr) et {_IOR,_IOW,_IOWR}(type,nr,size). Elles utilisent sizeof(size), donc la taille est ici une appellation inappropriée : ce troisième argument est de type donnée.

Notez que les bits de taille ne sont pas fiables du tout : dans de nombreux cas, ils sont faux, soit du fait de macros boguées qui utilisent sizeof(sizeof(struct)), soit à cause de valeurs patrimoniales.

Ainsi, il semble que cette nouvelle structure ne procure que des inconvénients : elle n'aide pas à faire des vérifications, mais il entraine des valeurs variables pour les différentes architectures.

VOIR AUSSI
execve(2), fcntl(2), ioctl_console(2), ioctl_fat(2), ioctl_fs(2), ioctl_fsmap(2), ioctl_nsfs(2), ioctl_tty(2), ioctl_userfaultfd(2), ioctl_eventpoll(2), open(2), sd(4), tty(4)

TRADUCTION
La traduction française de cette page de manuel a été créée par Christophe Blaess <https://www.blaess.fr/christophe/>, Stéphan Rafin <stephan.rafin@laposte.net>, Thierry Vignaud <tvignaud@mandriva.com>, François Micaux, Alain Portal <aportal@univ-montp2.fr>, Jean-Philippe Guérard <fevrier@tigreraye.org>, Jean-Luc Coulon (f5ibh) <jean-luc.coulon@wanadoo.fr>, Julien Cristau <jcristau@debian.org>, Thomas Huriaux <thomas.huriaux@gmail.com>, Nicolas François <nicolas.francois@centraliens.net>, Florentin Duneau <fduneau@gmail.com>, Simon Paillard <simon.paillard@resel.enst-bretagne.fr>, Denis Barbier <barbier@debian.org>, David Prévot <david@tilapin.org>, Jean-Philippe MENGUAL <jpmengual@debian.org> et Jean-Paul Guillonneau <guillonneau.jeanpaul@free.fr>

Cette traduction est une documentation libre ; veuillez vous reporter à la GNU General Public License version 3 (https://www.gnu.org/licenses/gpl-3.0.html) concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.

Si vous découvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message à debian-l10n-french@lists.debian.org.