aboutsummaryrefslogtreecommitdiffstats
path: root/manual/signal.texi
diff options
context:
space:
mode:
authorRical Jasan <ricaljasan@pacific.net>2017-06-15 21:12:39 -0700
committerRical Jasan <ricaljasan@pacific.net>2017-06-15 21:26:20 -0700
commitd08a7e4cbe43d5e4e4b14dea950fea623d96c1a1 (patch)
tree6f27987046ae0e8804f4d641c99ff1666652117a /manual/signal.texi
parent27691d5cec9b896ea0792151a27c6d7d7a4065ea (diff)
downloadtermbaud-d08a7e4cbe43d5e4e4b14dea950fea623d96c1a1.tar.gz
termbaud-d08a7e4cbe43d5e4e4b14dea950fea623d96c1a1.tar.xz
termbaud-d08a7e4cbe43d5e4e4b14dea950fea623d96c1a1.zip
manual: Replace summary.awk with summary.pl.
The Summary is now generated from @standards, and syntax-checking is performed. If invalid @standards syntax is detected, summary.pl will fail, reporting all errors. Failure and error reporting is disabled for now, however, since much of the manual is still incomplete wrt. header and standards annotations. Note that the sorting order of the Summary has changed; summary.pl respects the locale, like summary.awk did, but the use of LC_ALL=C is introduced in the Makefile. Other notable deviations are improved detection of the annotated elements' names, which are used for sorting, and improved detection of the @node used to reference into the manual. The most noticeable difference in the rendered Summary is that entries may now contain multiple lines, one for each header and standard combination. summary.pl accepts a `--help' option, which details the expected syntax of @standards. If errors are reported, the user is directed to this feature for further information. * manual/Makefile: Generate summary.texi with summary.pl. Force use of the C locale. Update Perl dependency comment. * manual/header.texi: Update reference to summary.awk. * manual/macros.texi: Refer authors to `summary.pl --help'. * manual/summary.awk: Remove file. * manual/summary.pl: New file. Generate summary.texi, and check for @standards-related syntax errors. * manual/argp.texi: Convert header and standards @comments to @standards. * manual/arith.texi: Likewise. * manual/charset.texi: Likewise. * manual/conf.texi: Likewise. * manual/creature.texi: Likewise. * manual/crypt.texi: Likewise. * manual/ctype.texi: Likewise. * manual/debug.texi: Likewise. * manual/errno.texi: Likewise. * manual/filesys.texi: Likewise. * manual/getopt.texi: Likewise. * manual/job.texi: Likewise. * manual/lang.texi: Likewise. * manual/llio.texi: Likewise. * manual/locale.texi: Likewise. * manual/math.texi: Likewise. * manual/memory.texi: Likewise. * manual/message.texi: Likewise. * manual/pattern.texi: Likewise. * manual/pipe.texi: Likewise. * manual/process.texi: Likewise. * manual/resource.texi: Likewise. * manual/search.texi: Likewise. * manual/setjmp.texi: Likewise. * manual/signal.texi: Likewise. * manual/socket.texi: Likewise. * manual/startup.texi: Likewise. * manual/stdio.texi: Likewise. * manual/string.texi: Likewise. * manual/sysinfo.texi: Likewise. * manual/syslog.texi: Likewise. * manual/terminal.texi: Likewise. * manual/threads.texi: Likewise. * manual/time.texi: Likewise. * manual/users.texi: Likewise.
Diffstat (limited to 'manual/signal.texi')
-rw-r--r--manual/signal.texi257
1 files changed, 85 insertions, 172 deletions
diff --git a/manual/signal.texi b/manual/signal.texi
index d6a1bfe94a8..9577ff091d9 100644
--- a/manual/signal.texi
+++ b/manual/signal.texi
@@ -219,9 +219,8 @@ the names are standardized and fairly uniform.
The signal names are defined in the header file @file{signal.h}.
-@comment signal.h
-@comment BSD
@deftypevr Macro int NSIG
+@standards{BSD, signal.h}
The value of this symbolic constant is the total number of signals
defined. Since the signal numbers are allocated consecutively,
@code{NSIG} is also one greater than the largest defined signal number.
@@ -279,9 +278,8 @@ the environment variable @code{COREFILE}.) The purpose of core dump
files is so that you can examine them with a debugger to investigate
what caused the error.
-@comment signal.h
-@comment ISO
@deftypevr Macro int SIGFPE
+@standards{ISO, signal.h}
The @code{SIGFPE} signal reports a fatal arithmetic error. Although the
name is derived from ``floating-point exception'', this signal actually
covers all arithmetic errors, including division by zero and overflow.
@@ -312,56 +310,45 @@ argument, but the value is meaningful only on operating systems that
provide the information (BSD systems and @gnusystems{}).
@vtable @code
-@comment signal.h
-@comment BSD
@item FPE_INTOVF_TRAP
+@standards{BSD, signal.h}
Integer overflow (impossible in a C program unless you enable overflow
trapping in a hardware-specific fashion).
-@comment signal.h
-@comment BSD
@item FPE_INTDIV_TRAP
+@standards{BSD, signal.h}
Integer division by zero.
-@comment signal.h
-@comment BSD
@item FPE_SUBRNG_TRAP
+@standards{BSD, signal.h}
Subscript-range (something that C programs never check for).
-@comment signal.h
-@comment BSD
@item FPE_FLTOVF_TRAP
+@standards{BSD, signal.h}
Floating overflow trap.
-@comment signal.h
-@comment BSD
@item FPE_FLTDIV_TRAP
+@standards{BSD, signal.h}
Floating/decimal division by zero.
-@comment signal.h
-@comment BSD
@item FPE_FLTUND_TRAP
+@standards{BSD, signal.h}
Floating underflow trap. (Trapping on floating underflow is not
normally enabled.)
-@comment signal.h
-@comment BSD
@item FPE_DECOVF_TRAP
+@standards{BSD, signal.h}
Decimal overflow trap. (Only a few machines have decimal arithmetic and
C never uses it.)
@ignore @c These seem redundant
-@comment signal.h
-@comment BSD
@item FPE_FLTOVF_FAULT
+@standards{BSD, signal.h}
Floating overflow fault.
-@comment signal.h
-@comment BSD
@item FPE_FLTDIV_FAULT
+@standards{BSD, signal.h}
Floating divide by zero fault.
-@comment signal.h
-@comment BSD
@item FPE_FLTUND_FAULT
+@standards{BSD, signal.h}
Floating underflow fault.
@end ignore
@end vtable
-@comment signal.h
-@comment ISO
@deftypevr Macro int SIGILL
+@standards{ISO, signal.h}
The name of this signal is derived from ``illegal instruction''; it
usually means your program is trying to execute garbage or a privileged
instruction. Since the C compiler generates only valid instructions,
@@ -378,9 +365,8 @@ the system has trouble running the handler for a signal.
@end deftypevr
@cindex illegal instruction
-@comment signal.h
-@comment ISO
@deftypevr Macro int SIGSEGV
+@standards{ISO, signal.h}
@cindex segmentation violation
This signal is generated when a program tries to read or write outside
the memory that is allocated for it, or to write memory that can only be
@@ -395,9 +381,8 @@ among systems whether dereferencing a null pointer generates
@code{SIGSEGV} or @code{SIGBUS}.
@end deftypevr
-@comment signal.h
-@comment BSD
@deftypevr Macro int SIGBUS
+@standards{BSD, signal.h}
This signal is generated when an invalid pointer is dereferenced. Like
@code{SIGSEGV}, this signal is typically the result of dereferencing an
uninitialized pointer. The difference between the two is that
@@ -412,41 +397,36 @@ The name of this signal is an abbreviation for ``bus error''.
@end deftypevr
@cindex bus error
-@comment signal.h
-@comment ISO
@deftypevr Macro int SIGABRT
+@standards{ISO, signal.h}
@cindex abort signal
This signal indicates an error detected by the program itself and
reported by calling @code{abort}. @xref{Aborting a Program}.
@end deftypevr
-@comment signal.h
-@comment Unix
@deftypevr Macro int SIGIOT
+@standards{Unix, signal.h}
Generated by the PDP-11 ``iot'' instruction. On most machines, this is
just another name for @code{SIGABRT}.
@end deftypevr
-@comment signal.h
-@comment BSD
@deftypevr Macro int SIGTRAP
+@standards{BSD, signal.h}
Generated by the machine's breakpoint instruction, and possibly other
trap instructions. This signal is used by debuggers. Your program will
probably only see @code{SIGTRAP} if it is somehow executing bad
instructions.
@end deftypevr
-@comment signal.h
-@comment BSD
@deftypevr Macro int SIGEMT
+@standards{BSD, signal.h}
Emulator trap; this results from certain unimplemented instructions
which might be emulated in software, or the operating system's
failure to properly emulate them.
@end deftypevr
-@comment signal.h
-@comment Unix
@deftypevr Macro int SIGSYS
+@standards{Unix, signal.h}
Bad system call; that is to say, the instruction to trap to the
operating system was executed, but the code number for the system call
to perform was invalid.
@@ -471,9 +451,8 @@ not had a handler. (@xref{Termination in Handler}.)
The (obvious) default action for all of these signals is to cause the
process to terminate.
-@comment signal.h
-@comment ISO
@deftypevr Macro int SIGTERM
+@standards{ISO, signal.h}
@cindex termination signal
The @code{SIGTERM} signal is a generic signal used to cause program
termination. Unlike @code{SIGKILL}, this signal can be blocked,
@@ -484,9 +463,8 @@ The shell command @code{kill} generates @code{SIGTERM} by default.
@pindex kill
@end deftypevr
-@comment signal.h
-@comment ISO
@deftypevr Macro int SIGINT
+@standards{ISO, signal.h}
@cindex interrupt signal
The @code{SIGINT} (``program interrupt'') signal is sent when the user
types the INTR character (normally @kbd{C-c}). @xref{Special
@@ -494,9 +472,8 @@ Characters}, for information about terminal driver support for
@kbd{C-c}.
@end deftypevr
-@comment signal.h
-@comment POSIX.1
@deftypevr Macro int SIGQUIT
+@standards{POSIX.1, signal.h}
@cindex quit signal
@cindex quit signal
The @code{SIGQUIT} signal is similar to @code{SIGINT}, except that it's
@@ -516,9 +493,8 @@ is better for @code{SIGQUIT} not to delete them, so that the user can
examine them in conjunction with the core dump.
@end deftypevr
-@comment signal.h
-@comment POSIX.1
@deftypevr Macro int SIGKILL
+@standards{POSIX.1, signal.h}
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.
@@ -538,9 +514,8 @@ unusual conditions where the program cannot possibly continue to run
@end deftypevr
@cindex kill signal
-@comment signal.h
-@comment POSIX.1
@deftypevr Macro int SIGHUP
+@standards{POSIX.1, signal.h}
@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
@@ -566,26 +541,23 @@ This default is rarely useful, but no other default would be useful;
most of the ways of using these signals would require handler functions
in any case.
-@comment signal.h
-@comment POSIX.1
@deftypevr Macro int SIGALRM
+@standards{POSIX.1, signal.h}
This signal typically indicates expiration of a timer that measures real
or clock time. It is used by the @code{alarm} function, for example.
@end deftypevr
@cindex alarm signal
-@comment signal.h
-@comment BSD
@deftypevr Macro int SIGVTALRM
+@standards{BSD, signal.h}
This signal typically indicates expiration of a timer that measures CPU
time used by the current process. The name is an abbreviation for
``virtual time alarm''.
@end deftypevr
@cindex virtual time alarm signal
-@comment signal.h
-@comment BSD
@deftypevr Macro int SIGPROF
+@standards{BSD, signal.h}
This signal typically indicates expiration of a timer that measures
both CPU time used by the current process, and CPU time expended on
behalf of the process by the system. Such a timer is used to implement
@@ -603,9 +575,8 @@ calling @code{fcntl} to enable a particular file descriptor to generate
these signals (@pxref{Interrupt Input}). The default action for these
signals is to ignore them.
-@comment signal.h
-@comment BSD
@deftypevr Macro int SIGIO
+@standards{BSD, signal.h}
@cindex input available signal
@cindex output possible signal
This signal is sent when a file descriptor is ready to perform input
@@ -619,17 +590,15 @@ On @gnusystems{} @code{SIGIO} will always be generated properly
if you successfully set asynchronous mode with @code{fcntl}.
@end deftypevr
-@comment signal.h
-@comment BSD
@deftypevr Macro int SIGURG
+@standards{BSD, signal.h}
@cindex urgent data signal
This signal is sent when ``urgent'' or out-of-band data arrives on a
socket. @xref{Out-of-Band Data}.
@end deftypevr
-@comment signal.h
-@comment SVID
@deftypevr Macro int SIGPOLL
+@standards{SVID, signal.h}
This is a System V signal name, more or less similar to @code{SIGIO}.
It is defined only for compatibility.
@end deftypevr
@@ -645,9 +614,8 @@ signals themselves can't be raised or handled.
You should generally leave these signals alone unless you really
understand how job control works. @xref{Job Control}.
-@comment signal.h
-@comment POSIX.1
@deftypevr Macro int SIGCHLD
+@standards{POSIX.1, signal.h}
@cindex child process signal
This signal is sent to a parent process whenever one of its child
processes terminates or stops.
@@ -660,15 +628,13 @@ applies to those processes or not depends on the particular operating
system.
@end deftypevr
-@comment signal.h
-@comment SVID
@deftypevr Macro int SIGCLD
+@standards{SVID, signal.h}
This is an obsolete name for @code{SIGCHLD}.
@end deftypevr
-@comment signal.h
-@comment POSIX.1
@deftypevr Macro int SIGCONT
+@standards{POSIX.1, signal.h}
@cindex continue signal
You can send a @code{SIGCONT} signal to a process to make it continue.
This signal is special---it always makes the process continue if it is
@@ -683,17 +649,15 @@ it is stopped and continued---for example, to reprint a prompt when it
is suspended while waiting for input.
@end deftypevr
-@comment signal.h
-@comment POSIX.1
@deftypevr Macro int SIGSTOP
+@standards{POSIX.1, signal.h}
The @code{SIGSTOP} signal stops the process. It cannot be handled,
ignored, or blocked.
@end deftypevr
@cindex stop signal
-@comment signal.h
-@comment POSIX.1
@deftypevr Macro int SIGTSTP
+@standards{POSIX.1, signal.h}
The @code{SIGTSTP} signal is an interactive stop signal. Unlike
@code{SIGSTOP}, this signal can be handled and ignored.
@@ -708,9 +672,8 @@ support, see @ref{Special Characters}.
@end deftypevr
@cindex interactive stop signal
-@comment signal.h
-@comment POSIX.1
@deftypevr Macro int SIGTTIN
+@standards{POSIX.1, signal.h}
A process cannot read from the user's terminal while it is running
as a background job. When any process in a background job tries to
read from the terminal, all of the processes in the job are sent a
@@ -720,9 +683,8 @@ the terminal driver, see @ref{Access to the Terminal}.
@end deftypevr
@cindex terminal input signal
-@comment signal.h
-@comment POSIX.1
@deftypevr Macro int SIGTTOU
+@standards{POSIX.1, signal.h}
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. @code{SIGTTOU} is
@@ -769,9 +731,8 @@ programming error in the program, but an error that prevents an
operating system call from completing. The default action for all of
them is to cause the process to terminate.
-@comment signal.h
-@comment POSIX.1
@deftypevr Macro int SIGPIPE
+@standards{POSIX.1, signal.h}
@cindex pipe signal
@cindex broken pipe signal
Broken pipe. If you use pipes or FIFOs, you have to design your
@@ -788,9 +749,8 @@ Another cause of @code{SIGPIPE} is when you try to output to a socket
that isn't connected. @xref{Sending Data}.
@end deftypevr
-@comment signal.h
-@comment GNU
@deftypevr Macro int SIGLOST
+@standards{GNU, signal.h}
@cindex lost resource signal
Resource lost. This signal is generated when you have an advisory lock
on an NFS file, and the NFS server reboots and forgets about your lock.
@@ -800,16 +760,14 @@ dies unexpectedly. It is usually fine to ignore the signal; whatever
call was made to the server that died just returns an error.
@end deftypevr
-@comment signal.h
-@comment BSD
@deftypevr Macro int SIGXCPU
+@standards{BSD, signal.h}
CPU time limit exceeded. This signal is generated when the process
exceeds its soft resource limit on CPU time. @xref{Limits on Resources}.
@end deftypevr
-@comment signal.h
-@comment BSD
@deftypevr Macro int SIGXFSZ
+@standards{BSD, signal.h}
File size limit exceeded. This signal is generated when the process
attempts to extend a file so it exceeds the process's soft resource
limit on file size. @xref{Limits on Resources}.
@@ -821,12 +779,9 @@ limit on file size. @xref{Limits on Resources}.
These signals are used for various other purposes. In general, they
will not affect your program unless it explicitly uses them for something.
-@comment signal.h
-@comment POSIX.1
@deftypevr Macro int SIGUSR1
-@comment signal.h
-@comment POSIX.1
@deftypevrx Macro int SIGUSR2
+@standards{POSIX.1, signal.h}
@cindex user signals
The @code{SIGUSR1} and @code{SIGUSR2} signals are set aside for you to
use any way you want. They're useful for simple interprocess
@@ -839,9 +794,8 @@ in @ref{Signaling Another Process}.
The default action is to terminate the process.
@end deftypevr
-@comment signal.h
-@comment BSD
@deftypevr Macro int SIGWINCH
+@standards{BSD, signal.h}
Window size change. This is generated on some systems (including GNU)
when the terminal driver's record of the number of rows and columns on
the screen is changed. The default action is to ignore it.
@@ -851,9 +805,8 @@ When the signal arrives, it should fetch the new screen size and
reformat its display accordingly.
@end deftypevr
-@comment signal.h
-@comment BSD
@deftypevr Macro int SIGINFO
+@standards{BSD, signal.h}
Information request. On 4.4 BSD and @gnuhurdsystems{}, this signal is sent
to all the processes in the foreground process group of the controlling
terminal when the user types the STATUS character in canonical mode;
@@ -876,9 +829,8 @@ kind of signal to describe. The signal number may come from the
termination status of a child process (@pxref{Process Completion}) or it
may come from a signal handler in the same process.
-@comment string.h
-@comment GNU
@deftypefun {char *} strsignal (int @var{signum})
+@standards{GNU, string.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:strsignal} @mtslocale{}}@asunsafe{@asuinit{} @ascuintl{} @asucorrupt{} @ascuheap{}}@acunsafe{@acuinit{} @acucorrupt{} @acsmem{}}}
@c strsignal @mtasurace:strsignal @mtslocale @asuinit @ascuintl @asucorrupt @ascuheap @acucorrupt @acsmem
@c uses a static buffer if tsd key creation fails
@@ -904,9 +856,8 @@ This function is a GNU extension, declared in the header file
@file{string.h}.
@end deftypefun
-@comment signal.h
-@comment BSD
@deftypefun void psignal (int @var{signum}, const char *@var{message})
+@standards{BSD, signal.h}
@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuintl{} @ascuheap{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{}}}
@c psignal @mtslocale @asucorrupt @ascuintl @ascuheap @aculock @acucorrupt @acsmem
@c _ @ascuintl
@@ -965,9 +916,8 @@ an action for a particular signal. The function and associated macros
are declared in the header file @file{signal.h}.
@pindex signal.h
-@comment signal.h
-@comment GNU
@deftp {Data Type} sighandler_t
+@standards{GNU, signal.h}
This is the type of signal handler functions. Signal handlers take one
integer argument specifying the signal number, and have return type
@code{void}. So, you should define handler functions like this:
@@ -979,9 +929,8 @@ void @var{handler} (int @code{signum}) @{ @dots{} @}
The name @code{sighandler_t} for this data type is a GNU extension.
@end deftp
-@comment signal.h
-@comment ISO
@deftypefun sighandler_t signal (int @var{signum}, sighandler_t @var{action})
+@standards{ISO, signal.h}
@safety{@prelim{}@mtsafe{@mtssigintr{}}@assafe{}@acsafe{}}
@c signal ok
@c sigemptyset dup ok
@@ -1107,9 +1056,8 @@ We do not handle @code{SIGQUIT} or the program error signals in this
example because these are designed to provide information for debugging
(a core dump), and the temporary files may give useful information.
-@comment signal.h
-@comment GNU
@deftypefun sighandler_t sysv_signal (int @var{signum}, sighandler_t @var{action})
+@standards{GNU, signal.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c sysv_signal ok
@c sigemptyset dup ok
@@ -1123,18 +1071,16 @@ function should be avoided when possible. @code{sigaction} is the
preferred method.
@end deftypefun
-@comment signal.h
-@comment SVID
@deftypefun sighandler_t ssignal (int @var{signum}, sighandler_t @var{action})
+@standards{SVID, signal.h}
@safety{@prelim{}@mtsafe{@mtssigintr{}}@assafe{}@acsafe{}}
@c Aliases signal and bsd_signal.
The @code{ssignal} function does the same thing as @code{signal}; it is
provided only for compatibility with SVID.
@end deftypefun
-@comment signal.h
-@comment ISO
@deftypevr Macro sighandler_t SIG_ERR
+@standards{ISO, signal.h}
The value of this macro is used as the return value from @code{signal}
to indicate an error.
@end deftypevr
@@ -1163,9 +1109,8 @@ handler is invoked.
The @code{sigaction} function is declared in @file{signal.h}.
@pindex signal.h
-@comment signal.h
-@comment POSIX.1
@deftp {Data Type} {struct sigaction}
+@standards{POSIX.1, signal.h}
Structures of type @code{struct sigaction} are used in the
@code{sigaction} function to specify all the information about how to
handle a particular signal. This structure contains at least the
@@ -1191,9 +1136,8 @@ the signal. These are described in more detail in @ref{Flags for Sigaction}.
@end table
@end deftp
-@comment signal.h
-@comment POSIX.1
@deftypefun int sigaction (int @var{signum}, const struct sigaction *restrict @var{action}, struct sigaction *restrict @var{old-action})
+@standards{POSIX.1, signal.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @var{action} argument is used to set up a new action for the signal
@var{signum}, while the @var{old-action} argument is used to return
@@ -1351,9 +1295,8 @@ Primitives}, to see what this is about.
@pindex signal.h
These macros are defined in the header file @file{signal.h}.
-@comment signal.h
-@comment POSIX.1
@deftypevr Macro int SA_NOCLDSTOP
+@standards{POSIX.1, signal.h}
This flag is meaningful only for the @code{SIGCHLD} signal. When the
flag is set, the system delivers the signal for a terminated child
process but not for one that is stopped. By default, @code{SIGCHLD} is
@@ -1362,18 +1305,16 @@ delivered for both terminated children and stopped children.
Setting this flag for a signal other than @code{SIGCHLD} has no effect.
@end deftypevr
-@comment signal.h
-@comment BSD
@deftypevr Macro int SA_ONSTACK
+@standards{BSD, signal.h}
If this flag is set for a particular signal number, the system uses the
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
-@comment BSD
@deftypevr Macro int SA_RESTART
+@standards{BSD, signal.h}
This flag controls what happens when a signal is delivered during
certain primitives (such as @code{open}, @code{read} or @code{write}),
and the signal handler returns normally. There are two alternatives:
@@ -2045,9 +1986,8 @@ The type @code{sig_atomic_t} is always an integer data type, but which
one it is, and how many bits it contains, may vary from machine to
machine.
-@comment signal.h
-@comment ISO
@deftp {Data Type} sig_atomic_t
+@standards{ISO, signal.h}
This is an integer data type. Objects of this type are always accessed
atomically.
@end deftp
@@ -2103,9 +2043,8 @@ to check, which is a common source of error.
@Theglibc{} provides a convenient way to retry a call after a
temporary failure, with the macro @code{TEMP_FAILURE_RETRY}:
-@comment unistd.h
-@comment GNU
@defmac TEMP_FAILURE_RETRY (@var{expression})
+@standards{GNU, unistd.h}
This macro evaluates @var{expression} once, and examines its value as
type @code{long int}. If the value equals @code{-1}, that indicates a
failure and @code{errno} should be set to show what kind of failure.
@@ -2181,9 +2120,8 @@ A process can send itself a signal with the @code{raise} function. This
function is declared in @file{signal.h}.
@pindex signal.h
-@comment signal.h
-@comment ISO
@deftypefun int raise (int @var{signum})
+@standards{ISO, signal.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c raise ok
@c [posix]
@@ -2198,9 +2136,8 @@ About the only reason for failure would be if the value of @var{signum}
is invalid.
@end deftypefun
-@comment signal.h
-@comment SVID
@deftypefun int gsignal (int @var{signum})
+@standards{SVID, signal.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c Aliases raise.
The @code{gsignal} function does the same thing as @code{raise}; it is
@@ -2292,9 +2229,8 @@ work. For more information on this subject, see @ref{Processes}.
The @code{kill} function is declared in @file{signal.h}.
@pindex signal.h
-@comment signal.h
-@comment POSIX.1
@deftypefun int kill (pid_t @var{pid}, int @var{signum})
+@standards{POSIX.1, signal.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c The hurd implementation is not a critical section, so it's not
@c immediately obvious that, in case of cancellation, it won't leak
@@ -2353,9 +2289,8 @@ The @var{pid} argument does not refer to an existing process or group.
@end table
@end deftypefun
-@comment signal.h
-@comment BSD
@deftypefun int killpg (int @var{pgid}, int @var{signum})
+@standards{BSD, signal.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c Calls kill with -pgid.
This is similar to @code{kill}, but sends signal @var{signum} to the
@@ -2502,9 +2437,8 @@ it as an argument to a library function.
These facilities are declared in the header file @file{signal.h}.
@pindex signal.h
-@comment signal.h
-@comment POSIX.1
@deftp {Data Type} sigset_t
+@standards{POSIX.1, signal.h}
The @code{sigset_t} data type is used to represent a signal set.
Internally, it may be implemented as either an integer or structure
type.
@@ -2527,26 +2461,23 @@ well. (In addition, it's not wise to put into your program an
assumption that the system has no signals aside from the ones you know
about.)
-@comment signal.h
-@comment POSIX.1
@deftypefun int sigemptyset (sigset_t *@var{set})
+@standards{POSIX.1, signal.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c Just memsets all of set to zero.
This function initializes the signal set @var{set} to exclude all of the
defined signals. It always returns @code{0}.
@end deftypefun
-@comment signal.h
-@comment POSIX.1
@deftypefun int sigfillset (sigset_t *@var{set})
+@standards{POSIX.1, signal.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This function initializes the signal set @var{set} to include
all of the defined signals. Again, the return value is @code{0}.
@end deftypefun
-@comment signal.h
-@comment POSIX.1
@deftypefun int sigaddset (sigset_t *@var{set}, int @var{signum})
+@standards{POSIX.1, signal.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This function adds the signal @var{signum} to the signal set @var{set}.
All @code{sigaddset} does is modify @var{set}; it does not block or
@@ -2561,9 +2492,8 @@ The @var{signum} argument doesn't specify a valid signal.
@end table
@end deftypefun
-@comment signal.h
-@comment POSIX.1
@deftypefun int sigdelset (sigset_t *@var{set}, int @var{signum})
+@standards{POSIX.1, signal.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This function removes the signal @var{signum} from the signal set
@var{set}. All @code{sigdelset} does is modify @var{set}; it does not
@@ -2573,9 +2503,8 @@ the same as for @code{sigaddset}.
Finally, there is a function to test what signals are in a signal set:
-@comment signal.h
-@comment POSIX.1
@deftypefun int sigismember (const sigset_t *@var{set}, int @var{signum})
+@standards{POSIX.1, signal.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{sigismember} function tests whether the signal @var{signum} is
a member of the signal set @var{set}. It returns @code{1} if the signal
@@ -2612,9 +2541,8 @@ Instead, use @code{pthread_sigmask}.
@xref{Threads and Signal Handling}.
@end ifset
-@comment signal.h
-@comment POSIX.1
@deftypefun int sigprocmask (int @var{how}, const sigset_t *restrict @var{set}, sigset_t *restrict @var{oldset})
+@standards{POSIX.1, signal.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:sigprocmask/bsd(SIG_UNBLOCK)}}@asunsafe{@asulock{/hurd}}@acunsafe{@aculock{/hurd}}}
@c This takes the hurd_self_sigstate-returned object's lock on HURD. On
@c BSD, SIG_UNBLOCK is emulated with two sigblock calls, which
@@ -2624,21 +2552,18 @@ process's signal mask. The @var{how} argument determines how the signal
mask is changed, and must be one of the following values:
@vtable @code
-@comment signal.h
-@comment POSIX.1
@item SIG_BLOCK
+@standards{POSIX.1, signal.h}
Block the signals in @code{set}---add them to the existing mask. In
other words, the new mask is the union of the existing mask and
@var{set}.
-@comment signal.h
-@comment POSIX.1
@item SIG_UNBLOCK
+@standards{POSIX.1, signal.h}
Unblock the signals in @var{set}---remove them from the existing mask.
-@comment signal.h
-@comment POSIX.1
@item SIG_SETMASK
+@standards{POSIX.1, signal.h}
Use @var{set} for the mask; ignore the previous value of the mask.
@end vtable
@@ -2796,9 +2721,8 @@ You can find out which signals are pending at any time by calling
@code{sigpending}. This function is declared in @file{signal.h}.
@pindex signal.h
-@comment signal.h
-@comment POSIX.1
@deftypefun int sigpending (sigset_t *@var{set})
+@standards{POSIX.1, signal.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{/hurd}}@acunsafe{@aculock{/hurd}}}
@c Direct rt_sigpending syscall on most systems. On hurd, calls
@c hurd_self_sigstate, it copies the sigstate's pending while holding
@@ -2963,9 +2887,8 @@ The simple way to wait until a signal arrives is to call @code{pause}.
Please read about its disadvantages, in the following section, before
you use it.
-@comment unistd.h
-@comment POSIX.1
@deftypefun int pause (void)
+@standards{POSIX.1, unistd.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:sigprocmask/!bsd!linux}}@asunsafe{@asulock{/hurd}}@acunsafe{@aculock{/hurd}}}
@c The signal mask read by sigprocmask may be overridden by another
@c thread or by a signal handler before we call sigsuspend. Is this a
@@ -3069,9 +2992,8 @@ and then use @code{sigsuspend}. By using @code{sigsuspend} in a loop,
you can wait for certain kinds of signals, while letting other kinds of
signals be handled by their handlers.
-@comment signal.h
-@comment POSIX.1
@deftypefun int sigsuspend (const sigset_t *@var{set})
+@standards{POSIX.1, signal.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:sigprocmask/!bsd!linux}}@asunsafe{@asulock{/hurd}}@acunsafe{@aculock{/hurd}}}
@c sigsuspend @mtasurace:sigprocmask/!bsd!linux @asulock/hurd @aculock/hurd
@c [posix] @mtasurace:sigprocmask/!bsd!linux
@@ -3166,9 +3088,8 @@ BSD. The @code{sigaltstack} interface has the advantage that it does
not require your program to know which direction the stack grows, which
depends on the specific machine and operating system.
-@comment signal.h
-@comment XPG
@deftp {Data Type} stack_t
+@standards{XPG, signal.h}
This structure describes a signal stack. It contains the following members:
@table @code
@@ -3214,9 +3135,8 @@ delivered on the normal user stack.
@end table
@end deftp
-@comment signal.h
-@comment XPG
@deftypefun int sigaltstack (const stack_t *restrict @var{stack}, stack_t *restrict @var{oldstack})
+@standards{XPG, signal.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{/hurd}}@acunsafe{@aculock{/hurd}}}
@c Syscall on Linux and BSD; the HURD implementation takes a lock on
@c the hurd_self_sigstate-returned struct.
@@ -3247,9 +3167,8 @@ It must be greater than @code{MINSIGSTKSZ}.
Here is the older @code{sigstack} interface. You should use
@code{sigaltstack} instead on systems that have it.
-@comment signal.h
-@comment BSD
@deftp {Data Type} {struct sigstack}
+@standards{BSD, signal.h}
This structure describes a signal stack. It contains the following members:
@table @code
@@ -3263,9 +3182,8 @@ This field is true if the process is currently using this stack.
@end table
@end deftp
-@comment signal.h
-@comment BSD
@deftypefun int sigstack (struct sigstack *@var{stack}, struct sigstack *@var{oldstack})
+@standards{BSD, signal.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{/hurd}}@acunsafe{@aculock{/hurd}}}
@c Lossy and dangerous (no size limit) wrapper for sigaltstack.
The @code{sigstack} function specifies an alternate stack for use during
@@ -3300,9 +3218,8 @@ represents signal masks as an @code{int} bit mask, rather than as a
The BSD facilities are declared in @file{signal.h}.
@pindex signal.h
-@comment signal.h
-@comment XPG
@deftypefun int siginterrupt (int @var{signum}, int @var{failflag})
+@standards{XPG, signal.h}
@safety{@prelim{}@mtunsafe{@mtasuconst{:@mtssigintr{}}}@asunsafe{}@acunsafe{@acucorrupt{}}}
@c This calls sigaction twice, once to get the current sigaction for the
@c specified signal, another to apply the flags change. This could
@@ -3318,9 +3235,8 @@ true, handling @var{signum} causes these primitives to fail with error
code @code{EINTR}. @xref{Interrupted Primitives}.
@end deftypefun
-@comment signal.h
-@comment BSD
@deftypefn Macro int sigmask (int @var{signum})
+@standards{BSD, signal.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c This just shifts signum.
This macro returns a signal mask that has the bit for signal @var{signum}
@@ -3336,9 +3252,8 @@ together to specify more than one signal. For example,
specifies a mask that includes all the job-control stop signals.
@end deftypefn
-@comment signal.h
-@comment BSD
@deftypefun int sigblock (int @var{mask})
+@standards{BSD, signal.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{/hurd}}@acunsafe{@aculock{/hurd}}}
@c On most POSIX systems, this is a wrapper for sigprocmask(SIG_BLOCK).
@c The exception are BSD systems other than 4.4, where it is a syscall.
@@ -3350,9 +3265,8 @@ signals specified by @var{mask} to the calling process's set of blocked
signals. The return value is the previous set of blocked signals.
@end deftypefun
-@comment signal.h
-@comment BSD
@deftypefun int sigsetmask (int @var{mask})
+@standards{BSD, signal.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{/hurd}}@acunsafe{@aculock{/hurd}}}
@c On most POSIX systems, this is a wrapper for sigprocmask(SIG_SETMASK).
@c The exception are BSD systems other than 4.4, where it is a syscall.
@@ -3364,9 +3278,8 @@ the calling process's signal mask to @var{mask}. The return value is
the previous set of blocked signals.
@end deftypefun
-@comment signal.h
-@comment BSD
@deftypefun int sigpause (int @var{mask})
+@standards{BSD, signal.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:sigprocmask/!bsd!linux}}@asunsafe{@asulock{/hurd}}@acunsafe{@aculock{/hurd}}}
@c sigpause @mtasurace:sigprocmask/!bsd!linux @asulock/hurd @aculock/hurd
@c [posix]