Linux Terminal Mode | canonical / nocanonical / cbreak / raw

注：本文为 “Linux 终端模式” 相关文章合辑。

略作重排，如有内容异常，请看原文。

---

终端输入输出的三种模式

guidao

1 前言

在进行项目开发时，需要实时读取终端输入（无需按下 Enter 键即可读取）。然而，Go 语言并未提供便捷的接口。为此，查阅了相关资料，对终端的 I/O 进行了深入研究，并将关键内容整理如下。

2 终端 I/O 的三种模式

2.1 Canonical 模式

该模式也称为 cooked 模式 。在这种模式下，终端每次返回一行数据，所有特殊字符均会被解释（例如：^C）。

2.2 Nocanonical 模式

此模式亦称 raw 模式 。在这种模式下，终端每次返回一个字符，而非先收集一行数据再返回。特殊字符不会被特殊处理，需自行处理。例如，终端编辑器 vi 即处于这种模式下，可完全控制输入输出字符。

2.3 Cbreak 模式

该模式与 raw 模式相似，但会处理特殊字符（某些场景下需使用此模式）。

3 终端控制结构

终端设备的所有可控制属性均通过以下结构进行管理。Go 语言中，该结构定义于 syscall 包中。

struct termios {tcflag_t    c_iflag;    /* 输入标志 */tcflag_t    c_oflag;    /* 输出标志 */tcflag_t    c_cflag;    /* 控制标志 */tcflag_t    c_lflag;    /* 本地标志 */cc_t        c_cc[NCCS]; /* 控制字符 */
};

其中，c_iflag 控制输入属性（例如：将 CR 映射为 NL），c_oflag 控制输出属性（例如：将 tab 扩展为空格），c_cflag 控制行属性，c_lflag 设置用户与设备接口属性（例如：本地回显、允许信号产生）。该结构通过两个函数进行获取与设置，函数声明如下：

#include <termios.h>
int tcgetattr(int filedes, struct termios *termptr);
int tcsetattr(int filedes, int opt, const struct termios *termptr);
% 返回值：若成功则返回 0，若失败则返回 -1

filedes 是文件描述符，通常通过打开设备文件 /dev/tty 获得。tcsetattr 函数中的 opt 参数可取以下值：

• TCSANOW ：使设置立即生效。
• TCSADRAIN ：在输出缓存区输出到屏幕后生效。
• TCSAFLUSH ：在输出缓存区输出到屏幕后生效，并且丢弃所有输入缓存中未处理的数据。

4 纯 Go 实现一个 getchar（可立即获取用户输入而无需按下 Enter 键）

package mainimport ("fmt""os""syscall""unsafe"
)% 通过系统调用设置属性
func ioctl(fd, request, argp uintptr) error {if _, _, e := syscall.Syscall6(syscall.SYS_IOCTL, fd, request, argp, 0, 0, 0); e != 0 {return e}return nil
}% 获取设备属性
func Tcgetattr(fd uintptr, argp *syscall.Termios) error {return ioctl(fd, syscall.TIOCGETA, uintptr(unsafe.Pointer(argp)))
}% 设置终端
func Tcsetattr(fd, opt uintptr, argp *syscall.Termios) error {return ioctl(fd, opt, uintptr(unsafe.Pointer(argp)))
}func main() {var term syscall.Termiosvar origin syscall.Termiosfd, err := os.Open("/dev/tty")must(err)err = Tcgetattr(fd.Fd(), &term)origin = termmust(err)% 设置为nobufferterm.Lflag &^= syscall.ICANONterm.Cc[syscall.VMIN] = 1term.Cc[syscall.VTIME] = 0Tcsetattr(fd.Fd(), syscall.TIOCSETA, &term)c, err := ReadChar(fd.Fd())must(err)fmt.Println(" read:", string(c))% 恢复原来的设置Tcsetattr(fd.Fd(), syscall.TIOCSETA, &origin)
}func ReadChar(fd uintptr) ([]byte, error) {b := make([]byte, 4)n, e := syscall.Read(int(fd), b)if e != nil {return nil, e}return b[:n], nil
}
func must(err error) {if err != nil {panic(err)}
}

5 参考资料

• http://www.lafn.org/~dave/linux/terminalIO.html

---

终端的 Raw Mode

Erzbir

2025-02-10

Raw Mode

在启动 Terminal 时，默认是以 canonical mode 或者叫 cooked mode 启动的。这种模式下，用户按键产生的字符会由终端驱动存入内部缓冲区，期间可以自动处理 Backspace 、Ctrl-C 等特殊字符，需要等待用户按下 Enter 后才将字符从缓冲区中送到程序的标准输入（STDIN_FILENO 为 0）。

例如下面这个程序：

#include <unistd.h>int main() {char c;while (read(STDIN_FILENO, &c, 1) == 1) {write(STDOUT_FILENO, &c, 1);}return 0;
}

终端默认是 canonical mode ，所以会在按下 Enter 后，从标准输入中每次读取一个字节到 c ，直到 0 个字节可读。

这也是常用的一种模式，输入命令及参数回车，然后 shell 就会解释我们的命令。但是你可能见过一些命令行程序比如 top ，按下 q 后并没有 Enter 就直接退出了，这就需要 raw mode 让我们自己来处理这些输入。

下面这个例子仍然是 canonical mode 的，也是通过 q 来退出，但是需要 Enter ：

#include <unistd.h>int main() {char c;while (read(STDIN_FILENO, &c, 1) == 1 && c != 'q') {write(STDOUT_FILENO, &c, 1);}return 0;
}

但是这样的问题就在于和预期稍微有些差别，我们不仅要 Enter ，而且那之后的字符可能是 wqeqweq 这样，而这个程序是读到一个 q char 就会退出。

而在 raw mode 下，没有回显，不会处理特殊字符，也没有缓冲区。

关闭回显

要切换到 raw mode 首先是关闭回显，需要用到 termios.h 提供的 tcgetattr() 函数以及 tcsetattr() 函数。

这两个函数的定义是这样的：

% The tcgetattr() function copies the parameters associated with the terminal referenced by fildes in the termios structure referenced by termios_p.
% This function is allowed from a background process; however, the terminal attributes may be subsequently changed by a foreground process.int tcgetattr(int, struct termios *);% The tcsetattr() function sets the parameters associated with the terminal from the termios structure referenced by termios_p.
% The optional_actions field is created by or'ing the following values, as specified in the include file ⟨termios.h⟩.int tcsetattr(int, int, const struct termios *);

通过下面这三个语句就可以获取到当前的状态：

struct termios raw;
tcgetattr(STDIN_FILENO, &raw);
printf("%lu", raw.c_lflag);

我们需要的就是这个 c_lflag ，将这个 flag 进行位运算后再调用 tcsetattr() 设置即可：

void enable_raw_mode() {struct termios raw;tcgetattr(STDIN_FILENO, &raw);raw.c_lflag &= ~(ECHO);tcsetattr(STDIN_FILENO, TCSAFLUSH, &raw);
}

这样就关闭了回显，运行之后输入字符就不会再有回显。如果你发现还是有回显，确保在终端运行，而不是用 IDE 的 run 来运行或是其他的一些 wrap。

切换到 Raw Mode

我们已经关闭了回显，现在还需要禁用缓冲区和禁用特殊字符处理等等操作，下面一步一步来。

禁用 SIGINT 和 SIGSTP

ISIG 控制是否发送 SIGINT 和 SIGSTP 。

void enable_raw_mode() {struct termios raw;tcgetattr(STDIN_FILENO, &raw);raw.c_lflag &= ~(ECHO | ICANON | ISIG);tcsetattr(STDIN_FILENO, TCSAFLUSH, &raw);
}

现在，不需要回车且 Ctrl-C 和 Ctrl-Z 的输入已经不起作用。

禁用输出流控^Software flow control^

通过 flag: c_iflag 的 IXON 控制。

void enable_raw_mode() {struct termios raw;tcgetattr(STDIN_FILENO, &raw);raw.c_lflag &= ~(ECHO | ICANON | ISIG);raw.c_iflag &= ~(IXON);tcsetattr(STDIN_FILENO, TCSAFLUSH, &raw);
}

禁用 Ctrl-V

通过 c_lflag 的 IEXTEN 控制。

void enable_raw_mode() {struct termios raw;tcgetattr(STDIN_FILENO, &raw);raw.c_lflag &= ~(ECHO | ICANON | ISIG | IEXTEN);raw.c_iflag &= ~(IXON);tcsetattr(STDIN_FILENO, TCSAFLUSH, &raw);
}

关闭换行映射

c_lflag ，ICRNL 。

\r 的 char 值是 13 ，\n 的 char 值是 10 。

为了消除不同操作系统之间换行符的差异，默认开启映射，可能会将 \r 自动转换成 \n ，也就是说 Ctrl-J 和 Ctrl-M 会是一样的值，而 Ctrl-M 原本是 13 。

void enable_raw_mode() {struct termios raw;tcgetattr(STDIN_FILENO, &raw);raw.c_lflag &= ~(ECHO | ICANON | ISIG | IEXTEN);raw.c_iflag &= ~(IXON | ICRNL);tcsetattr(STDIN_FILENO, TCSAFLUSH, &raw);
}

关闭输出处理

c_oflag ，OPOST 。

开启时终端会将换行符 \n 转换成回车符后跟一个换行符：\r\n 。

void enable_raw_mode() {struct termios raw;tcgetattr(STDIN_FILENO, &raw);raw.c_lflag &= ~(ECHO | ICANON | ISIG | IEXTEN);raw.c_iflag &= ~(IXON | ICRNL);raw.c_oflag &= ~(OPOST);tcsetattr(STDIN_FILENO, TCSAFLUSH, &raw);
}

实际上还需要更多的操作，比如通过结构体中的 c_cc 来设置 read() 返回所需要的最小字节数以及读超时时间等：

void enable_raw_mode() {struct termios raw;tcgetattr(STDIN_FILENO, &raw);% 修改 raw.c_lflag 来禁用终端的一些本地模式% 禁用 ECHO: 关闭回显% 禁用 ICANON: 关闭规范模式 (行缓冲), 使得输入按字符处理% 禁用 IEXTEN: 禁用扩展输入处理% 禁用 ISIG: 禁用信号生成 (例如 Ctrl+C 不再生成 SIGINT 信号)raw.c_lflag &= ~(ECHO | ICANON | ISIG | IEXTEN);% 修改 raw.c_iflag 来禁用某些输入处理% 禁用 BRKINT, ICRNL, INPCK, ISTRIP, IXON 等标志raw.c_iflag &= ~(IXON | ICRNL | BRKINT | INPCK | ISTRIP);% 修改 raw.c_oflag 来禁用输出处理 (比如自动转换换行符)raw.c_oflag &= ~(OPOST);% 修改 raw.c_cflag" 设置字符大小为 8 位 (通常为 CS8)raw.c_cflag |= (CS8);% 设置控制字符% VMIN = 0: read() 至少读取 0 个字节% VTIME = 1000: read() 超时时间为 1000msraw.c_cc[VMIN] = 0;raw.c_cc[VTIME] = 1000;tcsetattr(STDIN_FILENO, TCSAFLUSH, &raw);
}int main() {char c;enable_raw_mode();while (read(STDIN_FILENO, &c, 1) == 1 && c != 'q') {if (c == '\r' | c == '\n') {write(STDOUT_FILENO, "\r\n", 2);}write(STDOUT_FILENO, &c, 1);}return 0;
}

这里就设置了 1000 秒后如果没有读取到 read() 就会直接返回，如果 c_cc[VMIN] 为 1 则是会阻塞到读取到一个字节为止。

• BRKINT ：当检测到 break 条件时触发中断行为或产生错误，帮助捕捉和处理输入中断。
• INPCK ：启用输入奇偶校验，用于检测数据传输中的错误。
• ISTRIP ：对输入数据进行剥离，将每个字节的最高位清零，确保只保留 7 位数据。

直接切换到 Raw Mode

实际上 termios.h 中有提供一个直接切换的 API ：cfmakeraw() 。

这个函数只需要传入一个 struct termios ，会修改结构体中的值就像我们上面做的那样。

void enable_raw_mode() {struct termios raw;cfmakeraw(&raw);tcsetattr(STDIN_FILENO, TCSAFLUSH, &raw);
}

使用其他语言

使用其他语言就要用到 FFI 了，比如下面使用 Rust ，好在 Rust 提供了一个 libc 库可以很容易做到：

fn enable_raw_mode() {unsafe {let mut termios = {std::mem::zeroed()};libc::tcgetattr(libc::STDIN_FILENO, &mut termios);libc::cfmakeraw(&mut termios);libc::tcsetattr(libc::STDIN_FILENO, libc::TCSANOW, &termios);}
}

这只是一个最简单的例子。

下面是纯 FFI 的例子：

#[repr(C)]
#[derive(Copy, Clone)]
struct Termios {c_iflag: u32,c_oflag: u32,c_cflag: u32,c_lflag: u32,cc_c: [u8; 20],c_ispeed: u32,c_ospeed: u32,
}extern "C" {fn tcgetattr(fd: i32, termios: &mut Termios) -> i32;fn tcsetattr(fd: i32, command: i32, termios: &Termios) -> i32;fn cfmakeraw(termios: &mut Termios);
}const STDIN_FILENO: i32 = 0;
const TCSAFLUSH: i32 = 2;fn enable_raw_mode() {unsafe {let mut termios = std::mem::zeroed();cfmakeraw(&mut termios);tcsetattr(STDIN_FILENO, TCSAFLUSH, &mut termios);}
}

---

via:

• 终端输入输出的三种模式
  https://guidao.github.io/termio.html

• 终端的 Raw Mode
  https://erzbir.com/archives/terminal-raw-mode