move documentation to docs/

1 files changed, 0 insertions, 424 deletions

diff --git a/loginutils/Serial-Programming-HOWTO.txt b/loginutils/Serial-Programming-HOWTO.txt
deleted file mode 100644
index 0dfc8aa..0000000
--- a/loginutils/Serial-Programming-HOWTO.txt
+++ /dev/null
@@ -1,424 +0,0 @@
-Downloaded from http://www.lafn.org/~dave/linux/Serial-Programming-HOWTO.txt
-Seems to be somewhat old, but contains useful bits for getty.c hacking
-============================================================================
-
-  The Linux Serial Programming HOWTO, Part 1 of 2
-  By Vernon C. Hoxie
-  v2.0 10 September 1999
-
-  This document describes how to program communications with devices
-  over a serial port on a Linux box.
-  ______________________________________________________________________
-
-  Table of Contents
-
-  1. Copyright
-
-  2. Introduction
-
-  3. Opening
-
-  4. Commands
-
-  5. Changing Baud Rates
-
-  6. Additional Control Calls
-
-     6.1 Sending a "break".
-     6.2 Hardware flow control.
-     6.3 Flushing I/O buffers.
-
-  7. Modem control
-
-  8. Process Groups
-
-     8.1 Sessions
-     8.2 Process Groups
-     8.3 Controlling Terminal
-        8.3.1 Get the foreground group process id.
-        8.3.2 Set the foreground process group id of a terminal.
-        8.3.3 Get process group id.
-
-  9. Lockfiles
-
-  10. Additional Information
-
-  11. Feedback
-
-  ______________________________________________________________________
-
-  1.  Copyright
-
-  The Linux Serial-Programming-HOWTO is copyright (C) 1997 by Vernon
-  Hoxie.  Linux HOWTO documents may be reproduced and distributed in
-  whole or in part, in any medium physical or electronic, as long as
-  this copyright notice is retained on all copies. Commercial
-  redistribution is allowed and encouraged; however, the author would
-  like to be notified of any such distributions.
-
-  All translations, derivative works, or aggregate works incorporating
-  this Linux HOWTO document must be covered under this copyright notice.
-  That is, you may not produce a derivative work from this HOWTO and
-  impose additional restrictions on its distribution.
-
-  This version is a complete rewrite of the previous Serial-Programming-
-  HOWTO  by Peter H. Baumann,  <mailto:Peter.Baumann@dlr.de>
-
-  2.  Introduction
-
-  This HOWTO will attempt to give hints about how to write a program
-  which needs to access a serial port.  Its principal focus will be on
-  the Linux implementation and what the meaning of the various library
-  functions available.
-
-  Someone asked about which of several sequences of operations was
-  right.  There is no absolute right way to accomplish an outcome.  The
-  options available are too numerous.  If your sequences produces the
-  desired results, then that is the right way for you.  Another
-  programmer may select another set of options and get the same results.
-  His method is right for him.
-
-  Neither of these methods may operate properly with some other
-  implementation of UNIX.  It is strange that many of the concepts which
-  were implemented in the SYSV version have been dumped.  Because UNIX
-  was developed by AT&T and much code has been generated on those
-  concepts, the AT&T version should be the standard to which others
-  should emulate.
-
-  Now the standard is POSIX.
-
-  It was once stated that the popularity of UNIX and C was that they
-  were created by programmers for programmers.  Not by scholars who
-  insist on purity of style in deference to results and simplicity of
-  use.  Not by committees with people who have diverse personal or
-  proprietary agenda.  Now ANSI and POSIX have strayed from those
-  original clear and simply concepts.
-
-  3.  Opening
-
-  The various serial devices are opened just as any other file.
-  Although, the fopen(3) command may be used, the plain open(2) is
-  preferred.  This call returns the file descriptor which is required
-  for the various commands that configure the interface.
-
-  Open(2) has the format:
-
-       #include <fcntl.h>
-       int open(char *path, int flags, [int mode]);
-
-  In addition to the obvious O_RDWR, O_WRONLY and O_RDONLY, two
-  additional flags are available.  These are O_NONBLOCK and O_NOCTTY.
-  Other flags listed in the open(2) manual page are not applicable to
-  serial devices.
-
-  Normally, a serial device opens in "blocking" mode.  This means that
-  the open() will not return until the Carrier Detect line from the port
-  is active, e.g. modem, is active.  When opened with the O_NONBLOCK
-  flag set, the open() will return immediately regardless of the status
-  of the DCD line.  The "blocking" mode also affects the read() call.
-
-  The fcntl(2) command can be used to change the O_NONBLOCK flag anytime
-  after the device has been opened.
-
-  The device driver and the data passing through it are controlled
-  according to settings in the struct termios.  This structure is
-  defined in "/usr/include/termios.h".  In the Linux tree, further
-  reference is made to "/usr/include/asm/termbits.h".
-  In blocking mode, a read(2) will block until data is available or a
-  signal is received.  It is still subject to state of the ICANON flag.
-
-  When the termios.c_lflag ICANON bit is set, input data is collected
-  into strings until a NL, EOF or EOL character is received.  You can
-  define these in the termios.c_cc[] array.  Also, ERASE and KILL
-  characters will operate on the incoming data before it is delivered to
-  the user.
-
-  In non-canonical mode, incoming data is quanitified by use of the
-  c_cc[VMIN and c_cc[VTIME] values in termios.c_cc[].
-
-  Some programmers use the select() call to detect the completion of a
-  read().  This is not the best way of checking for incoming data.
-  Select() is part of the SOCKETS scheme and too complex for most
-  applications.
-
-  A full explanation of the fields of the termios structure is contained
-  in termios(7) of the Users Manual.  A version is included in Part 2 of
-  this HOWTO document.
-
-  4.  Commands
-
-  Changes to the struct termios are made by retrieving the current
-  settings, making the desired changes and transmitting the modified
-  structure back to the kernel.
-
-  The historic means of communicating with the kernel was by use of the
-  ioctl(fd, COMMAND, arg) system call.  Then the purists in the
-  computer industry decided that this was not genetically consistent.
-  Their argument was that the argument changed its stripes.  Sometimes
-  it was an int, sometimes it was a pointer to int and other times it
-  was a pointer to struct termios.  Then there were those times it was
-  empty or NULL.  These variations are dependent upon the COMMAND.
-
-  As a alternative, the tc* series of functions were concocted.
-
-  These are:
-
-       int tcgetattr(int filedes, struct termios *termios_p);
-       int tcsetattr(int filedes, int optional_actions,
-                     const struct termios *termios_p);
-
-  instead of:
-
-       int ioctl(int filedes, int command,
-                 struct termios *termios_p);
-
-  where command is TCGETS or one of TCSETS, TCSETSW or TCSETSF.
-
-  The TCSETS command is comparable to the TCSANOW optional_action for
-  the tc* version.  These direct the kernel to adopt the changes
-  immediately.  Other pairs are:
-
-    command   optional_action   Meaning
-    TCSETSW   TCSADRAIN         Change after all output has drained.
-    TCSETSF   TCSAFLUSH         Change after all output has drained
-                                then discard any input characters
-                                not read.
-
-  Since the return code from either the ioctl(2) or the tcsetattr(2)
-  commands only indicate that the command was processed by the kernel.
-  These do not indicate whether or not the changes were actually
-  accomplished.  Either of these commands should be followed by a call
-  to:
-
-       ioctl(fd, TCGETS, &new_termios);
-
-  or:
-
-       tcgetattr(fd, &new_termios);
-
-  A user function which makes changes to the termios structure should
-  define two struct termios variables.  One of these variables should
-  contain the desired configuration.  The other should contain a copy of
-  the kernels version.  Then after the desired configuration has been
-  sent to the kernel, another call should be made to retrieve the
-  kernels version.  Then the two compared.
-
-  Here is an example of how to add RTS/CTS flow control:
-
-       struct termios my_termios;
-       struct termios new_termios;
-
-       tcgetattr(fd, &my_termios);
-       my_termios.c_flag |= CRTSCTS;
-       tcsetattr(fd, TCSANOW, &my_termios);
-       tcgetattr(fd, &new_termios);
-       if (memcmp(my_termios, new_termios,
-            sizeof(my_termios)) != 0) {
-           /* do some error handling */
-       }
-
-  5.  Changing Baud Rates
-
-  With Linux, the baud rate can be changed using a technique similar to
-  add/delete RTS/CTS.
-
-  struct termios my_termios;
-  struct termios new_termios;
-
-  tcgetattr(fd, &my_termios);
-  my_termios.c_flag &= ~CBAUD;
-  my_termios.c_flag |= B19200;
-  tcsetattr(fd, TCSANOW, &my_termios);
-  tcgetattr(fd, &new_termios);
-  if (memcmp(my_termios, new_termios,
-       sizeof(my_termios)) != 0) {
-      /* do some error handling */
-  }
-
-  POSIX adds another method.  They define:
-
-       speed_t cfgetispeed(const struct termios *termios_p);
-       speed_t cfgetospeed(const struct termios *termios_p);
-
-  library calls to extract the current input or output speed from the
-  struct termios pointed to with *termio_p.  This is a variable defined
-  in the calling process.  In practice, the data contained in this
-  termios, should be obtained by the tcgetattr() call or an ioctl() call
-  using the TCGETS command.
-
-  The companion library calls are:
-
-       int cfsetispeed(struct termios *termios_p, speed_t speed);
-       int cfsetospeed(struct termios *termios_p, speed_t speed);
-
-  which are used to change the value of the baud rate in the locally
-  defined *termios_p.  Following either of these calls, either a call to
-  tcsetattr() or ioctl() with one of TCSETS, TCSETSW or TCSETSF as the
-  command to transmit the change to the kernel.
-
-  The cf* commands are preferred for portability.  Some weird Unices use
-  a considerably different format of termios.
-
-  Most implementations of Linux use only the input speed for both input
-  and output.  These functions are defined in the application program by
-  reference to <termios.h>.  In reality, they are in
-  /usr/include/asm/termbits.h.
-
-  6.  Additional Control Calls
-
-  6.1.  Sending a "break".
-
-       int ioctl(fd, TCSBRK, int arg);
-       int tcsendbreak(fd, int arg);
-
-  Send a break:  Here the action differs between the conventional
-  ioctl() call and the POSIX call.  For the conventional call, an arg of
-  '0' sets the break control line of the UART for 0.25 seconds.  For the
-  POSIX command, the break line is set for arg times 0.1 seconds.
-
-  6.2.  Hardware flow control.
-
-       int ioctl(fd, TCXONC, int action);
-       int tcflow(fd, int action);
-
-  The action flags are:
-
-  o  TCOOFF  0  suspend output
-
-  o  TCOON   1  restart output
-
-  o  TCIOFF  2  transmit STOP character to suspend input
-
-  o  TCION   3  transmit START character to restart input
-
-  6.3.  Flushing I/O buffers.
-
-       int ioctl(fd, TCFLSH, queue_selector);
-       int tcflush(fd, queue_selector);
-
-  The queue_selector flags are:
-
-  o  TCIFLUSH  0  flush any data not yet read from the input buffer
-
-  o  TCOFLUSH  1  flush any data written to the output buffer but not
-     yet transmitted
-
-  o  TCIOFLUSH 2  flush both buffers
-
-  7.  Modem control
-
-  The hardware modem control lines can be monitored or modified by the
-  ioctl(2) system call.  A set of comparable tc* calls apparently do not
-  exist.  The form of this call is:
-
-       int ioctl(fd, COMMAND, (int *)flags);
-
-  The COMMANDS and their action are:
-
-  o  TIOCMBIS  turn on control lines depending upon which bits are set
-     in flags.
-
-  o  TIOCMBIC  turn off control lines depending upon which bits are
-     unset in flags.
-  o  TIOCMGET  the appropriate bits are set in flags according to the
-     current status
-
-  o  TIOCMSET  the state of the UART is changed according to which bits
-     are set/unset in 'flags'
-
-     The bit pattern of flags refer to the following control lines:
-
-  o  TIOCM_LE      Line enable
-
-  o  TIOCM_DTR     Data Terminal Ready
-
-  o  TIOCM_RTS     Request to send
-
-  o  TIOCM_ST      Secondary transmit
-
-  o  TIOCM_SR      Secondary receive
-
-  o  TIOCM_CTS     Clear to send
-
-  o  TIOCM_CAR     Carrier detect
-
-  o  TIOCM_RNG     Ring
-
-  o  TIOCM_DSR     Data set ready
-
-  It should be noted that some of these bits are controlled by the modem
-  and the UART cannot change them but their status can be sensed by
-  TIOCMGET.  Also, most Personal Computers do not provide hardware for
-  secondary transmit and receive.
-
-  There are also a pair of ioctl() to monitor these lines.  They are
-  undocumented as far as I have learned.  The commands are TIOCMIWAIT
-  and TCIOGICOUNT.  They also differ between versions of the Linux
-  kernel.
-
-  See the lines.c file in my "serial_suite" for an example of how these
-  can be used see  <ftp://scicom.alphacd.com/pub/linux/serial_suite>
-
-  8.  Process Groups
-
-  8.1.  Sessions
-
-  8.2.  Process Groups
-
-  Any newly created process inherits the Process Group of its creator.
-  The Process Group leader has the same PID as PGID.
-
-  8.3.  Controlling Terminal
-
-  There are a series of ioctl(2) and tc*(2) calls which can be used to
-  monitor or to change the process group to which the device is
-  attached.
-
-  8.3.1.  Get the foreground group process id.
-
-  If there is no foreground group, a number not representing an existing
-  process group is returned.  On error, a -1 is returned and errno is
-  set.
-
-       int ioctl(fd, TIOCGPGRP, (pid_t *)pid);
-       int tcgetpgrp(fd, (pid_t *)pid);
-
-  8.3.2.  Set the foreground process group id of a terminal.
-
-  The fd must be the controlling terminal and be associated with the
-  session of the calling process.
-
-       int ioctl(fd, TIOCSPGRP, (pid_t *)pid);
-       int tcsetpgrp(fd, (pid_t *)pid);
-
-  8.3.3.  Get process group id.
-
-       int ioctl(fd, TIOCGPGRP, &(pid_t)pid);
-       int tcgetpgrp(fd, &(pid_t)pid);
-
-  9.  Lockfiles
-
-  Any process which accesses a serial device should first check for the
-  existence of lock file for the desired device.  If such a lock lock
-  file exists, this means that the device may be in use by another
-  process.
-
-  Check my "libdevlocks-x.x.tgz" at
-  <ftp://scicom.alphacdc.com/pub/linux> for an example of how these lock
-  files should be utilized.
-
-  10.  Additional Information
-
-  Check out my "serial_suite.tgz" for more information about programming
-  the serial ports at   <mailto:vern@zebra.alphacdc.com>.  There some
-  examples and some blurbs about setting up modems and comments about
-  some general considerations.
-
-  11.  Feedback
-
-  Please send me any corrections, questions, comments, suggestions, or
-  additional material. I would like to improve this HOWTO!  Tell me
-  exactly what you don't understand, or what could be clearer.  You can
-  reach me at  <mailto:vern@zebra.alphacdc.com> via email.  Please
-  include the version number of the Serial-Programming-HOWTO when
-  writing.