Misc changes suggested by mib.

1 files changed, 119 insertions, 91 deletions

diff --git a/manual/signal.texi b/manual/signal.texi
index 575fbdc329..eff0f3ce42 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