Generally, place '||' at start of a line, rather than the end of
the previous line.
Rationale: this placement clearly indicates that that each piece
is an alternative.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Different source styles are used in different pages to achieve the
same formatted output, and in some cases the source mark-up is a
rather convoluted combination of .RS/.RE/.TP/.PD macros. Simplify
this greatly, and unify all of the pages to use more or less the
same source code style. This makes the source code rather easier
to read, and may simplify future scripted global changes.
The feature test macro info is currently bracketed by .nf/.fi
pairs. This is not strictly necessary (i.e., it makes no
difference to the rendered output), but for the moment we keep
these "brackets" in case they may be replaced with something else.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This rather ancient FTM is not mentioned in other pages for
reasons discussed in feature_test_macros(7). Remove this FTM
from the three pages where it does appear.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The majority of pages use .nf/.fi in SYNOPSIS, but there are
still many that don't and use .br to achieve newlines. Fix many
of those. This brings greater consistency to the pages, which
eases editing and may ease future scripted edits to the pages.
Many of these changes were script-assisted, with some additional
manual edits.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Yet more clean-ups after commit
15d6565317.
Reported-by: Alejandro Colomar (man-pages) <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Most pages use 'unsigned int' (and the kernel too).
Make them all do so.
$ find man? -type f \
| xargs sed -i \
-e 's/unsigned \*/unsigned int */g'
-e 's/unsigned "/unsigned int "/g';
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The use of vertical white space in the SYNOPSIS sections
is rather inconsistent. Make it more consistent, subject to the
following heuristics:
* Prefer no blank lines between function signatures by default.
* Where many functions are defined in the SYNOPSIS, add blank
lines where needed to improve readability, possibly by using
blank lines to separate logical groups of functions.
Reported-by: Alejandro Colomar (man-pages) <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The functions are all declared in <netdb.h>. <sys/socket.h> is only
needed for the AF_* constants.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Bring a bit more consistency to Feature Test Macro information
(mainly .PP between differnt FTM lists).
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Use .PP (which gives a bit of vertical white space) rather than
.br to separate functions in Feature Test Macro requirement lists.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Rationale:
$ man 7 man-pages 2>/dev/null | sed -n /Paragraphs/,/^$/p
Paragraphs should be separated by suitable markers (usually
either .PP or .IP). Do not separate paragraphs using blank
lines, as this results in poor rendering in some output
formats (such as PostScript and PDF).
Fix:
$ sed -i -e '1,/^\.EX/s/^$/.PP/' -e '/^\.EE/,/^\.EX/s/^$/.PP/' man?/*
And then some manual adjustments.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Quoting Heinrich:
The strnlen.3 manpage has the following sentence:
"In doing this, strnlen() looks only at the first maxlen
characters in the string pointed to by s and never beyond
s+maxlen."
This sentence is self-contradictory:
The last visited character implied by "first maxlen
characters" is s[maxlen-1].
Given that "beyond a" does not include "a", the last visited
character implied by "never beyond s+maxlen" is s[maxlen].
A consistent sentence would be
"In doing this, strnlen() looks only at the first maxlen
characters in the string pointed to by s and never beyond
s+maxlen-1."
I would prefer
"In doing this, strnlen() looks only at the first maxlen
characters in the string pointed to by s and never beyond
s[maxlen-1]"
Reported-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Learned from an email converasation with Mike Crowe, and
verified by experiment.
Reported-by: Mike Crowe <mac@mcrowe.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
As far as I can see, it is instead simply an alias for a
wrapper that calls _llseek(). Saying it's an alias for "llseek()"
seems confusing.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
We're talking of a mix of wrapper functions and system calls
in this page. lseek() is both a system and a wrapper function,
and this page is mostly describing the wrapper
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
{.IR var [x]} -> {.I var[x]}
There were around 15 entries of the former,
and around 360 of the latter.
Found using:
$ grep -rn '^\.I[ |R].* \[.*\]' |sort
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
With this change, there remain almost no vestiges of information
about the long defunct Linux libc.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Add a page documenting the pthread_attr_setsigmask_np(3) and
pthread_attr_getsigmask_np() functions added in glibc 2.32.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
queue.3 has been moved to queue.7.
Fix SEE ALSO accordingly.
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
queue has been for so many years in Section 3,
and still is in Section 3 in most manuals.
For legacy reasons,
especially because hyperlinks to the online manual pages
would break otherwise,
a link queue.3 -> queue(7) is necessary.
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
After forking slist.3, list.3, tailq.3, stailq.3 & circleq.3
in the previous commits,
this page no longer belongs in Section 3 of the manual pages.
According to its contents, the most suitable section is Section 7.
Because of legacy reasons, a link queue.3 -> queue(7)
would be appropriate.
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This helps differentiate 'TYPE' in some arguments from
'struct TYPE *var' in others, and is technically more correct.
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
- ffix: Use man markup
- Remove specific notes about code size increase
and execution time increase,
as they were (at least) inaccurate.
Instead, a generic note has been added.
- Structure the text into subsections.
- Remove sections that were empty after the forks.
- Clearly relate macro names (SLIST, TAILQ, ...)
to a human readable name of which data structure
they implement.
Reported-by: Michael Kerrisk <mtk.manpages@gmail.com>
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Add remaining details to complete the page.
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
A few fixes to note:
- Sorted alphabetically some macros
- ffix: remove alignment spaces in example (as in list.3)
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
list.3: NAME: Add description
list.3: DESCRIPTION: Add short description
list.3: SEE ALSO: Add insque(3) and queue(3)
list.3: BUGS: Note LIST_FOREACH() limitations
list.3: RETURN VALUE: Add details about the return value of those macros that "return" a value
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
list.3: NAME: ffix: Use man markup
list.3: SYNOPSIS: ffix: Use man markup
list.3: DESCRIPTION: ffix: Use man markup
list.3: DESCRIPTION: ffix: Use man markup
list.3: CONFORMING TO: ffix: Use man markup
list.3: EXAMPLES: ffix: Use man markup
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
list.3: SYNOPSIS: Copy include from queue.3
list.3: DESCRIPTION: Copy description about naming of macros from queue.3
list.3: DESCRIPTION: Remove unrelated code to adapt to this page
list.3: DESCRIPTION: Remove lines pointing to the EXAMPLES
list.3: CONFORMING TO: Copy from queue.3
list.3: CONFORMING TO: Adapt to this page
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The wording was incorrect:
It stated that 'eflags' may be the OR of one or two of those two flags,
but then a third flag was documented
(which according to the previous wording could not be used?!).
Moreover, the wording also disallowed using 0 (i.e., no flags at all),
which POSIX specifically allows;
I tested the function with no flags and it worked fine for me,
so I guess it was a problem with the documentation,
and not with the implementation itself.
POSIX ref: https://pubs.opengroup.org/onlinepubs/9699919799/
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
I added the EXAMPLES section.
The examples in this page are incomplete
(you can't copy&paste&compile&run).
I fixed the one about TAILQ first,
and the rest should follow.
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
POSIX requires that the <regex.h> header shall define
the structures and symbolic constants used by the
regcomp(), regexec(), regerror(), and regfree() functions.
Therefore, there should be no need to include <sys/types.h>
at all.
The POSIX docs don't use that include:
https://pubs.opengroup.org/onlinepubs/9699919799/functions/regcomp.html
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Revert "uint_least8_t.3, uint_least16_t.3, uint_least32_t.3, uint_least64_t.3, uint_leastN_t.3: New links to system_data_types(7)"
This reverts commit a5d13a32b7.
Revert "system_data_types.7: Add uint_leastN_t family of types"
This reverts commit 3450a5621e.
Revert "int_least8_t.3, int_least16_t.3, int_least32_t.3, int_least64_t.3, int_leastN_t.3: New links to system_data_types(7)"
This reverts commit 876838354d.
Revert "system_data_types.7: Add int_leastN_t family of types"
This reverts commit f9b54d3a2e.
Revert "uint_fast8_t.3, uint_fast16_t.3, uint_fast32_t.3, uint_fast64_t.3, uint_fastN_t.3: New links to system_data_types(7)"
This reverts commit 496b1aad79.
Revert "system_data_types.7: Add uint_fastN_t family of types"
This reverts commit 3c9ae6e5a2.
Revert "int_fast8_t.3, int_fast16_t.3, int_fast32_t.3, int_fast64_t.3, int_fastN_t.3: New links to system_data_types(7)"
This reverts commit 9df81a23e5.
Revert "system_data_types.7: Add int_fastN_t family of types"
This reverts commit 8f12d3f683.
Reported-by: Michael Kerrisk <mtk.manpages@gmail.com>
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Through some accident, 'sys_siglist' has been documented in
two different pages. Consolidate the information to one page
(strsignal(3)) and add 'sys_siglist" to the NAME line of that
page.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Around the text:
"Feature Test Macro Requirements for glibc..."
replace ".in -4n/.in" with ".RS -4/.RE".
The latter form is more idiomatic use of man macros.
The nroff output is unchanged.
Reported-by: G. Branden Robinson <g.branden.robinson@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Use \(aq to get an unslanted single quote inside monospace code
blocks. Using a simple ' results in a slanted quote inside PDFs.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
[mtk: the coding style used in the example could lead people to
inject memory leaks in their code if they cut/paste/modify the
code to replace "exit" paths with "return" paths from a library
function.]
[Marko, from the mail thread discussing this patch:]
You are right about terminating the process. However, people copy
that example and put the code in a function changing "exit" to
"return". There are a bunch of examples like that here
https://beej.us/guide/bgnet/html/#poll, for instance. That error
bothered me when reading the network programming guide
https://beej.us/guide/bgnet/html/. Than I looked for information
elsewhere:
https://stackoverflow.com/questions/6712740/valgrind-reporting-that-getaddrinfo-is-leaking-memoryhttps://stackoverflow.com/questions/15690303/server-client-sockets-freeaddrinfo3-placement
And finally, I checked manual pages and saw where these errors
come from.
When you change that to a function and return without doing
freeaddrinfo, that is a memory leak. I believe an example should
show good programming practices. Relying on exiting and clearing
the memory in that case is not such a case. In my opinion, these
examples lead people to make mistakes in their programs.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Let's move to the 21st century. Instead of casting system data
types to long/long long/etc. in printf() calls, instead cast to
intmax_t or uintmax_t, the largest available signed/unsigned
integer types.
[mtk: rewrote commit message]
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Use printf()'s '#' flag character to prepend the string "0x".
However, when the number is printed in uppercase, and the prefix
is in lowercase, the string "0x" needs to be manually written.
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
For consistency.
The types are written both with and without the redundant 'int' keyword
all over the man-pages. However, the most used form, by far, is the one
without 'int'.
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Member 'tv_nsec' of 'struct timespec' is of type 'long' (see time.h.0p),
and therefore, the cast is completely redundant.
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
For consistency.
Most man pages use 'long' instead of 'long int'.
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
It is the DT_RUNPATH/DT_RPATH of the calling object (not the
executable) that is relevant for the library search. Verified
by experiment.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
fread(3), unlike read(2) which returns a ssize_t, returns a
size_t. It doesn't distinguish between error and enf-of-file.
Instead, either ferror(3) or feof(3) need to be checked if fread()
returned 0.
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
`p1` (and `p2` too) is `const void *` and it comes from a
`const char **` (for legacy reasons, argv is not `const` but should be
treated as if it were). That means, the ultimate `char` is `const`:
"a pointer to a pointer to a const char".
Let's see what is going on before the fix first, and then the fix.
Before the fix:
`(char *const *)` (I removed the space on purpose) casts `p1` to be
"a pointer to a const pointer to a non-const char". That's clearly
not what it originally was.
Then we dereference, ending with a `char *const`, which is
"a const pointer to a non-const char". But given that the pointer value
is passed to a function, `const` doesn't make sense there, because the
function will already take a copy of it, so it is impossible to modify
the pointer itself.
The fix:
`(const char **)` The only thing that is const is the ultimate `char`,
which is the only thing that matters, because it is the only thing
strcmp(3) has access to (everything else, i.e. the pointers, are
copies).
Then, after the dereference we end up with `const char *`, the type of
argv (more or less, as previously noted), which is also the type of the
arguments to strcmp(3).
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Casting `const void *` to `struct mi *` should result in a warning if
done implicitly. The explicit cast was probably silencing that warning.
`const` can and should be kept.
Now, casting `const void *` to `const struct mi *` is done implicitly.
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The type `sigset_t *` is implicitly casted to `void *`.
Explicitly casting can silence warnings when mistakes are made, so it's
better to remove those casts when possible.
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Casting `void *` to `double (*cosine)(double)` is already done
implicitly.
I had doubts about this one, but `gcc -Wall -Wextra` didn't complain
about it.
Explicitly casting can silence warnings when mistakes are made, so it's
better to remove those casts when possible.
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The type of `val` is `int **`, and it will work with tsearch()
anyway because of implicit cast from `void *`, so declaring it as an
`int **` simplifies the code.
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Casting `int *` to `const void *` is already done implicitly.
Not only that, but the explicit cast to `void *` was slightly
misleading.
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Rather than:
sometype x;
for (x = ....; ...)
use
for (sometype x = ...; ...)
This brings the declaration and use closer together (thus aiding
readability) and also clearly indicates the scope of the loop
counter variable.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Rather than writing things such as:
struct sometype *x;
...
x = malloc(sizeof(*x));
let's use C99 style so that the type info is in the same line as
the allocation:
struct sometype *x = malloc(sizeof(*x));
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Use ``sizeof`` consistently through all the examples in the following
way:
- Use the name of the variable instead of its type as argument for
``sizeof``.
Rationale:
https://www.kernel.org/doc/html/v5.8/process/coding-style.html#allocating-memory
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Use ``sizeof`` consistently through all the examples in the following
way:
- Use the name of the variable instead of its type as argument for
``sizeof``.
Rationale:
https://www.kernel.org/doc/html/v5.8/process/coding-style.html#allocating-memory
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Use ``sizeof`` consistently through all the examples in the following
way:
- Use the name of the variable instead of its type as argument for
``sizeof``.
Rationale:
https://www.kernel.org/doc/html/v5.8/process/coding-style.html#allocating-memory
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Use ``sizeof`` consistently through all the examples in the following
way:
- Use the name of the variable instead of its type as argument for
``sizeof``.
Rationale:
https://www.kernel.org/doc/html/v5.8/process/coding-style.html#allocating-memory
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Use ``sizeof`` consistently through all the examples in the following
way:
- Use the name of the variable instead of its type as argument for
``sizeof``.
Rationale:
https://www.kernel.org/doc/html/v5.8/process/coding-style.html#allocating-memory
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Use ``sizeof`` consistently through all the examples in the following
way:
- Use the name of the variable instead of its type as argument for
``sizeof``.
Rationale:
https://www.kernel.org/doc/html/v5.8/process/coding-style.html#allocating-memory
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Use ``sizeof`` consistently through all the examples in the following
way:
- Use the name of the variable instead of its type as argument for
``sizeof``.
Rationale:
https://www.kernel.org/doc/html/v5.8/process/coding-style.html#allocating-memory
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Use ``sizeof`` consistently through all the examples in the following
way:
- Use the name of the variable instead of its type as argument for
``sizeof``.
Rationale:
https://www.kernel.org/doc/html/v5.8/process/coding-style.html#allocating-memory
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Use ``sizeof`` consistently through all the examples in the following
way:
- Use the name of the variable instead of its type as argument for
``sizeof``.
Rationale:
https://www.kernel.org/doc/html/v5.8/process/coding-style.html#allocating-memory
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Use ``sizeof`` consistently through all the examples in the following
way:
- Use the name of the variable instead of its type as argument for
``sizeof``.
Rationale:
https://www.kernel.org/doc/html/v5.8/process/coding-style.html#allocating-memory
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Use ``sizeof`` consistently through all the examples in the following
way:
- Use the name of the variable instead of its type as argument for
``sizeof``.
Rationale:
https://www.kernel.org/doc/html/v5.8/process/coding-style.html#allocating-memory
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Use ``sizeof`` consistently through all the examples in the following
way:
- Use the name of the variable instead of its type as argument for
``sizeof``.
Rationale:
https://www.kernel.org/doc/html/v5.8/process/coding-style.html#allocating-memory
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Use ``sizeof`` consistently through all the examples in the following
way:
- Use the name of the variable instead of its type as argument for
``sizeof``.
Rationale:
https://www.kernel.org/doc/html/v5.8/process/coding-style.html#allocating-memory
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Use ``sizeof`` consistently through all the examples in the following
way:
- Use the name of the variable instead of its type as argument for
``sizeof``.
Rationale:
https://www.kernel.org/doc/html/v5.8/process/coding-style.html#allocating-memory
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Use ``sizeof`` consistently through all the examples in the following
way:
- Use the name of the variable instead of its type as argument for
``sizeof``.
Rationale:
https://www.kernel.org/doc/html/v5.8/process/coding-style.html#allocating-memory
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Use ``sizeof`` consistently through all the examples in the following
way:
- Use the name of the variable instead of its type as argument for
``sizeof``.
Rationale:
https://www.kernel.org/doc/html/v5.8/process/coding-style.html#allocating-memory
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Use ``sizeof`` consistently through all the examples in the following
way:
- Use the name of the variable instead of its type as argument for
``sizeof``.
Rationale:
https://www.kernel.org/doc/html/v5.8/process/coding-style.html#allocating-memory
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Use ``sizeof`` consistently through all the examples in the
following way:
- When the result of ``sizeof`` is multiplied (or otherwise
modified), write ``sizeof`` in the first place.
Rationale:
``(sizeof(x) * INT_MAX * 2)`` doesn't overflow.
``(INT_MAX * 2 * sizeof(x))`` overflows, giving incorrect
results.
As a side effect, the parentheses of ``sizeof`` are not next to
the parentheses of the whole expression, and it is visually
easier to read.
Detailed rationale:
In C, successive multiplications are evaluated left to right (*),
and therefore here is what happens (assuming x86_64):
``(sizeof(x) * INT_MAX * 2)``:
1) sizeof(x) * INT_MAX (the type is the largest of both, which
is size_t (unsigned long; uint64_t)).
2) ANS * 2 (the type is again the largest: size_t)
``(INT_MAX * 2 * sizeof(x))``:
1) INT_MAX * 2 (the type is the largest of both, which is
int as both are int (int; int32_t), so the
result is already truncated as it doesn't fit
an int; at this point, the intermediate result
will be 2^32 - 2 (``INT_MAX - 1``) (if I did
the math right)).
2) ANS * 2 (the type is again the largest of both: size_t;
however, ANS was already incorrect, so the
result will be an incorrect size_t value)
(*): https://en.cppreference.com/w/c/language/operator_precedence
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Use ``sizeof`` consistently through all the examples in the
following way:
- Never use a space after ``sizeof``, and always use parentheses
around the argument.
Rationale:
https://www.kernel.org/doc/html/v5.8/process/coding-style.html#spaces
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
I run ``sudo make`` and then visualized the man page with
``man 3 queue``, and the contents looked good.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
In C89 strtod returns zero on underflow, but since C99 it can return
non-zero. This means the strtod.3 page contradicts all recent C and
POSIX standards. Both C and POSIX say "smallest normalized positive
number", but for consistency with HUGE_VAL, HUGE_VALF and HUGE_VALL
this patch uses the constants for those numbers.
Also slightly improve the presentation of return values for overflow.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The description of hexadecimal floating-point output is missing a
character describing the exponent. The guarantee of at least one digit
in the exponent is present in both C99 and POSIX.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This header is used inconsistently -- man pages are UTF-8 encoded
but not setting this marker. It's only respected by the man-db
package, and seems a bit anachronistic at this point when UTF-8
is the standard default nowadays.
Signed-off-by: Mike Frysinger <vapier@gentoo.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
There was code containing ``CIRCLEQ_*`` in the examples for ``TAILQ_*``. It was introduced by accident in commit ``041abbe``.
From 0c9dfbe9b1ce1130e9a92d1a16fbecd4a08bbe29 Mon Sep 17 00:00:00 2001
From: Alejandro Colomar <colomar.6.4.3@gmail.com>
Date: Wed, 12 Aug 2020 09:11:27 +0200
Subject: [PATCH] queue.3: Remove wrong code from example
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
A naked tilde ("~") renders poorly in PDF. Instead use "\(ti",
which renders better in a PDF, and produces the same glyph
when rendering on a terminal.
Reported-by: Geoff Clare <gwc@opengroup.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
===========
DESCRIPTION
===========
I'm documenting ``CIRCLEQ_*`` macros in queue.3. While writing
this, I noticed that the documentation for some types of
queues/lists talked about swapping contents of two lists, but only
for some of them. I then found that those macros (``*_SWAP``)
don't exist in my system (Debian), but exist in BSD, and I also
found that a previous commit (6559169cac) commented out a lot of
the *_SWAP macros documentation, but not all, and the reason was
that they were not present on glibc.
I checked that I didn't have any of the *_SWAP macros on my glibc,
so I think this is probably that the commit simply forgot to
comment some of
them.
=======
TESTING
=======
I did ``sudo make`` and then visualized the man page with
``man 3 queue``, and the changes looked good.
I also noticed that the subsection ``Tail queue example`` contents
were wrong, as they contained calls to CIRCLEQ_* macros. I will
address that in a future patch, before I submit the patch
documenting CIRCLEQ_*.
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Michael Kerrisk