TTY_IOCTL(4)

NOMBRE
tty ioctl - ioctls para terminales y líneas serie

SINOPSIS

#include <termios.h>

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

DESCRIPCIÓN
La llamada ioctl() para terminales y puertos serie acepta muchas órdenes que se pasan como argumentos. La mayoría necesita un tercer argumento, de tipo variable, que aquí llamamos argp o arg.

El uso de ioctl hace que un programa no sea (trans)portable. Use la interfaz POSIX descrita en termios(3) siempre que sea posible.

  Obtener y establecer los atributos de un terminal

TCGETS	struct termios *argp
    Equivalente a tcgetattr(fd, argp).
    Obtiene la configuración actual de un puerto serie.

TCSETS	const struct termios *argp
    Equivalente a tcsetattr(fd, TCSANOW, argp).
    Establece la configuración actual de un puerto serie.

TCSETSW	const struct termios *argp
    Equivalente a tcsetattr(fd, TCSADRAIN, argp).
    Permite vaciar el buffer de salida y establecer la configuración actual de un puerto serie.

TCSETSF	const struct termios *argp
    Equivalente a tcsetattr(fd, TCSAFLUSH, argp).
    Permite vaciar el buffer de salida, descartar la entrada pendiente y establecer la configuración actual de un puerto serie.

Las siguientes cuatro ioctls son exactamente iguales a TCGETS, TCSETS, TCSETSW y TCSETSF, excepto en que toman un argumento struct termio * en lugar de un argumento struct termios *.

TCGETA	struct termio *argp

TCSETA	const struct termio *argp

TCSETAW	const struct termio *argp

TCSETAF	const struct termio *argp

  Bloqueo de una estructura termios
La estructura termios de un tty se puede bloquear. El propio bloqueo es una estructura termios con bits o campos distintos de cero indicando un valor bloqueado.

TIOCGLCKTRMIOS	struct termios *argp
    Obtiene el estado de bloqueo de la estructura termios del terminal.

TIOCSLCKTRMIOS	const struct termios *argp
    Establece el estado de bloqueo de la estructura termios del terminal. Sólo el superusuario puede hacer esto.

  Obtener y establecer el tamaño de la ventana
Los tamaños de las ventanas se guardan en el núcleo pero éste no los usa (excepto en el caso de las consolas virtuales, donde el núcleo actualizará el tamaño de la ventana cuando el tamaño de la consola virtual cambie, por ejemplo, al cargar una nueva fuente).

TIOCGWINSZ	struct winsize *argp
    Obtiene el tamaño de la ventana.

TIOCSWINSZ	const struct winsize *argp
    Establece el tamaño de la ventana.

La estructura usada por estas ioctls se define como

struct winsize {
        unsigned short ws_row;
        unsigned short ws_col;
        unsigned short ws_xpixel;   /* sin usar */
        unsigned short ws_ypixel;   /* sin usar */
};

Cuando el tamaño de la ventana cambia, se envía una señal SIGWINCH al grupo de procesos en primer plano.

  Envío de una pausa (break)

TCSBRK	int arg
    Equivalente a tcsendbreak(fd, arg).
    Si la termina usa una transmisión asíncrona serie de datos y si el argumento arg es cero, entonces envía una pausa (un flujo de bits a cero) con una duración de entre 0'25 y 0'5 segundos. Si el terminal no usa una transmisión asíncrona serie de datos, entonces o se envía una pausa o la función regresa sin hacer nada. Cuando arg no es cero, nadie sabe qué ocurrirá.

    (SVR4, UnixWare, Solaris y Linux tratan tcsendbreak(fd,arg) como tcdrain(fd) cuando el argumento arg es distinto de cero. SunOS trata arg como un multiplicador y envía arg veces un flujo de bits tan largo como el que se envía para un valor de arg igual a cero. DG-UX y AIX tratan a arg (cuando no es cero) como un intervalo de tiempo medido en milisegundos. HP-UX ignora arg.)

TCSBRKP	int arg
    Conocida como la "versión POSIX" de TCSBRK. Trata un arg distinto de cero como un intervalo de tiempo medido en décimas de segundo y no hace nada cuando el driver no soporta pausas.

TIOCSBRK	void
    Activa la pausa, es decir, empieza a enviar bits a cero.

TIOCCBRK	void
    Desactiva la pausa, es decir, deja de enviar bits a cero.

  Control de flujo software

TCXONC	int arg
    Equivalente a tcflow(fd, arg).
    Vea tcflow(3) para los valores de argumento TCOOFF, TCOON, TCIOFF y TCION.

  Escrutinio y vaciado de buffers

FIONREAD	int *argp
    Obtiene el número de bytes en el buffer de entrada.

TIOCINQ	int *argp
    Igual que FIONREAD.

TIOCOUTQ	int *argp
    Obtienen el número de bytes en el buffer de salida.

TCFLSH	int arg
    Equivalente a tcflush(fd, arg).
    Vea tcflush(3) para los valores de argumento TCIFLUSH, TCOFLUSH y TCIOFLUSH.

  Falsificación de la entrada

TIOCSTI	const char *argp
    Inserta el byte dado en la cola de entrada.

  Redirección de la salida de consola

TIOCCONS	void
    Redirecciona la salida que habría ido a /dev/console o /dev/tty0 al tty dado. Si éste es un pty maestro, envía la salida a la parte esclava. Cualquier usuario puede hacer esto siempre que la salida no haya sido ya redireccionada. Si ya fue redireccionada, se devuelve el valor EBUSY, aunque el root puede detener la redirección usando esta ioctl con fd apuntando a /dev/console o /dev/tty0.

  tty controlador

TIOCSCTTY	int arg
    Convierte al tty dado en el tty controlador del proceso actual. El proceso actual debe ser un líder de sesión y no tener ya un tty controlador. Si este tty es ya el tty controlador de un grupo de sesión diferente entonces la llamada a ioctl falla con EPERM, a menos que el invocador sea el root y arg valga 1, en cuyo caso se `roba' el tty y todos los procesos que lo tenían como tty controlador lo pierden.

TIOCNOTTYvoid
    Si el tty dado fuera el tty controlador del proceso actual, se abandona este tty controlador. Si el proceso fuera el líder de sesión, entonces se envía SIGHUP y SIGCONT al grupo de procesos en primer plano y todos los procesos en la sesión actual pierden sus ttys controladores.

  (Número) identificador (ID) de grupo de procesos y sesión

TIOCGPGRP	pid_t *argp
    Cuando tiene éxito, equivale a *argp = tcgetpgrp(fd).
    Obtiene el ID del grupo de procesos en primer plano en este tty.

TIOCSPGRP	const pid_t *argp
    Equivalente a tcsetpgrp(fd, *argp).
    Establece el ID del grupo de procesos en primer plano de este tty.

TIOCGSID	pid_t *argp
    Obtiene el ID de sesión del tty dado. La llamada fallará con ENOTTY en el caso en el que el tty no sea un pty maestro ni nuestro tty controlador. Raro.

  Modo exclusivo

TIOCEXCL	void
    Coloca el tty en modo exclusivo. No se permiten más operaciones open(2) sobre el terminal (éstas fallarán con EBUSY excepto para el root).

TIOCNXCL	void
    Desactiva el modo exclusivo.

  Disciplina de línea

TIOCGETD	int *argp
    Obtiene la disciplina de línea del tty.

TIOCSETD	const int *argp
    Establece la disciplina de línea del tty.

  Ioctls de los pseudo-tty

TIOCPKT	const int *argp
    Activa (cuando *argp no es cero) o desactiva el modo de paquetes. Sólo se puede aplicar a la parte maestra de un pseudo-tty (y devolverá ENOTTY en otro caso). En el modo de paquetes, cada read(2) posterior devolverá un paquete que contiene o bien un único byte de control distinto de cero o bien un único byte a 0 seguido de datos escritos en la parte esclava del pty. Si el primer byte no es TIOCPKT_DATA (0), entonces es un O-lógico de uno o más de los siguientes bits:

    TIOCPKT_FLUSHREAD   La cola de lectura del terminal está vacía.
    TIOCPKT_FLUSHWRITE  La cola de escritura del terminal está vacía.
    TIOCPKT_STOP        Se para la salida del terminal.
    TIOCPKT_START       Se reinicia la salida del terminal.
    TIOCPKT_DOSTOP      t_stopc es `^S' y t_startc es `^Q'.
    TIOCPKT_NOSTOP      los caracteres de inicio y parada no son `^S/^Q'.

    Mientras se use este modo, se puede detectar la presencia de datos de entrada en la parte maestra del pty mediante una llamada a select(2). Dichos datos contienen información de estado de control para condiciones excepcionales.

    Este modo lo usan rlogin(1) y rlogind(8) para implementar un login remoto con un flujo controlado localmente mediante `^S/^Q' y un eco remoto.

    Las ioctls de BSD TIOCSTOP, TIOCSTART, TIOCUCNTL, TIOCREMOTE no se han implementado en Linux.

  Control del modem

TIOCMGET	int *argp
    Obtiene el estado de los bits del modem.

TIOCMSET	const int *argp
    Configura el estado de los bits del modem.

TIOCMBIC	const int *argp
    Borra los bits del modem que se indican.

TIOCMBIS	const int *argp
    Activa los bits del modem que se indican.

Los bits usados para estas cuatro ioctls son:

TIOCM_LE        DSR (data set ready/line enable)
TIOCM_DTR       DTR (data terminal ready)
TIOCM_RTS       RTS (request to send)
TIOCM_ST        TXD secundario (transmitir)
TIOCM_SR        RXD secundario (recibir)
TIOCM_CTS       CTS (clear to send)
TIOCM_CAR       DCD (data carrier detect)
TIOCM_CD         vea TIOCM_CAR
TIOCM_RNG       RNG (ring)
TIOCM_RI         vea TIOCM_RNG
TIOCM_DSR       DSR (data set ready)

  Marcar una línea como local

TIOCGSOFTCAR	int *argp
    ("Get software carrier flag") Obtiene el estado de la bandera CLOCAL del campo c_cflag de la estructura termios.

TIOCSSOFTCAR	const int *argp
    ("Set software carrier flag") Activa la bandera CLOCAL de la estructura termios cuando *argp es distinto de cero y la borra en caso contrario.

Si la bandera CLOCAL para una línea está apagada, la señal de detección de la portadora hardware (DCD) es significativa y una operación open(2) sobre el tty correspondiente se bloqueará hasta que se produzca el aserto de DCD, a menos que se haya especificado la opción O_NONBLOCK. Si CLOCAL está activa, la línea se comporta como si DCD estuviera siempre activa. Normalmente, la bandera de la portadora software se enciende para los dispositivos locales y se apaga para las líneas con modems.

  Específico de Linux
Para la ioctl TIOCLINUX vea console_ioctl(4).

  Depuración del núcleo

#include <linux/tty.h>

TIOCTTYGSTRUCT	struct tty_struct *argp
    Obtiene la tty_struct correspondiente a fd.

VALOR DEVUELTO
La llamada al sistema ioctl() devuelve 0 en caso de éxito. En caso de error devuelve -1 y asigna a errno un valor adecuado.

ERRORES

ENOIOCTLCMD
    Orden desconocida.

EINVAL
    Parámetro de orden inválido.

EPERM
    Permiso insuficiente.

ENOTTY
    fd inapropiado.

EJEMPLO
Comprueba el estado de la línea DTR del puerto serie.

#include <termios.h>
#include <fcntl.h>
#include <sys/ioctl.h>

main() {
    int fd, serial;

    fd = open("/dev/ttyS0", O_RDONLY);
    ioctl(fd, TIOCMGET, &serial);
    if (serial & TIOCM_DTR)
        puts("TIOCM_DTR está apagado");
    else
        puts("TIOCM_DTR está encendido");
    close(fd);
}

VÉASE TAMBIÉN
ioctl(2), termios(3), console_ioctl(4).