hush: add leak detector helper; fix/add tests for it
[oweals/busybox.git] / docs / Serial-Programming-HOWTO.txt
1 Downloaded from http://www.lafn.org/~dave/linux/Serial-Programming-HOWTO.txt
2 Seems 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 quanitified 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.