ioctl_tty

NOM

BIBLIOTHÈQUE

SYNOPSIS

#include <sys/ioctl.h>
#include <asm/termbits.h>   /* Définition de struct termios,
                               struct termios2 et
                               Bnnn, BOTHER, CBAUD, CLOCAL,
                               TC*{FLUSH,ON,OFF} et d'autres
                                 constantes */

int ioctl(int fd, int cmd, ...);

DESCRIPTION

Utiliser des ioctls rend les programmes non portables. Utilisez l'interface POSIX décrite dans termios(3) si possible.

Veuillez noter que struct termios de <asm/termbits.h> est différente et incompatible avec struct termios de <termios.h>. Ces appels ioctl exigent struct termios de <asm/termbits.h>.  

Récupérer et positionner les attributs d'un terminal

TCGETS

Argument : struct termios~*argp

Équivalent à tcgetattr(fd, argp).

Récupérer la configuration du port série courant.

TCSETS

Argument : const struct termios~*argp

Équivalent à tcsetattr(fd, TCSANOW, argp).

Configurer le port série courant.

TCSETSW

Argument : const struct termios~*argp

Équivalent à tcsetattr(fd, TCSADRAIN, argp).

Laisser le tampon de sortie se vider, puis configurer le port série courant.

TCSETSF

Argument : const struct termios~*argp

Équivalent à tcsetattr(fd, TCSAFLUSH, argp).

Laisser le tampon de sortie se vider, abandonner toute entrée en cours, puis configurer le port série courant.

Les quatre ioctls suivants, ajoutés à Linux 2.6.20, sont équivalents à TCGETS, TCSETS, TCSETSW, TCSETSF, sauf qu'ils prennent une struct termios2~* à la place d'une struct termios~*. Si le membre de structure c_cflag contient l'attribut BOTHER, le débit en bauds est stocké dans les membres de structure c_ispeed et c_ospeed en tant qu'entier. Ces ioctls ne sont pas pris en charge sur toutes les architectures.

TCGETS2	struct termios2 *argp
TCSETS2	const struct termios2 *argp
TCSETSW2	const struct termios2 *argp
TCSETSF2	const struct termios2 *argp

Les quatre ioctls suivants sont équivalents à TCGETS, TCSETS, TCSETSW et TCSETSF, sauf qu'ils prennent une structure struct termio~* à la place d'une struct termios~*.

TCGETA	struct termio *argp
TCSETA	const struct termio *argp
TCSETAW	const struct termio *argp
TCSETAF	const struct termio *argp

Verrouiller une structure termios

TIOCGLCKTRMIOS

Argument : struct termios~*argp

Récupérer l'état du verrou de la structure termios du terminal.

TIOCSLCKTRMIOS

Argument : const struct termios~*argp

Définir l'état du verrou de la structure termios du terminal. Seul un processus avec la capacité CAP_SYS_ADMIN peut faire cela.

Récupérer et configurer les tailles de fenêtre

TIOCGWINSZ

Argument : struct winsize~*argp

Récupérer la taille de la fenêtre.

TIOCSWINSZ

Argument : const struct winsize~*argp

Définir la taille de la fenêtre.

La structure utilisée par ces ioctls est la suivante :

struct winsize {
    unsigned short ws_row;
    unsigned short ws_col;
    unsigned short ws_xpixel;   /* non utilisé */
    unsigned short ws_ypixel;   /* non utilisé */ };

Lorsque la taille d'une fenêtre change, un signal SIGWINCH est envoyé au groupe de processus au premier plan.  

Envoyer une interruption (« break »)

TCSBRK

Argument : int arg

Équivalent à tcsendbreak(fd, arg).

Si le terminal utilise un mode de transmission série asynchrone et que arg est nul, alors une interruption (un flux de bits nuls) est envoyée pendant 0,25 à 0,5 seconde. Si le terminal n'utilise pas un mode de transmission série asynchrone, alors soit une interruption est envoyée, soit la fonction ne fait rien. Quand arg est non nul, le comportement n'est pas défini.

(SVr4, UnixWare, Solaris et Linux traitent tcsendbreak(fd,arg) avec un paramètre arg non nul de la même façon que tcdrain(fd). SunOS considère arg comme un coefficient multiplicateur et envoie un flux de bits arg fois plus long que lorsque arg est nul. DG/UX et AIX traitent arg (lorsqu'il est non nul) comme un intervalle de temps exprimé en millisecondes. HP-UX ignore arg.)

TCSBRKP

Argument : int arg

Ce qu'on appelle la « version POSIX » de TCSBRK. Elle traite le arg non nul comme un intervalle de temps mesuré en dixièmes de seconde et ne fait rien lorsque le pilote ne gère pas les interruptions.

TIOCSBRK

Argument : void

Activer les interruptions, c'est-à-dire commencer à envoyer des bits nuls.

TIOCCBRK

Argument : void

Désactiver les interruptions, c'est-à-dire arrêter d'envoyer les bits nuls.

Contrôle de flux logiciel

TCXONC

Argument : int arg

Équivalent à tcflow(fd, arg).

Consultez tcflow(3) pour avoir la signification des valeurs TCOOFF, TCOON, TCIOFF et TCION.

Information sur les tampons et vidage

FIONREAD

Argument : int~*argp

Récupérer le nombre d'octets dans le tampon d'entrée.

TIOCINQ

Argument : int~*argp

Identique à FIONREAD.

TIOCOUTQ

Argument : int~*argp

Récupérer le nombre d'octets dans le tampon de sortie.

TCFLSH

Argument : int arg

Équivalent à tcflush(fd, arg).

Consultez tcflush(3) pour la signification de TCIFLUSH, TCOFLUSH et TCIOFLUSH.

TIOCSERGETLSR

Argument : int~*argp

Récupérer le registre d'état de ligne. Le registre d'état a le bit TIOCSER_TEMT défini quand le tampon de sortie est vide et qu'également le transmetteur matériel est physiquement vide.

Ne doit pas être pris en charge par tous les pilotes tty série.

tcdrain(3) n'attend pas et renvoie immédiatement lorsque le bit TIOCSER_TEMT est défini.

Simuler l'entrée

TIOCSTI

Argument : const char~*argp

Insérer l'octet donné dans la queue d'entrée.

Rediriger la sortie de la console

TIOCCONS

Argument : void

Rediriger la sortie qui serait allée vers /dev/console ou /dev/tty0 vers un terminal donné. S'il s'agit d'un pseudoterminal maître, envoyer à l'esclave. Avant Linux 2.6.10, n'importe qui peut utiliser cet appel à condition que la sortie ne soit pas déjà redirigée ; depuis Linux 2.6.10, seul un processus avec la capacité CAP_SYS_ADMIN peut l'utiliser. Si elle a déjà été redirigée, EBUSY est renvoyée, mais la redirection peut être arrêtée en utilisant cet ioctl avec fd pointant vers /dev/console ou /dev/tty0.

Terminal de contrôle

TIOCSCTTY

Argument : int arg

Faire du terminal donné le terminal de contrôle du processus appelant. Le processus appelant doit être un leader de session et ne doit pas déjà avoir de terminal de contrôle. Dans ce cas, arg doit valoir zéro.

Si ce terminal est déjà le terminal de contrôle d'une autre session, alors l'ioctl échoue avec le code d'erreur EPERM, à moins que l'appelant soit un superutilisateur (plus précisément : qu'il ait la capacité CAP_SYS_ADMIN) et que arg vaille 1. Dans ce dernier cas, le terminal est « volé », et tous les processus pour lesquels c'était le terminal de contrôle le perdent.

TIOCNOTTY

Argument : void

Si le terminal donné est le terminal de contrôle du processus appelant, abandonner ce terminal de contrôle. Si le processus est un leader de session, alors SIGHUP et SIGCONT seront envoyés au groupe de processus au premier plan, et tous les processus de la session perdent leur terminal de contrôle.

Groupe de processus et identifiant de session

TIOCGPGRP

Argument : pid_t~*argp

En cas de succès, équivalent à *argp = tcgetpgrp(fd).

Récupérer l'identifiant du groupe de processus au premier plan sur ce terminal.

TIOCSPGRP

Argument : const pid_t~*argp

Équivalent à tcsetpgrp(fd, *argp).

Définir l'identifiant du groupe de processus au premier plan du terminal.

TIOCGSID

Argument : pid_t~*argp

En cas de succès, équivalent à *argp = tcgetsid(fd).

Récupérer l'identifiant de session du terminal donné. L'appel échouera avec pour erreur ENOTTY si le terminal n'est pas un pseudoterminal maître et n'est pas notre terminal de contrôle. Étrange.

Mode exclusif

TIOCEXCL

Argument : void

Mettre le terminal en mode exclusif. Plus aucun appel open(2) sur le terminal ne sera autorisé. (Ils échoueront avec l'erreur EBUSY, sauf pour un processus ayant la capacité CAP_SYS_ADMIN.)

TIOCGEXCL

Argument : int~*argp

(Depuis Linux 3.8) Si le terminal est actuellement en mode exclusif, mettre une valeur positive à l'endroit vers lequel pointe argp ; sinon mettre un zéro dans *argp.

TIOCNXCL

Argument : void

Désactiver le mode exclusif.

Paramètres de la ligne (« line discipline »)

TIOCGETD

Argument : int~*argp

Récupérer les paramètres de la ligne du terminal.

TIOCSETD

Argument : const int~*argp

Définir les paramètres de la ligne (« line discipline ») du terminal.

Ioctls pour les pseudoterminaux

TIOCPKT

Argument : const int~*argp

Activer (quand *argp n'est pas nul) ou désactiver le mode paquet. Ne peut être appliqué qu'à la partie maître d'un pseudoterminal (renvoie ENOTTY sinon). En mode paquet, chaque read(2) suivant renverra un paquet qui contient soit un seul octet de contrôle non nul, soit un unique octet nul ('\0') suivi par les données écrites du côté esclave du pseudoterminal. Si le premier octet n'est pas TIOCPKT_DATA (0), il s'agit d'un OU logique entre les bits suivants :

TIOCPKT_FLUSHREAD	La file de lecture du terminal est vidée.
TIOCPKT_FLUSHWRITE	La file d'écriture du terminal est vidée.
TIOCPKT_STOP	La sortie sur le terminal est arrêtée.
TIOCPKT_START	La sortie sur le terminal est redémarrée.
TIOCPKT_DOSTOP	Les caractères de démarrage et d'arrêt sont haS/haQ.
TIOCPKT_NOSTOP	Les caractères de démarrage et d'arrêt ne sont pas haS/haQ.

Tant que le mode paquet est utilisé, la présence d'informations d'état de contrôle à lire du côté maître peut être détectée avec select(2) pour les conditions exceptionnelles ou un poll(2) pour l'événement POLLPRI.

Ce mode est utilisé par rlogin(1) et rlogind(8) pour implémenter l'envoi distant du contrôle de flux haS/haQ en local.

TIOCGPKT

Argument : const int~*argp

(Depuis Linux 3.8) Renvoyer le paramètre du mode paquet actuel dans l'entier vers lequel pointe argp.

TIOCSPTLCK

Argument : int~*argp

Positionner (si *argp n'est pas nul) ou effacer (si *argp est zéro) le verrou sur le périphérique esclave du pseudoterminal (voir aussi unlockpt(3)).

TIOCGPTLCK

Argument : int~*argp

(Depuis Linux 3.8) Mettre l'état actuel du verrou du périphérique esclave du terminal virtuel à l'emplacement vers lequel pointe argp.

TIOCGPTPEER

Argument : int flags

(Depuis Linux 4.13) À partir d'un descripteur de fichier de fd qui se rapporte à un terminal virtuel maître, ouvrir (avec les flags donnés à la manière de open(2)) et renvoyer un nouveau descripteur de fichier qui renvoie au terminal virtuel esclave correspondant. Cette opération peut être effectuée que le chemin du périphérique esclave soit accessible par l'espace de noms de montage du processus appelant ou pas.

Les programmes soucieux de la sécurité qui interagissent avec les espaces de noms peuvent souhaiter utiliser cette opération au lieu de open(2) avec le chemin renvoyé par ptsname(3) et les fonctions de bibliothèque semblables ayant des APIs non sécurisées (par exemple, il peut y avoir des confusions dans certains cas en utilisant ptsname(3) avec un chemin où un système de fichiers devpts a été monté dans un autre espace de noms de montage).

Les ioctls BSD TIOCSTOP, TIOCSTART, TIOCUCNTL et TIOCREMOTE n'ont pas été implémentés sous Linux.  

Contrôle des modems

TIOCMGET

Argument : int~*argp

Récupérer l'état des bits du modem.

TIOCMSET

Argument : const int~*argp

Définir l'état des bits du modem.

TIOCMBIC

Argument : const int~*argp

Effacer les bits du modem indiqués.

TIOCMBIS

Argument : const int~*argp

Positionner les bits du modem indiqués.

Les bits suivants sont utilisés par les ioctls ci-dessus :

TIOCM_LE	DSR (data set ready/ligne activée)
TIOCM_DTR	DTR (data terminal ready, terminal de données prêt)
TIOCM_RTS	RTS (request to send, requête à envoyer)
TIOCM_ST	TXD secondaire (transmit)
TIOCM_SR	RXD secondaire (receive)
TIOCM_CTS	CTS (clear to send, vider pour envoyer)
TIOCM_CAR	DCD (data carrier detect)
TIOCM_CD	voir TIOCM_CAR
TIOCM_RNG	RNG (ring)
TIOCM_RI	voir TIOCM_RNG
TIOCM_DSR	DSR (data set ready)

TIOCMIWAIT

Argument : int arg

Attendre qu'un des bits de modem (DCD, RI, DSR, CTS) change. Les bits intéressants sont indiqués sous la forme de masques de bits dans arg en reliant (opération OR) toutes les valeurs de bits, TIOCM_RNG, TIOCM_DSR, TIOCM_CD et TIOCM_CTS. L'appelant doit utiliser TIOCGICOUNT pour savoir le bit qui a changé.

TIOCGICOUNT

Argument : struct serial_icounter_struct~*argp

Récupérer le nombre d'interruptions de la ligne série d'entrée (DCD, RI, DSR, CTS). Le nombre est écrit dans une structure serial_icounter_struct vers laquelle pointe argp.

Note : les transitions 1->0 et 0->1 sont prises en compte, sauf pour RI, où seules les transitions 0->1 sont prises en compte.

Marquer une ligne comme étant locale

TIOCGSOFTCAR

Argument : int~*argp

(GSOFTCAR : « Get SOFTware CARrier flag ») Récupérer l'état du drapeau CLOCAL dans le champ c_cflag de la structure termios.

TIOCSSOFTCAR

Argument : const int~*argp

(SSOFTCAR : « Set SOFTware CARrier flag ») Positionner le drapeau CLOCAL de la structure termios si *argp n'est pas nul, et l'effacer dans le cas contraire.

Si le drapeau CLOCAL d'une ligne est désactivé, le signal de détection de porteuse (DCD) est significatif et un appel à open(2) sur le terminal correspondant sera bloqué tant que le signal DCD sera maintenu, à moins que le drapeau O_NONBLOCK soit fourni. Si CLOCAL est positionné, la ligne se comporte comme si DCD était maintenu en permanence. Le drapeau logiciel pour la porteuse est généralement positionné pour les périphériques locaux et désactivé pour les lignes par modem.  

Spécifique à Linux

Débogage du noyau

TIOCTTYGSTRUCT

Argument : struct tty_struct~*argp

Récupérer la structure tty_struct correspondant à fd. Cette commande a été supprimée dans Linux 2.5.67.

VALEUR RENVOYÉE

ERREURS

EINVAL

Paramètre de commande non valable.

ENOIOCTLCMD

Commande inconnue.

ENOTTY

fd inapproprié.

EPERM

Droits insuffisants.

EXEMPLES

#include <fcntl.h> #include <stdio.h> #include <sys/ioctl.h> #include <unistd.h>

int main(void) {
    int fd, serial;

    fd = open("/dev/ttyS0", O_RDONLY);
    ioctl(fd, TIOCMGET, &serial);
    if (serial & TIOCM_DTR)
        puts("TIOCM_DTR is set");
    else
        puts("TIOCM_DTR is not set");
    close(fd); }

Récupérer ou définir un débit en bauds sur le port série.

/* SPDX-License-Identifier : GPL-2.0-or-later */

#include <asm/termbits.h> #include <fcntl.h> #include <stdio.h> #include <stdlib.h> #include <sys/ioctl.h> #include <unistd.h>

int main(int argc, char *argv[]) { #if !defined BOTHER
    fprintf(stderr, "BOTHER n'est pas pris en charge\n");
    /* Le programme peut se rabattre sur TCGETS/TCSETS avec des constantes Bnnn */
    exit(EXIT_FAILURE); #else
    /* Déclarer la structure tio, son type dépend de l'ioctl pris en charge */ # if defined TCGETS2
    struct termios2 tio; # else
    struct termios tio; # endif
    int fd, rc;

    if (argc != 2 && argc != 3 && argc != 4) {
        fprintf(stderr, "Utilisation : %s périphérique [sortie] [entrée] ]\n", argv[0]);
        exit(EXIT_FAILURE);
    }

    fd = open(argv[1], O_RDWR | O_NONBLOCK | O_NOCTTY);
    if (fd < 0) {
        perror("open");
        exit(EXIT_FAILURE);
    }

    /* Récupérer les paramètres du port série actuel à l'aide de l'ioctl
       pris en charge */ # if defined TCGETS2
    rc = ioctl(fd, TCGETS2, &tio); # else
    rc = ioctl(fd, TCGETS, &tio); # endif
    if (rc) {
        perror("TCGETS");
        close(fd);
        exit(EXIT_FAILURE);
    }

    /* Modifier le débit en bauds quand plus d'arguments ont été fournis */
    if (argc == 3 || argc == 4) {
        /* Effacer le débit en bauds en sortie actuel et définir une nouvelle valeur */
        tio.c_cflag &= ~CBAUD;
        tio.c_cflag |= BOTHER;
        tio.c_ospeed = atoi(argv[2]);

        /* Effacer le débit en bauds en entrée actuel et définir une nouvelle valeur */
        tio.c_cflag &= ~(CBAUD << IBSHIFT);
        tio.c_cflag |= BOTHER << IBSHIFT;
        /* Quand le 4e argument n'est pas fourni, réutiliser le débit en bauds de
           sortie */
        tio.c_ispeed = (argc == 4) ? atoi(argv[3]) : atoi(argv[2]);

        /* Définir de nouveaux paramètres du port série à l'aide de l'ioctl
           pris en charge */ # if defined TCSETS2
        rc = ioctl(fd, TCSETS2, &tio); # else
        rc = ioctl(fd, TCSETS, &tio); # endif
        if (rc) {
            perror("TCSETS");
            close(fd);
            exit(EXIT_FAILURE);
        }

        /* Et obtenir de nouvelles valeurs vraiment configurées */ # if defined TCGETS2
        rc = ioctl(fd, TCGETS2, &tio); # else
        rc = ioctl(fd, TCGETS, &tio); # endif
        if (rc) {
            perror("TCGETS");
            close(fd);
            exit(EXIT_FAILURE);
        }
    }

    close(fd);

    printf("débit en bauds en sortie : %u\n", tio.c_ospeed);
    printf("débit en bauds en entrée : %u\n", tio.c_ispeed);

    exit(EXIT_SUCCESS); #endif }  

VOIR AUSSI

TRADUCTION

Cette traduction est une documentation libre ; veuillez vous reporter à la GNU General Public License version 3 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 à

Index

NOM

BIBLIOTHÈQUE

SYNOPSIS

DESCRIPTION

Récupérer et positionner les attributs d'un terminal

Verrouiller une structure termios

Récupérer et configurer les tailles de fenêtre

Envoyer une interruption (« break »)

Contrôle de flux logiciel

Information sur les tampons et vidage

Simuler l'entrée

Rediriger la sortie de la console

Terminal de contrôle

Groupe de processus et identifiant de session

Mode exclusif

Paramètres de la ligne (« line discipline »)

Ioctls pour les pseudoterminaux

Contrôle des modems

Marquer une ligne comme étant locale

Spécifique à Linux

Débogage du noyau

VALEUR RENVOYÉE

ERREURS

EXEMPLES

VOIR AUSSI

TRADUCTION