Terminal Line Speed (Bit Rate)

Different terminals (and serial lines) are capable of transmitting and receiving at different speeds (bits per second). The cfgetispeed() and cfsetispeed() functions retrieve and modify the input line speed. The cfgetospeed() and cfsetospeed() functions retrieve and modify the output line speed.

Note

The term baud is commonly used as a synonym for the terminal line speed (in bits per second), although this usage is not technically correct. Precisely, baud is the per-second rate at which signal changes can occur on the line, which is not necessarily the same as the number of bits transmitted per second, since the latter depends on how bits are encoded into signals. Nevertheless, the term baud continues to be used synonymously with bit rate (bits per second). (The term baud rate is often also used synonymously with baud, but this is redundant; the baud is by definition a rate.) To avoid confusion, we’ll generally use terms like line speed or bit rate.

#include <termios.h>

speed_t cfgetispeed(const struct termios *termios_p);
speed_t cfgetospeed(const struct termios *termios_p);

Note

Both return a line speed from given termios structure

int cfsetospeed(struct termios *termios_p, speed_t speed);
int cfsetispeed(struct termios *termios_p, speed_t speed);

Note

Both return 0 on success, or -1 on error

Each of these functions works on a termios structure that must be previously initialized by a call to tcgetattr().

For example, to find out the current terminal output line speed, we would do the following:

struct termios tp;
speed_t rate;

if (tcgetattr(fd, &tp) == -1)
    errExit("tcgetattr");
rate = cfgetospeed(&tp);
if (rate == -1)
    errExit("cfgetospeed");

If we then wanted to change this line speed, we would continue as follows:

if (cfsetospeed(&tp, B38400) == -1)
    errExit("cfsetospeed");
if (tcsetattr(fd, TCSAFLUSH, &tp) == -1)
    errExit("tcsetattr");

The speed_t data type is used to store a line speed. Rather than directly assigning numeric values for line speeds, a set of symbolic constants (defined in <termios.h>) is used. These constants define a series of discrete values. Some examples of such constants are B300, B2400, B9600, and B38400, corresponding, respectively, to the line speeds 300, 2400, 9600, and 38,400 bits per second. The use of a set of discrete values reflects the fact that terminals are normally designed to work with a limited set of different (standardized) line speeds, derived from the division of some base rate (e.g., 115,200 is typical on PCs) by integral values (e.g., 115,200 / 12 = 9600).

SUSv3 specifies that the terminal line speeds are stored in the termios structure, but (deliberately) does not specify where. Many implementations, including Linux, maintain these values in the c_cflag field, using the CBAUD mask and the CBAUDEX flag. (In Retrieving and Modifying Terminal Attributes, we noted that the nonstandard c_ispeed and c_ospeed fields of the Linux termios structure are unused.)

Although the cfsetispeed() and cfsetospeed() functions allow separate input and output line speeds to be specified, on many terminals, these two speeds must be the same. Furthermore, Linux uses only a single field to store the line speed (i.e., the two rates are assumed to be always the same), which means that all of the input and output line-speed functions access the same termios field.

Note

Specifying speed as 0 in a call to cfsetispeed() means “set the input speed to whatever the output speed is when tcsetattr() is later called.” This is useful on systems where the two line speeds are maintained as separate values.