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>
Historically, a comment of the following form at the top of a
manual page was used to indicate too man(1) that the use of tbl(1)
was required in order to process tables:
'\" t
However, at least as far back as 2001 (according to Branden),
man-db's man(1) automatically uses tbl(1) as needed, rendering
this comment unnecessary. And indeed many existing pages in
man-pages that have tables don't have this comment at the top of
the file. So, drop the comment from those files where it is
present.
[mtk: completely rewrote commit message]
Reported-by: G. Branden Robinson <g.branden.robinson@gmail.com>
Signed-off-by: Mike Frysinger <vapier@gentoo.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The \" comment produces blank lines. Use the .\" that the vast
majority of the codebase uses instead.
Signed-off-by: Mike Frysinger <vapier@gentoo.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Alejandro Colomar