From: Alejandro Colomar Date: Tue, 30 Jun 2026 23:59:44 +0000 (+0200) Subject: man/man3{,type}/termios.3{,type}: Move 'Canonical and noncanonical mode' to termios... X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b092da0f26d6529f2b7fc2f4e31ddcafb39d996a;p=thirdparty%2Fman-pages.git man/man3{,type}/termios.3{,type}: Move 'Canonical and noncanonical mode' to termios(3type) Signed-off-by: Alejandro Colomar --- diff --git a/man/man3/termios.3 b/man/man3/termios.3 index f0e937111..26e02a570 100644 --- a/man/man3/termios.3 +++ b/man/man3/termios.3 @@ -92,158 +92,8 @@ has been transmitted, and all input that has been received but not read will be discarded before the change is made. .SS Canonical and noncanonical mode -The setting of the -.B ICANON -canon flag in -.I c_lflag -determines whether the terminal is operating -in canonical mode -.RB ( ICANON -set) -or noncanonical mode -.RB ( ICANON -unset). -By default, -.B ICANON -is set. -.P -In canonical mode: -.IP \[bu] 3 -Input is made available line by line. -An input line is available when one of the line delimiters is typed -(NL, EOL, EOL2; -or EOF at the start of line). -Except in the case of EOF, -the line delimiter is included -in the buffer returned by -.BR read (2). -.IP \[bu] -Line editing is enabled -(ERASE, KILL; -and if the -.B IEXTEN -flag is set: WERASE, REPRINT, LNEXT). -A -.BR read (2) -returns at most one line of input; -if the -.BR read (2) -requested fewer bytes than are available in the current line of input, -then only as many bytes as requested are read, -and the remaining characters will be available for a future -.BR read (2). -.IP \[bu] -The maximum line length is 4096 chars -(including the terminating newline character); -lines longer than 4096 chars are truncated. -After 4095 characters, -input processing -(e.g., -.B ISIG -and -.B ECHO* -processing) -continues, -but any input data after 4095 characters -up to (but not including) any terminating newline -is discarded. -This ensures that -the terminal can always receive more input -until at least one line can be read. -.P -In noncanonical mode input is available immediately -(without the user having to type a line-delimiter character), -no input processing is performed, -and line editing is disabled. -The read buffer will only accept 4095 chars; -this provides the necessary space for a newline char -if the input mode is switched to canonical. -The settings of MIN -.RI ( c_cc[VMIN] ) -and TIME -.RI ( c_cc[VTIME] ) -determine the circumstances in which a -.BR read (2) -completes; -there are four distinct cases: -.TP -MIN == 0, TIME == 0 (polling read) -If data is available, -.BR read (2) -returns immediately, -with the lesser of the number of bytes available, -or the number of bytes requested. -If no data is available, -.BR read (2) -returns 0. -.TP -MIN > 0, TIME == 0 (blocking read) -.BR read (2) -blocks until MIN bytes are available, -and returns up to the number of bytes requested. -.TP -MIN == 0, TIME > 0 (read with timeout) -TIME specifies the limit for a timer in tenths of a second. -The timer is started when -.BR read (2) -is called. -.BR read (2) -returns either when at least one byte of data is available, -or when the timer expires. -If the timer expires without any input becoming available, -.BR read (2) -returns 0. -If data is already available at the time of the call to -.BR read (2), -the call behaves as though the data was received immediately after the call. -.TP -MIN > 0, TIME > 0 (read with interbyte timeout) -TIME specifies the limit for a timer in tenths of a second. -Once an initial byte of input becomes available, -the timer is restarted after each further byte is received. -.BR read (2) -returns when any of the following conditions is met: -.RS -.IP \[bu] 3 -MIN bytes have been received. -.IP \[bu] -The interbyte timer expires. -.IP \[bu] -The number of bytes requested by -.BR read (2) -has been received. -(POSIX does not specify this termination condition, -and on some other implementations -.\" e.g., Solaris -.BR read (2) -does not return in this case.) -.RE -.IP -Because the timer is started only after the initial byte becomes available, -at least one byte will be read. -If data is already available at the time of the call to -.BR read (2), -the call behaves as though the data was received immediately after the call. -.P -POSIX -.\" POSIX.1-2008 XBD 11.1.7 -does not specify whether the setting of the -.B O_NONBLOCK -file status flag takes precedence over the MIN and TIME settings. -If -.B O_NONBLOCK -is set, a -.BR read (2) -in noncanonical mode may return immediately, -regardless of the setting of MIN or TIME. -Furthermore, -if no data is available, -POSIX permits a -.BR read (2) -in noncanonical mode to return either 0, or \-1 with -.I errno -set to -.BR EAGAIN . +See +.BR termios (3type). .SS Raw mode .BR cfmakeraw () sets the terminal to something like the diff --git a/man/man3type/termios.3type b/man/man3type/termios.3type index ab5e880d9..91fee3b8b 100644 --- a/man/man3type/termios.3type +++ b/man/man3type/termios.3type @@ -72,8 +72,7 @@ and .BR VTIME , see the description of noncanonical mode -in -.BR termios (3). +below. .SS \f[I].c_iflag\f[] flag constants .TP .B IGNBRK @@ -742,6 +741,159 @@ by setting the value of the corresponding .I .c_cc element to .BR _POSIX_VDISABLE . +.SS Canonical and noncanonical mode +The setting of the +.B ICANON +canon flag in +.I c_lflag +determines whether the terminal is operating +in canonical mode +.RB ( ICANON +set) +or noncanonical mode +.RB ( ICANON +unset). +By default, +.B ICANON +is set. +.P +In canonical mode: +.IP \[bu] 3 +Input is made available line by line. +An input line is available when one of the line delimiters is typed +(NL, EOL, EOL2; +or EOF at the start of line). +Except in the case of EOF, +the line delimiter is included +in the buffer returned by +.BR read (2). +.IP \[bu] +Line editing is enabled +(ERASE, KILL; +and if the +.B IEXTEN +flag is set: WERASE, REPRINT, LNEXT). +A +.BR read (2) +returns at most one line of input; +if the +.BR read (2) +requested fewer bytes than are available in the current line of input, +then only as many bytes as requested are read, +and the remaining characters will be available for a future +.BR read (2). +.IP \[bu] +The maximum line length is 4096 chars +(including the terminating newline character); +lines longer than 4096 chars are truncated. +After 4095 characters, +input processing +(e.g., +.B ISIG +and +.B ECHO* +processing) +continues, +but any input data after 4095 characters +up to (but not including) any terminating newline +is discarded. +This ensures that +the terminal can always receive more input +until at least one line can be read. +.P +In noncanonical mode input is available immediately +(without the user having to type a line-delimiter character), +no input processing is performed, +and line editing is disabled. +The read buffer will only accept 4095 chars; +this provides the necessary space for a newline char +if the input mode is switched to canonical. +The settings of MIN +.RI ( c_cc[VMIN] ) +and TIME +.RI ( c_cc[VTIME] ) +determine the circumstances in which a +.BR read (2) +completes; +there are four distinct cases: +.TP +MIN == 0, TIME == 0 (polling read) +If data is available, +.BR read (2) +returns immediately, +with the lesser of the number of bytes available, +or the number of bytes requested. +If no data is available, +.BR read (2) +returns 0. +.TP +MIN > 0, TIME == 0 (blocking read) +.BR read (2) +blocks until MIN bytes are available, +and returns up to the number of bytes requested. +.TP +MIN == 0, TIME > 0 (read with timeout) +TIME specifies the limit for a timer in tenths of a second. +The timer is started when +.BR read (2) +is called. +.BR read (2) +returns either when at least one byte of data is available, +or when the timer expires. +If the timer expires without any input becoming available, +.BR read (2) +returns 0. +If data is already available at the time of the call to +.BR read (2), +the call behaves as though the data was received immediately after the call. +.TP +MIN > 0, TIME > 0 (read with interbyte timeout) +TIME specifies the limit for a timer in tenths of a second. +Once an initial byte of input becomes available, +the timer is restarted after each further byte is received. +.BR read (2) +returns when any of the following conditions is met: +.RS +.IP \[bu] 3 +MIN bytes have been received. +.IP \[bu] +The interbyte timer expires. +.IP \[bu] +The number of bytes requested by +.BR read (2) +has been received. +(POSIX does not specify this termination condition, +and on some other implementations +.\" e.g., Solaris +.BR read (2) +does not return in this case.) +.RE +.IP +Because the timer is started only after the initial byte becomes available, +at least one byte will be read. +If data is already available at the time of the call to +.BR read (2), +the call behaves as though the data was received immediately after the call. +.P +POSIX +.\" POSIX.1-2008 XBD 11.1.7 +does not specify whether the setting of the +.B O_NONBLOCK +file status flag takes precedence over the MIN and TIME settings. +If +.B O_NONBLOCK +is set, a +.BR read (2) +in noncanonical mode may return immediately, +regardless of the setting of MIN or TIME. +Furthermore, +if no data is available, +POSIX permits a +.BR read (2) +in noncanonical mode to return either 0, or \-1 with +.I errno +set to +.BR EAGAIN . .SH STANDARDS POSIX.1-2024. .SH HISTORY