1Downloaded from http://www.lafn.org/~dave/linux/Serial-Programming-HOWTO.txt 2Seems to be somewhat old, but contains useful bits for getty.c hacking 3============================================================================ 4 5 The Linux Serial Programming HOWTO, Part 1 of 2 6 By Vernon C. Hoxie 7 v2.0 10 September 1999 8 9 This document describes how to program communications with devices 10 over a serial port on a Linux box. 11 ______________________________________________________________________ 12 13 Table of Contents 14 15 1. Copyright 16 17 2. Introduction 18 19 3. Opening 20 21 4. Commands 22 23 5. Changing Baud Rates 24 25 6. Additional Control Calls 26 27 6.1 Sending a "break". 28 6.2 Hardware flow control. 29 6.3 Flushing I/O buffers. 30 31 7. Modem control 32 33 8. Process Groups 34 35 8.1 Sessions 36 8.2 Process Groups 37 8.3 Controlling Terminal 38 8.3.1 Get the foreground group process id. 39 8.3.2 Set the foreground process group id of a terminal. 40 8.3.3 Get process group id. 41 42 9. Lockfiles 43 44 10. Additional Information 45 46 11. Feedback 47 48 ______________________________________________________________________ 49 50 1. Copyright 51 52 The Linux Serial-Programming-HOWTO is copyright (C) 1997 by Vernon 53 Hoxie. Linux HOWTO documents may be reproduced and distributed in 54 whole or in part, in any medium physical or electronic, as long as 55 this copyright notice is retained on all copies. Commercial 56 redistribution is allowed and encouraged; however, the author would 57 like to be notified of any such distributions. 58 59 All translations, derivative works, or aggregate works incorporating 60 this Linux HOWTO document must be covered under this copyright notice. 61 That is, you may not produce a derivative work from this HOWTO and 62 impose additional restrictions on its distribution. 63 64 This version is a complete rewrite of the previous Serial-Programming- 65 HOWTO by Peter H. Baumann, <mailto:Peter.Baumann@dlr.de> 66 67 2. Introduction 68 69 This HOWTO will attempt to give hints about how to write a program 70 which needs to access a serial port. Its principal focus will be on 71 the Linux implementation and what the meaning of the various library 72 functions available. 73 74 Someone asked about which of several sequences of operations was 75 right. There is no absolute right way to accomplish an outcome. The 76 options available are too numerous. If your sequences produces the 77 desired results, then that is the right way for you. Another 78 programmer may select another set of options and get the same results. 79 His method is right for him. 80 81 Neither of these methods may operate properly with some other 82 implementation of UNIX. It is strange that many of the concepts which 83 were implemented in the SYSV version have been dumped. Because UNIX 84 was developed by AT&T and much code has been generated on those 85 concepts, the AT&T version should be the standard to which others 86 should emulate. 87 88 Now the standard is POSIX. 89 90 It was once stated that the popularity of UNIX and C was that they 91 were created by programmers for programmers. Not by scholars who 92 insist on purity of style in deference to results and simplicity of 93 use. Not by committees with people who have diverse personal or 94 proprietary agenda. Now ANSI and POSIX have strayed from those 95 original clear and simply concepts. 96 97 3. Opening 98 99 The various serial devices are opened just as any other file. 100 Although, the fopen(3) command may be used, the plain open(2) is 101 preferred. This call returns the file descriptor which is required 102 for the various commands that configure the interface. 103 104 Open(2) has the format: 105 106 #include <fcntl.h> 107 int open(char *path, int flags, [int mode]); 108 109 In addition to the obvious O_RDWR, O_WRONLY and O_RDONLY, two 110 additional flags are available. These are O_NONBLOCK and O_NOCTTY. 111 Other flags listed in the open(2) manual page are not applicable to 112 serial devices. 113 114 Normally, a serial device opens in "blocking" mode. This means that 115 the open() will not return until the Carrier Detect line from the port 116 is active, e.g. modem, is active. When opened with the O_NONBLOCK 117 flag set, the open() will return immediately regardless of the status 118 of the DCD line. The "blocking" mode also affects the read() call. 119 120 The fcntl(2) command can be used to change the O_NONBLOCK flag anytime 121 after the device has been opened. 122 123 The device driver and the data passing through it are controlled 124 according to settings in the struct termios. This structure is 125 defined in "/usr/include/termios.h". In the Linux tree, further 126 reference is made to "/usr/include/asm/termbits.h". 127 In blocking mode, a read(2) will block until data is available or a 128 signal is received. It is still subject to state of the ICANON flag. 129 130 When the termios.c_lflag ICANON bit is set, input data is collected 131 into strings until a NL, EOF or EOL character is received. You can 132 define these in the termios.c_cc[] array. Also, ERASE and KILL 133 characters will operate on the incoming data before it is delivered to 134 the user. 135 136 In non-canonical mode, incoming data is quantified by use of the 137 c_cc[VMIN and c_cc[VTIME] values in termios.c_cc[]. 138 139 Some programmers use the select() call to detect the completion of a 140 read(). This is not the best way of checking for incoming data. 141 Select() is part of the SOCKETS scheme and too complex for most 142 applications. 143 144 A full explanation of the fields of the termios structure is contained 145 in termios(7) of the Users Manual. A version is included in Part 2 of 146 this HOWTO document. 147 148 4. Commands 149 150 Changes to the struct termios are made by retrieving the current 151 settings, making the desired changes and transmitting the modified 152 structure back to the kernel. 153 154 The historic means of communicating with the kernel was by use of the 155 ioctl(fd, COMMAND, arg) system call. Then the purists in the 156 computer industry decided that this was not genetically consistent. 157 Their argument was that the argument changed its stripes. Sometimes 158 it was an int, sometimes it was a pointer to int and other times it 159 was a pointer to struct termios. Then there were those times it was 160 empty or NULL. These variations are dependent upon the COMMAND. 161 162 As a alternative, the tc* series of functions were concocted. 163 164 These are: 165 166 int tcgetattr(int filedes, struct termios *termios_p); 167 int tcsetattr(int filedes, int optional_actions, 168 const struct termios *termios_p); 169 170 instead of: 171 172 int ioctl(int filedes, int command, 173 struct termios *termios_p); 174 175 where command is TCGETS or one of TCSETS, TCSETSW or TCSETSF. 176 177 The TCSETS command is comparable to the TCSANOW optional_action for 178 the tc* version. These direct the kernel to adopt the changes 179 immediately. Other pairs are: 180 181 command optional_action Meaning 182 TCSETSW TCSADRAIN Change after all output has drained. 183 TCSETSF TCSAFLUSH Change after all output has drained 184 then discard any input characters 185 not read. 186 187 Since the return code from either the ioctl(2) or the tcsetattr(2) 188 commands only indicate that the command was processed by the kernel. 189 These do not indicate whether or not the changes were actually 190 accomplished. Either of these commands should be followed by a call 191 to: 192 193 ioctl(fd, TCGETS, &new_termios); 194 195 or: 196 197 tcgetattr(fd, &new_termios); 198 199 A user function which makes changes to the termios structure should 200 define two struct termios variables. One of these variables should 201 contain the desired configuration. The other should contain a copy of 202 the kernels version. Then after the desired configuration has been 203 sent to the kernel, another call should be made to retrieve the 204 kernels version. Then the two compared. 205 206 Here is an example of how to add RTS/CTS flow control: 207 208 struct termios my_termios; 209 struct termios new_termios; 210 211 tcgetattr(fd, &my_termios); 212 my_termios.c_flag |= CRTSCTS; 213 tcsetattr(fd, TCSANOW, &my_termios); 214 tcgetattr(fd, &new_termios); 215 if (memcmp(my_termios, new_termios, 216 sizeof(my_termios)) != 0) { 217 /* do some error handling */ 218 } 219 220 5. Changing Baud Rates 221 222 With Linux, the baud rate can be changed using a technique similar to 223 add/delete RTS/CTS. 224 225 struct termios my_termios; 226 struct termios new_termios; 227 228 tcgetattr(fd, &my_termios); 229 my_termios.c_flag &= ~CBAUD; 230 my_termios.c_flag |= B19200; 231 tcsetattr(fd, TCSANOW, &my_termios); 232 tcgetattr(fd, &new_termios); 233 if (memcmp(my_termios, new_termios, 234 sizeof(my_termios)) != 0) { 235 /* do some error handling */ 236 } 237 238 POSIX adds another method. They define: 239 240 speed_t cfgetispeed(const struct termios *termios_p); 241 speed_t cfgetospeed(const struct termios *termios_p); 242 243 library calls to extract the current input or output speed from the 244 struct termios pointed to with *termio_p. This is a variable defined 245 in the calling process. In practice, the data contained in this 246 termios, should be obtained by the tcgetattr() call or an ioctl() call 247 using the TCGETS command. 248 249 The companion library calls are: 250 251 int cfsetispeed(struct termios *termios_p, speed_t speed); 252 int cfsetospeed(struct termios *termios_p, speed_t speed); 253 254 which are used to change the value of the baud rate in the locally 255 defined *termios_p. Following either of these calls, either a call to 256 tcsetattr() or ioctl() with one of TCSETS, TCSETSW or TCSETSF as the 257 command to transmit the change to the kernel. 258 259 The cf* commands are preferred for portability. Some weird Unices use 260 a considerably different format of termios. 261 262 Most implementations of Linux use only the input speed for both input 263 and output. These functions are defined in the application program by 264 reference to <termios.h>. In reality, they are in 265 /usr/include/asm/termbits.h. 266 267 6. Additional Control Calls 268 269 6.1. Sending a "break". 270 271 int ioctl(fd, TCSBRK, int arg); 272 int tcsendbreak(fd, int arg); 273 274 Send a break: Here the action differs between the conventional 275 ioctl() call and the POSIX call. For the conventional call, an arg of 276 '0' sets the break control line of the UART for 0.25 seconds. For the 277 POSIX command, the break line is set for arg times 0.1 seconds. 278 279 6.2. Hardware flow control. 280 281 int ioctl(fd, TCXONC, int action); 282 int tcflow(fd, int action); 283 284 The action flags are: 285 286 o TCOOFF 0 suspend output 287 288 o TCOON 1 restart output 289 290 o TCIOFF 2 transmit STOP character to suspend input 291 292 o TCION 3 transmit START character to restart input 293 294 6.3. Flushing I/O buffers. 295 296 int ioctl(fd, TCFLSH, queue_selector); 297 int tcflush(fd, queue_selector); 298 299 The queue_selector flags are: 300 301 o TCIFLUSH 0 flush any data not yet read from the input buffer 302 303 o TCOFLUSH 1 flush any data written to the output buffer but not 304 yet transmitted 305 306 o TCIOFLUSH 2 flush both buffers 307 308 7. Modem control 309 310 The hardware modem control lines can be monitored or modified by the 311 ioctl(2) system call. A set of comparable tc* calls apparently do not 312 exist. The form of this call is: 313 314 int ioctl(fd, COMMAND, (int *)flags); 315 316 The COMMANDS and their action are: 317 318 o TIOCMBIS turn on control lines depending upon which bits are set 319 in flags. 320 321 o TIOCMBIC turn off control lines depending upon which bits are 322 unset in flags. 323 o TIOCMGET the appropriate bits are set in flags according to the 324 current status 325 326 o TIOCMSET the state of the UART is changed according to which bits 327 are set/unset in 'flags' 328 329 The bit pattern of flags refer to the following control lines: 330 331 o TIOCM_LE Line enable 332 333 o TIOCM_DTR Data Terminal Ready 334 335 o TIOCM_RTS Request to send 336 337 o TIOCM_ST Secondary transmit 338 339 o TIOCM_SR Secondary receive 340 341 o TIOCM_CTS Clear to send 342 343 o TIOCM_CAR Carrier detect 344 345 o TIOCM_RNG Ring 346 347 o TIOCM_DSR Data set ready 348 349 It should be noted that some of these bits are controlled by the modem 350 and the UART cannot change them but their status can be sensed by 351 TIOCMGET. Also, most Personal Computers do not provide hardware for 352 secondary transmit and receive. 353 354 There are also a pair of ioctl() to monitor these lines. They are 355 undocumented as far as I have learned. The commands are TIOCMIWAIT 356 and TCIOGICOUNT. They also differ between versions of the Linux 357 kernel. 358 359 See the lines.c file in my "serial_suite" for an example of how these 360 can be used see <ftp://scicom.alphacd.com/pub/linux/serial_suite> 361 362 8. Process Groups 363 364 8.1. Sessions 365 366 8.2. Process Groups 367 368 Any newly created process inherits the Process Group of its creator. 369 The Process Group leader has the same PID as PGID. 370 371 8.3. Controlling Terminal 372 373 There are a series of ioctl(2) and tc*(2) calls which can be used to 374 monitor or to change the process group to which the device is 375 attached. 376 377 8.3.1. Get the foreground group process id. 378 379 If there is no foreground group, a number not representing an existing 380 process group is returned. On error, a -1 is returned and errno is 381 set. 382 383 int ioctl(fd, TIOCGPGRP, (pid_t *)pid); 384 int tcgetpgrp(fd, (pid_t *)pid); 385 386 8.3.2. Set the foreground process group id of a terminal. 387 388 The fd must be the controlling terminal and be associated with the 389 session of the calling process. 390 391 int ioctl(fd, TIOCSPGRP, (pid_t *)pid); 392 int tcsetpgrp(fd, (pid_t *)pid); 393 394 8.3.3. Get process group id. 395 396 int ioctl(fd, TIOCGPGRP, &(pid_t)pid); 397 int tcgetpgrp(fd, &(pid_t)pid); 398 399 9. Lockfiles 400 401 Any process which accesses a serial device should first check for the 402 existence of lock file for the desired device. If such a lock lock 403 file exists, this means that the device may be in use by another 404 process. 405 406 Check my "libdevlocks-x.x.tgz" at 407 <ftp://scicom.alphacdc.com/pub/linux> for an example of how these lock 408 files should be utilized. 409 410 10. Additional Information 411 412 Check out my "serial_suite.tgz" for more information about programming 413 the serial ports at <mailto:vern@zebra.alphacdc.com>. There some 414 examples and some blurbs about setting up modems and comments about 415 some general considerations. 416 417 11. Feedback 418 419 Please send me any corrections, questions, comments, suggestions, or 420 additional material. I would like to improve this HOWTO! Tell me 421 exactly what you don't understand, or what could be clearer. You can 422 reach me at <mailto:vern@zebra.alphacdc.com> via email. Please 423 include the version number of the Serial-Programming-HOWTO when 424 writing. 425