Made cosmetic changes and documented routines in file.

1 files changed, 151 insertions, 53 deletions

diff --git a/doc/new_chapters/device.t b/doc/new_chapters/device.t
index a1b562bc47..ae71aa7170 100644
--- a/doc/new_chapters/device.t
+++ b/doc/new_chapters/device.t
@@ -10,45 +10,52 @@
 
 @section Introduction
 
-The 
-device- and class- specific functions manager is ...
+The device- and class- specific functions manager is ...
 
-The directives provided by the device- and class- specific functions manager are:
+The directives provided by the device- and class- specific functions
+manager are:
 
 @itemize @bullet
-@item @code{cfgetispeed} - 
-@item @code{cfgetospeed} - 
-@item @code{cfsetispeed} - 
-@item @code{cfsetospeed} - 
-@item @code{tcgetattr} - 
-@item @code{tcsetattr} - 
-@item @code{tcsendbreak} - 
-@item @code{tcdrain} - 
-@item @code{tcflush} - 
-@item @code{tcflow} - 
-@item @code{tcgetpgrp} - 
-@item @code{tcsetpgrp} - 
+@item @code{cfgetispeed} - Reads terminal input baud rate
+@item @code{cfgetospeed} - Reads terminal output baud rate
+@item @code{cfsetispeed} - Sets terminal input baud rate
+@item @code{cfsetospeed} - Set terminal output baud rate
+@item @code{tcgetattr} - Gets terminal attributes
+@item @code{tcsetattr} - Set terminal attributes
+@item @code{tcsendbreak} - Sends a break to a terminal
+@item @code{tcdrain} - Waits for all output to be transmitted to the terminal
+@item @code{tcflush} - Discards terminal data
+@item @code{tcflow} - Suspends/restarts terminal output
+@item @code{tcgetpgrp} - Gets foreground process group ID
+@item @code{tcsetpgrp} - Sets foreground process group ID
 @end itemize
 
 @section Background
 
+There is currently no text in this section.
+
 @section Operations
 
+There is currently no text in this section.
+
 @section Directives
 
-This section details the device- and class- specific functions manager's directives.
-A subsection is dedicated to each of this manager's directives
+This section details the device- and class- specific functions manager's
+directives.  A subsection is dedicated to each of this manager's directives
 and describes the calling sequence, related constants, usage,
 and status codes.
 
 @page
-@subsection cfgetispeed - 
+@subsection cfgetispeed - Reads terminal input baud rate
 
 @subheading CALLING SEQUENCE:
 
 @ifset is-C
 @example
+#include <termios.h>
+
 int cfgetispeed(
+  const struct termios *p
 );
 @end example
 @end ifset
@@ -58,24 +65,34 @@ int cfgetispeed(
 
 @subheading STATUS CODES:
 
-@table @b
-@item E
-The
-
-@end table
+The @code{cfgetispeed()} function returns a code for baud rate.  
 
 @subheading DESCRIPTION:
 
+The @code{cfsetispeed()} function stores a code for the terminal speed 
+stored in a struct termios.  The codes are defined in @code{<termios.h>} 
+by the macros BO, B50, B75, B110, B134, B150, B200, B300, B600, B1200,
+B1800, B2400, B4800, B9600, B19200, and B38400.
+
+The @code{cfsetispeed()} function does not do anything to the hardware.
+It merely stores a value for use by @code{tcsetattr()}.
+
 @subheading NOTES:
 
+Baud rates are defined by symbols, such as B110, B1200, B2400.  The actual
+number returned for any given speed may change from system to system.
+
 @page
-@subsection cfgetospeed - 
+@subsection cfgetospeed - Reads terminal output baud rate
 
 @subheading CALLING SEQUENCE:
 
 @ifset is-C
 @example
-int cfgetospeed(
+#include <termios.h>
+
+int cfgetospeed( 
+  const struct termios *p
 );
 @end example
 @end ifset
@@ -85,24 +102,35 @@ int cfgetospeed(
 
 @subheading STATUS CODES:
 
-@table @b
-@item E
-The
-
-@end table
+The @code{cfgetospeed()} function returns the termios code for the baud rate.
 
 @subheading DESCRIPTION:
 
+The @code{cfgetospeed()} function returns a code for the terminal speed
+stored in a @code{struct termios}.  The codes are defined in @code{<termios.h>}
+by the macros BO, B50, B75, B110, B134, B150, B200, B300, B600, B1200, B1800,
+B2400, B4800, B9600, B19200, and B38400.
+
+The @code{cfgetospeed()} function does not do anything to the hardware.
+It merely returns the value stored by a previous call to @code{tcgetattr()}.
+
 @subheading NOTES:
 
+Baud reates are defined by symbols, such as B110, B1200, B2400.  The actual
+number returned for any given speed may change from system to system.
+
 @page
-@subsection cfsetispeed - 
+@subsection cfsetispeed - Sets terminal input baud rate
 
 @subheading CALLING SEQUENCE:
 
 @ifset is-C
 @example
+#include <termios.h>
+
 int cfsetispeed(
+  struct termios *p,
+  speed_t         speed
 );
 @end example
 @end ifset
@@ -112,24 +140,34 @@ int cfsetispeed(
 
 @subheading STATUS CODES:
 
-@table @b
-@item E
-The
-
-@end table
+The @code{cfsetispeed()} function returns a zero when successful and 
+returns -1 when an error occurs.  
 
 @subheading DESCRIPTION:
 
+The @code{cfsetispeed()} function stores a code for the terminal speed
+stored in a struct termios.  The codes are defined in @code{<termios.h>}
+by the macros B0, B50, B75, B110, B134, B150, B200, B300, B600, B1200, 
+B1800, B2400, B4800, B9600, B19200, and B38400.
+
 @subheading NOTES:
 
+This function merely stores a value in the @code{termios} structure.  It
+does not change the terminal speed until a @code{tcsetattr()} is done. 
+It does not detect impossible terminal speeds.
+
 @page
-@subsection cfsetospeed - 
+@subsection cfsetospeed - Sets terminal output baud rate 
 
 @subheading CALLING SEQUENCE:
 
 @ifset is-C
 @example
+#include <termios.h>
+
 int cfsetospeed(
+  struct termios *p,
+  speed_t         speed
 );
 @end example
 @end ifset
@@ -139,24 +177,39 @@ int cfsetospeed(
 
 @subheading STATUS CODES:
 
-@table @b
-@item E
-The
+The @code{cfsetospeed()} function returns a zero when successful and 
+returns -1 when an error occurs.  
 
-@end table
 
 @subheading DESCRIPTION:
 
+The @code{cfsetospeed()} function stores a code for the terminal speed stored 
+in a struct @code{termios}.  The codes are defiined in @code{<termios.h>} by the
+macros B0, B50, B75, B110, B134, B150, B200, B300, B600, B1200, B1800, B2400,
+B4800, B9600, B19200, and B38400.
+
+The @code{cfsetospeed()} function does not do anything to the hardware.  It
+merely stores a value for use by @code{tcsetattr()}.
+
 @subheading NOTES:
 
+This function merely stores a value in the @code{termios} structure. 
+It does not change the terminal speed until a @code{tcsetattr()} is done.
+It does not detect impossible terminal speeds.
+
 @page
-@subsection tcgetattr - 
+@subsection tcgetattr - Gets terminal attributes
 
 @subheading CALLING SEQUENCE:
 
 @ifset is-C
 @example
+#include <termios.h>
+#include <unistd.h>
+
 int tcgetattr(
+  int fildes,
+  struct termios *p
 );
 @end example
 @end ifset
@@ -167,23 +220,37 @@ int tcgetattr(
 @subheading STATUS CODES:
 
 @table @b
-@item E
-The
+@item EBADF
+Invalid file descriptor
 
+@item ENOOTY
+Terminal control function attempted for a file that is not a terminal.
 @end table
 
 @subheading DESCRIPTION:
 
+The @code{tcgetattr()} gets the parameters associated with the terminal
+referred to by @code{fildes} and stores them into the @code{termios()}
+structure pointed to by @code{termios_p}.
+
 @subheading NOTES:
 
+NONE
+
 @page
-@subsection tcsetattr - 
+@subsection tcsetattr - Set terminal attributes
 
 @subheading CALLING SEQUENCE:
 
 @ifset is-C
 @example
+#include <termios.h>
+#include <unistd.h>
+
 int tcsetattr(
+  int                   fildes,
+  int                   options,
+  const struct termios *tp
 );
 @end example
 @end ifset
@@ -204,7 +271,7 @@ The
 @subheading NOTES:
 
 @page
-@subsection tcsendbreak - 
+@subsection tcsendbreak - Sends a break to a terminal 
 
 @subheading CALLING SEQUENCE:
 
@@ -230,14 +297,21 @@ The
 
 @subheading NOTES:
 
+This routine is not currently supported by RTEMS but could be 
+in a future version.
+
 @page
-@subsection tcdrain - 
+@subsection tcdrain - Waits for all output to be transmitted to the terminal.
 
 @subheading CALLING SEQUENCE:
 
 @ifset is-C
 @example
+#include <termios.h>
+#include <unistd.h>
+
 int tcdrain(
+  int fildes
 );
 @end example
 @end ifset
@@ -248,17 +322,28 @@ int tcdrain(
 @subheading STATUS CODES:
 
 @table @b
-@item E
-The
+@item EBADF
+Invalid file descriptor
+
+@item EINTR
+Function was interrupted by a signal
+
+@item ENOTTY
+Terminal control function attempted for a file that is not a terminal.
 
 @end table
 
 @subheading DESCRIPTION:
 
+The @code{tcdrain()} function waits until all output written to 
+@code{fildes} has been transmitted.
+
 @subheading NOTES:
 
+NONE
+
 @page
-@subsection tcflush - 
+@subsection tcflush - Discards terminal data 
 
 @subheading CALLING SEQUENCE:
 
@@ -284,8 +369,11 @@ The
 
 @subheading NOTES:
 
+This routine is not currently supported by RTEMS but could be 
+in a future version.
+
 @page
-@subsection tcflow - 
+@subsection tcflow - Suspends/restarts terminal output.
 
 @subheading CALLING SEQUENCE:
 
@@ -311,8 +399,11 @@ The
 
 @subheading NOTES:
 
+This routine is not currently supported by RTEMS but could be 
+in a future version.
+
 @page
-@subsection tcgetpgrp - 
+@subsection tcgetpgrp - Gets foreground process group ID
 
 @subheading CALLING SEQUENCE:
 
@@ -338,8 +429,11 @@ The
 
 @subheading NOTES:
 
+This routine is not currently supported by RTEMS but could be 
+in a future version.
+
 @page
-@subsection tcsetpgrp - 
+@subsection tcsetpgrp - Sets foreground process group ID
 
 @subheading CALLING SEQUENCE:
 
@@ -365,3 +459,7 @@ The
 
 @subheading NOTES:
 
+This routine is not currently supported by RTEMS but could be 
+in a future version.
+
+