* Re: [PATCH] man-pages(7): Add attributive annotation advice
2023-07-20 8:24 ` Alejandro Colomar
@ 2023-07-20 9:14 ` G. Branden Robinson
0 siblings, 0 replies; 5+ messages in thread
From: G. Branden Robinson @ 2023-07-20 9:14 UTC (permalink / raw)
To: Alejandro Colomar; +Cc: linux-man
[-- Attachment #1.1: Type: text/plain, Size: 504 bytes --]
Hi Alex,
At 2023-07-20T10:24:18+0200, Alejandro Colomar wrote:
> A gzip works,
And it did! I see it on lore.kernel.org.
> although in such cases of scripted patches, you can just send the
> header of the patch, and maybe the first pages to allow me to check
> the results of the script, and then I will reproduce the patch myself
> by running the script.
I did not include my annotations of the changes I observed when applying
it. I hope this will save you some time. Attached.
Regards,
Branden
[-- Attachment #1.2: dump-annotated.diff --]
[-- Type: text/x-diff, Size: 43509 bytes --]
Annotation key:
[MR]: Hyphenation will be suppressed by migration to `MR` macro.
[CH]: Change in hyphenation break location due to undesired change of
hyphenation mode by former use of `.hy` request outside of tbl(1)
data, which caused the hyphenation mode to be set to "1", which
works suboptimally with the TeX-based hyphenation patterns groff
has used since around 1990. (A better value for English is 4, and
this is used by default [unless loading of troffrc is suppressed]
in groff 1.23.0. I have further ideas to improve quality-of-life
around groff hyphenation; please raise the subject on groff@gnu if
interested.)
[HY]: New hyphenation breaks appear because I only disabled hyphenation
in text blocks that seemed to need it; that is, in the "Interface"
column of "MT-safety" tables, where the only cell content is a
list of C function names. Two text blocks in namespaces(7) were
ordinary prose that, other things being equal, should be formatted
ordinarily.
--- DUMP1 2023-07-19 20:18:36.754653394 -0500
+++ DUMP2 2023-07-19 20:18:48.274710984 -0500
@@ -15162,8 +15162,9 @@
SEE ALSO
prlimit(1), dup(2), fcntl(2), fork(2), getrusage(2), mlock(2), mmap(2),
- open(2), quotactl(2), sbrk(2), shmctl(2), malloc(3), sigqueue(3), ulim‐
- it(3), core(5), capabilities(7), cgroups(7), credentials(7), signal(7)
+ open(2), quotactl(2), sbrk(2), shmctl(2), malloc(3), sigqueue(3),
+ ulimit(3), core(5), capabilities(7), cgroups(7), credentials(7), sig‐
+ nal(7)
[MR]
Linux man‐pages (unreleased) (date) getrlimit(2)
───────────────────────────────────────────────────────────────────────────────
@@ -26226,8 +26227,8 @@
Certain flags constants are defined only if suitable feature test
macros are defined (possibly by default): _DEFAULT_SOURCE with glibc
- 2.19 or later; or _BSD_SOURCE or _SVID_SOURCE in glibc 2.19 and earli‐
- er. (Employing _GNU_SOURCE also suffices, and requiring that macro
+ 2.19 or later; or _BSD_SOURCE or _SVID_SOURCE in glibc 2.19 and ear‐
+ lier. (Employing _GNU_SOURCE also suffices, and requiring that macro
[CH]
specifically would have been more logical, since these flags are all
Linux‐specific.) The relevant flags are: MAP_32BIT, MAP_ANONYMOUS (and
the synonym MAP_ANON), MAP_DENYWRITE, MAP_EXECUTABLE, MAP_FILE,
@@ -51676,8 +51677,8 @@
the inclusion of SS_ONSTACK in ss.ss_flags is a no‐op). On other im‐
plementations, and according to POSIX.1, SS_ONSTACK appears only as a
reported flag in old_ss.ss_flags. On Linux, there is no need ever to
- specify SS_ONSTACK in ss.ss_flags, and indeed doing so should be avoid‐
- ed on portability grounds: various other systems give an error if
+ specify SS_ONSTACK in ss.ss_flags, and indeed doing so should be
+ avoided on portability grounds: various other systems give an error if
[CH]
SS_ONSTACK is specified in ss.ss_flags.
EXAMPLES
@@ -64251,19 +64252,20 @@
These functions make some assumptions about how a function’s return ad‐
dress is stored on the stack. Note the following:
- • Omission of the frame pointers (as implied by any of gcc(1)’s nonze‐
- ro optimization levels) may cause these assumptions to be violated.
+ • Omission of the frame pointers (as implied by any of gcc(1)’s
+ nonzero optimization levels) may cause these assumptions to be vio‐
+ lated.
[CH]
• Inlined functions do not have stack frames.
• Tail‐call optimization causes one stack frame to replace another.
- • backtrace() and backtrace_symbols_fd() don’t call malloc() explicit‐
- ly, but they are part of libgcc, which gets loaded dynamically when
- first used. Dynamic loading usually triggers a call to malloc(3).
- If you need certain calls to these two functions to not allocate
- memory (in signal handlers, for example), you need to make sure
- libgcc is loaded beforehand.
+ • backtrace() and backtrace_symbols_fd() don’t call malloc() explic‐
+ itly, but they are part of libgcc, which gets loaded dynamically
+ when first used. Dynamic loading usually triggers a call to mal‐
+ loc(3). If you need certain calls to these two functions to not al‐
+ locate memory (in signal handlers, for example), you need to make
+ sure libgcc is loaded beforehand.
[CH]
[MR] (malloc(3))
The symbol names may be unavailable without the use of special linker
options. For systems using the GNU linker, it is necessary to use the
@@ -65238,8 +65240,8 @@
by a correct program, then it may remove the bzero() call altogether.
This is a problem if the intent of the bzero() call was to erase sensi‐
tive data (e.g., passwords) to prevent the possibility that the data
- was leaked by an incorrect or compromised program. Calls to explic‐
- it_bzero() are never optimized away by the compiler.
+ was leaked by an incorrect or compromised program. Calls to ex‐
+ plicit_bzero() are never optimized away by the compiler.
[CH]
The explicit_bzero() function does not solve all problems associated
with erasing sensitive data:
@@ -66177,8 +66179,8 @@
rno to ERANGE, or raise an FE_OVERFLOW exception). In practice, the
result cannot overflow on any current machine, so this error‐handling
stuff is just nonsense. (More precisely, overflow can happen only when
- the maximum value of the exponent is smaller than the number of mantis‐
- sa bits. For the IEEE‐754 standard 32‐bit and 64‐bit floating‐point
+ the maximum value of the exponent is smaller than the number of man‐
+ tissa bits. For the IEEE‐754 standard 32‐bit and 64‐bit floating‐point
[CH]
numbers the maximum value of the exponent is 127 (respectively, 1023),
and the number of mantissa bits including the implicit bit is 24 (re‐
spectively, 53).)
@@ -68463,10 +68465,10 @@
and does not employ the double‐fork technique (i.e., fork(2), set‐
sid(2), fork(2)) that is necessary to ensure that the resulting daemon
process is not a session leader. Instead, the resulting daemon is a
- session leader. On systems that follow System V semantics (e.g., Lin‐
- ux), this means that if the daemon opens a terminal that is not already
- a controlling terminal for another session, then that terminal will in‐
- advertently become the controlling terminal for the daemon.
+ session leader. On systems that follow System V semantics (e.g.,
+ Linux), this means that if the daemon opens a terminal that is not al‐
+ ready a controlling terminal for another session, then that terminal
+ will inadvertently become the controlling terminal for the daemon.
[CH]
SEE ALSO
fork(2), setsid(2), daemon(7), logrotate(8)
@@ -69169,10 +69171,10 @@
dlpi_phdr, and dlpi_phnum in addition to other implementation‐specific
fields.
- Future versions of the C library may add further fields to the dl_ph‐
- dr_info structure; in that event, the size argument provides a mecha‐
- nism for the callback function to discover whether it is running on a
- system with added fields.
+ Future versions of the C library may add further fields to the
+ dl_phdr_info structure; in that event, the size argument provides a
+ mechanism for the callback function to discover whether it is running
+ on a system with added fields.
[CH]
STANDARDS
None.
@@ -70202,13 +70204,13 @@
NOTES
There are several scenarios when the address of a global symbol is
- NULL. For example, a symbol can be placed at zero address by the link‐
- er, via a linker script or with --defsym command‐line option. Unde‐
- fined weak symbols also have NULL value. Finally, the symbol value may
- be the result of a GNU indirect function (IFUNC) resolver function that
- returns NULL as the resolved value. In the latter case, dlsym() also
- returns NULL without error. However, in the former two cases, the be‐
- havior of GNU dynamic linker is inconsistent: relocation processing
+ NULL. For example, a symbol can be placed at zero address by the
+ linker, via a linker script or with --defsym command‐line option. Un‐
+ defined weak symbols also have NULL value. Finally, the symbol value
+ may be the result of a GNU indirect function (IFUNC) resolver function
+ that returns NULL as the resolved value. In the latter case, dlsym()
+ also returns NULL without error. However, in the former two cases, the
+ behavior of GNU dynamic linker is inconsistent: relocation processing
[CH]
succeeds and the symbol can be observed to have NULL value, but dlsym()
fails and dlerror() indicates a lookup error.
@@ -72116,8 +72118,8 @@
AT_EACCESS and AT_SYMLINK_NOFOLLOW.
SEE ALSO
- access(2), chmod(2), chown(2), faccessat(2), open(2), setgid(2), setu‐
- id(2), stat(2), credentials(7), path_resolution(7)
+ access(2), chmod(2), chown(2), faccessat(2), open(2), setgid(2), se‐
+ tuid(2), stat(2), credentials(7), path_resolution(7)
[MR]
Linux man‐pages (unreleased) (date) euidaccess(3)
───────────────────────────────────────────────────────────────────────────────
@@ -72414,13 +72416,13 @@
Except in the above cases, where the signalled processes may be chil‐
dren of the terminating process, termination of a process does not in
- general cause a signal to be sent to children of that process. Howev‐
- er, a process can use the prctl(2) PR_SET_PDEATHSIG operation to
+ general cause a signal to be sent to children of that process. How‐
+ ever, a process can use the prctl(2) PR_SET_PDEATHSIG operation to
[CH]
arrange that it receives a signal if its parent terminates.
SEE ALSO
- _exit(2), get_robust_list(2), setpgid(2), wait(2), atexit(3), on_ex‐
- it(3), tmpfile(3)
+ _exit(2), get_robust_list(2), setpgid(2), wait(2), atexit(3),
+ on_exit(3), tmpfile(3)
[MR]
Linux man‐pages (unreleased) (date) exit(3)
───────────────────────────────────────────────────────────────────────────────
@@ -73545,9 +73547,9 @@
NOTES
It is not advisable to mix calls to input functions from the stdio li‐
- brary with low‐level calls to read(2) for the file descriptor associat‐
- ed with the input stream; the results will be undefined and very proba‐
- bly not what you want.
+ brary with low‐level calls to read(2) for the file descriptor associ‐
+ ated with the input stream; the results will be undefined and very
+ probably not what you want.
[CH]
SEE ALSO
read(2), write(2), ferror(3), fgetwc(3), fgetws(3), fopen(3), fread(3),
@@ -73823,8 +73825,8 @@
it is reasonable to expect that fgetws() will actually read a multibyte
string from the stream and then convert it to a wide‐character string.
- This function is unreliable, because it does not permit to deal proper‐
- ly with null wide characters that may be present in the input.
+ This function is unreliable, because it does not permit to deal prop‐
+ erly with null wide characters that may be present in the input.
[CH]
SEE ALSO
fgetwc(3), unlocked_stdio(3)
@@ -74117,8 +74119,8 @@
rno to ERANGE, or raise an FE_OVERFLOW exception). In practice, the
result cannot overflow on any current machine, so this error‐handling
stuff is just nonsense. (More precisely, overflow can happen only when
- the maximum value of the exponent is smaller than the number of mantis‐
- sa bits. For the IEEE‐754 standard 32‐bit and 64‐bit floating‐point
+ the maximum value of the exponent is smaller than the number of man‐
+ tissa bits. For the IEEE‐754 standard 32‐bit and 64‐bit floating‐point
[CH]
numbers the maximum value of the exponent is 127 (respectively, 1023),
and the number of mantissa bits including the implicit bit is 24 (re‐
spectively, 53).)
@@ -74407,10 +74409,10 @@
BUGS
Before glibc 2.22, if size is specified as zero, fmemopen() fails with
- the error EINVAL. It would be more consistent if this case successful‐
- ly created a stream that then returned end‐of‐file on the first attempt
- at reading; since glibc 2.22, the glibc implementation provides that
- behavior.
+ the error EINVAL. It would be more consistent if this case success‐
+ fully created a stream that then returned end‐of‐file on the first at‐
+ tempt at reading; since glibc 2.22, the glibc implementation provides
+ that behavior.
[CH]
Before glibc 2.22, specifying append mode ("a" or "a+") for fmemopen()
sets the initial buffer position to the first null byte, but (if the
@@ -82129,10 +82131,10 @@
VERSIONS
POSIX specifies that the argv array argument should be const, but these
- functions permute its elements unless the environment variable POSIX‐
- LY_CORRECT is set. const is used in the actual prototype to be compat‐
- ible with other systems; however, this page doesn’t show the qualifier,
- to avoid confusing readers.
+ functions permute its elements unless the environment variable
+ POSIXLY_CORRECT is set. const is used in the actual prototype to be
+ compatible with other systems; however, this page doesn’t show the
+ qualifier, to avoid confusing readers.
[CH]
STANDARDS
getopt()
@@ -82157,8 +82159,8 @@
NOTES
A program that scans multiple argument vectors, or rescans the same
vector more than once, and wants to make use of GNU extensions such as
- '+' and '-' at the start of optstring, or changes the value of POSIX‐
- LY_CORRECT between scans, must reinitialize getopt() by resetting
+ '+' and '-' at the start of optstring, or changes the value of
+ POSIXLY_CORRECT between scans, must reinitialize getopt() by resetting
[CH]
optind to 0, rather than the traditional value of 1. (Resetting to 0
forces the invocation of an internal initialization routine that
rechecks POSIXLY_CORRECT and checks for GNU extensions in optstring.)
@@ -86999,8 +87001,8 @@
This is still what you will get if _GNU_SOURCE is defined before in‐
cluding <search.h>.
- The location of the prototypes for these functions differs among sever‐
- al versions of UNIX. The above is the POSIX version. Some systems
+ The location of the prototypes for these functions differs among sev‐
+ eral versions of UNIX. The above is the POSIX version. Some systems
[CH]
place them in <string.h>.
STANDARDS
@@ -89391,9 +89393,9 @@
SEE ALSO
fcntl(2), flock(2)
- locks.txt and mandatory-locking.txt in the Linux kernel source directo‐
- ry Documentation/filesystems (on older kernels, these files are direct‐
- ly under the Documentation directory, and mandatory-locking.txt is
+ locks.txt and mandatory-locking.txt in the Linux kernel source direc‐
+ tory Documentation/filesystems (on older kernels, these files are di‐
+ rectly under the Documentation directory, and mandatory-locking.txt is
[CH]
called mandatory.txt)
Linux man‐pages (unreleased) (date) lockf(3)
@@ -90237,20 +90239,20 @@
use POSIX threads instead.
NOTES
- The interpretation of ucp->uc_stack is just as in sigaltstack(2), name‐
- ly, this struct contains the start and length of a memory area to be
- used as the stack, regardless of the direction of growth of the stack.
- Thus, it is not necessary for the user program to worry about this di‐
- rection.
+ The interpretation of ucp->uc_stack is just as in sigaltstack(2),
+ namely, this struct contains the start and length of a memory area to
+ be used as the stack, regardless of the direction of growth of the
+ stack. Thus, it is not necessary for the user program to worry about
+ this direction.
[CH]
On architectures where int and pointer types are the same size (e.g.,
x86‐32, where both types are 32 bits), you may be able to get away with
- passing pointers as arguments to makecontext() following argc. Howev‐
- er, doing this is not guaranteed to be portable, is undefined according
- to the standards, and won’t work on architectures where pointers are
- larger than ints. Nevertheless, starting with glibc 2.8, glibc makes
- some changes to makecontext(), to permit this on some 64‐bit architec‐
- tures (e.g., x86‐64).
+ passing pointers as arguments to makecontext() following argc. How‐
+ ever, doing this is not guaranteed to be portable, is undefined accord‐
+ ing to the standards, and won’t work on architectures where pointers
+ are larger than ints. Nevertheless, starting with glibc 2.8, glibc
+ makes some changes to makecontext(), to permit this on some 64‐bit ar‐
+ chitectures (e.g., x86‐64).
[CH]
EXAMPLES
The example program below demonstrates the use of getcontext(3), make‐
@@ -90512,8 +90514,8 @@
EXAMPLES
The program below employs mallinfo2() to retrieve memory allocation
- statistics before and after allocating and freeing some blocks of memo‐
- ry. The statistics are displayed on standard output.
+ statistics before and after allocating and freeing some blocks of mem‐
+ ory. The statistics are displayed on standard output.
[CH]
The first two command‐line arguments specify the number and size of
blocks to be allocated with malloc(3).
@@ -90832,8 +90834,8 @@
tions; see "Replacing malloc" in the glibc manual for details.
Crashes in memory allocators are almost always related to heap corrup‐
- tion, such as overflowing an allocated chunk or freeing the same point‐
- er twice.
+ tion, such as overflowing an allocated chunk or freeing the same
+ pointer twice.
[CH]
The malloc() implementation is tunable via environment variables; see
mallopt(3) for details.
@@ -93728,8 +93730,8 @@
glibc 2.4. POSIX.1‐2008.
SEE ALSO
- mkfifo(1), close(2), open(2), read(2), stat(2), umask(2), write(2), fi‐
- fo(7)
+ mkfifo(1), close(2), open(2), read(2), stat(2), umask(2), write(2),
+ fifo(7)
[CH] (but would also be addressed by [MR])
Linux man‐pages (unreleased) (date) mkfifo(3)
───────────────────────────────────────────────────────────────────────────────
@@ -96025,8 +96027,8 @@
None.
HISTORY
- SunOS 4, glibc. Removed in Solaris (SunOS 5). Use the standard atex‐
- it(3) instead.
+ SunOS 4, glibc. Removed in Solaris (SunOS 5). Use the standard
+ atexit(3) instead.
[CH] (but would also be addressed by [MR])
CAVEATS
By the time function is executed, stack (auto) variables may already
@@ -98160,8 +98162,8 @@
Code such as printf(foo); often indicates a bug, since foo may contain
a % character. If foo comes from untrusted user input, it may contain
- %n, causing the printf() call to write to memory and creating a securi‐
- ty hole.
+ %n, causing the printf() call to write to memory and creating a secu‐
+ rity hole.
[CH]
EXAMPLES
To print Pi to five decimal places:
@@ -99386,10 +99388,10 @@
NOTES
The PTHREAD_SCOPE_SYSTEM contention scope typically indicates that a
- user‐space thread is bound directly to a single kernel‐scheduling enti‐
- ty. This is the case on Linux for the obsolete LinuxThreads implemen‐
- tation and the modern NPTL implementation, which are both 1:1 threading
- implementations.
+ user‐space thread is bound directly to a single kernel‐scheduling en‐
+ tity. This is the case on Linux for the obsolete LinuxThreads imple‐
+ mentation and the modern NPTL implementation, which are both 1:1
+ threading implementations.
[CH]
POSIX.1 specifies that the default contention scope is implementation‐
defined.
@@ -99466,8 +99468,8 @@
NOTES
The signal mask attribute determines the signal mask that will be as‐
signed to a thread created using the thread attributes object attr. If
- this attribute is not set, then a thread created using attr will inher‐
- it a copy of the creating thread’s signal mask.
+ this attribute is not set, then a thread created using attr will in‐
+ herit a copy of the creating thread’s signal mask.
[CH]
For more details on signal masks, see sigprocmask(2). For a descrip‐
tion of a set of macros that can be used to manipulate and inspect sig‐
@@ -100684,8 +100686,8 @@
NOTES
The pthread_equal() function is necessary because thread IDs should be
- considered opaque: there is no portable way for applications to direct‐
- ly compare two pthread_t values.
+ considered opaque: there is no portable way for applications to di‐
+ rectly compare two pthread_t values.
[CH]
SEE ALSO
pthread_create(3), pthread_self(3), pthreads(7)
@@ -101361,8 +101363,8 @@
}
SEE ALSO
- clock_gettime(2), clock_settime(2), timer_create(2), clock_getcpuclock‐
- id(3), pthread_self(3), pthreads(7), time(7)
+ clock_gettime(2), clock_settime(2), timer_create(2), clock_getcpu‐
+ clockid(3), pthread_self(3), pthreads(7), time(7)
[MR]
Linux man‐pages (unreleased) (date) pthread_getcpuclockid(3)
───────────────────────────────────────────────────────────────────────────────
@@ -101443,8 +101445,8 @@
threads (or processes).
There is no pthreads analog of waitpid(-1, &status, 0), that is, "join
- with any terminated thread". If you believe you need this functionali‐
- ty, you probably need to rethink your application design.
+ with any terminated thread". If you believe you need this functional‐
+ ity, you probably need to rethink your application design.
[CH]
All of the threads in a process are peers: any thread can join with any
other thread in the process.
@@ -101453,8 +101455,8 @@
See pthread_create(3).
SEE ALSO
- pthread_cancel(3), pthread_create(3), pthread_detach(3), pthread_ex‐
- it(3), pthread_tryjoin_np(3), pthreads(7)
+ pthread_cancel(3), pthread_create(3), pthread_detach(3),
+ pthread_exit(3), pthread_tryjoin_np(3), pthreads(7)
[MR]
Linux man‐pages (unreleased) (date) pthread_join(3)
───────────────────────────────────────────────────────────────────────────────
@@ -102729,13 +102731,13 @@
In the following run, the main thread sets its scheduling policy to
SCHED_FIFO with a priority of 10, and initializes a thread attributes
object with a scheduling policy attribute of SCHED_RR and a scheduling
- priority attribute of 20. The program then sets (using pthread_at‐
- tr_setinheritsched(3)) the inherit scheduler attribute of the thread
- attributes object to PTHREAD_EXPLICIT_SCHED, meaning that threads cre‐
- ated using this attributes object should take their scheduling attrib‐
- utes from the thread attributes object. The program then creates a
- thread using the thread attributes object, and that thread displays its
- scheduling policy and priority.
+ priority attribute of 20. The program then sets (using
+ pthread_attr_setinheritsched(3)) the inherit scheduler attribute of the
+ thread attributes object to PTHREAD_EXPLICIT_SCHED, meaning that
+ threads created using this attributes object should take their schedul‐
+ ing attributes from the thread attributes object. The program then
+ creates a thread using the thread attributes object, and that thread
+ displays its scheduling policy and priority.
[CH] (but the first hyphenation break would also be addressed by [MR])
$ su # Need privilege to set real-time scheduling policies
Password:
@@ -102750,8 +102752,8 @@
Scheduler attributes of new thread
policy=SCHED_RR, priority=20
- In the above output, one can see that the scheduling policy and priori‐
- ty were taken from the values specified in the thread attributes ob‐
+ In the above output, one can see that the scheduling policy and prior‐
+ ity were taken from the values specified in the thread attributes ob‐
[CH]
ject.
The next run is the same as the previous, except that the inherit
@@ -102771,8 +102773,8 @@
Scheduler attributes of new thread
policy=SCHED_FIFO, priority=10
- In the above output, one can see that the scheduling policy and priori‐
- ty were taken from the creating thread, rather than the thread attrib‐
+ In the above output, one can see that the scheduling policy and prior‐
+ ity were taken from the creating thread, rather than the thread attrib‐
[CH]
utes object.
Note that if we had omitted the -i i option, the output would have been
@@ -103572,9 +103574,9 @@
BUGS
The pthread_timedjoin_np() function measures time by internally calcu‐
lating a relative sleep interval that is then measured against the
- CLOCK_MONOTONIC clock instead of the CLOCK_REALTIME clock. Consequent‐
- ly, the timeout is unaffected by discontinuous changes to the CLOCK_RE‐
- ALTIME clock.
+ CLOCK_MONOTONIC clock instead of the CLOCK_REALTIME clock. Conse‐
+ quently, the timeout is unaffected by discontinuous changes to the
+ CLOCK_REALTIME clock.
[CH]
EXAMPLES
The following code waits to join for up to 5 seconds:
@@ -104528,9 +104530,9 @@
NOTES
Random‐number generation is a complex topic. Numerical Recipes in C:
The Art of Scientific Computing (William H. Press, Brian P. Flannery,
- Saul A. Teukolsky, William T. Vetterling; New York: Cambridge Universi‐
- ty Press, 2007, 3rd ed.) provides an excellent discussion of practical
- random‐number generation issues in Chapter 7 (Random Numbers).
+ Saul A. Teukolsky, William T. Vetterling; New York: Cambridge Univer‐
+ sity Press, 2007, 3rd ed.) provides an excellent discussion of practi‐
+ cal random‐number generation issues in Chapter 7 (Random Numbers).
[CH]
For a more theoretical discussion which also covers many practical is‐
sues in depth, see Chapter 3 (Random Numbers) in Donald E. Knuth’s The
@@ -105008,10 +105010,10 @@
unspecified size, with at most NAME_MAX characters preceding the termi‐
nating null byte ('\0').
- POSIX.1 explicitly notes that this field should not be used as an lval‐
- ue. The standard also notes that the use of sizeof(d_name) is incor‐
- rect; use strlen(d_name) instead. (On some systems, this field is de‐
- fined as char d_name[1]!) By implication, the use sizeof(struct
+ POSIX.1 explicitly notes that this field should not be used as an
+ lvalue. The standard also notes that the use of sizeof(d_name) is in‐
+ correct; use strlen(d_name) instead. (On some systems, this field is
+ defined as char d_name[1]!) By implication, the use sizeof(struct
dirent) to capture the size of the record including the size of d_name
is also incorrect.
[CH]
@@ -105021,8 +105023,8 @@
returns the value 255 for most filesystems, on some filesystems (e.g.,
CIFS, Windows SMB servers), the null‐terminated filename that is (cor‐
- rectly) returned in d_name can actually exceed this size. In such cas‐
- es, the d_reclen field will contain a value that exceeds the size of
+ rectly) returned in d_name can actually exceed this size. In such
+ cases, the d_reclen field will contain a value that exceeds the size of
[CH]
the glibc dirent structure shown above.
STANDARDS
@@ -106501,8 +106503,8 @@
rno to ERANGE, or raise an FE_OVERFLOW exception). In practice, the
result cannot overflow on any current machine, so this error‐handling
stuff is just nonsense. (More precisely, overflow can happen only when
- the maximum value of the exponent is smaller than the number of mantis‐
- sa bits. For the IEEE‐754 standard 32‐bit and 64‐bit floating‐point
+ the maximum value of the exponent is smaller than the number of man‐
+ tissa bits. For the IEEE‐754 standard 32‐bit and 64‐bit floating‐point
[CH]
numbers the maximum value of the exponent is 127 (respectively, 1023),
and the number of mantissa bits including the implicit bit is 24 (re‐
spectively, 53).)
@@ -109348,11 +109350,11 @@
mends avoiding the use of these functions from signal handlers and goes
on to point out that if these functions are called from a signal han‐
dler that interrupted a call to a non‐async‐signal‐safe function (or
- some equivalent, such as the steps equivalent to exit(3) that occur up‐
- on a return from the initial call to main()), the behavior is undefined
- if the program subsequently makes a call to a non‐async‐signal‐safe
- function. The only way of avoiding undefined behavior is to ensure one
- of the following:
+ some equivalent, such as the steps equivalent to exit(3) that occur
+ upon a return from the initial call to main()), the behavior is unde‐
+ fined if the program subsequently makes a call to a non‐async‐signal‐
+ safe function. The only way of avoiding undefined behavior is to en‐
+ sure one of the following:
[CH]
• After long jumping from the signal handler, the program does not
call any non‐async‐signal‐safe functions and does not return from
@@ -109416,12 +109418,12 @@
If locale is an empty string, "", each part of the locale that should
be modified is set according to the environment variables. The details
- are implementation‐dependent. For glibc, first (regardless of catego‐
- ry), the environment variable LC_ALL is inspected, next the environment
- variable with the same name as the category (see the table above), and
- finally the environment variable LANG. The first existing environment
- variable is used. If its value is not a valid locale specification,
- the locale is unchanged, and setlocale() returns NULL.
+ are implementation‐dependent. For glibc, first (regardless of cate‐
+ gory), the environment variable LC_ALL is inspected, next the environ‐
+ ment variable with the same name as the category (see the table above),
+ and finally the environment variable LANG. The first existing environ‐
+ ment variable is used. If its value is not a valid locale specifica‐
+ tion, the locale is unchanged, and setlocale() returns NULL.
[CH]
The locale "C" or "POSIX" is a portable locale; it exists on all con‐
forming systems.
@@ -109460,8 +109462,8 @@
honored.
ATTRIBUTES
- For an explanation of the terms used in this section, see attribut‐
- es(7).
+ For an explanation of the terms used in this section, see attrib‐
+ utes(7).
[MR]
┌────────────────────────┬───────────────┬────────────────────────────┐
│ Interface │ Attribute │ Value │
├────────────────────────┼───────────────┼────────────────────────────┤
@@ -109836,8 +109838,8 @@
Program source: pshm_ucase.h
The following header file is included by both programs below. Its pri‐
- mary purpose is to define a structure that will be imposed on the memo‐
- ry object that is shared between the two programs.
+ mary purpose is to define a structure that will be imposed on the mem‐
+ ory object that is shared between the two programs.
[CH]
#include <fcntl.h>
#include <semaphore.h>
@@ -109870,8 +109872,8 @@
semaphores inside the object to 0.
After the "send" program has posted the first of the semaphores, the
- "bounce" program upper cases the data that has been placed in the memo‐
- ry by the "send" program and then posts the second semaphore to tell
+ "bounce" program upper cases the data that has been placed in the mem‐
+ ory by the "send" program and then posts the second semaphore to tell
[CH]
the "send" program that it may now access the shared memory.
/* pshm_ucase_bounce.c
@@ -110849,8 +110851,8 @@
See pthread_sigmask(3).
SEE ALSO
- sigaction(2), signalfd(2), sigpending(2), sigsuspend(2), sigwaitin‐
- fo(2), sigsetops(3), signal(7)
+ sigaction(2), signalfd(2), sigpending(2), sigsuspend(2), sigwait‐
+ info(2), sigsetops(3), signal(7)
[MR]
Linux man‐pages (unreleased) (date) sigwait(3)
───────────────────────────────────────────────────────────────────────────────
@@ -114260,8 +114262,8 @@
strftime_l()
POSIX.1‐2008.
- There are strict inclusions between the set of conversions given in AN‐
- SI C (unmarked), those given in the Single UNIX Specification (marked
+ There are strict inclusions between the set of conversions given in
+ ANSI C (unmarked), those given in the Single UNIX Specification (marked
[CH]
SU), those given in Olson’s timezone package (marked TZ), and those
given in glibc (marked GNU), except that %+ is not supported in glibc2.
On the other hand glibc2 has several more extensions. POSIX.1 only
@@ -114310,8 +114312,8 @@
^ Convert alphabetic characters in result string to uppercase.
# Swap the case of the result string. (This flag works only with
- certain conversion specifier characters, and of these, it is on‐
- ly really useful with %Z.)
+ certain conversion specifier characters, and of these, it is
+ only really useful with %Z.)
[CH]
An optional decimal width specifier may follow the (possibly absent)
flag. If the natural size of the field is smaller than this width,
@@ -115457,8 +115459,8 @@
VERSIONS
In the glibc implementation, the n‐char‐sequence that optionally fol‐
lows "NAN" is interpreted as an integer number (with an optional ’0’ or
- ’0x’ prefix to select base 8 or 16) that is to be placed in the mantis‐
- sa component of the returned value.
+ ’0x’ prefix to select base 8 or 16) that is to be placed in the man‐
+ tissa component of the returned value.
[CH]
STANDARDS
C11, POSIX.1‐2008.
@@ -115710,8 +115712,8 @@
exit(EXIT_SUCCESS);
}
- Another example program using strtok() can be found in getaddrin‐
- fo_a(3).
+ Another example program using strtok() can be found in getad‐
+ drinfo_a(3).
[MR]
SEE ALSO
memchr(3), strchr(3), string(3), strpbrk(3), strsep(3), strspn(3),
@@ -116805,8 +116807,8 @@
system(" -unfortunate-command-name");
SEE ALSO
- sh(1), execve(2), fork(2), sigaction(2), sigprocmask(2), wait(2), ex‐
- ec(3), signal(7)
+ sh(1), execve(2), fork(2), sigaction(2), sigprocmask(2), wait(2),
+ exec(3), signal(7)
[MR]
Linux man‐pages (unreleased) (date) system(3)
───────────────────────────────────────────────────────────────────────────────
@@ -118358,9 +118360,9 @@
Before glibc 2.19, the glibc implementation of these functions did not
set errno to ERANGE on an underflow range error.
- In glibc versions 2.3.3 and earlier, an argument of +0 or -0 incorrect‐
- ly produced a domain error (errno set to EDOM and an FE_INVALID excep‐
- tion raised), rather than a pole error.
+ In glibc versions 2.3.3 and earlier, an argument of +0 or -0 incor‐
+ rectly produced a domain error (errno set to EDOM and an FE_INVALID ex‐
+ ception raised), rather than a pole error.
[CH]
SEE ALSO
gamma(3), lgamma(3)
@@ -120347,8 +120349,8 @@
Only the EINVAL error return is documented by SUSv2 and POSIX.1‐2001.
CAVEATS
- The interaction of this function with the SIGALRM signal, and with oth‐
- er timer functions such as alarm(2), sleep(3), nanosleep(2),
+ The interaction of this function with the SIGALRM signal, and with
+ other timer functions such as alarm(2), sleep(3), nanosleep(2),
[CH]
setitimer(2), timer_create(2), timer_delete(2), timer_getoverrun(2),
timer_gettime(2), timer_settime(2), ualarm(3) is unspecified.
@@ -122641,8 +122643,8 @@
ing their Unicode (ISO/IEC 10646) code point, but other platforms don’t
do this. Also, the use of C99 universal character names of the form
\unnnn does not solve this problem.) Therefore, in internationalized
- programs, the format string should consist of ASCII wide characters on‐
- ly, or should be constructed at run time in an internationalized way
+ programs, the format string should consist of ASCII wide characters
+ only, or should be constructed at run time in an internationalized way
[CH]
(e.g., using gettext(3) or iconv(3), followed by mbstowcs(3)).
SEE ALSO
@@ -164342,8 +164344,8 @@
umn is a summary of the resources that are isolated by the namespace
type.
Namespace Flag Page Isolates
- Cgroup CLONE_NEWCGROUP cgroup_namespaces(7) Cgroup root
- directory
+ Cgroup CLONE_NEWCGROUP cgroup_namespaces(7) Cgroup root di‐
+ rectory
[HY]
IPC CLONE_NEWIPC ipc_namespaces(7) System V IPC,
POSIX message
queues
@@ -164352,8 +164354,8 @@
etc.
Mount CLONE_NEWNS mount_namespaces(7) Mount points
PID CLONE_NEWPID pid_namespaces(7) Process IDs
- Time CLONE_NEWTIME time_namespaces(7) Boot and
- monotonic clocks
+ Time CLONE_NEWTIME time_namespaces(7) Boot and monoto‐
+ nic clocks
[HY]
User CLONE_NEWUSER user_namespaces(7) User and group
IDs
UTS CLONE_NEWUTS uts_namespaces(7) Hostname and NIS
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 5+ messages in thread