Misc changes suggested by mib.

5 files changed, 199 insertions, 133 deletions

diff --git a/manual/job.texi b/manual/job.texi
index 12bbef8..7066bd7 100644
--- a/manual/job.texi
+++ b/manual/job.texi
@@ -88,8 +88,9 @@ that are executing without such access to the terminal are called
 @dfn{background jobs}.
 
 @cindex stopped job
-If a background job needs to read from or write to its controlling
-terminal, it is @dfn{stopped} by the terminal driver.  The user can stop
+If a background job needs to read from its controlling
+terminal, it is @dfn{stopped} by the terminal driver; if the
+@code{TOSTOP} mode is set, likewise for writing.  The user can stop
 a foreground job by typing the SUSP character (@pxref{Special
 Characters}) and a program can stop any job by sending it a
 @code{SIGSTOP} signal.  It's the responsibility of the shell to notice
@@ -194,9 +195,7 @@ the old session are still trying to use that terminal.
 
 To prevent problems, process groups that continue running even after the
 session leader has terminated are marked as @dfn{orphaned process
-groups}.  Processes in an orphaned process group cannot read from or
-write to the controlling terminal.  Attempts to do so will fail with an
-@code{EIO} error.
+groups}.
 
 When a process group becomes an orphan, its processes are sent a
 @code{SIGHUP} signal.  Ordinarily, this causes the processes to
@@ -1029,8 +1028,11 @@ You can use the @code{ctermid} function to get a file name that you can
 use to open the controlling terminal.  In the GNU library, it returns
 the same string all the time: @code{"/dev/tty"}.  That is a special
 ``magic'' file name that refers to the controlling terminal of the
-current process (if it has one).  The function @code{ctermid} is
-declared in the header file @file{stdio.h}.
+current process (if it has one).  To find the name of the specific
+terminal device, use @code{ttyname}; @pxref{Is it a Terminal}.
+
+The function @code{ctermid} is declared in the header file
+@file{stdio.h}.
 @pindex stdio.h
 
 @comment stdio.h
diff --git a/manual/signal.texi b/manual/signal.texi
index 575fbdc..eff0f3c 100644
--- a/manual/signal.texi
+++ b/manual/signal.texi
@@ -84,6 +84,11 @@ A call to @code{kill} or @code{raise} by the same process.
 @item
 A call to @code{kill} from another process.  Signals are a limited but
 useful form of interprocess communication.
+
+@item
+An attempt to perform an I/O operation that cannot be done.  Examples
+are reading from a pipe that has no writer (@pxref{Pipes}), and reading
+or writing to a terminal in certain situations (@pxref{Job Control}).
 @end itemize
 
 Each of these kinds of events (excepting explicit calls to @code{kill}
@@ -117,9 +122,12 @@ An explicit request means the use of a library function such as
 
 Signals may be generated @dfn{synchronously} or @dfn{asynchronously}.  A
 synchronous signal pertains to a specific action in the program, and is
-delivered (unless blocked) during that action.  Errors generate signals
-synchronously, and so do explicit requests by a process to generate a
-signal for that same process.
+delivered (unless blocked) during that action.  Most errors generate
+signals synchronously, and so do explicit requests by a process to
+generate a signal for that same process.  On some machines, certain
+kinds of hardware errors (usually floating-point exceptions) are not
+reported completely synchronously, but may arrive a few instructions
+later.
 
 Asynchronous signals are generated by events outside the control of the
 process that receives them.  These signals arrive at unpredictable times
@@ -362,7 +370,7 @@ Floating underflow fault.
 @comment ANSI
 @deftypevr Macro int SIGILL
 The name of this signal is derived from ``illegal instruction''; it
-means your program is trying to execute garbage or a privileged
+usually means your program is trying to execute garbage or a privileged
 instruction.  Since the C compiler generates only valid instructions,
 @code{SIGILL} typically indicates that the executable file is corrupted,
 or that you are trying to execute data.  Some common ways of getting
@@ -371,6 +379,9 @@ pointer to a function was expected, or by writing past the end of an
 automatic array (or similar problems with pointers to automatic
 variables) and corrupting other data on the stack such as the return
 address of a stack frame.
+
+@code{SIGILL} can also be generated when the stack overflows, or when
+the system has trouble running the handler for a signal.
 @end deftypevr
 @cindex illegal instruction
 
@@ -379,23 +390,16 @@ address of a stack frame.
 @deftypevr Macro int SIGSEGV
 @cindex segmentation violation
 This signal is generated when a program tries to read or write outside
-the memory that is allocated for it.  (Actually, the signals only occur
-when the program goes far enough outside to be detected by the system's
-memory protection mechanism.)  The name is an abbreviation for
-``segmentation violation''.
-
-The most common way of getting a @code{SIGSEGV} condition is by
-dereferencing a null or uninitialized pointer.  A null pointer refers to
-the address 0, and most operating systems make sure this address is
-always invalid precisely so that dereferencing a null pointer will cause
-@code{SIGSEGV}.  (Some operating systems place valid memory at address
-0, and dereferencing a null pointer does not cause a signal on these
-systems.)  As for uninitialized pointer variables, they contain random
-addresses which may or may not be valid.
-
-Another common way of getting into a @code{SIGSEGV} situation is when
-you use a pointer to step through an array, but fail to check for the
-end of the array.
+the memory that is allocated for it, or to write memory that can only be
+read.  (Actually, the signals only occur when the program goes far
+enough outside to be detected by the system's memory protection
+mechanism.)  The name is an abbreviation for ``segmentation violation''.
+
+Common ways of getting a @code{SIGSEGV} condition include dereferencing
+a null or uninitialized pointer, or when you use a pointer to step
+through an array, but fail to check for the end of the array.  It varies
+among systems whether dereferencing a null pointer generates
+@code{SIGSEGV} or @code{SIGBUS}.
 @end deftypevr
 
 @comment signal.h
@@ -443,19 +447,16 @@ The (obvious) default action for all of these signals is to cause the
 process to terminate.
 
 @comment signal.h
-@comment POSIX.1
-@deftypevr Macro int SIGHUP
-@cindex hangup signal
-The @code{SIGHUP} (``hang-up'') signal is used to report that the user's
-terminal is disconnected, perhaps because a network or telephone
-connection was broken.  For more information about this, see @ref{Control
-Modes}.
+@comment ANSI
+@deftypevr Macro int SIGTERM
+@cindex termination signal
+The @code{SIGTERM} signal is a generic signal used to cause program
+termination.  Unlike @code{SIGKILL}, this signal can be blocked,
+handled, and ignored.  It is the normal way to politely ask a program to
+terminate.
 
-This signal is also used to report the termination of the controlling
-process on a terminal to jobs associated with that session; this
-termination effectively disconnects all processes in the session from
-the controlling terminal.  For more information, see @ref{Termination
-Internals}.
+The shell command @code{kill} generates @code{SIGTERM} by default.
+@pindex kill
 @end deftypevr
 
 @comment signal.h
@@ -491,35 +492,43 @@ examine them in conjunction with the core dump.
 @end deftypevr
 
 @comment signal.h
-@comment ANSI
-@deftypevr Macro int SIGTERM
-@cindex termination signal
-The @code{SIGTERM} signal is a generic signal used to cause program
-termination.  Unlike @code{SIGKILL}, this signal can be blocked,
-handled, and ignored.
-
-The shell command @code{kill} generates @code{SIGTERM} by default.
-@pindex kill
-@end deftypevr
-
-@comment signal.h
 @comment POSIX.1
 @deftypevr Macro int SIGKILL
 The @code{SIGKILL} signal is used to cause immediate program termination.
 It cannot be handled or ignored, and is therefore always fatal.  It is
 also not possible to block this signal.
 
-This signal is generated only by explicit request.  Since it cannot be
-handled, you should generate it only as a last resort, after first
-trying a less drastic method such as @kbd{C-c} or @code{SIGTERM}.  If a
-process does not respond to any other termination signals, sending it a
-@code{SIGKILL} signal will almost always cause it to go away.
+This signal is usually generated only by explicit request.  Since it
+cannot be handled, you should generate it only as a last resort, after
+first trying a less drastic method such as @kbd{C-c} or @code{SIGTERM}.
+If a process does not respond to any other termination signals, sending
+it a @code{SIGKILL} signal will almost always cause it to go away.
 
 In fact, if @code{SIGKILL} fails to terminate a process, that by itself
 constitutes an operating system bug which you should report.
+
+The system will generate @code{SIGKILL} for a process itself under some
+unusual conditions where the program cannot possible continue to run
+(even to run a signal handler).
 @end deftypevr
 @cindex kill signal
 
+@comment signal.h
+@comment POSIX.1
+@deftypevr Macro int SIGHUP
+@cindex hangup signal
+The @code{SIGHUP} (``hang-up'') signal is used to report that the user's
+terminal is disconnected, perhaps because a network or telephone
+connection was broken.  For more information about this, see @ref{Control
+Modes}.
+
+This signal is also used to report the termination of the controlling
+process on a terminal to jobs associated with that session; this
+termination effectively disconnects all processes in the session from
+the controlling terminal.  For more information, see @ref{Termination
+Internals}.
+@end deftypevr
+
 @node Alarm Signals
 @subsection Alarm Signals
 
@@ -580,6 +589,9 @@ or output.
 On most operating systems, terminals and sockets are the only kinds of
 files that can generate @code{SIGIO}; other kinds, including ordinary
 files, never generate @code{SIGIO} even if you ask them to.
+
+In the GNU system @code{SIGIO} will always be generated properly 
+if you successfully set asynchronous mode with @code{fcntl}.
 @end deftypevr
 
 @comment signal.h
@@ -621,8 +633,10 @@ system.
 @deftypevr Macro int SIGCONT
 @cindex continue signal
 You can send a @code{SIGCONT} signal to a process to make it continue.
-The default behavior for this signal is to make the process continue if
-it is stopped, and to ignore it otherwise.
+This signal is special---it always makes the process continue if it is
+stopped, before the signal is delivered.  The default behavior is to do
+nothing else.  You cannot block this signal.  You can set a handler, but
+@code{SIGCONT} always makes the process continue regardless.
 
 Most programs have no reason to handle @code{SIGCONT}; they simply
 resume execution without realizing they were ever stopped.  You can use
@@ -673,19 +687,22 @@ the terminal driver, see @ref{Access to the Terminal}.
 @deftypevr Macro int SIGTTOU
 This is similar to @code{SIGTTIN}, but is generated when a process in a
 background job attempts to write to the terminal or set its modes.
-Again, the default action is to stop the process.
+Again, the default action is to stop the process.  @code{SIGTTOU} is
+only generated for an attempt to write to the terminal if the
+@code{TOSTOP} output mode is set; @pxref{Output Modes}.
 @end deftypevr
 @cindex terminal output signal
 
 While a process is stopped, no more signals can be delivered to it until
 it is continued, except @code{SIGKILL} signals and (obviously)
-@code{SIGCONT} signals.  The @code{SIGKILL} signal always causes
-termination of the process and can't be blocked or ignored.  You can
-block or ignore @code{SIGCONT}, but it always causes the process to
-be continued anyway if it is stopped.  Sending a @code{SIGCONT} signal
-to a process causes any pending stop signals for that process to be
-discarded.  Likewise, any pending @code{SIGCONT} signals for a process
-are discarded when it receives a stop signal.
+@code{SIGCONT} signals.  The signals are marked as pending, but not
+delivered until the process is continued.  The @code{SIGKILL} signal
+always causes termination of the process and can't be blocked, handled
+or ignored.  You can ignore @code{SIGCONT}, but it always causes the
+process to be continued anyway if it is stopped.  Sending a
+@code{SIGCONT} signal to a process causes any pending stop signals for
+that process to be discarded.  Likewise, any pending @code{SIGCONT}
+signals for a process are discarded when it receives a stop signal.
 
 When a process in an orphaned process group (@pxref{Orphaned Process
 Groups}) receives a @code{SIGTSTP}, @code{SIGTTIN}, or @code{SIGTTOU}
@@ -783,8 +800,8 @@ Generated by the PDP-11 ``iot'' instruction; equivalent to @code{SIGABRT}.
 Default action is to dump core.
 
 @item SIGEMT
-Emulator trap; this results from certain unimplemented instructions.
-It is a program error signal.
+Emulator trap; this results from certain unimplemented instructions
+which might be emulated in software.  It is a program error signal.
 
 @item SIGSYS
 Bad system call; that is to say, the instruction to trap to the
@@ -1129,11 +1146,12 @@ Since @code{sigaction} is more general, it can properly save and
 reestablish any action, regardless of whether it was established
 originally with @code{signal} or @code{sigaction}.
 
-If you establish an action with @code{signal} and then examine it with
-@code{sigaction}, the handler address that you get may not be the same
-as what you specified with @code{signal}.  It may not even be suitable
-for use as an action argument with @code{signal}.  But you can rely on
-using it as an argument to @code{sigaction}.
+On some systems if you establish an action with @code{signal} and then
+examine it with @code{sigaction}, the handler address that you get may
+not be the same as what you specified with @code{signal}.  It may not
+even be suitable for use as an action argument with @code{signal}.  But
+you can rely on using it as an argument to @code{sigaction}.  This
+problem never happens on the GNU system.
 
 So, you're better off using one or the other of the mechanisms
 consistently within a single program.  
@@ -1253,8 +1271,9 @@ Setting this flag for a signal other than @code{SIGCHLD} has no effect.
 @comment BSD
 @deftypevr Macro int SA_ONSTACK
 If this flag is set for a particular signal number, the system uses the
-signal stack when delivering that kind of signal.  @xref{BSD Signal
-Handling}.
+signal stack when delivering that kind of signal.  @xref{Signal Stack}.
+If a signal with this flag arrives and you have not set a signal stack,
+the system terminates the program with @code{SIGILL}.
 @end deftypevr
 
 @comment signal.h
@@ -1361,7 +1380,7 @@ describes what your handler should do, and what you should avoid.
 @end menu
 
 @node Handler Returns
-@subsection Signal Handlers That Return
+@subsection Signal Handlers that Return
 
 Handlers which return normally are usually used for signals such as
 @code{SIGALRM} and the I/O and interprocess communication signals.  But
@@ -1513,11 +1532,11 @@ read_data ()
 @subsection Signals Arriving While a Handler Runs
 @cindex race conditions, relating to signals
 
-What happens if another signal arrives when your signal handler function
-is running?
+What happens if another signal arrives while your signal handler
+function is running?
 
 When the handler for a particular signal is invoked, that signal is
-normally blocked until the handler returns.  That means that if two
+automatically blocked until the handler returns.  That means that if two
 signals of the same kind arrive close together, the second one will be
 held until the first has been handled.  (The handler can explicitly
 unblock the signal using @code{sigprocmask}, if you want to allow more
@@ -1531,6 +1550,11 @@ signals are in addition to the signal for which the handler was invoked,
 and any other signals that are normally blocked by the process.
 @xref{Blocking for Handler}.
 
+When the handler returns, the set of blocked signals is restored to the
+value it had before the handler ran.  So using @code{sigprocmask} inside
+the handler only affects what signals can arrive during the execution of
+the handler itself, not what signals can arrive once the handler returns.
+
 @strong{Portability Note:} Always use @code{sigaction} to establish a
 handler for a signal that you expect to receive asynchronously, if you
 want your program to work properly on System V Unix.  On this system,
@@ -1713,12 +1737,12 @@ Handler functions usually don't do very much.  The best practice is to
 write a handler that does nothing but set an external variable that the
 program checks regularly, and leave all serious work to the program.
 This is best because the handler can be called at asynchronously, at
-unpredictable times---perhaps in the middle of a system call, or even
-between the beginning and the end of a C operator that requires multiple
-instructions.  The data structures being manipulated might therefore be
-in an inconsistent state when the handler function is invoked.  Even
-copying one @code{int} variable into another can take two instructions
-on most machines.
+unpredictable times---perhaps in the middle of a primitive function, or
+even between the beginning and the end of a C operator that requires
+multiple instructions.  The data structures being manipulated might
+therefore be in an inconsistent state when the handler function is
+invoked.  Even copying one @code{int} variable into another can take two
+instructions on most machines.
 
 This means you have to be very careful about what you do in a signal
 handler.
@@ -1795,11 +1819,14 @@ care, because placing an object on a chain is not atomic, and if it is
 interrupted by another signal handler that does the same thing, you
 could ``lose'' one of the objects.
 
+@ignore
+!!! not true
 On the GNU system, @code{malloc} and @code{free} are safe to use in
-signal handlers because it blocks signals.  As a result, the library
+signal handlers because they block signals.  As a result, the library
 functions that allocate space for a result are also safe in signal
 handlers.  The obstack allocation functions are safe as long as you
 don't use the same obstack both inside and outside of a signal handler.
+@end ignore
 
 The relocating allocation functions (@pxref{Relocating Allocator})
 are certainly not safe to use in a signal handler.
@@ -1837,7 +1864,7 @@ Whether the data in your application concerns atoms, or mere text, you
 have to be careful about the fact that access to a single datum is not
 necessarily @dfn{atomic}.  This means that it can take more than one
 instruction to read or write a single object.  In such cases, a signal
-handler can run in the middle of reading or writing the object.
+handler might in the middle of reading or writing the object.
 
 There are three ways you can cope with this problem.  You can use data
 types that are always accessed atomically; you can carefully arrange
@@ -2002,6 +2029,7 @@ that handler will cause @code{EINTR}.  @xref{Flags for Sigaction}.
 Another way to specify the choice is with the @code{siginterrupt}
 function.  @xref{POSIX vs BSD}.
 
+@c !!! not true now about _BSD_SOURCE
 When you don't specify with @code{sigaction} or @code{siginterrupt} what
 a particular handler should do, it uses a default choice.  The default
 choice in the GNU library depends on the feature test macros you have
@@ -2017,10 +2045,8 @@ Test Macros}.
 @cindex primitives, interrupting
 @c !!! want to have @cindex system calls @i{see} primitives [no page #]
 
-The primitives affected by this issue are @code{accept}, @code{close},
-@code{fcntl} (operation @code{F_SETLK}), @code{open}, @code{read},
-@code{recv}, @code{recvfrom}, @code{select}, @code{send}, @code{sendto},
-@code{tcdrain}, @code{waitpid}, @code{wait}, and @code{write}.
+The description of each primitive affected by this issue
+lists @code{EINTR} among the error codes it can return.
 
 There is one situation where resumption never happens no matter which
 choice you make: when a data-transfer function such as @code{read} or
@@ -2177,8 +2203,7 @@ signal:
 The process whose identifier is @var{pid}.
 
 @item @var{pid} == 0
-All processes in the same process group as the sender.  The sender
-itself does not receive the signal.
+All processes in the same process group as the sender.
 
 @item @var{pid} < -1
 The process group whose identifier is @minus{}@var{pid}.
@@ -2628,7 +2653,10 @@ mechanism.  However, you can make calls to @code{sigprocmask} within
 your handler to block or unblock signals as you wish.
 
 In any case, when the handler returns, the system restores the mask that
-was in place before the handler was entered.
+was in place before the handler was entered.  If any signals that become
+unblocked by this restoration are pending, the process will receive
+those signals immediately, before returning to the code that was
+interrupted.
 
 @node Checking for Pending Signals
 @subsection Checking for Pending Signals
@@ -2991,7 +3019,7 @@ should fail.  @xref{Interrupted Primitives}.
 
 @item
 BSD Unix has a concept of a @dfn{signal stack}.  This is an alternate
-stack that is used during the execution of signal handler functions,
+stack that can be used during the execution of signal handler functions,
 instead of its normal execution stack.
 @cindex signal stack
 @end itemize
@@ -3136,9 +3164,9 @@ space for the signal stack.
 
 You don't need to write signal handlers differently in order to use a
 signal stack.  Switching from one stack to the other happens
-automatically.  However, some debuggers on some machines may get
+automatically.  (Some non-GNU debuggers on some machines may get
 confused if you examine a stack trace while a handler that uses the
-signal stack is running.
+signal stack is running.)
 
 There are two interfaces for telling the system to use a separate signal
 stack.  @code{sigstack} is the older interface, which comes from 4.2
diff --git a/manual/startup.texi b/manual/startup.texi
index 2f415a0..cf5d36b 100644
--- a/manual/startup.texi
+++ b/manual/startup.texi
@@ -25,15 +25,20 @@ of a process, to terminate its process, and to receive information
 @section Program Arguments
 @cindex program arguments
 @cindex command line arguments
+@cindex arguments, to program
 
+@cindex program startup
+@cindex startup of program
+@cindex invocation of program
 @cindex @code{main} function
+@findex main
 The system starts a C program by calling the function @code{main}.  It
 is up to you to write a function named @code{main}---otherwise, you
 won't even be able to link your program without errors.
 
-You can define @code{main} either to take no arguments, or to take two
-arguments that represent the command line arguments to the program, like
-this:
+In ANSI C you can define @code{main} either to take no arguments, or to
+take two arguments that represent the command line arguments to the
+program, like this:
 
 @smallexample
 int main (int @var{argc}, char *@var{argv}[])
@@ -65,6 +70,17 @@ But unless your program takes a fixed number of arguments, or all of the
 arguments are interpreted in the same way (as file names, for example),
 you are usually better off using @code{getopt} to do the parsing.
 
+@c !!! does posix allow envp?
+In Unix systems you can define @code{main} a third way, using three arguments:
+
+@smallexample
+int main (int @var{argc}, char *@var{argv}[], char *@var{envp})
+@end smallexample
+
+The first two arguments are just the same.  The third argument
+@var{envp} gives the process's environment; it is the same as the value
+of @code{environ}.  @xref{Environment Variables}.
+
 @menu
 * Argument Syntax::       By convention, options start with a hyphen.
 * Parsing Options::       The @code{getopt} function.
@@ -405,7 +421,7 @@ The @var{argv} mechanism is typically used to pass command-line
 arguments specific to the particular program being invoked.  The
 environment, on the other hand, keeps track of information that is
 shared by many programs, changes infrequently, and that is less
-frequently accessed.
+frequently used.
 
 The environment variables discussed in this section are the same
 environment variables that you set using assignments and the
@@ -493,14 +509,19 @@ If you just want to get the value of an environment variable, use
 @code{getenv}.
 @end deftypevar
 
+@c !!! posix?
+Unix systems, and the GNU system, pass the initial value of
+@code{environ} as the third argument to @code{main}.
+@xref{Program Arguments}.
+
 @node Standard Environment
 @subsection Standard Environment Variables
 @cindex standard environment variables
 
 These environment variables have standard meanings.  This doesn't mean
 that they are always present in the environment; but if these variables
-@emph{are} present, they have these meanings, and that you shouldn't try
-to use these environment variable names for some other purpose.
+@emph{are} present, they have these meanings.  You shouldn't try to use
+these environment variable names for some other purpose.
 
 @comment Extra blank lines make it look better.
 @table @code
@@ -857,6 +878,8 @@ following things happen:
 @itemize @bullet
 @item
 All open file descriptors in the process are closed.  @xref{Low-Level I/O}.
+Note that streams are not flushed automatically when the process
+terminates; @xref{I/O on Streams}.
 
 @item
 The low-order 8 bits of the return status code are saved to be reported
@@ -865,7 +888,8 @@ back to the parent process via @code{wait} or @code{waitpid}; see
 
 @item
 Any child processes of the process being terminated are assigned a new
-parent process.  (This is the @code{init} process, with process ID 1.)
+parent process.  (On most systems, including GNU, this is the @code{init}
+process, with process ID 1.)
 
 @item
 A @code{SIGCHLD} signal is sent to the parent process.
diff --git a/manual/sysinfo.texi b/manual/sysinfo.texi
index 39a7210..a30536d 100644
--- a/manual/sysinfo.texi
+++ b/manual/sysinfo.texi
@@ -18,7 +18,10 @@ software, and the individual machine's name.
 
 This section explains how to identify the particular machine that your
 program is running on.  The identification of a machine consists of its
-Internet host name and Internet address; see @ref{Internet Namespace}.  
+Internet host name and Internet address; see @ref{Internet Namespace}.
+The host name should always be a fully qualified domain name, like
+@w{@samp{crispy-wheats-n-chicken.ai.mit.edu}}, not a simple name like
+just @w{@samp{crispy-wheats-n-chicken}}.
 
 @pindex hostname
 @pindex hostid
@@ -77,7 +80,7 @@ This process cannot set the host name because it is not privileged.
 @deftypefun {long int} gethostid (void)
 This function returns the ``host ID'' of the machine the program is
 running on.  By convention, this is usually the primary Internet address
-of that machine, converted to a @w{@code{long int}}.  But on some
+of that machine, converted to a @w{@code{long int}}.  However, some
 systems it is a meaningless but unique number which is hard-coded for
 each machine.
 @end deftypefun
diff --git a/manual/terminal.texi b/manual/terminal.texi
index 931d8e5..f66ed28 100644
--- a/manual/terminal.texi
+++ b/manual/terminal.texi
@@ -79,8 +79,10 @@ for Files}.  If input flow control is enabled by setting the
 @code{IXOFF} input mode bit (@pxref{Input Modes}), the terminal driver
 transmits STOP and START characters to the terminal when necessary to
 prevent the queue from overflowing.  Otherwise, input may be lost if it
-comes in too fast from the terminal.  (This is unlikely if you are
-typing the input by hand!)
+comes in too fast from the terminal.  In canonical mode, all input stays
+in the queue until a newline character is received, so the terminal
+input queue can fill up when you type a very long line.
+@xref{Canonical or Not}.
 
 @cindex terminal output queue
 The @dfn{terminal output queue} is like the input queue, but for output;
@@ -109,8 +111,8 @@ the @code{read} function (@pxref{I/O Primitives}) returns at most a
 single line of input, no matter how many bytes are requested.
 
 In canonical input mode, the operating system provides input editing
-facilities: the ERASE and KILL characters are interpreted specially to
-perform editing operations within the current line of text.
+facilities: some characters are interpreted specially to perform editing
+operations within the current line of text, such as ERASE and KILL.
 @xref{Editing Characters}.
 
 The constants @code{_POSIX_MAX_CANON} and @code{MAX_CANON} parameterize
@@ -283,7 +285,8 @@ This is like @code{TCSADRAIN}, but also discards any queued input.
 @vindex TCSASOFT
 This is a flag bit that you can add to any of the above alternatives.
 Its meaning is to inhibit alteration of the state of the terminal
-hardware.  It is a BSD extension; it has no effect on non-BSD systems.
+hardware.  It is a BSD extension; it is only supported on BSD systems
+and the GNU system.
 @end table
 
 If this function is called from a background process on its controlling
@@ -613,8 +616,8 @@ should be ignored.
 @cindex modem status lines
 @cindex carrier detect
 
-If this bit is not set and you call @code{open} without the
-@code{O_NONBLOCK} flag set, @code{open} blocks until a modem
+On many systems if this bit is not set and you call @code{open} without
+the @code{O_NONBLOCK} flag set, @code{open} blocks until a modem
 connection is established.
 
 If this bit is not set and a modem disconnect is detected, a
@@ -1065,21 +1068,6 @@ BSD defines two additional speed symbols as aliases: @code{EXTA} is an
 alias for @code{B19200} and @code{EXTB} is an alias for @code{B38400}.
 These aliases are obsolete.
 
-@comment termios.h
-@comment BSD
-@deftypefun int cfmakeraw (struct termios *@var{termios-p})
-This function provides an easy way to set up @code{*@var{termios-p}} for
-what has traditionally been called ``raw mode'' in BSD.  It does exactly this:
-@smallexample
-  @var{termios-p}->c_iflag &= ~(IGNBRK|BRKINT|PARMRK|ISTRIP
-                  |INLCR|IGNCR|ICRNL|IXON);
-  @var{termios-p}->c_oflag &= ~OPOST;
-  @var{termios-p}->c_lflag &= ~(ECHO|ECHONL|ICANON|ISIG|IEXTEN);
-  @var{termios-p}->c_cflag &= ~(CSIZE|PARENB);
-  @var{termios-p}->c_cflag |= CS8;
-@end smallexample
-@end deftypefun
-
 @node Special Characters
 @subsection Special Characters
 
@@ -1336,7 +1324,7 @@ The DSUSP (suspend) character is recognized only if the implementation
 supports job control (@pxref{Job Control}).  It sends a @code{SIGTSTP}
 signal, like the SUSP character, but not right away---only when the
 program tries to read it as input.  Not all systems with job control
-support DSUSP; only BSD systems.
+support DSUSP; only BSD-compatible systems (including the GNU system).
 
 @xref{Signal Handling}, for more information about signals.
 
@@ -1361,8 +1349,9 @@ character itself.
 The START character is used to support the @code{IXON} and @code{IXOFF}
 input modes.  If @code{IXON} is set, receiving a START character resumes
 suspended output; the START character itself is discarded.  If
-@code{IXOFF} is set, the system may also transmit START characters to
-the terminal.
+@code{IXANY} is set, receiving any character at all resumes suspended
+output.  @code{IXOFF} is set, the system may also transmit START
+characters to the terminal.
 
 The usual value for the START character is @kbd{C-q}.  You may not be
 able to change this value---the hardware may insist on using @kbd{C-q}
@@ -1405,7 +1394,8 @@ itself.
 The DISCARD character is recognized only when @code{IEXTEN} is set.  Its
 effect is to toggle the discard-output flag.  When this flag is set, all
 program output is discarded.  Setting the flag also discards all output
-currently in the output buffer.
+currently in the output buffer.  Typing any other character resets the
+flag.
 @end deftypevr
 
 @comment termios.h
@@ -1527,6 +1517,25 @@ input and the EOF and EOL slots are used only in canonical input, but it
 isn't very clean.  The GNU library allocates separate slots for these
 uses.
 
+@comment termios.h
+@comment BSD
+@deftypefun int cfmakeraw (struct termios *@var{termios-p})
+This function provides an easy way to set up @code{*@var{termios-p}} for
+what has traditionally been called ``raw mode'' in BSD.  This uses
+noncanonical input, and turns off most processing to give an unmodified
+channel to the terminal.
+
+It does exactly this:
+@smallexample
+  @var{termios-p}->c_iflag &= ~(IGNBRK|BRKINT|PARMRK|ISTRIP
+                                |INLCR|IGNCR|ICRNL|IXON);
+  @var{termios-p}->c_oflag &= ~OPOST;
+  @var{termios-p}->c_lflag &= ~(ECHO|ECHONL|ICANON|ISIG|IEXTEN);
+  @var{termios-p}->c_cflag &= ~(CSIZE|PARENB);
+  @var{termios-p}->c_cflag |= CS8;
+@end smallexample
+@end deftypefun
+
 @node Line Control
 @section Line Control Functions
 @cindex terminal line control functions