Line Speed (The GNU C Library)

#### 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 identical 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 compatibility 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`.