2012-02-28 22:44:20 +08:00
|
|
|
@c Define common macros used to keep phrasing consistent in the manual.
|
|
|
|
|
|
|
|
@ifclear MACROS
|
|
|
|
@set MACROS
|
|
|
|
|
|
|
|
@c Names used to refer to the library, as noun phrases at the start or
|
|
|
|
@c not at the start of a sentence.
|
|
|
|
@macro Theglibc
|
|
|
|
The GNU C Library
|
|
|
|
@end macro
|
|
|
|
@macro theglibc
|
|
|
|
the GNU C Library
|
|
|
|
@end macro
|
|
|
|
|
|
|
|
@c Name used to refer to the library as an adjective.
|
|
|
|
@macro glibcadj
|
|
|
|
GNU C Library
|
|
|
|
@end macro
|
|
|
|
|
2012-03-08 09:27:38 +08:00
|
|
|
@c Description applying to all GNU systems; that is, used in
|
|
|
|
@c describing a property of a system such that no system without that
|
|
|
|
@c property would be considered a variant of the GNU system.
|
|
|
|
@macro gnusystems
|
|
|
|
GNU systems
|
|
|
|
@end macro
|
|
|
|
|
|
|
|
@c Systems that are not GNU systems.
|
|
|
|
@macro nongnusystems
|
|
|
|
non-GNU systems
|
|
|
|
@end macro
|
|
|
|
|
|
|
|
@c Description applying to GNU/Linux and GNU/Hurd systems, but not
|
|
|
|
@c necessarily to other variants of the GNU system.
|
|
|
|
@macro gnulinuxhurdsystems
|
|
|
|
GNU/Linux and GNU/Hurd systems
|
|
|
|
@end macro
|
|
|
|
|
2014-02-04 03:26:08 +08:00
|
|
|
@c Description applying to GNU/Hurd systems; that is, systems using the
|
2012-03-08 09:27:38 +08:00
|
|
|
@c GNU Hurd with the GNU C Library.
|
|
|
|
@macro gnuhurdsystems
|
|
|
|
GNU/Hurd systems
|
|
|
|
@end macro
|
|
|
|
|
2014-02-04 03:26:08 +08:00
|
|
|
@c Description applying to GNU/Linux systems; that is, systems using
|
2012-03-08 09:27:38 +08:00
|
|
|
@c the Linux kernel with the GNU C Library.
|
|
|
|
@macro gnulinuxsystems
|
|
|
|
GNU/Linux systems
|
|
|
|
@end macro
|
|
|
|
|
2014-01-29 15:20:37 +08:00
|
|
|
@c Document the safety functions as preliminary. It does NOT expand its
|
|
|
|
@c comments.
|
|
|
|
@macro prelim {comments}
|
|
|
|
Preliminary:
|
|
|
|
|
|
|
|
@end macro
|
|
|
|
@c Document a function as thread safe.
|
|
|
|
@macro mtsafe {comments}
|
|
|
|
| MT-Safe \comments\
|
|
|
|
|
|
|
|
@end macro
|
|
|
|
@c Document a function as thread unsafe.
|
|
|
|
@macro mtunsafe {comments}
|
|
|
|
| MT-Unsafe \comments\
|
|
|
|
|
|
|
|
@end macro
|
|
|
|
@c Document a function as safe for use in asynchronous signal handlers.
|
|
|
|
@macro assafe {comments}
|
|
|
|
| AS-Safe \comments\
|
|
|
|
|
|
|
|
@end macro
|
|
|
|
@c Document a function as unsafe for use in asynchronous signal
|
|
|
|
@c handlers. This distinguishes unmarked functions, for which this
|
|
|
|
@c property has not been assessed, from those that have been analyzed.
|
|
|
|
@macro asunsafe {comments}
|
|
|
|
| AS-Unsafe \comments\
|
|
|
|
|
|
|
|
@end macro
|
|
|
|
@c Document a function as safe for use when asynchronous cancellation is
|
|
|
|
@c enabled.
|
|
|
|
@macro acsafe {comments}
|
|
|
|
| AC-Safe \comments\
|
|
|
|
|
|
|
|
@end macro
|
|
|
|
@c Document a function as unsafe for use when asynchronous cancellation
|
|
|
|
@c is enabled. This distinguishes unmarked functions, for which this
|
|
|
|
@c property has not been assessed, from those that have been analyzed.
|
|
|
|
@macro acunsafe {comments}
|
|
|
|
| AC-Unsafe \comments\
|
|
|
|
|
|
|
|
@end macro
|
|
|
|
@c Format safety properties without referencing the section of the
|
|
|
|
@c definitions. To be used in the definitions of the properties
|
|
|
|
@c themselves.
|
|
|
|
@macro sampsafety {notes}
|
|
|
|
@noindent
|
|
|
|
\notes\|
|
|
|
|
|
|
|
|
|
|
|
|
@end macro
|
|
|
|
@c Format the safety properties of a function.
|
|
|
|
@macro safety {notes}
|
|
|
|
\notes\| @xref{POSIX Safety Concepts}.
|
|
|
|
|
|
|
|
|
|
|
|
@end macro
|
2014-02-04 03:26:08 +08:00
|
|
|
@c Function is MT- and AS-Unsafe due to an internal race.
|
2014-01-29 15:20:37 +08:00
|
|
|
@macro mtasurace {comments}
|
|
|
|
race\comments\
|
|
|
|
@end macro
|
2014-02-04 03:26:08 +08:00
|
|
|
@c Function is AS-Unsafe due to an internal race.
|
2014-01-29 15:20:37 +08:00
|
|
|
@macro asurace {comments}
|
|
|
|
race\comments\
|
|
|
|
@end macro
|
2014-02-04 03:26:08 +08:00
|
|
|
@c Function is MT-Safe, but with potential race on user-supplied object
|
|
|
|
@c of opaque type.
|
2014-01-29 15:20:37 +08:00
|
|
|
@macro mtsrace {comments}
|
|
|
|
race\comments\
|
|
|
|
@end macro
|
2014-02-04 03:26:08 +08:00
|
|
|
@c Function is MT- and AS-Unsafe for modifying an object that is decreed
|
|
|
|
@c MT-constant due to MT-Unsafe accesses elsewhere.
|
2014-01-29 15:20:37 +08:00
|
|
|
@macro mtasuconst {comments}
|
|
|
|
const\comments\
|
|
|
|
@end macro
|
2014-02-04 03:26:08 +08:00
|
|
|
@c Function accesses the assumed-constant locale object.
|
2014-01-29 15:20:37 +08:00
|
|
|
@macro mtslocale {comments}
|
|
|
|
locale\comments\
|
|
|
|
@end macro
|
2014-02-04 03:26:08 +08:00
|
|
|
@c Function accesses the assumed-constant environment.
|
2014-01-29 15:20:37 +08:00
|
|
|
@macro mtsenv {comments}
|
|
|
|
env\comments\
|
|
|
|
@end macro
|
2014-02-04 03:26:08 +08:00
|
|
|
@c Function accesses the assumed-constant hostid.
|
2014-01-29 15:20:37 +08:00
|
|
|
@macro mtshostid {comments}
|
|
|
|
hostid\comments\
|
|
|
|
@end macro
|
2014-02-04 03:26:08 +08:00
|
|
|
@c Function accesses the assumed-constant _sigintr variable.
|
2014-01-29 15:20:37 +08:00
|
|
|
@macro mtssigintr {comments}
|
|
|
|
sigintr\comments\
|
|
|
|
@end macro
|
2014-02-04 03:26:08 +08:00
|
|
|
@c Function performs MT-Unsafe initialization at the first call.
|
2014-01-29 15:20:37 +08:00
|
|
|
@macro mtuinit {comments}
|
|
|
|
init\comments\
|
|
|
|
@end macro
|
2014-02-04 03:26:08 +08:00
|
|
|
@c Function performs libc_once AS-Unsafe initialization.
|
2014-01-29 15:20:37 +08:00
|
|
|
@macro asuinit {comments}
|
|
|
|
init\comments\
|
|
|
|
@end macro
|
2014-02-04 03:26:08 +08:00
|
|
|
@c Function performs libc_once AC-Unsafe initialization.
|
2014-01-29 15:20:37 +08:00
|
|
|
@macro acuinit {comments}
|
|
|
|
init\comments\
|
|
|
|
@end macro
|
2014-02-04 03:26:08 +08:00
|
|
|
@c Function is AS-Unsafe because it takes a non-recursive mutex that may
|
|
|
|
@c already be held by the function interrupted by the signal.
|
2014-01-29 15:20:37 +08:00
|
|
|
@macro asulock {comments}
|
|
|
|
lock\comments\
|
|
|
|
@end macro
|
2014-02-04 03:26:08 +08:00
|
|
|
@c Function is AC-Unsafe because it may fail to release a mutex.
|
2014-01-29 15:20:37 +08:00
|
|
|
@macro aculock {comments}
|
|
|
|
lock\comments\
|
|
|
|
@end macro
|
2014-02-04 03:26:08 +08:00
|
|
|
@c Function is AS-Unsafe because some data structure may be inconsistent
|
|
|
|
@c due to an ongoing updated interrupted by a signal.
|
2014-01-29 15:20:37 +08:00
|
|
|
@macro asucorrupt {comments}
|
|
|
|
corrupt\comments\
|
|
|
|
@end macro
|
2014-02-04 03:26:08 +08:00
|
|
|
@c Function is AC-Unsafe because some data structure may be left
|
|
|
|
@c inconsistent when cancelled.
|
2014-01-29 15:20:37 +08:00
|
|
|
@macro acucorrupt {comments}
|
|
|
|
corrupt\comments\
|
|
|
|
@end macro
|
2014-02-04 03:26:08 +08:00
|
|
|
@c Function is AS- and AC-Unsafe because of malloc/free.
|
2014-01-29 15:20:37 +08:00
|
|
|
@macro ascuheap {comments}
|
|
|
|
heap\comments\
|
|
|
|
@end macro
|
2014-02-04 03:26:08 +08:00
|
|
|
@c Function is AS-Unsafe because of malloc/free.
|
2014-01-29 15:20:37 +08:00
|
|
|
@macro asuheap {comments}
|
|
|
|
heap\comments\
|
|
|
|
@end macro
|
2014-02-04 03:26:08 +08:00
|
|
|
@c Function is AS- and AC-Unsafe because of dlopen/dlclose.
|
2014-01-29 15:20:37 +08:00
|
|
|
@macro ascudlopen {comments}
|
|
|
|
dlopen\comments\
|
|
|
|
@end macro
|
2014-02-04 03:26:08 +08:00
|
|
|
@c Function is AS- and AC-Unsafe because of unknown plugins.
|
2014-01-29 15:20:37 +08:00
|
|
|
@macro ascuplugin {comments}
|
|
|
|
plugin\comments\
|
|
|
|
@end macro
|
2014-02-04 03:26:08 +08:00
|
|
|
@c Function is AS- and AC-Unsafe because of i18n.
|
2014-01-29 15:20:37 +08:00
|
|
|
@macro ascuintl {comments}
|
|
|
|
i18n\comments\
|
|
|
|
@end macro
|
2014-02-04 03:26:08 +08:00
|
|
|
@c Function is AS--Unsafe because of i18n.
|
2014-01-29 15:20:37 +08:00
|
|
|
@macro asuintl {comments}
|
|
|
|
i18n\comments\
|
|
|
|
@end macro
|
2014-02-04 03:26:08 +08:00
|
|
|
@c Function may leak file descriptors if async-cancelled.
|
2014-01-29 15:20:37 +08:00
|
|
|
@macro acsfd {comments}
|
|
|
|
fd\comments\
|
|
|
|
@end macro
|
2014-02-04 03:26:08 +08:00
|
|
|
@c Function may leak memory if async-cancelled.
|
2014-01-29 15:20:37 +08:00
|
|
|
@macro acsmem {comments}
|
|
|
|
mem\comments\
|
|
|
|
@end macro
|
2014-02-04 03:26:08 +08:00
|
|
|
@c Function is unsafe due to temporary overriding a signal handler.
|
2014-01-29 15:20:37 +08:00
|
|
|
@macro mtascusig {comments}
|
|
|
|
sig\comments\
|
|
|
|
@end macro
|
2014-02-04 03:26:08 +08:00
|
|
|
@c Function is MT- and AS-Unsafe due to temporarily changing attributes
|
|
|
|
@c of the controlling terminal.
|
2014-01-29 15:20:37 +08:00
|
|
|
@macro mtasuterm {comments}
|
|
|
|
term\comments\
|
|
|
|
@end macro
|
2014-02-04 03:26:08 +08:00
|
|
|
@c Function is AC-Unsafe for failing to restore attributes of the
|
|
|
|
@c controlling terminal.
|
2014-01-29 15:20:37 +08:00
|
|
|
@macro acuterm {comments}
|
|
|
|
term\comments\
|
|
|
|
@end macro
|
2014-02-04 03:26:08 +08:00
|
|
|
@c Function sets timers atomically.
|
2014-01-29 15:20:37 +08:00
|
|
|
@macro mtstimer {comments}
|
|
|
|
timer\comments\
|
|
|
|
@end macro
|
2014-02-04 03:26:08 +08:00
|
|
|
@c Function sets and restores timers.
|
2014-01-29 15:20:37 +08:00
|
|
|
@macro mtascutimer {comments}
|
|
|
|
timer\comments\
|
|
|
|
@end macro
|
2014-02-04 03:26:08 +08:00
|
|
|
@c Function temporarily changes the current working directory.
|
2014-01-29 15:20:37 +08:00
|
|
|
@macro mtasscwd {comments}
|
|
|
|
cwd\comments\
|
|
|
|
@end macro
|
2014-02-04 03:26:08 +08:00
|
|
|
@c Function may fail to restore to the original current working
|
|
|
|
@c directory after temporarily changing it.
|
2014-01-29 15:20:37 +08:00
|
|
|
@macro acscwd {comments}
|
|
|
|
cwd\comments\
|
|
|
|
@end macro
|
2014-02-04 03:26:08 +08:00
|
|
|
@c Function is MT-Safe while POSIX says it needn't be MT-Safe.
|
2014-01-29 15:20:37 +08:00
|
|
|
@macro mtsposix {comments}
|
|
|
|
!posix\comments\
|
|
|
|
@end macro
|
2014-02-04 03:26:08 +08:00
|
|
|
@c Function is MT-Unsafe while POSIX says it should be MT-Safe.
|
2014-01-29 15:20:37 +08:00
|
|
|
@macro mtuposix {comments}
|
|
|
|
!posix\comments\
|
|
|
|
@end macro
|
2014-02-04 03:26:08 +08:00
|
|
|
@c Function is AS-Safe while POSIX says it needn't be AS-Safe.
|
2014-01-29 15:20:37 +08:00
|
|
|
@macro assposix {comments}
|
|
|
|
!posix\comments\
|
|
|
|
@end macro
|
2014-02-04 03:26:08 +08:00
|
|
|
@c Function is AS-Unsafe while POSIX says it should be AS-Safe.
|
2014-01-29 15:20:37 +08:00
|
|
|
@macro asuposix {comments}
|
|
|
|
!posix\comments\
|
|
|
|
@end macro
|
2014-02-04 03:26:08 +08:00
|
|
|
@c Function is AC-Safe while POSIX says it needn't be AC-Safe.
|
2014-01-29 15:20:37 +08:00
|
|
|
@macro acsposix {comments}
|
|
|
|
!posix\comments\
|
|
|
|
@end macro
|
2014-02-04 03:26:08 +08:00
|
|
|
@c Function is AC-Unsafe while POSIX says it should be AC-Safe.
|
2014-01-29 15:20:37 +08:00
|
|
|
@macro acuposix {comments}
|
|
|
|
!posix\comments\
|
|
|
|
@end macro
|
|
|
|
|
2015-07-12 17:32:56 +08:00
|
|
|
@iftex
|
|
|
|
@macro twoexp{exp}
|
|
|
|
@math{2^{{\exp\}}}
|
|
|
|
@end macro
|
|
|
|
@end iftex
|
|
|
|
@ifnottex
|
|
|
|
@macro twoexp{exp}
|
|
|
|
2^\exp\
|
|
|
|
@end macro
|
|
|
|
@end ifnottex
|
|
|
|
|
manual: Convert errno @comments to new @errno macro.
errno.texi documents error macros, their values, and error strings in
Texinfo @comments, some of which are also used for @standards. The
purpose of this commit is to separate the standards from the error
strings so that both the @standards conversion script picks up clean
@standards and the errno documentation framework is improved.
The error names, values, and messages are consolidated in a new custom
macro, @errno. It is not clear that scripts within the sources rely
on the special Texinfo @comment-based format to generate files used
throughout the library, so the definition of @errno in macros.texi now
provides a comment indicating the dependency. The dependent scripts
are updated to use @errno, which also simplifies them a bit. The
files those scripts generate were verified to be unchanged.
The @errno macro is not visibly rendered in any way at this time, but
it does use an @cindex command to add the error string to the Concept
Index, to facilitate searching on error messages.
* manual/errno.texi: Convert @comment-based errno
documentation to @errno.
* manual/macros.texi (@errno): New macro. Consolidate errors,
their values, and messages, adding the error string to the
Concept Index. Provide a warning in the comment about
external (to the manual) dependencies.
* sysdeps/gnu/errlist.awk: Use @errno instead of @comments.
* sysdeps/mach/hurd/errnos.awk: Likewise.
2017-05-20 13:44:25 +08:00
|
|
|
@c Used by errlist.awk and errnos.awk to generate other files.
|
|
|
|
@c Note that error values have ABI implications for the Hurd.
|
|
|
|
@macro errno {err, val, str}
|
|
|
|
@cindex \str\
|
2017-06-01 17:07:01 +08:00
|
|
|
``\str\.''
|
manual: Convert errno @comments to new @errno macro.
errno.texi documents error macros, their values, and error strings in
Texinfo @comments, some of which are also used for @standards. The
purpose of this commit is to separate the standards from the error
strings so that both the @standards conversion script picks up clean
@standards and the errno documentation framework is improved.
The error names, values, and messages are consolidated in a new custom
macro, @errno. It is not clear that scripts within the sources rely
on the special Texinfo @comment-based format to generate files used
throughout the library, so the definition of @errno in macros.texi now
provides a comment indicating the dependency. The dependent scripts
are updated to use @errno, which also simplifies them a bit. The
files those scripts generate were verified to be unchanged.
The @errno macro is not visibly rendered in any way at this time, but
it does use an @cindex command to add the error string to the Concept
Index, to facilitate searching on error messages.
* manual/errno.texi: Convert @comment-based errno
documentation to @errno.
* manual/macros.texi (@errno): New macro. Consolidate errors,
their values, and messages, adding the error string to the
Concept Index. Provide a warning in the comment about
external (to the manual) dependencies.
* sysdeps/gnu/errlist.awk: Use @errno instead of @comments.
* sysdeps/mach/hurd/errnos.awk: Likewise.
2017-05-20 13:44:25 +08:00
|
|
|
@end macro
|
|
|
|
|
2012-02-28 22:44:20 +08:00
|
|
|
@end ifclear
|