For Gauche 0.9.5

Next: , Previous: , Up: Library modules - Gauche extensions   [Contents][Index]

9.30 gauche.termios - Terminal control

Module: gauche.termios

This module provides procedures to control terminals. On Unix platforms, the low-level API provides POSIX termios interface as the module name suggests. This module also provides pseudo tty interface, if the system supports it.

On Windows native platforms, POSIX termios interface is not available. It is too different from Windows console API to provide a meaningful emulation. The low-level Windows console API is available in the module (see Windows support). You can still use high-level terminal control procedures in this module.

Next: , Previous: , Up: Terminal control   [Contents][Index]

9.30.1 Posix termios interface

These procedures are available when the feature identifier is not defined. See cond-expand in Feature conditional for how to switch code using feature identifiers.

Builtin Class: <sys-termios>

POSIX termios(7) structure.

Instance Variable of <sys-termios>: iflag
Instance Variable of <sys-termios>: oflag
Instance Variable of <sys-termios>: cflag
Instance Variable of <sys-termios>: lflag
Instance Variable of <sys-termios>: cc

The slots iflag, oflag, cflag and lflag contains non-negative integers representing bitmasks.

The slot cc contains a copy of c_cc array of struct termios, as an u8vector (see Uniform vectors for the details about u8vector). Since cc slot is a copy of the internal structure, you have to set! an u8vector to the slot explicitly to make changes to the c_cc array.

Throughout this section, argument port-or-fd refers to either a port object or a small integer representing system’s file descriptor. If port is not associated to the system terminal, an error is signaled. (You can check if port has an associated terminal by sys-isatty?. see Other file operations).

Function: sys-tcgetattr port-or-fd

Returns terminal parameters in a <sys-termios> object, associated to port-or-fd.

Function: sys-tcsetattr port-or-fd when termios

Sets terminal parameters associated to port-or-fd by termios, which must be an instance of <sys-termios>.

An integer argument when specifies when the changes take effect. Three variables are pre-defined for the argument:


The change is reflected immediately.


The change is reflected after all pending output is flushed.


The change is reflected after all pending output is flushed, and all pending input is discarded.

Function: sys-tcsendbreak port-or-fd duration

Transmits a zero stream for the specified duration to the terminal associated to port-or-fd. The unit of duration depends on the system; see man tcsendbreak(3) of your system for details.

Function: sys-tcdrain port-or-fd

Waits until all output written to port-or-fd is transmitted.

Function: sys-tcflush port-or-fd queue

Discards data in the buffer of port-or-fd, specified by queue, which may be one of the following values.


Discards data received but not read.


Discards data written but not transmitted.


Do both TCIFLUSH and TCOFLUSH action.

Function: sys-tcflow port-or-fd action

Controls data flow of port-or-fd by action, which may be one of the following values:


Suspends output transmission.


Restarts output transmission.


Transmits a STOP character to make the terminal device stop transmitting data to the system.


Transmits a START character to make the terminal device resume transmitting data to the system.

Function: sys-tcgetpgrp port-or-fd

Returns process group ID of the terminal associated to port-or-fd.

Function: sys-tcsetpgrp port-or-fd pgrp

Sets process group ID of the terminal associated to port-or-fd to pgrp.

Function: sys-cfgetispeed termios
Function: sys-cfsetispeed termios speed
Function: sys-cfgetospeed termios
Function: sys-cfsetospeed termios speed

Gets/sets input/output speed (baud rate) parameter stored in termios object. Speed is represented by the following predefined numbers: B0, B50, B75, B110, B134, B150, B200, B300, B600, B1200, B1800, B2400, B4800, B9600, B19200, B38400.

Some system may support higher baud rate, such as B57600, B115200 or B230400. You can use symbol-bound? to check these options are defined. B0 is used to terminate the connection.

Function: sys-openpty :optional term

Opens a pair of pseudo ttys, one for master and the other for slave, then returns two integers which are their file descriptors. An optional argument term must be, if passed, a <sys-termios> object; it sets the slave pty’s parameters.

You can use open-input-fd-port and/or open-output-fd-port to create a port around the returned file descriptor (see File ports). To obtain pseudo tty’s name, use sys-ttyname (see Other file operations).

This function is available only if the system supports openpty(3).

Function: sys-forkpty :optional term

Opens a pair of pseudo ttys, one for master and the other for slave, sets the slave pty suitable for login terminal, then fork(2).

Returns two integers; the first value is a child pid for the parent process, and 0 for the child process. The second value is a file descriptor of the master pty.

An optional argument term must be, if passed, a <sys-termios> object; it sets the slave pty’s parameters.

This function is available only if the system supports forkpty(3).

Note: sys-forkpty has the same MT hazard as sys-fork (see Process management, for details). If you’re running multiple threads, use sys-forkpty-and-exec below.

Function: sys-forkpty-and-exec command args :key iomap term sigmask

Does sys-forkpty, and lets the child process immediately execs the specified command with arguments args. This function doesn’t have the hazard in multi-thread environment.

The meanings of arguments command, args, iomap and sigmask are the same as sys-exec (see Process management). If the keyword argument term is given, it is used to initialize the slave pty.

Previous: , Up: Terminal control   [Contents][Index]

9.30.2 Common high-level terminal control

Function: without-echoing iport proc

If iport is an input port connected to a terminal, sets the terminal mode non-echoing and call proc with iport as an argument. Before returning from without-echoing, or throwing an error, the terminal mode is reset to the original state when this procedure is called. The procedure returns whatever value(s) proc returns.

You can also pass #f to iport. In that case, this procedure tries to open a console (/dev/tty on Unix, CON on Windows) and set the console mode, then calls proc with the opened input port. An error is thrown if the procedure can not open a console.

If iport is other than above, this procedure simply calls proc with iport. This allows the caller to read password from redirected input, for example.

Note: Because of an implementation issue, on Windows native platforms this procedure always changes console mode of the standard input handle when iport is either #f or a terminal input port.

Function: has-windows-console?

Returns #t iff the running Gauche is Windows-native and the process has attached console. On POSIX platforms this procedure always returns #f.

The reason that cond-expand isn’t enough is that on Windows the program may start without console, but you can attach console afterwards. See Windows console API, for the details.

Previous: , Up: Terminal control   [Contents][Index]