Serial-Programming-HOWTO-Part 2 TERMIOS(7) by Verne Hoxie (same License as his Serial-Programming-HOWTO) The file '/usr/include/asm/termios.h' defines: struct termios { tcflag_t c_iflag; /* input mode flags */ tcflag_t c_oflag; /* output mode flags */ tcflag_t c_cflag; /* control mode flags */ tcflag_t c_lflag; /* local mode flags */ cc_t c_line; /* line discipline */ cc_t c_cc[NCCS]; /* control characters */ }; where: typedef unsigned long tcflag_t; typedef unsigned char cc_t; and: #define NCCS 19 The 'c_iflag' flags set the input mode and are: IGNBRK Ignore a BREAK condition. A BREAK condition is defined to mean a character framing error with the data all zeroes. A framing error is one where the 'start' and 'stop' bits don't appear at the input of the UART in the time slot where they are expected by the circuitry. In order to guarantee a BREAK for any speed, the signal should be placed in the 'space' condition for at least 275-300 milliseconds. BRKINT Send an 'INTR' (interrupt) signal to the processes associated to this terminal. This definition would open a big bag of worms if I tried to explain all the implications of a 'signal', 'controlling terminal' etc here. Instead I'll cop out and refer you to the 'intro(2)', 'signal(2)' and 'setpgrp(2)' manual pages. IGNPAR Ignore parity or parity errors except for the 'BREAK condition'. PARMRK Mark the character as the result of a parity error. INPCK Enable input parity check. This bit controls the action of the device driver only and does not effect the hardware. If the hardware is set to check the parity bit the result is not processed by the driver. While these definitions seem simple, there are some rather complex interactions. When: IGNBRK set, BRKINT set or unset. A BREAK condition is completely ignored. IGNBRK unset, BRKINT set, All data is flushed from the input and output queues. If the terminal associated with the device is a controlling terminal to a foreground process, a SIGINT is sent to that process. IGNBRK unset, BRKINT unset. A BREAK condition is changed to a single NUL character. However if PARMRK is set, then send the sequence '0x3f', '0x00', '0x00' is sent to the process. IGNPAR unset, PARMRK set. A framing error or parity error is sent to the process as the sequence '0x3f', '0x00', char where 'char' is the character received. If ISTRIP is unset then the sequence becomes '0x3f', '0x3f' if the received 'char' is also '0x3f'. IGNPAR unset, PARMRK unset. A framing or parity error is sent to the process as a single '0x00' unless the framing error is the result of a BREAK condition. ISTRIP Strip off the eighth bit of the incoming byte. INLCR An incoming new line character is translated to a carriage return. IGNCR Ignore an incoming carriage return. ICRNL Translate an incoming carriage return to a new line character. Of course if the IGNCR flag is set, this is another do nothing. IUCLC Translate incoming upper case alphabetic characters to lower case. This has no effect on control characters of non-alphabetic character. IXON Suspend sending output characters when the 'STOP' character is received. This character is conventionally the control-S, 0x13, character but is actually defined in 'c_cc' array later in this structure. IXANY Resume output of data when any character is received after data flow has been stopped with a STOP character. If the IXANY flag is not set, flow is resumed only when a 'START' character is received. By convention this is the control-Q character, 0x11. Like the STOP character, the actual character used is in the 'c_cc' field. IXOFF Send a STOP character on the output when the input buffer is nearly full. Then send a START character when the sufficient room is available to receive additional characters. IMAXBEL Echo the ASCII BEL character, 0x07 or as defined in 'c_cc' when the input stream overflows. Additional data is lost. If MAXBEL is not set, the BEL character is not sent but the data is lost anyhow. The 'c_oflag' flags set the output mode and are: OPOST Enable post processing of output character according to the setting of other flags in this field. Otherwise the characters are transmitted unprocessed. OLCUC Convert lower case alphabetic characters to their upper case counter parts. ONLCR Translate a newline character to the 'carriage return' - 'new line' pair. OCRNL Translate the carriage return character to a new line character. ONOCR Don't send a carriage return if this is column one. ONLRET Assume that the new line character infers a carriage return and add the appropriate amount of fill characters. See 'CRDLY' below. The following series of flags are needed to create delays when sending to a mechanical machine such as TeleType writer. These are needed to allow time for the mechanical action to complete before another character is transmitted. OFILL Use fill characters for the delay instead of a mere time delay for the mechanical action to complete. OFDEL Use the DEL character, '0x3f' for the delay instead of NUL's, '0x00'. NLDLY - a mask to detect the presence of new line delay flags. NL0 No delay. NL1 Delay approximately 0.1 seconds unless ONLRET is set, then use the carriage return delays listed below. CRDLY - a mask to detect the presence of carriage return flags. CR0 No delay. CR1 Determine a delay according to which is the current column. CR2 Delay about 0.10 seconds. CR3 Delay about 0.15 seconds. TABDLY - mask to detect the presence of tab delay flags. TAB0 No delay. TAB1 Determine the delay according to current column. TAB2 Delay about 0.10 seconds. TAB3 or XTABS Expand tabs into spaces. BSDLY - a mask to detect the presence of a backspace delay flag. BS0 No delay. BS1 Delay about 0.05 seconds. If OFILL is also set, send one fill character. VTDLY - a mask to detect the presence of a vertical tab delay flag. VT0 No delay. VT1 Delay about 2 seconds. FFDLY - a mask to detect the presence of a form feed delay flag. FF0 No delay. FF1 Delay about 2 seconds. The 'c_cflag' flags describe the hardware control and are: CBAUD - a mask to detect the presence of the baud rate flag. B0 Hang up the connection and do not assert DTR. B50 Use 50 baud. This can be used to send a BREAK. B75 Use 75 baud. This rate and 50 baud are commonly used for international cable traffic. B110 Use 110 baud. Used by Teletypes. B134 Use 134 baud. B150 Use 150 baud. Used by Teletypes. B200 Use 200 baud. B300 Use 300 baud. B600 Use 600 baud. B1200 Use 1200 baud. B1800 Use 1800 baud. B2400 Use 2400 baud. B4800 Use 4800 baud. B9600 Use 9600 baud. EXTA - a depreciated flag since replaced by B19200 B19200 Use 19200 baud. EXTB - a depreciated flag since replaced by B38400 B38400 Use 38400 baud. CSIZE - a mask to detect the presence of character size flags. CS5 Use character size of five bits. CS6 Use character size of six bits. CS7 Use character size of seven bits. CS8 Use character size of eight bits. CSTOPB Send two stop bits otherwise send one. CREAD Enable receiver else don't receive any characters. PARENB Enable parity generation and detection. If the 'c_iflag' IGNPAR is set, ignore parity detection but generate parity for output. PARODD If PARENB is set then generate 'odd' parity if this bit is set. If PARODD is unset then generate 'even' parity. HUPCL Disconnect the line when the last process closes the device. Infers drop DTR. CLOCAL Assume local control with no control from the modem. CBAUDEX - a mask to detect extended baud rates. B57600 Use 57600 baud. B115200 Use 115200 baud. B230400 Use 230400 baud. Not implemented on Linux. CIBAUD Use specified baud rates for input and standard baud rates for output. Not implemented on Linux. CRTSCTS Use RTS/CTS flow control. The 'c_lflag' flags describe how the line discipline should control the terminal and are: ISIG Enable signals. When set, the input characters are checked against the special control character INTR, QUIT, SWTCH, STATUS and DSUSP. ICANON Perform canonical processing. This enables the ERASE and KILL EDIT functions and assembles the input into lines delimited by NL, EOF, EOL and EOL2 characters. If unset, use MIN and TIME to determine when a 'read' should be satisfied. XCASE If this flag is set and ICANON is set, perform some weird processing to be able to accept escaped lower case letters to produce upper case letters. Also provides the ability to generate some symbols from escaped other symbols. This appears to be a fossil from when keyboards did not have the ability to generate the full ASCII set of characters. for ` send \' for | send \! for ~ send \^ for { send \( for } send \) for \ send \\ for A send \a This works for all upper case characters for \n send \\n for \N send \\\n ECHO Enable echoing of characters as sent. ECHOE Enable erase characters as BS-SP-BS. ECHOK Echo a NL after a kill character. ECHONL Echo NL even if other echoing is suppressed. NOFLSH Disable a flush for the INTR, QUIT or SUSP characters. This should be set when restarting a system call that read from or wrote to a terminal. See 'sigaction(2). TOSTOP Send SIGTTOU to a process operating in the background and it tries to write to the controlling terminal of it's process group. If not set, the output is output to the current output stream. Processes set to ignore SIGTTOU or are blocking are excepted. ECHOCTL Echo control characters in caret format. '0x01' is echoed as "^A". The 'rubout' (delete) characters is echoed as "^?". Don't translate the TAB, NL, START or STOP characters. ECHOPRT Echo erase character as character erased. ECHOKE BS-SP-BS erase entire line on line kill. FLUSHO Output is being flushed. Data written to the terminal is discarded. This bit is set when the FLUSH character is typed. A program can cancel the effect of the FLUSH character by clearing FLUSHO. PENDIN Retype pending input at next read or input character. IEXTEN Enable extended functions. Implementation dependent. If ICANON is set and .. 1. ECHO and ECHOE are set but ECHOPRT is not set, the BS-SP-BS are sent to erase the last character on a CRT screen. 2. ECHO and ECHOPRT are set the first ERASE or WERASE erase sends a backslash followed by the character being erased. Additional ERASE or WERASE character will be echoed as the character being erased. The next non-erase character causes a forward slash to be printed before the character itself. ECHOPRT should be used for hard copy terminals. 3. If ECHOKE is set erase the entire line from the screen. 4. If ECHOK is set and ECHOEK is not set, the NL character is echoed after the KILL character to emphasize that line is deleted. This action is not performed if the ERASE or KILL character is preceded by a back slash or the LNEXT character. 5. If ECHONL is set the NL character is echoed even if ECHO is not set. Initial settings of the 'c_lflag' is ISIG, ICANON, ECHO and ECHOK. The 'c_line' field defines the line discipline. Linux has the following line disciplines implemented. N_TTY - standard interface for terminals and communication N_SLIP - for communication with 'Slip' protocol N_MOUSE - to read serial mice N_PPP - for communication with the PPP protocol Several others exist and can be found in /usr/include/asm/termios.h. This list expands as new devices and protocol are developed. The 'c_cc' field defines special control character. Entry Mnemonic Linux SYSV ASCII key ASCII key c_cc[VINTR] CINTR ETX ^C DEL ^? INTR - send a SIGINT signal to all processes associated with the controlling terminal unless INT is ignored or caught to another function. c_cc[VQUIT] CQUIT FS ^\ FS ^| QUIT - send a SIGQUIT signal to all processes associated with the controlling terminal just like INTR except that a core image is dumped also. c_cc[VERASE] CERASE DEL ^? '#' ERASE - erases the preceding character but will not erase beyond the start of a line as delimited by NL, EOF, EOL or EOL2. c_cc[VKILL] CKILL NAK ^U '@' KILL - deletes an entire line as delimited by NL, EOF, EOL or EOL2. c_cc[VEOF] CEOF EOT ^D EOT ^D EOF - used to generate an end-of-file from a terminal. When received, all characters waiting to be read are immediately passed to the program without waiting for a newline. The EOF is discarded. EOF characters are not echoed unless it is escaped or ECHOCTL is set. By not echoing EOF, terminals are prevented from hanging up. c_cc[VTIME] TIME 0 No time delay c_cc[VMIN] MIN 1 One character See below for an explanation of TIME and MIN. c_cc[VSWTC] CSWITCH NUL ^@ EM ^Z SWTCH - is only used when 'shl' layers are invoked. c_cc[VSTART] CSTART DC1 ^Q DC1 ^Q START - resume output. c_cc[VSTOP] CSTOP DC3 ^S DC3 ^S STOP - suspend output c_cc[VSUSP] CSUSP SUB ^Z SUB ^Z SUSP - sends a SIGTSTP signal to the foreground process for that terminal. c_cc[VEOL] CEOL NUL \0 NUL \0 EOL - acts as a new-line. Not normally used. c_cc[VREPRINT] CRPRNT DC2 ^R DC2 ^R REPRINT - print a new line then reprint all characters which have not been read. c_cc[VDISCARD] CFLUSH NAK ^U SI ^O DISCARD - causes all output to be discarded until another DISCARD is typed, more input arrives or the condition is cleared by a program. c_cc[VWERASE] '\027' ETB ^W ETB ^W WERASE - erases the preceding word but will not erase beyond the start of a line as delimited by NL, EOF, or EOL2. c_cc[VLNEXT] CEOL2 SYN ^V undefined A Sun feature with no available documentation. c_cc[VEOL2] CEOL2 NUL \0 undefined VEOL2 - another additional line delimiter. c_cc[18] '\0' c_cc[19] '\0' NON CANONICAL MODE In non-canonical mode, input characters are not assembled into lines. Erase and kill processing does not occur. The MIN and TIME values are used to determine how to process the characters received. MIN requires the minimum number of characters that should be received to satisfy a 'read(2)'. TIME is a timer of 0.10 seconds granularity that is used to timeout bursty and short-term data transmissions. Case A. MIN > 0, TIME > 0. TIME serves as an intercharacter timer and is activated after each character is received. If MIN characters are received and before the timer expires, the read returns with the received characters. If TIME expires before MIN characters are received, the characters received so far are returned. If TIME expires at least one character is returned since the timer would not have started until one character was received. In this case, the read sleeps until the MIN and TIME mechanisms are activated by the receipt of the first character. If the number of characters read is less than the number of characters available, the timer is not reactivated and the subsequent read is satisfied immediately. Case B. MIN > 0, TIME = 0. In this case, since the value of TIME is zero, the timer plays no role and only MIN is significant. A pending read is not satisfied until MIN characters are received. A program that uses this case to read a record based terminal I/O may block indefinitely in the read operation. Case C. MIN = 0, TIME > 0. Since MIN = 0, TIME no longer represents an intercharacter timer. It now serves as a read timer that is activated as soon as the read is done. The read is satisfied as soon as a single character is received or the read timer expires. In this case, if the timer expires before a character is received, the read returns with zero characters. Case D. MIN = 0, TIME = 0. For this case, return is immediate. Only those characters available will be returned. Note that MIN and TIME are not symmetric. For example, when MIN > 0, TIME has no effect. However when TIME > 0 and MIN = 0 both MIN and TIME play a role since MIN is satisfied when the first character is received. For Case A, TIME represents an intercharacter time but in Case C, TIME represent a read timer. Cases A and B exist to handle burst mode activities such as file transfer programs. The program can process at least MIN characters at a time. In Case A the timer acts as a safety measure and in Case B the timer is turned off. Cases C and D exist to handle single character, timed transfers. These cases can used to screen based applications that need to know if a character is present in the input queue. Also note that MIN is a minimum number of characters to be returned. If MIN is 10 and 25 characters are in the input queue, a read request for 20 characters will receive 20 characters. IOCTL COMMANDS Form - ioctl( fildes, command, arg ); TCGETS fetches and stores the current terminal parameters to a termios structure pointed to by the argument. TCSETS set the current terminal parameters according to the values in the termios structure pointed to by the argument. TCSETSW same as TCSETS except it doesn't take effect until all the characters queued for output have been transmitted. TCSETSF same as TCSETSW except that all characters queued for input are discarded. TCGETA fetches and stores the current terminal parameters to a termio structure pointed to by the argument. TCSETA set the current terminal parameters according to the values in the termio structure pointed to by the argument. TCSETAW same a TCSET except it doesn't take effect until all the characters queued for output have been transmitted. TCSETAF same as TCSETAW except that all characters queued for input are discarded. TCSBRK wait for output to drain then send a BREAK for 1/4 seconds. TCSBRKP same as TCSBRK except BREAK is measured in tenths of a second. An arg of '0' sends a 1/4 second BREAK. TCXONC perform start/stop control. If arg = 0, suspend output If arg = 1, restart output If arg = 2, suspend input If arg = 3, restart input TCFLSH if arg = 0, flush the input queue if arg = 1, flush the output queue if arg = 2, flush both queues. TIOCGPGRP get the process group ID of the 'pid_t' pointed to by the arg to the foreground processes group ID. TIOCSPGRP associate the process pointed to by 'pid_t' in the arg to the value of the terminal TIOCSID the session ID of the terminal is fetched and stored in the 'pid_t' pointed to by the arg. TIOCGWINSZ the terminal drivers notion of terminal size is stored in the 'winsize' structure pointed to by the arg. TIOCSWINSZ the terminal drivers notion of the terminal size is set to value in the 'winsize' structure pointed to by the arg. TIOCMBIS the argument is a pointer to an 'int' whose value is a mask for the modem control lines to be turned on. TIOCMBIC the argument is a pointer to an 'int' whose value is a mask for the modem control lines to be turned off. TIOCMGET the 'int' pointed to by the arg is set to current state of the modem control lines. TIOCMSET the 'int' pointed to by the arg contains a new set of modem control lines. The bits set are turned on and those unset are turned off. MODEM CONTROL LINES Here are flags which can be set in the 'int arg' pointed to by TIOCMBIS, TIOCMBIC, TIOCMGET and TIOCMSET. They can be 'or'd for the 'arg'. TIOCM_LE line enable TIOCM_DTR data terminal ready TIOCM_RTS request to send TIOCM_ST secondary transmit TIOCM_SR secondary receive TIOCM_CTS clear to send TIOCM_CAR carrier detect TIOCM_RNG ring TIOCM_DSR data set ready THE 'TC*()' COMMANDS Somewhere along the evolutionalary line of Unix, someone concocted the 'tc*' set of commands to replace the 'ioctl(2)' calls. The rationalization given by the POSIX committee is the inconsistent nature of the 'arg's for the 'ioctl(2)' commands. For some commands there is no argument. For others, the 'arg' can be a pointer to 'struct termios', a pointer to an 'int' or simply an 'int'. int tcgetattr( int fildes, struct termios *termios_p ); inr tcsetattr( int fildes, int optional_actions, const struct termios *termios_p ); Where "optional_actions" one of the following: TCSANOW action to occur immediately TCSDRAIN action to occur after all output has been transmitted. TCSAFLUSH action to occur after all output has been transmitted, and all input that has been received, but not read, shall be discarded before the change is made. These are comparable to the TCGETS, TCSETS, TCSETSW and TCSETSF of the 'ioctl(2)' call. int tcsendbreak( int fildes, int duration ); This is similar to "ioctl( fd, TCSBRK, int duration )". The difference is that the "ioctl()" sends a break of 1/4 second while the "tcsendbrak()" sends a break whose duration is incremts of 1/10 seconds depending upon the value of the "duration" argument. int tcdrain( int fildes ); Wait for all data written to the device has been transmitted. There does not appear to be an 'ioctl(2)' command for this operation. It can be simulated with the TCSETSW command. int tcflush( int fildes, int queue_selector ); Where "queue_selector" can be one of: TCIFLUSH - flush received data not yet read. TCOFLUSH - flush data written but not yet transmitted. TCIOFLUSH - both of the above. This is the same as "ioctl(fd , TCFLUSH, int option ); int tcflow( int fildes, int action ); Where "action" is one of: TCOOFF - suspend output. TCOON - restart output. TCIOFF - send STOP character. TCION - send START character. The first two are comparable to: "ioctl( fd, TIOCMSET, ( & ~TIOCM_RTS ))" and "ioctl( fd, TIOCMSET, ( | TIOCM_RTS ))". The second two are the same as "write( fd, "c_cc[XSTOP]", 1 )" and "write( fd, "c_cc[XON]", 1 );". pid_t tcgetpgrp( int fildes ); Get the process group ID of the foreground process group. This is the same as "ioctl( fd, TIOCGPGRP, &pid_t );" int tcsetpgrp( int fildes, pid_t pgrp_id ); Set the process group ID of the process group. PGID's set by a background process may be subsequently changed by the foreground process. This is the same as "ioctl( fd, TIOCSPGRP, &pid_t );" speed_t cfgetospeed( const struct termios *termios_p ); Get the output speed specified in the *termio_p. This is simply speed_t = termios.c_oflg & CBAUD ). int cfsetospeed( struct termios *termios_p, speed_t speed ); Set the output speed in the *termios_p to "speed". This is the same as: termios_p.c_oflag &= ~CBAUD; termios_p.c_oflag |= speed; followed by "ioctl( fd, TCSETS, &termios_p )". speed_t cfgetispeed( const struct termios *termios_p ); int cfsetispeed( struct termios *termios_p, speed_t speed ); Comparable commands to operate on the input speeds where they differ from output speeds. The distinction between input and output speeds is not supported by the UARTS used by Linux.