17.5.8 Line Speed

The terminal line speed tells the computer how fast to read and write data on the terminal.

For standard asynchronous serial lines employing binary NRZ encoding such as RS232, RS422, RS423, or RS485, the terminal speed will equal the physical layer baud rate including asynchronous framing and parity bits. This needs to match the communication speed expected by the peer device, or communication will not work. Which particular speeds are supported by any particular interface is hardware specific.

For other types of devices the meaning of the line speed is device-specific and may not even affect the actual data transmission speed at all (for example, if it is a pseudo-terminal or network connection), but some programs will use it to determine the amount of padding needed. It’s best to specify a line speed value that matches the actual speed of the actual terminal, but you can safely experiment with different values to vary the amount of padding.

As the terminal interface models an RS232 serial interface (see Terminal Device Model), the term “baud rate” is frequently used as a direct alias for “line speed”; this convention is followed in the following descriptions.

There are actually two line speeds for each terminal, one for input and one for output. You can set them independently, but most often terminals use the same speed for both directions. If the hardware does not support different speeds for each direction, the output speed will be used for both input and output.

Specifying an output speed of zero generates a modem disconnect request. For the speed_t interface, this is the constant B0 which may or may not have the numeric value 0.

Specifying an input speed value of zero sets the input speed to equal the output speed. This is the numeric constant 0 (not necessarily the same as B0) for both the speed_t and baud_t interfaces. This use is deprecated.

The line speed values are stored in the struct termios structure, but don’t try to access them in the struct termios structure directly. Instead, you should use the functions defined by the interfaces below to access them.

The line speed setting functions report errors only when attempting to set line rate values that the system simply cannot handle. If you specify a line speed value that is plausible for the system, then the functions will succeed. However, they do not check that a particular hardware device can actually support the specified value—in fact, they don’t know which device you plan to set the line speed for until tcsetattr is called. If you use tcsetattr to set the speed of a particular device to a value that it cannot handle, either tcsetattr returns -1 and sets errno to EINVAL, or the value is adjusted to the closest supported value, depending on the policy of the kernel driver. In the latter case, a subsequent call to tcgetattr may or may not reflect this adjustment.

The GNU C Library supports two interoperable interfaces for setting the line speed: the POSIX.1 speed_t interface, which requires the use of a set of enumerated constants, and the baud_t interface, a GNU extension, which is guaranteed to use plain numeric values.

17.5.8.1 The speed_t interface

Data Type: speed_t

The speed_t type is an unsigned integer data type used to represent line speeds.

Portability note: In the current version of the GNU C Library, the speed_t type is numerically indentical to the line speed rate. Other libraries and older versions of the GNU C Library may require speeds to be indicated by enumerated constants, which may not be numerically identical to the requested line speed. For portability, you must use one of the following symbols to represent the speed; their precise numeric values are system-dependent, but each name has a fixed meaning: B110 stands for 110 bps, B300 for 300 bps, and so on. There is no portable way to represent any speed but these.

B0  B50  B75  B110  B134  B150  B200  B300  B600  B1200
B1800  B2400  B4800  B9600  B19200  B38400

The GNU C Library defines these additional constants:

B7200 B14400 B28800 B33600 B57600 B76800 B115200 B153600 B230400 B307200
B460800 B500000 B576000 B614400 B921600 B1000000 B1152000 B1500000
B2000000 B2500000 B3000000 B3500000 B4000000 B5000000 B10000000

BSD defines two additional speed symbols as aliases: EXTA is an alias for B19200 and EXTB is an alias for B38400. These aliases are obsolete.

Macro: speed_t SPEED_MAX

The GNU C Library defines the constant SPEED_MAX for the largest valid value of type speed_t. This value may be smaller than the underlying C type can store.

For compatiblity with some other platforms the alias __MAX_BAUD is defined for this constant.

Function: speed_t cfgetospeed (const struct termios *termios-p)

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

This function returns the output line speed stored in the structure *termios-p.

Function: speed_t cfgetispeed (const struct termios *termios-p)

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

This function returns the input line speed stored in the structure *termios-p.

Function: int cfsetospeed (struct termios *termios-p, speed_t speed)

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

This function stores speed in *termios-p as the output line speed. If speed is B0, generates a modem disconnect request.

If speed is neither a plausible line speed nor B0, cfsetospeed returns -1 and sets errno to EINVAL.

Function: int cfsetispeed (struct termios *termios-p, speed_t speed)

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

This function stores speed in *termios-p as the input speed. If speed is 0, the input speed is set to equal the output speed; note that POSIX.1 specifies this as the numeric value 0 which is not required to equal the constant B0.

If speed is not a plausible line speed or 0, cfsetispeed returns -1 and sets errno to EINVAL.

Portability note: POSIX.1-2024 has deprecated setting of the input speed to 0 to set the input line speed to equal the output line speed. After calling tcsetattr followed by tcgetattr, cfgetispeed may report the input line speed either as 0 or the same as cfgetospeed.

Function: int cfsetspeed (struct termios *termios-p, speed_t speed)

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

This function stores speed in *termios-p as both the input and output speeds.

If baud is not a plausible line speed, cfsetbaud returns -1 and sets errno to EINVAL.

This function is an extension which originated in 4.4 BSD.

17.5.8.2 The baud_t interface

Data Type: baud_t

The baud_t type is a numeric data type used to represent line baud rates. It will always represent the actual numeric value corresponding to the line speed, unlike speed_t. In the current version of the GNU C Library this is the same type as speed_t, but this may not be the case in future versions or on other implementations; it is specifically not guaranteed to be an integer type.

Macro: baud_t BAUD_MAX

The constant BAUD_MAX is defined to the maximum valid value of type baud_t. This value may be smaller than the underlying C type can store.

Function: baud_t cfgetobaud (const struct termios *termios-p)

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

This function returns the output line speed stored in the structure *termios-p as a numeric value.

Function: baud_t cfgetibaud (const struct termios *termios-p)

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

This function returns the input line speed stored in the structure *termios-p as a numeric value.

Function: int cfsetobaud (struct termios *termios-p, baud_t baud)

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

This function stores baud in *termios-p as the output line speed. If baud is 0, generates a modem disconnect.

If speed is not a plausible line speed, cfsetspeed returns -1 and sets errno to EINVAL.

Function: int cfsetibaud (struct termios *termios-p, baud_t baud)

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

This function stores baud in *termios-p as the input line speed.

To simplify conversions from the speed_t interface, setting the input line speed to 0 is interpreted as setting the input line speed equal to the output line speed. The caveats described under cfsetispeed apply equally to cfsetibaud. As for cfsetispeed, this usage is deprecated.

If baud is not a plausible line speed or 0, cfsetibaud returns -1 and sets errno to EINVAL.

Function: int cfsetbaud (struct termios *termios-p, baud_t baud)

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

This function stores baud in *termios-p as both the input and output line speeds.

If baud is not a plausible line speed, cfsetbaud returns -1 and sets errno to EINVAL.