There is a lot of unnecessary duplication of content of the seccomp
material in prctl(2) and seccomp(2). Trevor Woerner also noted that
there is an error in prctl(2), where it says that the filters
"are run in order until the first non-allow result is seen", which
contradicts the correct statement in seccomp(2) that *all* filters
are executed.
So, rewrite the seccomp material in prctl(2) to strip out most of
the content duplicated in seccomp(2), and replace the removed
text with statements deferring to to seccomp(2).
Reported-by: Trevor Woerner <twoerner@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Add some subsection (.SS) headings and paragraph breaks in
DESCRIPTION, to make the page more easily readable.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
glibc has tightened up its rules for replacing the memory
allocator. I went through the malloc man page and looked for how
it documented malloc() and related functions, and fixed
discrepancies with glibc malloc() documentation and/or
implementation. I also reorganized the portability discussion so
that portability issues can be seen more clearly.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Documentation/filesystems/sharedsubtree.txt has changed to
Documentation/filesystems/sharedsubtree.rst.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Especially the change to .rst format in the kernel Documentation/
tree has rendered many of the references in this manual page
obsolete. Fix them.
Reported-by: Vito Caputo <vcaputo@pengaru.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This makes it easier to compare this page to the standard,
to get more details about the rules between operators.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Unary operators are mentioned in C11::6.5.3, and casts are in
C11::6.5.4 (they are mentioned in order of precedence).
And from note 85 (in section 6.5) in that same C11 standard, major
subsections 6.5.X are sorted by precedence.
As an example (from Jakub), `sizeof(int)+1` is interpreted as
`(sizeof(int))+1`, and not `sizeof((int)+1)`.
I used C11 and not C18 (the latest) because at least in the draft
copy of C18 that I have, there are a few important typos in that
section, while the draft copy of C11 that I have is free of those
typos. And C11 and C18 are almost identical, with no major
changes to the language.
Reported-by: David Sletten <david.paul.sletten@gmail.com>
Cc: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Zero in this case refers to literal constant 0 and not symbolic
constant B0.
Signed-off-by: Pali Rohár <pali@kernel.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
As noted by Jakub:
BTW, the exit_group.2 man page could use an update (possibly
by merging it into exit.2): it says that the "system
call is is equivalent to _exit(2) except that it terminates
not only the calling thread, but all threads in the calling
process's thread group", which isn't helpful these days.
Reported-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The previous wording wasn't very explicit, leaving room for
believing that 'errno' may be 0 after returning EAI_SYSTEM.
Use a wording similar to other pages, for added consistency.
[mtk: edited commit message title; also, POSIX notes that
'errno' is set in this case.]
Reported-by: Cristian Morales Vega <christian.morales.vega@gmail.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Many times, this page use the terminology "mount point", where
"mount" would be better. A "mount point" is the location at which
a mount is attached. A "mount" is an association between a
filesystem and a mount point.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The correct terminology is "less privileged mount namespace"
(not "less privileged user namespace").
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The "Restrictions on mount namespaces" subsection belongs lower in
the page, following the discussion of concepts (e.g., shared
subtrees and propagation) that are discussed elsewhere in the page.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The previous commit injected a large block of text into a list,
separating one example in the previous list item from a
"continuation" in the following list item. repair that.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
For a long time, this manual page has had a brief discussion of
"locked" mounts, without clearly saying what this concept is, or
why it exists. Expand the discussion with an explanation of what
locked mounts are, why mounts are locked, and some examples of the
effect of locking.
Thanks to Christian Brauner for a lot of help in understanding
these details.
Reported-by: Christian Brauner <christian.brauner@ubuntu.com>
Acked-by: Christian Brauner <christian.brauner@ubuntu.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
These pages split out extra errors for some APIs into a separate
list. Probably, the pages are easier to ready if all errors are
combined into a single list.
Note that there still remain a few pages where the errors are
listed separately for different APIs. For the moment, it seems
best to leave those pages as is, since the error lists are
largely distinct in those pages.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
These split out errors into separate lists (perhaps per API,
perhaps "may" vs "shall", perhaps "Linux-specific" vs
standard(??)), but there's no good reason to do this. It makes
the error list harder to read, and is inconsistent with other
pages. So, combine the errors into a single list.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Mainly in preparation for the following patch on project IDs maps.
Add some words that will make the parallels between the rules for
updating uid_map and projid_map clearer.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Many times, these pages use the terminology "mount point", where
"mount" would be better. A "mount point" is the location at which
a mount is attached. A "mount" is an association between a
filesystem and a mount point.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Linux 5.8 adds STATX_MNT_ID and stx_mnt_id.
Add description to statx.2
Signed-off-by: NeilBrown <neilb@suse.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
From email with Christian Brauner:
>>>>>> int fd_tree = open_tree(-EBADF, source,
>>>>>> OPEN_TREE_CLONE | OPEN_TREE_CLOEXEC |
>>>>>> AT_EMPTY_PATH | (recursive ? AT_RECURSIVE : 0));
>>>>>
>>>>> ???
>>>>> What is the significance of -EBADF here? As far as I can tell, it
>>>>> is not meaningful to open_tree()?
>>>>
>>>> I always pass -EBADF for similar reasons to [2]. Feel free to just use -1.
>>>
>>> ????
>>> But here, both -EBADF and -1 seem to be wrong. This argument
>>> is a dirfd, and so should either be a file descriptor or the
>>> value AT_FDCWD, right?
>>
>> [1]: In this code "source" is expected to be absolute. If it's not
>> absolute we should fail. This can be achieved by passing -1/-EBADF,
>> afaict.
>
> D'oh! Okay. I hadn't considered that use case for an invalid dirfd.
> (And now I've done some adjustments to openat(2),which contains a
> rationale for the *at() functions.)
>
> So, now I understand your purpose, but still the code is obscure,
> since
>
> * You use a magic value (-EBADF) rather than (say) -1.
> * There's no explanation (comment about) of the fact that you want
> to prevent relative pathnames.
>
> So, I've changed the code to use -1, not -EBADF, and I've added some
> comments to explain that the intent is to prevent relative pathnames.
> Okay?
Sounds good.
>
> But, there is still the meta question: what's the problem with using
> a relative pathname?
Nothing per se. Ok, you asked so it's your fault:
When writing programs I like to never use relative paths with AT_FDCWD
because. Because making assumptions about the current working directory
of the calling process is just too easy to get wrong; especially when
pivot_root() or chroot() are in play.
My absolut preference (joke intended) is to open a well-known starting
point with an absolute path to get a dirfd and then scope all future
operations beneath that dirfd. This already works with old-style
openat() and _very_ cautious programming but openat2() and its
resolve-flag space have made this **chef's kiss**.
If I can't operate based on a well-known dirfd I use absolute paths with
a -EBADF dirfd passed to *at() functions.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
From email:
>> Thanks. I made it "detached". Elsewhere, the page already explains
>> that a detached mount is one that:
>>
>> must have been created by calling open_tree(2) with the
>> OPEN_TREE_CLONE flag and it must not already have been
>> visible in the filesystem.
>>
>> Which seems a fine explanation.
>>
>> ????
>> But, just a thought... "visible in the filesystem" seems not quite accurate.
>> What you really mean I guess is that it must not already have been
>> /visible in the filesystem hierarchy/previously mounted/something else/,
>> right?
I suppose that I should have clarified that my main problem was
that you were using the word "filesystem" in a way that I find
unconventional/ambiguous. I mean, I normally take the term
"filesystem" to be "a storage system for folding files".
Here, you are using "filesystem" to mean something else, what
I might call like "the single directory hierarchy" or "the
filesystem hierarchy" or "the list of mount points".
> A detached mount is created via the OPEN_TREE_CLONE flag. It is a
> separate new mount so "previously mounted" is not applicable.
> A detached mount is _related_ to what the MS_BIND flag gives you with
> mount(2). However, they differ conceptually and technically. A MS_BIND
> mount(2) is always visible in the fileystem when mount(2) returns, i.e.
> it is discoverable by regular path-lookup starting within the
> filesystem.
>
> However, a detached mount can be seen as a split of MS_BIND into two
> distinct steps:
> 1. fd_tree = open_tree(OPEN_TREE_CLONE): create a new mount
> 2. move_mount(fd_tree, <somewhere>): attach the mount to the filesystem
>
> 1. and 2. together give you the equivalent of MS_BIND.
> In between 1. and 2. however the mount is detached. For the kernel
> "detached" means that an anonymous mount namespace is attached to it
> which doen't appear in proc and has a 0 sequence number (Technically,
> there's a bit of semantical argument to be made that "attached" and
> "detached" are ambiguous as they could also be taken to mean "does or
> does not have a parent mount". This ambiguity e.g. appears in
> do_move_mount(). That's why the kernel itself calls it an "anonymous
> mount". However, an OPEN_TREE_CLONE-detached mount of course doesn't
> have a parent mount so it works.).
>
> For userspace it's better to think of detached and attached in terms of
> visibility in the filesystem or in a mount namespace. That's more
> straightfoward, more relevant, and hits the target in 90% of the cases.
>
> However, the better and clearer picture is to say that a
> OPEN_TREE_CLONE-detached mount is a mount that has never been
> move_mount()ed. Which in turn can be defined as the detached mount has
> never been made visible in a mount namespace. Once that has happened the
> mount is irreversibly an attached mount.
>
> I keep thinking that maybe we should just say "anonymous mount"
> everywhere. So changing the wording to:
I'm not against the word "detached". To user space, I think it is a
little more meaningful than "anonymous". For the moment, I'll stay with
"detached", but if you insist on "anonymous", I'll probably change it.
> [...]
> EINVAL The mount that is to be ID mapped is not an anonymous mount;
> that is, the mount has already been visible in a mount namespace.
I like that text *a lot* better! Thanks very much for suggesting
wordings. It makes my life much easier.
I've made the text:
EINVAL The mount that is to be ID mapped is not a detached
mount; that is, the mount has not previously been
visible in a mount namespace.
> [...]
> The mount must be an anonymous mount; that is, it must have been
> created by calling open_tree(2) with the OPEN_TREE_CLONE flag and it
> must not already have been visible in a mount namespace, i.e. it must
> not have been attached to the filesystem hierarchy with syscalls such
> as move_mount() syscall.
And that too! I've made the text:
• The mount must be a detached mount; that is, it must have
been created by calling open_tree(2) with the
OPEN_TREE_CLONE flag and it must not already have been
visible in a mount namespace. (To put things another way:
the mount must not have been attached to the filesystem
hierarchy with a system call such as move_mount(2).)
Reported-by: Christian Brauner <christian.brauner@ubuntu.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
From email with Christian Braner:
> [1]: In this code "source" is expected to be absolute. If it's not
> absolute we should fail. This can be achieved by passing -1/-EBADF,
> afaict.
D'oh! Okay. I hadn't considered that use case for an invalid dirfd.
(And now I've done some adjustments to openat(2),which contains a
rationale for the *at() functions.)
So, now I understand your purpose, but still the code is obscure,
since
* You use a magic value (-EBADF) rather than (say) -1.
* There's no explanation (comment about) of the fact that you want
to prevent relative pathnames.
So, I've changed the code to use -1, not -EBADF, and I've added some
comments to explain that the intent is to prevent relative pathnames.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Make the description of the EBADF error for invalid 'dirfd' more
uniform. In particular, note that the error only occurs when the
pathname is relative, and that it occurs when the 'dirfd' is
neither valid *nor* has the value AT_FDCWD.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
In particular, specifying an invalid file descriptor number
in 'dirfd' can be used as a check that 'pathname' is absolute.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Kir Kolyshkin made a start, but I think much more needs to
be said...
Reviewed-by: Serge E. Hallyn <serge@hallyn.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
From an email conversation with Alexis:
Hello Alexis,
On 8/6/21 7:06 PM, Alexis Wilke wrote:
> Hi guys,
>
> The pthread_setname_np(3) manual page has an example where the second
> argument is used to get a size of the thread name.
>
> https://man7.org/linux/man-pages/man3/pthread_setname_np.3.html#EXAMPLES
>
> The current code:
>
> rc = pthread_getname_np(thread, thread_name,
> (argc > 2) ? atoi(argv[1]) : NAMELEN);
>
> The suggested code:
>
> rc = pthread_getname_np(thread, thread_name,
> (argc > 2) ? atoi(argv[2]) : NAMELEN);
I agree that there's a problem, but I think we could go even simpler:
rc = pthread_getname_np(thread, thread_name, NAMELEN);
> I'm thinking that maybe the author meant to compute the length like so:
>
> rc = pthread_getname_np(thread, thread_name,
> (argc > 2) ? strlen(argv[1]) + 1 :
> NAMELEN);
>
> But I think that the atoi() points to using argv[2] as a number
> representing the length.
>
> (Of course, it should be tested against NAMELEN as a maximum, but I
> understand that examples do not always show how to verify each possible
> error).
I imagine that the author's intention was to allow the user to do
experiments where argv[2] specified a number less than NAMELEN,
in order to see the resulting ERANGE error. But, that experiment
is of limited value, and complicates the code unnecessarily, IMO,
so that's why I made the change above.
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
Reported-by: Alexis Wilke <alexis@m2osw.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Phrases such as "In the new mount API" will date fast. Remove it.
Also:
* Make it clear that MOUNT_ATTR__ATIME expresses a bit field.
* Replace 'enum' with 'enumeration'.
* Clarify what is meant by "partially" set MOUNT_ATTR__ATIME.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
These types are already well described in mount_namespaces(7);
indeed, much of the text from that page seems to have just been
cut and pasted into this page! Simply referring the reader to
mount_namespaces(7) is sufficient.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Point out that this field can have the value zero, meaning
no change. And avoid discussions of 'enum', and simply say
that otherwise the field has one of the MS_* values.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Reported-by: Acked-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Eric W. Biederman <ebiederm@xmission.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Having this discussion under DESCRIPTION clutters that section,
and has the effect of burying the discussion of propagation. Move
the discussion to NOTES, to make the page more readable.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
- Change some instances of "-" to "\"
- Use C99 style (declare variables nearer use in code)
- Add a bit of white space
- Remove one 'const...const' added by Alex that caused
compiler warnings
- Use "reverse Christmas tree" form for declarations in main()
- Other minor changes
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
We don't really need ext4(5) and xfs(5) here. They provide
no further info that is directly relevant to the reader of
mount_setattr(2).
clone3(2) isn't necessary because it is the same page as clone(2).
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
- Fix SYNOPSIS to fit in 78 columns
Also, we don't show when an include is included for a specific type,
unless that header is included _only_ for the type,
or there might be confusion (e.g., termios).
Instead, that type should be documented in system_data_types(7),
with a link page mount_attr-struct(3).
- Fix references to mount_setattr(). See man-pages(7):
Any reference to the subject of the current manual page should be writ‐
ten with the name in bold followed by a pair of parentheses in Roman
(normal) font. For example, in the fcntl(2) man page, references to
the subject of the page would be written as: fcntl(). The preferred
way to write this in the source file is:
.BR fcntl ()
- Fix line breaks according to semantic newline rules (and add some commas)
- Fix wrong usage of .IR when .RI should have been used
- Fix formatting of variable part in FOO<number>:
- Make italic the variable part (as groff_man(7) recommends)
- Remove <>
- Use syntax recommended by G. Branden Robinson (groff)
- Fix unnecessary uses of .BR or .IR when .B or .I would suffice
- Fix formatting of punctuation
In some cases, it was in italics or bold, and it should always be in roman.
- Use uppercase to begin text, even in bullet points, since those were
multi-sentence.
- Simplify usage of .RS/.RE in combination with .IP
- s/fat/FAT/ as fs(7) does
- Slightly reword some sentences for consistency
- Use Linux-specific for consistency with other pages (in VERSIONS)
- EXAMPLES: Place the return type in a line of its own (as in other pages)
- Fix alignment of code
- Replace unnecessary use of the GNU extension ({}) by do {} while (0)
In that case, there was no return value (moreover, it's a noreturn).
- Break complex declaration lines into a line for each variable
The variables were being initialized, some to non-zero values,
so for clarity, a line for each one seems more appropriate.
- Add const to pointers when possible
- s/\\/\e/
- Remove unmatched groff commands
Cc: Christian Brauner <brauner@kernel.org>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Note the use of FUTEX_CLOCK_REALTIME for selecting the clock,
and eliminate repetition of details already covered in the
description of FUTEX_LOCK_PI.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
FUTEX_LOCK_PI2 is a new futex operation which was recently introduced into the
Linux kernel. It works exactly like FUTEX_LOCK_PI. However, it has support for
selectable clocks for timeouts. By default CLOCK_MONOTONIC is used. If
FUTEX_CLOCK_REALTIME is specified then the timeout is measured against
CLOCK_REALTIME.
This new operation addresses an inconsistency in the futex interface:
FUTEX_LOCK_PI only works with timeouts based on CLOCK_REALTIME in contrast to
all the other PI operations.
Document the FUTEX_LOCK_PI2 command.
Signed-off-by: Kurt Kanzenbach <kurt@linutronix.de>
Reviewed-by: Thomas Gleixner <tglx@linutronix.de>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
- Move example program to a new EXAMPLES section
- Invert logic in the handler to have the failure in the
conditional path, and the success out of any conditionals.
- Use NULL, EXIT_SUCCESS, and EXIT_FAILURE instead of magic numbers
- Separate declarations from code
- Put function return type on its own line
- Put function opening brace on its line
Cc: Peter Collingbourne <pcc@google.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
See https://bugzilla.kernel.org/show_bug.cgi?id=212385
some/path/dir/ is not always the same as some/path/dir/:
$ mkdir u
$ rmdir u/.
rmdir: failed to remove 'u/.': Invalid argument
$ rmdir u
$
The text in POSIX.1-2018 Section 4.13 ("Pathname Resolution")
is helpful in pointing to a better wording.
Reported-by: Askar Safin <safinaskar@mail.ru>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Emanuele Torre via linux-man@:
[
I was reading the man page for ldd(1)[1]; and I read this in the first
paragraph of the DECRIPTION section:
ldd prints the shared objects (shared libraries) required by each
program or shared object specified on the command line. An
example of its use and output (using sed(1) to trim leading white
space for readability in this page) is the following:
$ ldd /bin/ls | sed 's/^ */ /'
linux-vdso.so.1 (0x00007ffcc3563000)
libselinux.so.1 => /lib64/libselinux.so.1 (0x00007f87e5459000)
libcap.so.2 => /lib64/libcap.so.2 (0x00007f87e5254000)
libc.so.6 => /lib64/libc.so.6 (0x00007f87e4e92000)
libpcre.so.1 => /lib64/libpcre.so.1 (0x00007f87e4c22000)
libdl.so.2 => /lib64/libdl.so.2 (0x00007f87e4a1e000)
/lib64/ld-linux-x86-64.so.2 (0x00005574bf12e000)
libattr.so.1 => /lib64/libattr.so.1 (0x00007f87e4817000)
libpthread.so.0 => /lib64/libpthread.so.0 (0x00007f87e45fa000)
This is a little confusing though since that sed(1) command does not
seem to work. (and also potentially misleading for someone who is trying
figure out how to parse ldd(1)'s output.)
ldd(1) prepends a TAB character (0x09) to each line, not spaces:
$ ldd /bin/ls | xxd | head -1
00000000: 096c 696e 7578 2d76 6473 6f2e 736f 2e31 .linux-vdso.so.1
I read ldd(1)'s source code[2] (it is part of glibc) and it seems to be
a bash script that tries to use different rtld programs ( ld.so(8) )
from an RTLDLIST.
Those, on my system, are:
* /usr/lib/ld-linux.so.2
* /usr/lib64/ld-linux-x86-64.so.2
* /usr/libx32/ld-linux-x32.so.2
And they all seem to also be part of glibc.
I have tried to follow the git history of glibc to see when the switch
from spaces to the TAB character occured, but, to me, it seems like
glibc.git/elf/rtld.c has always used '\t'; at since
6a76c115150318eae5d02eca76f2fc03be7bd029[3] (358th commit since glibc
started using the git repository repository - Nov 18th 1995): before
that commit there are not any results for `git grep '\\t'` in the elf
directory and I did not investigate further.
Still, at the time of that commit, glibc did not seem to have an ldd(1)
utility.
Perhaps the man page is old and its original author was using and
documenting an ldd(1) utility that was not part of glibc when he was
writing it.
Anyhow, since I think that sed(1) command will not work on any system
that uses, at least, the most recent version of glibc (because lld(1)
and the ld.so(8) programs it depends on are all part of glibc), I think
that that example should be changed to avoid confusions.
The output format of ldd(1) does not seem to be clearly defined, so I
think this would be a good option:
$ ldd /bin/ls | sed 's/^[[:space:]]*/ /'
NB: ^\s* should also work on most GNU/Linux systems, but \s is
non-standard or documented so I don not suggest using it in the man
page.
Another option could be to remove "the pipe to sed(1)" part and the note
in parentheses that explains why it was used by the original author.
Cheers.
emanuele6
[1]: https://man7.org/linux/man-pages/man1/ldd.1.html
[2]: https://sourceware.org/git/?p=glibc.git;a=blob;f=elf/ldd.bash.in;h=ba736464ac5e4a9390b1b6a39595035238250232;hb=5188a9d0265cc6f7235a8af1d31ab02e4a24853d
[3]: https://sourceware.org/git/?p=glibc.git;a=commit;h=6a76c115150318eae5d02eca76f2fc03be7bd029
///////
$ uname -a
Linux t420 5.10.54-1-lts #1 SMP Wed, 28 Jul 2021 15:05:20 +0000
x86_64 GNU/Linux
$ pacman -Qo ldd
/usr/bin/ldd is owned by glibc 2.33-5
$ pacman -Qo /usr/share/man/man1/ldd.1.gz
/usr/share/man/man1/ldd.1.gz is owned by man-pages 5.12-2
$ pacman -Qo /usr/lib/ld-linux.so.2
/usr/lib/ld-linux.so.2 is owned by lib32-glibc 2.33-5
$ pacman -Qo /usr/lib64/ld-linux-x86-64.so.2
/usr/lib/ld-linux-x86-64.so.2 is owned by glibc 2.33-5
$ pacman -F /usr/libx32/ld-linux-x32.so.2 || echo not available on arch linux.
not available on arch linux.
]
Reported-by: EmanueleTorre <torreemanuele6@gmail.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Cc: James O. D. Hunt <jamesodhunt@gmail.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Explain that `optstring` cannot contain a semi-colon (`;`)
character.
[mtk: verified with a small test program; see also posix/getopt.c
in the glibc sources:
if (temp == NULL || c == ':' || c == ';')
{
if (print_errors)
fprintf (stderr, _("%s: invalid option -- '%c'\n"), argv[0], c);
d->optopt = c;
return '?';
}
]
Also explain that `optstring` can include `+` as an option
character, possibly in addition to that character being used as
the first character in `optstring` to denote `POSIXLY_CORRECT`
behaviour.
[mtk: verified with a small test program.]
Test program below. Example runs:
$ ./a.out -+
opt = 43 (+); optind = 2
Got plus
$ ./a.out -';'
./a.out: invalid option -- ';'
opt = 63 (?); optind = 2; optopt = 59 (;)
Unrecognized option (-;)
Usage: ./a.out [-p arg] [-x]
Signed-off-by: James O. D. Hunt <jamesodhunt@gmail.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
8x---8x---8x---8x---8x---8x---8x---8x---8x---8x---8x---
#include <ctype.h>
#include <sys/types.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#define printable(ch) (isprint((unsigned char) ch) ? ch : '#')
static void /* Print "usage" message and exit */
usageError(char *progName, char *msg, int opt)
{
if (msg != NULL && opt != 0)
fprintf(stderr, "%s (-%c)\n", msg, printable(opt));
fprintf(stderr, "Usage: %s [-p arg] [-x]\n", progName);
exit(EXIT_FAILURE);
}
int
main(int argc, char *argv[])
{
int opt, xfnd;
char *pstr;
xfnd = 0;
pstr = NULL;
while ((opt = getopt(argc, argv, "p:x+;")) != -1) {
printf("opt =%3d (%c); optind = %d", opt, printable(opt), optind);
if (opt == '?' || opt == ':')
printf("; optopt =%3d (%c)", optopt, printable(optopt));
printf("\n");
switch (opt) {
case 'p': pstr = optarg; break;
case 'x': xfnd++; break;
case ';': printf("Got semicolon\n"); break;
case '+': printf("Got plus\n"); break;
case ':': usageError(argv[0], "Missing argument", optopt);
case '?': usageError(argv[0], "Unrecognized option", optopt);
default:
printf("Unexpected case in switch()\n");
exit(EXIT_FAILURE);
}
}
if (xfnd != 0)
printf("-x was specified (count=%d)\n", xfnd);
if (pstr != NULL)
printf("-p was specified with the value \"%s\"\n", pstr);
if (optind < argc)
printf("First nonoption argument is \"%s\" at argv[%d]\n",
argv[optind], optind);
exit(EXIT_SUCCESS);
}
Do not include unused (and incompatible) header file termios.h and
include required header files for puts() and close() functions.
Signed-off-by: Pali Rohár <pali@kernel.org>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
SPARC is special, it does not have Bnnn constants for baud rates above
2000000. Instead it defines 4 Bnnn constants with smaller baud rates.
This difference between SPARC and non-SPARC architectures is present in
both glibc API (termios.h) and also kernel ioctl API (asm/termbits.h).
Signed-off-by: Pali Rohár <pali@kernel.org>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Format variable parts of words referring to a group of identifiers
in italics, following groff_man(7) recommendations.
Also srcfix surrounding uses of \f escape sequences to use macros
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
These baud-rate macro constants are defined in bits/termios.h and are
already supported.
Signed-off-by: Pali Rohár <pali@kernel.org>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Saw this while preparing the "switch to \~" change Alex invited.
Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
After a patch proposal from наб triggered by concerns that, when
talking about PIPE_BUF, pipe(7) explicitly mentions write(2) but
not writev(2), I've concluded that the reference in writev(2) to
pipe(7) is not needed (mea culpa; I added that text), and I think
the text in pipe(7) could be written to be closer to the POSIX
spec, which doesn't talk about "write() calls", but simply about
"writes".
Reported-by: наб <nabijaczleweli@nabijaczleweli.xyz>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Mainly: I generally don't want us to be including URLs to mailing
list discussions in a manual page. Either, the issue in the
discussion is worth writing up in the manual page (so that
the reader doesn't have to look elsewhere), or the details
are less important, in which case it is sufficient to note the
existence of the bug. I think this is an example of the latter.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The correct kernel version seems to 5.11, not 5.10:
$ git describe --contains d0e3fc69d00d
v5.11-rc1~76^2~251
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Christophe Leroy via Bugzilla:
https://bugzilla.kernel.org/show_bug.cgi?id=213421
[
In ppc32 functions section, the Y2038 compliant function
__kernel_clock_gettime64() is missing.
It was added by commit d0e3fc69d00d
("powerpc/vdso: Provide __kernel_clock_gettime64() on vdso32")
]
.../linux$ git describe d0e3fc69d00d
v5.10-rc2-76-gd0e3fc69d00d
Reported-by: Christophe Leroy <christophe.leroy@csgroup.eu>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
As pointed out by Nora, the example shown in the manual
page already demonstrates that the pathname is not absolute!
Reported-by: Nora Platiel <nplatiel@gmx.us>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Remove duplicated word.
Signed-off-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Fix a typo in the documentation of using fallocate to allocate shared
blocks. The flag FALLOC_FL_UNSHARE should instead be documented as
FALLOC_FL_UNSHARE_RANGE.
Fixes: 63a599c657 ("man2/fallocate.2: Document behavior with shared blocks")
Signed-off-by: Dan Robertson <dan@dlrobertson.com>
Reviewed-by: Darrick J. Wong <djwong@kernel.org>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Alan:
[
The on-line copy of the manual page "posixoptions(7)" dated
2018-04-30 has an entry for "getcwd()" in the section headed
"XSI - _XOPEN_LEGACY - _SC_XOPEN_LEGACY".
I believe that entry should be "getwd()" as that is the API call
which was present in X/Open-6 but withdrawn in X/Open-7.
]
mtk: confirmed by reviewing the table ("Removed Functions and
Symbols in Issue 7") at the end of Section B.1.1 on page
3564 of IEEE Std 1003.1, 2016 Edition.
Reported-by: Alan Peakall <Alan.Peakall@helpsystems.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
See https://bugzilla.kernel.org/show_bug.cgi?id=213419
ppc/32 and ppc/64 sections both have the following note:
The CLOCK_REALTIME_COARSE and CLOCK_MONOTONIC_COARSE clocks are
not supported by the __kernel_clock_getres and
__kernel_clock_gettime interfaces; the kernel falls back to the
real system call
This note has been wrong from quite some time now, since commit
654abc69ef2e ("powerpc/vdso32: Add support for
CLOCK_{REALTIME/MONOTONIC}_COARSE") and commit
5c929885f1bb ("powerpc/vdso64: Add support for
CLOCK_{REALTIME/MONOTONIC}_COARSE")
Reported-by: Christophe Leroy <christophe.leroy@csgroup.eu>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Since commit ee81d7e418, the flags list has been (only) above, not
below, these references.
(The flags table was added even before that, in commit 0b497138b9
("namespaces.7: Add table of namespaces to top of page"))
Fixes: ee81d7e418 ("namespaces.7: Include manual page references in the summary table of namespace types")
Signed-off-by: Štěpán Němec <stepnem@gmail.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Correct function signature by adding missing parenthesis.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
I regularly get mildly lost in this table (and, indeed, didn't realise
it had two columns the first few times I used it to look at something
from the left column) ‒ separating the two columns improves clarity,
and makes which soup of numbers belongs to which character
much more obvious
Other encodings don't need this as they don't use double-columnated
tables
Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The recv.2 misspelled `SO_EE_OFFENDER` to `SOCK_EE_OFFENDER`.
This patch fix this typo.
Signed-off-by: kXuan <kxuanobj@gmail.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The file being referred to no longer exists, as it was moved to
*.rst first (commit 20a78ae9ed297f2) and then to under
admin-guide (commit bf6b7a742e3f82b). Both those commits
are from 2019 (Linux 5.3).
Signed-off-by: Kir Kolyshkin <kolyshkin@gmail.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Using mount flag `MS_NOSUID` also affects SELinux domain transitions but
this has not been documented well.
Signed-off-by: Topi Miettinen <toiwoton@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
With a simple backslash, '\0' ended up as ' ' in the man output.
Reported-by: Štěpán Němec <stepnem@gmail.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
No implementation or spec requires *n to be 0 to allocate a new buffer:
* musl checks for !*lineptr
(and sets *n=0 for later allocations)
* glibc checks for !*lineptr || !*n
(but only because it allocates early)
* NetBSD checks for !*lineptr
(and sets *n=0 for later allocations)
(but specifies *n => mlen(*lineptr) >= *n as a precondition,
to which this appears to be an exception)
* FreeBSD checks for !*lineptr and sets *n=0
(and specifies !*lineptr as sufficient)
* Lastly, POSIX.1-2017 specifies:
> If *n is non-zero, the application shall ensure that *lineptr
> either points to an object of size at least *n bytes,
> or is a null pointer.
The new wording matches POSIX, even if it arrives at the point slightly
differently
Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Don't document includes that provide types; only those that
provide prototypes and constants.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The types that need <sys/types.h> are better documented in
system_data_types(7). Let's keep only the includes for the
prototypes and the constants.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
'struct iovec' is defined in <bits/types/struct_iovec.h>,
which is included by <sys/io.h>, but it is also included by
<bits/fcntl-linux.h>, which is in the end included by <fcntl.h>.
Given that we already include <fcntl.h>, we don't need any more
includes.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
'struct utimbuf' is provided by <utime.h>.
There's no need for <sys/types.h>.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
<sys/types.h> makes no sense for a function that only uses 'int'.
The flags used by this function are provided by <fcntl.h>
(or others), but not by <linux/userfaultfd.h>.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
'mode_t', which is the only reason this might have been ever
needed, is provided by <sys/stat.h> since POSIX.1-2001.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
'off_t', which is the only reason this might have been ever
needed, is provided by <unistd.h> since POSIX.1-2001.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
There seems to be no reason to include <unistd.h>.
<sys/swap.h> already provides both the function prototypes and the
SWAP_* constants.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
<unistd.h> doesn't seem to be needed:
AT_* constants come from <fcntl.h>
STATX_* constants come from <sys/stat.h>
'struct statx' comes from <sys/stat.h>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Remove <sys/types.h>; ffix too
<sys/types.h> is only needed for 'struct stat'.
That is better documented in system_data_types(7).
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
A function declarator with empty parentheses, which is not a
prototype, is an obsolescent feature of C (See C17 6.11.6.1), and
doesn't mean 0 parameters, but instead that no information about
the parameters is provided (See C17 6.5.2.2).
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
It's only needed for getting 'mode_t'.
But that type is better documented in system_data_types(7).
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Doing so decreases the degree to which text is indented, and
thus avoids short, poorly wrapped lines.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Quoting Jann Horn:
[[
As discussed at
<https://lore.kernel.org/r/CAG48ez0m4Y24ZBZCh+Tf4ORMm9_q4n7VOzpGjwGF7_Fe8EQH=Q@mail.gmail.com>,
we need to re-check checkNotificationIdIsValid() after reading remote
memory but before using the read value in any way. Otherwise, the
syscall could in the meantime get interrupted by a signal handler, the
signal handler could return, and then the function that performed the
syscall could free() allocations or return (thereby freeing buffers on
the stack).
In essence, this pread() is (unavoidably) a potential use-after-free
read; and to make that not have any security impact, we need to check
whether UAF read occurred before using the read value. This should
probably be called out elsewhere in the manpage, too...
Now, of course, **reading** is the easy case. The difficult case is if
we have to **write** to the remote process... because then we can't
play games like that. If we write data to a freed pointer, we're
screwed, that's it. (And for somewhat unrelated bonus fun, consider
that /proc/$pid/mem is originally intended for process debugging,
including installing breakpoints, and will therefore happily write
over "readonly" private mappings, such as typical mappings of
executable code.)
So, uuuuh... I guess if anyone wants to actually write memory back to
the target process, we'd better come up with some dedicated API for
that, using an ioctl on the seccomp fd that magically freezes the
target process inside the syscall while writing to its memory, or
something like that? And until then, the manpage should have a big fat
warning that writing to the target's memory is simply not possible
(safely).
]]
and
<https://lore.kernel.org/r/CAG48ez0m4Y24ZBZCh+Tf4ORMm9_q4n7VOzpGjwGF7_Fe8EQH=Q@mail.gmail.com>:
[[
The second bit of trouble is that if the supervisor is so oblivious
that it doesn't realize that syscalls can be interrupted, it'll run
into other problems. Let's say the target process does something like
this:
int func(void) {
char pathbuf[4096];
sprintf(pathbuf, "/tmp/blah.%d", some_number);
mount("foo", pathbuf, ...);
}
and mount() is handled with a notification. If the supervisor just
reads the path string and immediately passes it into the real mount()
syscall, something like this can happen:
target: starts mount()
target: receives signal, aborts mount()
target: runs signal handler, returns from signal handler
target: returns out of func()
supervisor: receives notification
supervisor: reads path from remote buffer
supervisor: calls mount()
but because the stack allocation has already been freed by the time
the supervisor reads it, the supervisor just reads random garbage, and
beautiful fireworks ensue.
So the supervisor *fundamentally* has to be written to expect that at
*any* time, the target can abandon a syscall. And every read of remote
memory has to be separated from uses of that remote memory by a
notification ID recheck.
And at that point, I think it's reasonable to expect the supervisor to
also be able to handle that a syscall can be aborted before the
notification is delivered.
]]
Reported-by: Jann Horn <jannh@google.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
- Rename the function that does the SECCOMP_IOCTL_NOTIF_ID_VALID
check.
- Make that function return a 'bool' rather than terminating the
process.
- Use that return value in the calling function.
- Rework/improve various related comments.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
pidfd_open(2) and pidfd_getfd(2) presumably have use cases
with the user-space notification feature.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
According to Tycho Andersen, he had no particular use case
in mind when building this detail into the API.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The seccomp user-space notification feature can cause changes in
the semantics of SA_RESTART with respect to system calls that
would never normally be restarted. Point the reader to the page
that provide further details.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
And, as noted by Jann Horn, note how the user-space notification
mechanism causes a small breakage in the user-space API with
respect to nonrestartable system calls.
====
From the email discussion with Jann Horn
> >> So, I partially demonstrated what you describe here, for two example
> >> system calls (epoll_wait() and pause()). But I could not exactly
> >> demonstrate things as I understand you to be describing them. (So,
> >> I'm not sure whether I have not understood you correctly, or
> >> if things are not exactly as you describe them.)
> >>
> >> Here's a scenario (A) that I tested:
> >>
> >> 1. Target installs seccomp filters for a blocking syscall
> >> (epoll_wait() or pause(), both of which should never restart,
> >> regardless of SA_RESTART)
> >> 2. Target installs SIGINT handler with SA_RESTART
> >> 3. Supervisor is sleeping (i.e., is not blocked in
> >> SECCOMP_IOCTL_NOTIF_RECV operation).
> >> 4. Target makes a blocking system call (epoll_wait() or pause()).
> >> 5. SIGINT gets delivered to target; handler gets called;
> >> ***and syscall gets restarted by the kernel***
> >>
> >> That last should never happen, of course, and is a result of the
> >> combination of both the user-notify filter and the SA_RESTART flag.
> >> If one or other is not present, then the system call is not
> >> restarted.
> >>
> >> So, as you note below, the UAPI gets broken a little.
> >>
> >> However, from your description above I had understood that
> >> something like the following scenario (B) could occur:
> >>
> >> 1. Target installs seccomp filters for a blocking syscall
> >> (epoll_wait() or pause(), both of which should never restart,
> >> regardless of SA_RESTART)
> >> 2. Target installs SIGINT handler with SA_RESTART
> >> 3. Supervisor performs SECCOMP_IOCTL_NOTIF_RECV operation (which
> >> blocks).
> >> 4. Target makes a blocking system call (epoll_wait() or pause()).
> >> 5. Supervisor gets seccomp user-space notification (i.e.,
> >> SECCOMP_IOCTL_NOTIF_RECV ioctl() returns
> >> 6. SIGINT gets delivered to target; handler gets called;
> >> and syscall gets restarted by the kernel
> >> 7. Supervisor performs another SECCOMP_IOCTL_NOTIF_RECV operation
> >> which gets another notification for the restarted system call.
> >>
> >> However, I don't observe such behavior. In step 6, the syscall
> >> does not get restarted by the kernel, but instead returns -1/EINTR.
> >> Perhaps I have misconstructed my experiment in the second case, or
> >> perhaps I've misunderstood what you meant, or is it possibly the
> >> case that things are not quite as you said?
>
> Thanks for the code, Jann (including the demo of the CLONE_FILES
> technique to pass the notification FD to the supervisor).
>
> But I think your code just demonstrates what I described in
> scenario A. So, it seems that I both understood what you
> meant (because my code demonstrates the same thing) and
> also misunderstood what you said (because I thought you
> were meaning something more like scenario B).
Ahh, sorry, I should've read your mail more carefully. Indeed, that
testcase only shows scenario A. But the following shows scenario B...
[Below, two pieces of code from Jann, with a lot of
cosmetic changes by mtk.]
====
[And from a follow-up in the same email thread:]
> If userspace relies on non-restarting behavior, it should be using
> something like epoll_pwait(). And that stuff only unblocks signals
> after we've already past the seccomp checks on entry.
Thanks for elaborating that detail, since as soon as you talked
about "enlarging a preexisting race" above, I immediately wondered
sigsuspend(), pselect(), etc.
(Mind you, I still wonder about the effect on system calls that
are normally nonrestartable because they have timeouts. My
understanding is that the kernel doesn't restart those system
calls because it's impossible for the kernel to restart the call
with the right timeout value. I wonder what happens when those
system calls are restarted in the scenario we're discussing.)
Anyway, returning to your point... So, to be clear (and to
quickly remind myself in case I one day reread this thread),
there is not a problem with sigsuspend(), pselect(), ppoll(),
and epoll_pwait() since:
* Before the syscall, signals are blocked in the target.
* Inside the syscall, signals are still blocked at the time
the check is made for seccomp filters.
* If a seccomp user-space notification event kicks, the target
is put to sleep with the signals still blocked.
* The signal will only get delivered after the supervisor either
triggers a spoofed success/failure return in the target or the
supervisor sends a CONTINUE response to the kernel telling it
to execute the target's system call. Either way, there won't be
any restarting of the target's system call (and the supervisor
thus won't see multiple notifications).
====
Scenario A
$ ./seccomp_unotify_restart_scen_A
C: installed seccomp: fd 3
C: woke 1 waiters
P: child installed seccomp fd 3
C: About to call pause(): Success
P: going to send SIGUSR1...
C: sigusr1_handler handler invoked
P: about to terminate
C: got pdeath signal on parent termination
C: about to terminate
/* Modified version of code from Jann Horn */
#define _GNU_SOURCE
#include <stdio.h>
#include <signal.h>
#include <err.h>
#include <errno.h>
#include <unistd.h>
#include <stdlib.h>
#include <sched.h>
#include <stddef.h>
#include <limits.h>
#include <sys/mman.h>
#include <sys/syscall.h>
#include <sys/prctl.h>
#include <linux/seccomp.h>
#include <linux/filter.h>
#include <linux/futex.h>
struct {
int seccomp_fd;
} *shared;
static void
sigusr1_handler(int sig, siginfo_t * info, void *uctx)
{
printf("C: sigusr1_handler handler invoked\n");
}
static void
sigusr2_handler(int sig, siginfo_t * info, void *uctx)
{
printf("C: got pdeath signal on parent termination\n");
printf("C: about to terminate\n");
exit(0);
}
int
main(void)
{
setbuf(stdout, NULL);
/* Allocate memory that will be shared by parent and child */
shared = mmap(NULL, 0x1000, PROT_READ | PROT_WRITE,
MAP_ANONYMOUS | MAP_SHARED, -1, 0);
if (shared == MAP_FAILED)
err(1, "mmap");
shared->seccomp_fd = -1;
/* glibc's clone() wrapper doesn't support fork()-style usage */
/* Child process and parent share file descriptor table */
pid_t child = syscall(__NR_clone, CLONE_FILES | SIGCHLD,
NULL, NULL, NULL, 0);
if (child == -1)
err(1, "clone");
/* CHILD */
if (child == 0) {
/* don't outlive the parent */
prctl(PR_SET_PDEATHSIG, SIGUSR2);
if (getppid() == 1)
exit(0);
/* Install seccomp filter */
prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0);
struct sock_filter insns[] = {
BPF_STMT(BPF_LD | BPF_W | BPF_ABS,
offsetof(struct seccomp_data, nr)),
BPF_JUMP(BPF_JMP | BPF_JEQ | BPF_K, __NR_pause, 0, 1),
BPF_STMT(BPF_RET | BPF_K, SECCOMP_RET_USER_NOTIF),
BPF_STMT(BPF_RET | BPF_K, SECCOMP_RET_ALLOW)
};
struct sock_fprog prog = {
.len = sizeof(insns) / sizeof(insns[0]),
.filter = insns
};
int seccomp_ret = syscall(__NR_seccomp, SECCOMP_SET_MODE_FILTER,
SECCOMP_FILTER_FLAG_NEW_LISTENER, &prog);
if (seccomp_ret < 0)
err(1, "install");
printf("C: installed seccomp: fd %d\n", seccomp_ret);
/* Place the notifier FD number into the shared memory */
__atomic_store(&shared->seccomp_fd, &seccomp_ret,
__ATOMIC_RELEASE);
/* Wake the parent */
int futex_ret =
syscall(__NR_futex, &shared->seccomp_fd, FUTEX_WAKE,
INT_MAX, NULL, NULL, 0);
printf("C: woke %d waiters\n", futex_ret);
/* Establish SA_RESTART handler for SIGUSR1 */
struct sigaction act = {
.sa_sigaction = sigusr1_handler,
.sa_flags = SA_RESTART | SA_SIGINFO
};
if (sigaction(SIGUSR1, &act, NULL))
err(1, "sigaction");
struct sigaction act2 = {
.sa_sigaction = sigusr2_handler,
.sa_flags = 0
};
if (sigaction(SIGUSR2, &act2, NULL))
err(1, "sigaction");
/* Make a blocking system call */
perror("C: About to call pause()");
pause();
perror("C: pause returned");
exit(0);
}
/* PARENT */
/* Wait for futex wake-up from child */
int futex_ret = syscall(__NR_futex, &shared->seccomp_fd, FUTEX_WAIT,
-1, NULL, NULL, 0);
if (futex_ret == -1 && errno != EAGAIN)
err(1, "futex wait");
/* Get notification FD from the child */
int fd = __atomic_load_n(&shared->seccomp_fd, __ATOMIC_ACQUIRE);
printf("\tP: child installed seccomp fd %d\n", fd);
sleep(1);
printf("\tP: going to send SIGUSR1...\n");
kill(child, SIGUSR1);
sleep(1);
printf("\tP: about to terminate\n");
exit(0);
}
====
Scenario B
$ ./seccomp_unotify_restart_scen_B
C: installed seccomp: fd 3
C: woke 1 waiters
C: About to call pause()
P: child installed seccomp fd 3
P: about to SECCOMP_IOCTL_NOTIF_RECV
P: got notif: id=17773741941218455591 pid=25052 nr=34
P: about to send SIGUSR1 to child...
P: about to SECCOMP_IOCTL_NOTIF_RECV
C: sigusr1_handler handler invoked
P: got notif: id=17773741941218455592 pid=25052 nr=34
P: about to send SIGUSR1 to child...
P: about to SECCOMP_IOCTL_NOTIF_RECV
C: sigusr1_handler handler invoked
P: got notif: id=17773741941218455593 pid=25052 nr=34
P: about to send SIGUSR1 to child...
P: about to SECCOMP_IOCTL_NOTIF_RECV
C: sigusr1_handler handler invoked
P: got notif: id=17773741941218455594 pid=25052 nr=34
P: about to send SIGUSR1 to child...
C: sigusr1_handler handler invoked
C: got pdeath signal on parent termination
C: about to terminate
/* Modified version of code from Jann Horn */
#define _GNU_SOURCE
#include <stdio.h>
#include <signal.h>
#include <err.h>
#include <errno.h>
#include <unistd.h>
#include <stdlib.h>
#include <sched.h>
#include <stddef.h>
#include <string.h>
#include <limits.h>
#include <inttypes.h>
#include <sys/mman.h>
#include <sys/syscall.h>
#include <sys/ioctl.h>
#include <sys/prctl.h>
#include <linux/seccomp.h>
#include <linux/filter.h>
#include <linux/futex.h>
struct {
int seccomp_fd;
} *shared;
static void
sigusr1_handler(int sig, siginfo_t * info, void *uctx)
{
printf("C: sigusr1_handler handler invoked\n");
}
static void
sigusr2_handler(int sig, siginfo_t * info, void *uctx)
{
printf("C: got pdeath signal on parent termination\n");
printf("C: about to terminate\n");
exit(0);
}
static size_t
max_size(size_t a, size_t b)
{
return (a > b) ? a : b;
}
int
main(void)
{
setbuf(stdout, NULL);
/* Allocate memory that will be shared by parent and child */
shared = mmap(NULL, 0x1000, PROT_READ | PROT_WRITE,
MAP_ANONYMOUS | MAP_SHARED, -1, 0);
if (shared == MAP_FAILED)
err(1, "mmap");
shared->seccomp_fd = -1;
/* glibc's clone() wrapper doesn't support fork()-style usage */
/* Child process and parent share file descriptor table */
pid_t child = syscall(__NR_clone, CLONE_FILES | SIGCHLD,
NULL, NULL, NULL, 0);
if (child == -1)
err(1, "clone");
/* CHILD */
if (child == 0) {
/* don't outlive the parent */
prctl(PR_SET_PDEATHSIG, SIGUSR2);
if (getppid() == 1)
exit(0);
/* Install seccomp filter */
prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0);
struct sock_filter insns[] = {
BPF_STMT(BPF_LD | BPF_W | BPF_ABS,
offsetof(struct seccomp_data, nr)),
BPF_JUMP(BPF_JMP | BPF_JEQ | BPF_K, __NR_pause, 0, 1),
BPF_STMT(BPF_RET | BPF_K, SECCOMP_RET_USER_NOTIF),
BPF_STMT(BPF_RET | BPF_K, SECCOMP_RET_ALLOW)
};
struct sock_fprog prog = {
.len = sizeof(insns) / sizeof(insns[0]),
.filter = insns
};
int seccomp_ret = syscall(__NR_seccomp, SECCOMP_SET_MODE_FILTER,
SECCOMP_FILTER_FLAG_NEW_LISTENER, &prog);
if (seccomp_ret < 0)
err(1, "install");
printf("C: installed seccomp: fd %d\n", seccomp_ret);
/* Place the notifier FD number into the shared memory */
__atomic_store(&shared->seccomp_fd, &seccomp_ret,
__ATOMIC_RELEASE);
/* Wake the parent */
int futex_ret =
syscall(__NR_futex, &shared->seccomp_fd, FUTEX_WAKE,
INT_MAX, NULL, NULL, 0);
printf("C: woke %d waiters\n", futex_ret);
/* Establish SA_RESTART handler for SIGUSR1 */
struct sigaction act = {
.sa_sigaction = sigusr1_handler,
.sa_flags = SA_RESTART | SA_SIGINFO
};
if (sigaction(SIGUSR1, &act, NULL))
err(1, "sigaction");
struct sigaction act2 = {
.sa_sigaction = sigusr2_handler,
.sa_flags = 0
};
if (sigaction(SIGUSR2, &act2, NULL))
err(1, "sigaction");
/* Make a blocking system call */
printf("C: About to call pause()\n");
pause();
perror("C: pause returned");
exit(0);
}
/* PARENT */
/* Wait for futex wake-up from child */
int futex_ret = syscall(__NR_futex, &shared->seccomp_fd, FUTEX_WAIT,
-1, NULL, NULL, 0);
if (futex_ret == -1 && errno != EAGAIN)
err(1, "futex wait");
/* Get notification FD from the child */
int fd = __atomic_load_n(&shared->seccomp_fd, __ATOMIC_ACQUIRE);
printf("\tP: child installed seccomp fd %d\n", fd);
/* Discover seccomp buffer sizes and allocate notification buffer */
struct seccomp_notif_sizes sizes;
if (syscall(__NR_seccomp, SECCOMP_GET_NOTIF_SIZES, 0, &sizes))
err(1, "notif_sizes");
struct seccomp_notif *notif =
malloc(max_size(sizeof(struct seccomp_notif),
sizes.seccomp_notif));
if (!notif)
err(1, "malloc");
for (int i = 0; i < 4; i++) {
printf("\tP: about to SECCOMP_IOCTL_NOTIF_RECV\n");
memset(notif, '\0', sizes.seccomp_notif);
if (ioctl(fd, SECCOMP_IOCTL_NOTIF_RECV, notif))
err(1, "notif_recv");
printf("\tP: got notif: id=%llu pid=%u nr=%d\n",
notif->id, notif->pid, notif->data.nr);
sleep(1);
printf("\tP: about to send SIGUSR1 to child...\n");
kill(child, SIGUSR1);
}
sleep(1);
exit(0);
}
====
Reported-by: Jann Horn <jannh@google.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
In the usual case, read(fd, buf, PATH_MAX) will return PATH_MAX
bytes that include trailing garbage after the pathname. So the
right check is to scan from the start of the buffer to see if
there's a NUL, and error if there is not.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
After some discussions with Jann Horn, perhaps a better way of
dealing with an invalid target pathname is to trigger an
error for the system call.
Reported-by: Jann Horn <jannh@google.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
From a conversation with Jann Horn:
[[
>>>> struct seccomp_notif_resp *resp = malloc(sizes.seccomp_notif_resp);
>>>
>>> This should probably do something like max(sizes.seccomp_notif_resp,
>>> sizeof(struct seccomp_notif_resp)) in case the program was built
>>> against new UAPI headers that make struct seccomp_notif_resp big, but
>>> is running under an old kernel where that struct is still smaller?
>>
>> I'm confused. Why? I mean, if the running kernel says that it expects
>> a buffer of a certain size, and we allocate a buffer of that size,
>> what's the problem?
>
> Because in userspace, we cast the result of malloc() to a "struct
> seccomp_notif_resp *". If the kernel tells us that it expects a size
> smaller than sizeof(struct seccomp_notif_resp), then we end up with a
> pointer to a struct that consists partly of allocated memory, partly
> of out-of-bounds memory, which is generally a bad idea - I'm not sure
> whether the C standard permits that. And if userspace then e.g.
> decides to access some member of that struct that is beyond what the
> kernel thinks is the struct size, we get actual OOB memory accesses.
Got it. (But gosh, this seems like a fragile API mess.)
I added the following to the code:
/* When allocating the response buffer, we must allow for the fact
that the user-space binary may have been built with user-space
headers where 'struct seccomp_notif_resp' is bigger than the
response buffer expected by the (older) kernel. Therefore, we
allocate a buffer that is the maximum of the two sizes. This
ensures that if the supervisor places bytes into the response
structure that are past the response size that the kernel expects,
then the supervisor is not touching an invalid memory location. */
size_t resp_size = sizes.seccomp_notif_resp;
if (sizeof(struct seccomp_notif_resp) > resp_size)
resp_size = sizeof(struct seccomp_notif_resp);
struct seccomp_notif_resp *resp = malloc(resp_size);
]]
Reported-by: Jann Horn <jannh@google.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
From a conversation with Jann Horn:
>> We should probably make sure here that the value we read is actually
>> NUL-terminated?
>
> So, I was curious about that point also. But, (why) are we not
> guaranteed that it will be NUL-terminated?
Because it's random memory filled by another process, which we don't
necessarily trust. While seccomp notifiers aren't usable for applying
*extra* security restrictions, the supervisor will still often be more
privileged than the supervised process.
Reported-by: Jann Horn <jannh@google.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Change "read(2) will return 0" to "read(2) may return 0".
Quoting Jann Horn:
Maybe make that "may return 0" instead of "will return 0" -
reading from /proc/$pid/mem can only return 0 in the
following cases AFAICS:
1. task->mm was already gone at open() time
2. mm->mm_users has dropped to zero (the mm only has lazytlb
users; page tables and VMAs are being blown away or have
been blown away)
3. the syscall was called with length 0
When a process has gone away, normally mm->mm_users will
drop to zero, but someone else could theoretically still be
holding a reference to the mm (e.g. someone else in the
middle of accessing /proc/$pid/mem). (Such references
should normally not be very long-lived though.)
Additionally, in the unlikely case that the OOM killer just
chomped through the page tables of the target process, I
think the read will return -EIO (same error as if the
address was simply unmapped) if the address is within a
non-shared mapping. (Maybe that's something procfs could do
better...)
Reported-by: Jann Horn <jannh@google.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Add some strongly worded text warning the reader about the correct
uses of seccomp user-space notification.
Reported-by: Jann Horn <jannh@google.com>
Cowritten-by: Christian Brauner <christian@brauner.io>
Cowritten-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The APIs used by this mechanism comprise not only seccomp(2), but
also a number of ioctl(2) operations. And any useful example
demonstrating these APIs is will necessarily be rather long.
Trying to cram all of this into the seccomp(2) page would make
that page unmanageably long. Therefore, let's document this
mechanism in a separate page.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The existing text says the structures (plural!) contain a 'struct
seccomp_data'. But this is only true for the received notification
structure (seccomp_notif). So, reword the sentence to be more
general, noting simply that the structures may evolve over time.
Add some comments to the structure definition.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Rework the description a little, and note that the close-on-exec
flag is set for the returned file descriptor.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
I can't see a reason to include it. <fcntl.h> provides O_*
constants for 'flags', S_* constants for 'mode', and mode_t.
Probably a long time ago, some of those weren't defined in
<fcntl.h>, and both headers needed to be included, or maybe it's
a historical error.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
My previous patch intended to drop the docs for the lockdown lift
SysRq, but it missed this other section that refers to lifting it
via a keyboard - an allusion to that same SysRq.
Signed-off-by: dann frazier <dann.frazier@canonical.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The patch that implemented lockdown lifting via SysRq ended up
getting dropped[*] before the feature was merged upstream. Having
the feature documented but unsupported has caused some confusion
for our users.
[*] http://archive.lwn.net:8080/linux-kernel/CACdnJuuxAM06TcnczOA6NwxhnmQUeqqm3Ma8btukZpuCS+dOqg@mail.gmail.com/
Signed-off-by: dann frazier <dann.frazier@canonical.com>
Cc: Heinrich Schuchardt <xypron.glpk@gmx.de>
Cc: David Howells <dhowells@redhat.com>
Cc: Pedro Principeza <pedro.principeza@canonical.com>
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Kyle McMartin <kyle@redhat.com>
Cc: Matthew Garrett <mjg59@google.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Instead of having a monolithic 'make install', break it into
multiple targets such as 'make install-man3'. This simplifies
packaging, for example in Debian, where they break this project
into several packages: 'manpages' and 'manpages-dev', each
containing different mandirs.
The above allows for multithread installation: 'make -j'
Also, don't overwrite files that don't need to be overwritten, by
having a target for files, which makes use of make's timestamp
comparison.
This allows for much faster installation times.
For comparison, on my laptop (i7-8850H; 6C/12T):
Old Makefile:
~/src/linux/man-pages$ time sudo make >/dev/null
real 0m7.509s
user 0m5.269s
sys 0m2.614s
The times with the old makefile, varied a lot, between
5 and 10 seconds. The times after applying this patch
are much more consistent. BTW, I compared these times to
the very old Makefile of man-pages-5-09, and those were
around 3.5 s, so it was a bit of my fault to have such a
slow Makefile, when I changed the Makefile some weeks ago.
New Makefile (full clean install):
~/src/linux/man-pages$ time sudo make >/dev/null
real 0m5.160s
user 0m4.326s
sys 0m1.137s
~/src/linux/man-pages$ time sudo make -j2 >/dev/null
real 0m1.602s
user 0m2.529s
sys 0m0.289s
~/src/linux/man-pages$ time sudo make -j >/dev/null
real 0m1.398s
user 0m2.502s
sys 0m0.281s
Here we can see that 'make -j' drops times drastically,
compared to the old monolithic Makefile. Not only that,
but since when we are working with the man pages there
aren't many pages involved, times will be even better.
Here are some times with a single page changed (touched):
New Makefile (one page touched):
~/src/linux/man-pages$ touch man2/membarrier.2
~/src/linux/man-pages$ time sudo make install
- INSTALL /usr/local/share/man/man2/membarrier.2
real 0m0.988s
user 0m0.966s
sys 0m0.025s
~/src/linux/man-pages$ touch man2/membarrier.2
~/src/linux/man-pages$ time sudo make install -j
- INSTALL /usr/local/share/man/man2/membarrier.2
real 0m0.989s
user 0m0.943s
sys 0m0.049s
Also, modify the output of the make install and uninstall commands
so that a line is output for each file or directory that is
installed, similarly to the kernel's Makefile. This doesn't apply
to html targets, which haven't been changed in this commit.
Also, make sure that for each invocation of $(INSTALL_DIR), no
parents are created, (i.e., avoid `mkdir -p` behavior). The GNU
make manual states that it can create race conditions. Instead,
declare as a prerequisite for each directory its parent directory,
and let make resolve the order of creation.
Also, use ':=' instead of '=' to improve performance, by
evaluating each assignment only once.
Ensure than the shell is not called when not needed, by removing
all ";" and quotes in the commands.
See also: <https://stackoverflow.com/q/67862417/6872717>
Specify conventions and rationales used in the Makefile in a comment.
Add copyright.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Document also why each header is required
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This function doesn't use any flags or special types, so there's
no reason to include <asm/unistd.h>; remove it. Add the includes
needed for syscall(2) only.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Also document why each header is needed.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This error can occur if the caller is does not have CAP_IPC_LOCK
and is not a member of the sysctl_hugetlb_shm_group.
Reported-by: Yang Xu <xuyang2018.jy@fujitsu.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
As a deprecated feature, it appears that the RLIMIT_MEMLOCK
can also be used to permit huge page allocation, but let's
not document that for now.
In the Linux 5.12, see fs/hugetlbfs/inode.c.
static int can_do_hugetlb_shm(void)
{
kgid_t shm_group;
shm_group = make_kgid(&init_user_ns, sysctl_hugetlb_shm_group);
return capable(CAP_IPC_LOCK) || in_group_p(shm_group);
}
...
struct file *hugetlb_file_setup(const char *name, size_t size,
vm_flags_t acctflag, struct user_struct **user,
int creat_flags, int page_size_log)
{
...
if (creat_flags == HUGETLB_SHMFS_INODE && !can_do_hugetlb_shm()) {
*user = current_user();
if (user_shm_lock(size, *user)) {
task_lock(current);
pr_warn_once("%s (%d): Using mlock ulimits for SHM_HUGETLB is deprecated\n",
current->comm, current->pid);
task_unlock(current);
} else {
*user = NULL;
return ERR_PTR(-EPERM);
}
}
...
}
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The installation path was changed recently (See 'prefix' in the
Makefile). I forgot to update the README with those changes.
Fix it.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Explain also why headers are needed.
And some ffix.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
It is only used for providing 'sigset_t'. We're only documenting
(with some exceptions) the includes needed for constants and the
prototype itself. And 'sigset_t' is better documented in
system_data_types(7). Remove that include.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
All of the constants used by mknod() are defined in <sys/stat.h>.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
AFAICS, there's no use for <unistd.h> here. The prototype is
declared in <sys/mman.h>, and there are no constants needed.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Remove the libkeyutils prototype from the synopsis, which isn't
documented in the rest of the page, and as NOTES says, it's
probably better to use the various library functions.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The constants needed for using this function are defined in
<linux/ipc.h>. Add the include, even when those constants are not
mentioned in this manual page.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Of course that is for the glibc wrapper. As all of the other
pages that don't explicitly say otherwise.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
In this case there's a wrapper provided by libaio,
but this page documents the raw syscall.
Also remove <linux/time.h> from the includes: 'struct timespec'
is already documented in system_data_types(7), where the
information is more up to date.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
In this case there's a wrapper provided by libaio,
but this page documents the raw syscall.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
At the same time, document only headers that are required
for calling the function, or those that are specific to the
function:
<unistd.h> is required for the syscall() prototype.
<sys/syscall.h> is required for the syscall name SYS_xxx.
<linux/futex.h> is specific to this syscall.
However, uint32_t is generic enough that it shouldn't be
documented here. The system_data_types(7) page already documents
it, and is more precise about it. The same goes for timespec.
As a general rule a man[23] page should document the header that
includes the prototype, and all of the headers that define macros
that should be used with the call. However, the information about
types should be restricted to system_data_types(7) (and that page
should probably be improved by adding types), except for types
that are very specific to the call. Otherwise, we're duplicating
info and it's then harder to maintain, and probably outdated in
the future.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This complements commit e3eba861bd.
Since we don't need syscall(2) anymore, we don't need SYS_* definitions.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
On 5/10/21 7:13 PM, Alejandro Colomar (man-pages) wrote:
> Hi Michael,
>
> On 5/10/21 1:39 AM, Michael Kerrisk (man-pages) wrote:
>>> - Specify shebang
>>
>> Why? It's not quite obvious to me, and the commit message
>> should really explain...
>
> Hmmm. I have some minor reasons to add it, but not a really good one.
>
> * Some editors don't recognize 'Makefile' as a special name, so the
> shebang helps detecting which language the file is using (e.g., for
> coloring).
>
> * I tend to subdivide a big Makefile into a small Makefile and many
> submakefiles stored in <./libexec/>. Those obviously need different
> names, and given that the makefile extension is not very standard (I use
> .mk), having a shebang helps knowing what the file is. After that, I
> also have it on the main Makefile for consistency. But here we only
> have one Makefile, so it doesn apply very much.
I think I'll remove it. It is kind of idiosyncratic, leaves the
reader asking "why?".
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Ignore everything new by default.
This avoids having to update the .gitignore when we need to ignore
something new. It also avoids accidents that may add an unwanted
temporary file.
Cc: Debian man-pages <manpages@packages.debian.org>
Cc: Dr. Tobias Quathamer <toddy@debian.org>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
fpurge(i_stream) does the same as fflush(i_stream), AFAIK.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
AT_EMPTY_PATH works with empty strings (""), but not with NULL
(or at least it's not obvious).
The relevant kernel code is the following:
linux$ sed -n 189,198p fs/namei.c
result->refcnt = 1;
/* The empty path is special. */
if (unlikely(!len)) {
if (empty)
*empty = 1;
if (!(flags & LOOKUP_EMPTY)) {
putname(result);
return ERR_PTR(-ENOENT);
}
}
Reported-by: Walter Harms <wharms@bfs.de>
Cc: Theodore Ts'o <tytso@mit.edu>
Cc: Adam Borowski <kilobyte@angband.pl>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
See <bits/byteswap.h> in glibc.
These macros call functions of the form __bswap_N(),
which use uintN_t.
Even though it's true that they are macros,
it's transparent to the user.
The user will see their results casted to unsigned types
after the conversion due to the underlying functions,
so it's better to document these as the underlying functions,
specifying the types.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Both POSIX and glibc use 'restrict' in
pthread_attr_getinheritsched().
Let's use it here too.
.../glibc$ grep_glibc_prototype pthread_attr_getinheritsched
sysdeps/htl/pthread.h:90:
extern int pthread_attr_getinheritsched (const pthread_attr_t *__restrict __attr,
int *__restrict __inheritsched)
__THROW __nonnull ((1, 2));
sysdeps/nptl/pthread.h:313:
extern int pthread_attr_getinheritsched (const pthread_attr_t *__restrict
__attr, int *__restrict __inherit)
__THROW __nonnull ((1, 2));
.../glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
'C library/kernel differences' was added to BUGS incorrectly.
Fix it
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Those pages didn't exist. Fix the section number.
I noticed the typo thanks to the HTML pages on man7.org.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Prerequisites can run in parallel. This wouldn't make any sense
when uninstalling and installing again.
For that, use consecutive commands, which run one after the other
even with multiple cores.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
IMPORTANT for distributions:
This changes prefix to be '/usr/local' as is expected by default,
instead of the old '/usr' value.
- Use standard variables:
- prefix should be '/usr/local'
- mandir (instead of MANDIR)
- htmldir (instead of HTDIR)
- ...
see <https://www.gnu.org/software/make/manual/html_node/Directory-Variables.html>
- Use standard targets:
- html (build html files; don't install them)
- install-html (instead of html)
- installdirs (instead of 'mkdir -p'/'install -d' inside other targets)
- ...
see <https://www.gnu.org/software/make/manual/html_node/Standard-Targets.html#Standard-Targets>
- Use .PHONY
- ?= is not needed. User input overrides any assignment. Use =
- Use standard command variables, instead of directly calling commands.
- $(INSTALL_DATA) (instead of install -m 644)
- $(INSTALL_DIR) (instead of install -d -m 755 or mkdir -p)
see <https://www.gnu.org/software/make/manual/html_node/Command-Variables.html#Command-Variables>
- Specify SHELL = /bin/bash
- Specify shebang
- Allow variable html extension (or no extension at all)
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
mkdir -p doesn't fail if the directory already exists.
Remove redundant checks.
Use .html as default HTDIR.
Remove checks for undefined HTDIR.
Show what the target does, as with other targets (remove '@').
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
I clarified the code about two things:
- Checking how many arguments are being passed.
Here, some functions didn't reject extra arguments when they
weren't being used. Fix that.
I also changed the code to use $#, which is more explicit.
And use arithmetic expressions, which better indicate that
we're dealing with numbers.
- Remove unneeded options from sort.
Reported-by: Stefan Puiu <stefan.puiu@gmail.com>
After Stefan asked about why am I using 'sort -V',
I noticed that I really don't need '-V', and it may confuse
people trying to understand the script, so even though I
slightly prefer the output of 'sort -V', in this case, it's
better to use the simpler 'sort' (yet I need 'sort', to
maintain consistency in the results (find is quite random)).
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Fix the error messages to clearly show that both dirs and manual
pages are accepted, and that more than one argument is accepted.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This patch makes man_lsfunc() search for the function prototypes,
instead of relying on the current manual page formatting,
which might change in the future, and break this function.
It also simplifies the code, by reusing man_section().
Create a new function sed_rm_ccomments(), which is needed by
man_lsfunc(), and may also be useful in other cases.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The output of 'git status' is not stable.
The more stable 'git status --porcelain' is more complex,
and scripting around it would be more complex.
However, 'git diff --staged --name-only' produces
the output that we were lookiong for.
Reported-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Neither POSIX or glibc use 'const' in
pthread_mutexattr_setrobust().
Remove it.
.../glibc$ grep_glibc_prototype pthread_mutexattr_setrobust
sysdeps/htl/pthread.h:355:
extern int pthread_mutexattr_setrobust (pthread_mutexattr_t *__attr,
int __robustness)
__THROW __nonnull ((1));
sysdeps/nptl/pthread.h:888:
extern int pthread_mutexattr_setrobust (pthread_mutexattr_t *__attr,
int __robustness)
__THROW __nonnull ((1));
.../glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The rest of the page writes the characters without naming them.
Follow that convention.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Improved the `getopt(3)` man page in the following ways:
1) Defined the existing term "legitimate option character".
2) Added an additional NOTE stressing that arguments are parsed in strict
order and the implications of this when numeric options are utilised.
Signed-off-by: James O. D. Hunt <jamesodhunt@gmail.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Despite my mention of this spawning a hilarious discussion
on IRC, this alignment restriction should be 128-bit, not
126-bit.
Signed-off-by: Johannes Berg <johannes@sipsolutions.net>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Add a missing "to" in an "in order to" formulation.
Signed-off-by: Borislav Petkov <bp@suse.de>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
CIFS flock() locks behave differently than the standard. Give overview
of those differences.
Here is the rendered text:
CIFS details
In Linux kernels up to 5.4, flock() is not propagated over SMB. A file
with such locks will not appear locked for remote clients.
Since Linux 5.5, flock() locks are emulated with SMB byte-range locks
on the entire file. Similarly to NFS, this means that fcntl(2) and
flock() locks interact with one another. Another important side-effect
is that the locks are not advisory anymore: any IO on a locked file
will always fail with EACCES when done from a separate file descriptor.
This difference originates from the design of locks in the SMB proto-
col, which provides mandatory locking semantics.
Remote and mandatory locking semantics may vary with SMB protocol,
mount options and server type. See mount.cifs(8) for additional infor-
mation.
Signed-off-by: Aurelien Aptel <aaptel@suse.com>
Discussion: linux-man <https://lore.kernel.org/linux-man/20210302154831.17000-1-aaptel@suse.com/>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
In b0b19983d9 we removed
<sys/types.h>. For the same reasons there, remove now <sys/ipc.h>
from many pages.
If someone wonders why <sys/ipc.h> was needed, the reason was to
get all the definitions of IPC_* constants. However, that header
is now included by <sys/msg.h>, so it's not needed anymore to
explicitly include it. Quoting POSIX: "In addition, the
<sys/msg.h> header shall include the <sys/ipc.h> header."
There were some remaining cases where I forgot to remove
<sys/types.h>; remove them now too.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
AFAICS, all types and constants used by these functions are
defined in <fcntl.h>.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
A few architectures have a different call signature for pipe().
Since those architectures are the minority, place the prototype
at the end of the SYNOPSIS, rather than the start.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
SEE ALSO: move pam_namespace(8) from namespaces(7) to
mount_namespaces(7) (since pam_namespace(8) makes use of
mount namespaces specifically).
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Userfaultfd write-protect mode is supported starting from Linux 5.7.
Acked-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
Signed-off-by: Peter Xu <peterx@redhat.com>
[alx: ffix + srcfix]
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
UFFD_FEATURE_THREAD_ID is supported in Linux 4.14.
Acked-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
Signed-off-by: Peter Xu <peterx@redhat.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Write-protect mode is supported starting from Linux 5.7.
Acked-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
Signed-off-by: Peter Xu <peterx@redhat.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
UFFD_FEATURE_THREAD_ID is supported since Linux 4.14.
Acked-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
Signed-off-by: Peter Xu <peterx@redhat.com>
[alx: srcfix]
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
My initial reading of this was that type modifiers were probably
not supported. But they are, and this is actually documented
further up, in the type modifiers documentation. But to make it
clearer, let's copy the language that printf(3) has in its %n
section.
Signed-off-by: Alyssa Ross <hi@alyssa.is>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
In this case there's a wrapper provided by libaio,
but this page documents the raw kernel syscall.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
<linux/unistd.h> is not needed. We need <unistd.h> for syscall(),
and <sys/syscall.h> for SYS_exit_group.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Add <linux/fcntl.h>, which contains AT_* definitions used by
execveat().
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The CLONE_* constants seem to be available from either
<linux/sched.h> or <sched.h>, and since clone3() already
includes <linux/sched.h> for 'struct clone_args', <sched.h>
is not really needed, AFAICS; however, to avoid confusion,
I also included <sched.h> for clone3() for consistency:
clone() is getting CLONE_* from <sched.h>, and it would confuse
the reader if clone3() got the same CLONE_* constants from a
different header.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
AFAICS, there's no reason to include that.
All of the macros that this function uses
are already defined in the other headers.
Cc: glibc <libc-alpha@sourceware.org>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The page didn't specify includes, and the syscalls are extinct, so
instead of adding incomplete information about includes, just
leave it without any includes.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Only the include that provides the prototype doesn't need a comment.
Also sort the includes alphabetically.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Only the one that provides the prototype doesn't need a comment.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
<linux/fs.h> doesn't seem to be needed!
Only the include that provides the prototype doesn't need a comment.
Also sort the includes alphabetically.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Only the include that provides the prototype doesn't need a comment.
Also sort the includes alphabetically.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Only the one that provides the prototype doesn't need a comment.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
[mtk: Alex's change switches the comment to the more generally used
form "Definition of..."]
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
<sys/time.h> is not needed to get the function declaration nor any
constant used by the function. It was only needed (before
POSIX.1) to get 'struct timeval', but that information would be
more suited for system_data_types(7), and not for this page.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
<sys/time.h> is not required by any of the function declarations
or macro definitions used by these functions. It may be (or maybe
not) needed by some type inside the rlimit structure, but that
info belongs in system_data_types(7), not here.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
<sys/types.h> was only needed for size_t, AFAIK. That is already
(and more precisely) documented in system_data_types(7). Let's
remove it here, as it's not really needed for calling add_key().
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
I couldn't find a reason for including <unistd.h>. All the macros
used by fcntl() are defined in <fcntl.h>. For comparison, FreeBSD
and OpenBSD don't specify <unistd.h> in their manual pages.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This function never returns to its caller.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
ENODATA is an XSI STREAMS extension (not base POSIX).
Linux reused the name for extended attributes.
The current manual pages don't use ENODATA with its POSIX
meaning, so use the xattr(7) specific text, and leave the POSIX
meaning for a secondary paragraph.
Reported-by: Mark Kettenis <kettenis@openbsd.org>
Reported-by: Florian Weimer <fw@deneb.enyo.de>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Checked via the latest glibc source. execvpe calls getenv("PATH") and
searches that; the PATH in envp does not affect the search.
Signed-off-by: Josh Triplett <josh@joshtriplett.org>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
In Linux kernel 5.12, a new mode flag, MPOL_F_NUMA_BALANCING, is
added to set_mempolicy() to optimize the page placement among the
NUMA nodes with the NUMA balancing mechanism even if the memory of
the applications is bound with MPOL_BIND. This patch updates the
man page for the new mode flag.
Related kernel commits:
bda420b985054a3badafef23807c4b4fa38a3dff
[mtk: Minor fixes to commit message]
Signed-off-by: "Huang, Ying" <ying.huang@intel.com>
Cc: "Michael Kerrisk" <mtk.manpages@gmail.com>
[ alx: srcfix ]
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The envp argument specifies the environment of the new process image,
not "the environment of the caller".
Signed-off-by: Josh Triplett <josh@joshtriplett.org>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The format string refers to the whole string passed in 'format'.
The syntax referred to is that of a conversion specification,
as called in the manual page.
Use specific language.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Can we add a small syntax structure for format string in printf(3)
manual. I personally find if easier to remember and scan. This has
been taken from OpenBSD printf(3) manual.
Signed-off-by: Utkarsh Singh <utkarsh190601@gmail.com>
[ alx: ffix ]
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Add a sentence explaining what dup2() does in terms of file
descriptors and open file descriptions.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Sometimes people are confused, thinking a file descriptor is just a
number. To help avoid such confusions, add text highlighting that
a file descriptor is an index to an entry in the process's FD table.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
As can be seen by any number of StackOverflow questions, people
persistently misunderstand what dup() does, and the existing manual
page text, which talks of "copying" a file descriptor doesn't help.
Rewrite the text a little to try to prevent some of these
misunderstandings, in particular noting at the start that dup()
allocates a new file descriptor.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
close_range() CLOSE_RANGE_USHARE triggers a call to dup_fd()
which in turn calls alloc_fdtable(), which checks that
sysctl_nr_open has not been exceeded.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The current example program can't really be used to demonstrate the
effect of close_range(). Replace it by a program that does show the
effect of this system call.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This documents close_range(2) based on information in
278a5fbaed89dacd04e9d052f4594ffd0e0585de,
60997c3d45d9a67daf01c56d805ae4fec37e0bd8, and
582f1fb6b721facf04848d2ca57f34468da1813e.
Reported-by: Christian Brauner <christian.brauner@ubuntu.com>
Signed-off-by: Stephen Kitt <steve@sk2.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The manual pages are already inconsistent in which headers need
to be included. Right now, not all of the types used by a
function have their required header included in the SYNOPSIS.
If we were to add the headers required by all of the types used by
functions, the SYNOPSIS would grow too much. Not only it would
grow too much, but the information there would be less precise.
Having system_data_types(7) document each type with all the
information about required includes is much more precise, and the
info is centralized so that it's much easier to maintain.
So let's document only the include required for the function
prototype, and also the ones required for the macros needed to
call the function.
<sys/types.h> only defines types, not functions or constants, so
it doesn't belong to man[23] (function) pages at all.
I ignore if some old systems had headers that required you to
include <sys/types.h> *before* them (incomplete headers), but if
so, those implementations would be broken, and those headers
should probably provide some kind of warning. I hope this is not
the case.
[mtk: Already in 2001, POSIX.1 removed the requirement to
include <sys/types.h> for many APIs, so this patch seems
well past due.]
Acked-by: Zack Weinberg <zackw@panix.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
POSIX uses 'restrict' in *wprintf() (see [v]fwprintf(3p)).
Let's use it here too.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
In SYNOPSIS, shift arguments right a little to make the function
names stand out a little more.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Both POSIX and glibc use 'restrict' in wordexp().
Let's use it here too.
.../glibc$ grep_glibc_prototype wordexp
posix/wordexp.h:62:
extern int wordexp (const char *__restrict __words,
wordexp_t *__restrict __pwordexp, int __flags);
.../glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Both POSIX and glibc use 'restrict' in wmemcpy().
Let's use it here too.
.../glibc$ grep_glibc_prototype wmemcpy
wcsmbs/wchar.h:262:
extern wchar_t *wmemcpy (wchar_t *__restrict __s1,
const wchar_t *__restrict __s2, size_t __n) __THROW;
.../glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Both POSIX and glibc use 'restrict' in wcstok().
Let's use it here too.
.../glibc$ grep_glibc_prototype wcstok
wcsmbs/wchar.h:217:
extern wchar_t *wcstok (wchar_t *__restrict __s,
const wchar_t *__restrict __delim,
wchar_t **__restrict __ptr) __THROW;
.../glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Both POSIX and glibc use 'restrict' in wcscpy().
Let's use it here too.
.../glibc$ grep_glibc_prototype wcscpy
wcsmbs/wchar.h:87:
extern wchar_t *wcscpy (wchar_t *__restrict __dest,
const wchar_t *__restrict __src)
__THROW __nonnull ((1, 2));
.../glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Both POSIX and glibc use 'restrict' in wcscat().
Let's use it here too.
.../glibc$ grep_glibc_prototype wcscat
wcsmbs/wchar.h:97:
extern wchar_t *wcscat (wchar_t *__restrict __dest,
const wchar_t *__restrict __src)
__THROW __nonnull ((1, 2));
.../glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Both POSIX and glibc use 'restrict' in wcrtomb().
Let's use it here too.
.../glibc$ grep_glibc_prototype wcrtomb
wcsmbs/wchar.h:301:
extern size_t wcrtomb (char *__restrict __s, wchar_t __wc,
mbstate_t *__restrict __ps) __THROW;
.../glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Both POSIX and glibc use 'restrict' in wcpncpy().
Let's use it here too.
.../glibc$ grep_glibc_prototype wcpncpy
wcsmbs/wchar.h:556:
extern wchar_t *wcpncpy (wchar_t *__restrict __dest,
const wchar_t *__restrict __src, size_t __n)
__THROW;
.../glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Both POSIX and glibc use 'restrict' in wcpcpy().
Let's use it here too.
.../glibc$ grep_glibc_prototype wcpcpy
wcsmbs/wchar.h:551:
extern wchar_t *wcpcpy (wchar_t *__restrict __dest,
const wchar_t *__restrict __src) __THROW;
.../glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Both POSIX and glibc use 'restrict' in tdelete().
Let's use it here too.
.../glibc$ grep_glibc_prototype tdelete
misc/search.h:138:
extern void *tdelete (const void *__restrict __key,
void **__restrict __rootp,
__compar_fn_t __compar);
.../glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Both POSIX and glibc use 'restrict' in sigwait().
Let's use it here too.
.../glibc$ grep_glibc_prototype sigwait
signal/signal.h:255:
extern int sigwait (const sigset_t *__restrict __set, int *__restrict __sig)
__nonnull ((1, 2));
.../glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Both POSIX and glibc use 'restrict' in strptime().
However, glibc doesn't specify 'restrict' for the last parameter.
Let's use the most restrictive form here
(although I believe both to be equivalent).
.../glibc$ grep_glibc_prototype strptime
time/time.h:95:
extern char *strptime (const char *__restrict __s,
const char *__restrict __fmt, struct tm *__tp)
__THROW;
.../glibc$
Cc: <libc-alpha@sourceware.org>
Cc: Ulrich Drepper <drepper@redhat.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Both POSIX and glibc use 'restrict' in stpcpy().
Let's use it here too.
.../glibc$ grep_glibc_prototype stpcpy
string/string.h:475:
extern char *stpcpy (char *__restrict __dest, const char *__restrict __src)
__THROW __nonnull ((1, 2));
.../glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Both POSIX and glibc use 'restrict' in statvfs().
Let's use it here too.
.../glibc$ grep_glibc_prototype statvfs
io/sys/statvfs.h:51:
extern int statvfs (const char *__restrict __file,
struct statvfs *__restrict __buf)
__THROW __nonnull ((1, 2));
.../glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Both POSIX and glibc use 'restrict' in sem_timedwait().
Let's use it here too.
.../glibc$ grep_glibc_prototype sem_timedwait
sysdeps/pthread/semaphore.h:62:
extern int sem_timedwait (sem_t *__restrict __sem,
const struct timespec *__restrict __abstime)
__nonnull ((1, 2));
.../glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Both POSIX and glibc use 'restrict' in sem_getvalue().
Let's use it here too.
.../glibc$ grep_glibc_prototype sem_getvalue
sysdeps/pthread/semaphore.h:81:
extern int sem_getvalue (sem_t *__restrict __sem, int *__restrict __sval)
__THROW __nonnull ((1, 2));
.../glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Both POSIX and glibc use 'restrict' in realpath().
Let's use it here too.
.../glibc$ grep_glibc_prototype realpath
stdlib/stdlib.h:800:
extern char *realpath (const char *__restrict __name,
char *__restrict __resolved) __THROW __wur;
.../glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Both POSIX and glibc use 'restrict' in readdir_r().
Let's use it here too.
.../glibc$ grep_glibc_prototype readdir_r
dirent/dirent.h:183:
extern int readdir_r (DIR *__restrict __dirp,
struct dirent *__restrict __entry,
struct dirent **__restrict __result)
__nonnull ((1, 2, 3)) __attribute_deprecated__;
.../glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Both POSIX and glibc use 'restrict' in fputs().
Let's use it here too.
.../glibc$ grep_glibc_prototype fputs
libio/stdio.h:631:
extern int fputs (const char *__restrict __s, FILE *__restrict __stream);
.../glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
glibc uses 'restrict' in putgrent().
Let's use it here too.
.../glibc$ grep_glibc_prototype putgrent
grp/grp.h:93:
extern int putgrent (const struct group *__restrict __p,
FILE *__restrict __f);
.../glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Both POSIX and glibc use 'restrict' in pthread_getschedparam().
Let's use it here too.
.../glibc$ grep_glibc_prototype pthread_getschedparam
sysdeps/htl/pthread.h:882:
extern int pthread_getschedparam (pthread_t __thr, int *__restrict __policy,
struct sched_param *__restrict __param)
__THROW __nonnull ((2, 3));
sysdeps/nptl/pthread.h:426:
extern int pthread_getschedparam (pthread_t __target_thread,
int *__restrict __policy,
struct sched_param *__restrict __param)
__THROW __nonnull ((2, 3));
.../glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Both POSIX and glibc use 'restrict' in
pthread_mutexattr_getpshared().
Let's use it here too.
.../glibc$ grep_glibc_prototype pthread_mutexattr_getpshared
sysdeps/htl/pthread.h:368:
extern int pthread_mutexattr_getpshared(const pthread_mutexattr_t *__restrict __attr,
int *__restrict __pshared)
__THROW __nonnull ((1, 2));
sysdeps/nptl/pthread.h:830:
extern int pthread_mutexattr_getpshared (const pthread_mutexattr_t *
__restrict __attr,
int *__restrict __pshared)
__THROW __nonnull ((1, 2));
.../glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Both POSIX and glibc use 'restrict' in pthread_attr_getscope().
Let's use it here too.
.../glibc$ grep_glibc_prototype pthread_attr_getscope
sysdeps/htl/pthread.h:125:
extern int pthread_attr_getscope (const pthread_attr_t *__restrict __attr,
int *__restrict __contentionscope)
__THROW __nonnull ((1, 2));
sysdeps/nptl/pthread.h:324:
extern int pthread_attr_getscope (const pthread_attr_t *__restrict __attr,
int *__restrict __scope)
__THROW __nonnull ((1, 2));
.../glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Both POSIX and glibc use 'restrict' in pthread_attr_getschedpolicy().
Let's use it here too.
.../glibc$ grep_glibc_prototype pthread_attr_getschedpolicy
sysdeps/htl/pthread.h:113:
extern int pthread_attr_getschedpolicy (const pthread_attr_t *__restrict __attr,
int *__restrict __policy)
__THROW __nonnull ((1, 2));
sysdeps/nptl/pthread.h:304:
extern int pthread_attr_getschedpolicy (const pthread_attr_t *__restrict
__attr, int *__restrict __policy)
__THROW __nonnull ((1, 2));
.../glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
POSIX uses 'restrict' in posix_spawnp().
However, glibc doesn't.
Let's document here the more restrictive of them, which is POSIX.
I reported a bug to glibc about this.
$ man 3p posix_spawnp |sed -n '/^SYNOPSIS/,/;/p'
SYNOPSIS
#include <spawn.h>
int posix_spawnp(pid_t *restrict pid, const char *restrict file,
const posix_spawn_file_actions_t *file_actions,
const posix_spawnattr_t *restrict attrp,
char *const argv[restrict], char *const envp[restrict]);
$
.../glibc$ grep_glibc_prototype posix_spawnp
posix/spawn.h:85:
extern int posix_spawnp (pid_t *__pid, const char *__file,
const posix_spawn_file_actions_t *__file_actions,
const posix_spawnattr_t *__attrp,
char *const __argv[], char *const __envp[])
__nonnull ((2, 5));
.../glibc$
I conciously did an exception with respect to the right margin
of the rendered page. Instead of having the right margin at 78
as usual (per Branden's recommendation), I let it use col 79
this time, to avoid breaking the prototype in an ugly way,
or shifting all of the parameters to the left, unaligned with
respect to the function parentheses.
Bug: glibc <https://sourceware.org/bugzilla/show_bug.cgi?id=27529>
Cc: G. Branden Robinson <g.branden.robinson@gmail.com>
Cc: glibc <libc-alpha@sourceware.org>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Both POSIX and glibc use 'restrict' in posix_spawn().
Let's use it here too.
.../glibc$ grep_glibc_prototype posix_spawn
posix/spawn.h:72:
extern int posix_spawn (pid_t *__restrict __pid,
const char *__restrict __path,
const posix_spawn_file_actions_t *__restrict
__file_actions,
const posix_spawnattr_t *__restrict __attrp,
char *const __argv[__restrict_arr],
char *const __envp[__restrict_arr])
__nonnull ((2, 5));
.../glibc$
I conciously did an exception with respect to the right margin
of the rendered page. Instead of having the right margin at 78
as usual (per Branden's recommendation), I let it use col 79
this time, to avoid breaking the prototype in an ugly way,
or shifting all of the parameters to the left, unaligned with
respect to the function parentheses.
Cc: G. Branden Robinson <g.branden.robinson@gmail.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Both POSIX and glibc use 'restrict' in mq_setattr().
Let's use it here too.
.../glibc$ grep_glibc_prototype mq_setattr
rt/mqueue.h:51:
extern int mq_setattr (mqd_t __mqdes,
const struct mq_attr *__restrict __mqstat,
struct mq_attr *__restrict __omqstat)
__THROW __nonnull ((2));
.../glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Both POSIX and glibc use 'restrict' in mbtowc().
Let's use it here too.
.../glibc$ grep_glibc_prototype mbtowc
stdlib/stdlib.h:925:
extern int mbtowc (wchar_t *__restrict __pwc,
const char *__restrict __s, size_t __n) __THROW;
.../glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Both POSIX and glibc use 'restrict' in mbrlen().
Let's use it here too.
.../glibc$ grep_glibc_prototype mbrlen
wcsmbs/wchar.h:307:
extern size_t mbrlen (const char *__restrict __s, size_t __n,
mbstate_t *__restrict __ps) __THROW;
.../glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Both POSIX.1-2001 and glibc use 'restrict' in swapcontext().
Let's use it here too.
.../glibc$ grep_glibc_prototype swapcontext
stdlib/ucontext.h:41:
extern int swapcontext (ucontext_t *__restrict __oucp,
const ucontext_t *__restrict __ucp)
__THROWNL __INDIRECT_RETURN;
.../glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Both POSIX and glibc use 'restrict' in lio_listio().
However, POSIX is a bit more restrictive than glibc
for the second parameter.
Let's document the more restrictive POSIX variant.
$ man 3p lio_listio |sed -n '/^SYNOPSIS/,/;/p'
SYNOPSIS
#include <aio.h>
int lio_listio(int mode, struct aiocb *restrict const list[restrict],
int nent, struct sigevent *restrict sig);
$
.../glibc$ grep_glibc_prototype lio_listio
rt/aio.h:148:
extern int lio_listio (int __mode,
struct aiocb *const __list[__restrict_arr],
int __nent, struct sigevent *__restrict __sig)
__THROW __nonnull ((2));
.../glibc$
Cc: Szabolcs Nagy <Szabolcs.Nagy@arm.com>
Cc: "Joseph S. Myers" <joseph@codesourcery.com>
Cc: Ulrich Drepper <drepper@redhat.com>
Cc: Florian Weimer <fweimer@redhat.com>
Cc: glibc <libc-alpha@sourceware.org>
Bug: glibc <https://sourceware.org/bugzilla/show_bug.cgi?id=16747>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Both POSIX and glibc use 'restrict' in inet_pton().
Let's use it here too.
.../glibc$ grep_glibc_prototype inet_pton
inet/arpa/inet.h:58:
extern int inet_pton (int __af, const char *__restrict __cp,
void *__restrict __buf) __THROW;
.../glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Both POSIX and glibc use 'restrict' in glob().
Let's use it here too.
.../glibc$ grep_glibc_prototype glob
posix/glob.h:146:
extern int glob (const char *__restrict __pattern, int __flags,
int (*__errfunc) (const char *, int),
glob_t *__restrict __pglob) __THROW;
.../glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Both POSIX and glibc use 'restrict' in getnameinfo().
Let's use it here too.
I consciously did an exception with respect to the right margin
of the rendered page. Instead of having the right margin at 78
as usual (per Branden's recommendation), I let it use col 79
this time, to avoid breaking the prototype in an ugly way.
.../glibc$ grep_glibc_prototype getnameinfo
resolv/netdb.h:675:
extern int getnameinfo (const struct sockaddr *__restrict __sa,
socklen_t __salen, char *__restrict __host,
socklen_t __hostlen, char *__restrict __serv,
socklen_t __servlen, int __flags);
.../glibc$
Cc: G. Branden Robinson <g.branden.robinson@gmail.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
POSIX does NOT specify these functions to use 'restrict'.
However, glibc uses 'restrict' in getgrnam_r(), getgrgid_r().
Users might be surprised by this! Let's use it here too!
.../glibc$ grep_glibc_prototype getgrnam_r
grp/grp.h:148:
extern int getgrnam_r (const char *__restrict __name,
struct group *__restrict __resultbuf,
char *__restrict __buffer, size_t __buflen,
struct group **__restrict __result);
.../glibc$ grep_glibc_prototype getgrgid_r
grp/grp.h:140:
extern int getgrgid_r (__gid_t __gid, struct group *__restrict __resultbuf,
char *__restrict __buffer, size_t __buflen,
struct group **__restrict __result);
.../glibc$
Cc: glibc <libc-alpha@sourceware.org>
Cc: Ulrich Drepper <drepper@redhat.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Both POSIX and glibc use 'restrict' in fgetpos().
Let's use it here too.
glibc:
============================= fgetpos
libio/stdio.h:736:
int fgetpos (FILE *restrict stream, fpos_t *restrict pos);
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Both POSIX and glibc use 'restrict' in these functions.
Let's use it here too.
glibc:
============================= fread
libio/stdio.h:651:
size_t fread (void *restrict ptr, size_t size,
size_t n, FILE *restrict stream) wur;
============================= fwrite
libio/stdio.h:657:
size_t fwrite (const void *restrict ptr, size_t size,
size_t n, FILE *restrict s);
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Both POSIX and glibc use 'restrict' in fputws().
Let's use it here too.
glibc:
============================= fputws
wcsmbs/wchar.h:765:
int fputws (const wchar_t *restrict ws,
FILE *restrict stream);
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Both POSIX and glibc use 'restrict' for fgetws().
Let's use it here too.
glibc:
wcsmbs/wchar.h:758:
wchar_t *fgetws (wchar_t *restrict ws, int n,
FILE *restrict stream);
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Both POSIX and glibc use 'restrict' in fgets().
Let's use it here too.
glibc:
libio/stdio.h:568:
char *fgets (char *restrict s, int n, FILE *restrict stream)
wur attr_access ((write_only__, 1, 2));
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
POSIX.1-2001 and glibc use 'restrict' for these functions.
Let's use it here too.
glibc:
============================= ecvt
stdlib/stdlib.h:872:
char *ecvt (double value, int ndigit, int *restrict decpt,
int *restrict sign) THROW nonnull ((3, 4)) wur;
============================= fcvt
stdlib/stdlib.h:878:
char *fcvt (double value, int ndigit, int *restrict decpt,
int *restrict sign) THROW nonnull ((3, 4)) wur;
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Glibc uses 'restrict' for some of the functions in this page:
============================= drand48_r
stdlib/stdlib.h:501:
int drand48_r (struct drand48_data *restrict buffer,
double *restrict result) THROW nonnull ((1, 2));
============================= erand48_r
stdlib/stdlib.h:503:
int erand48_r (unsigned short int xsubi[3],
struct drand48_data *restrict buffer,
double *restrict result) THROW nonnull ((1, 2));
============================= lrand48_r
stdlib/stdlib.h:508:
int lrand48_r (struct drand48_data *restrict buffer,
long int *restrict result)
THROW nonnull ((1, 2));
============================= nrand48_r
stdlib/stdlib.h:511:
int nrand48_r (unsigned short int xsubi[3],
struct drand48_data *restrict buffer,
long int *restrict result)
THROW nonnull ((1, 2));
============================= mrand48_r
stdlib/stdlib.h:517:
int mrand48_r (struct drand48_data *restrict buffer,
long int *restrict result)
THROW nonnull ((1, 2));
============================= jrand48_r
stdlib/stdlib.h:520:
int jrand48_r (unsigned short int xsubi[3],
struct drand48_data *restrict buffer,
long int *restrict result)
THROW nonnull ((1, 2));
============================= srand48_r
stdlib/stdlib.h:526:
int srand48_r (long int seedval, struct drand48_data *buffer)
THROW nonnull ((2));
============================= seed48_r
stdlib/stdlib.h:529:
int seed48_r (unsigned short int seed16v[3],
struct drand48_data *buffer) THROW nonnull ((1, 2));
============================= lcong48_r
stdlib/stdlib.h:532:
int lcong48_r (unsigned short int param[7],
struct drand48_data *buffer)
THROW nonnull ((1, 2));
Let's use it here too.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
POSIX specifies that the parameters of memcpy()
shall be 'restrict'. Glibc uses 'restrict' too.
Let's use it here too.
It's especially important in memcpy(),
as it's been a historical source of bugs.
......
.../glibc$ grep_glibc_prototype memcpy
posix/regex_internal.h:746:
{
memcpy (dest, src, sizeof (bitset_t));
string/string.h:43:
extern void *memcpy (void *__restrict __dest, const void *__restrict __src,
size_t __n) __THROW __nonnull ((1, 2));
.../glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Epoch is 1970-01-01 00:00:00 +0000, UTC (see time(7)).
Reported-by: Walter Franzini <walter.franzini@gmail.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Both functions have the same header.
There's no reason to separate the prototypes repeating the header.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
RESOLVE_CACHED allows an application to attempt a cache-only open
of a file. If this isn't possible, the request will fail with
-1/EAGAIN and the caller should retry without RESOLVE_CACHED set.
This will generally happen from a different context, where a slower
open operation can be performed.
Signed-off-by: Jens Axboe <axboe@kernel.dk>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Make it clear that netlink error responses (i.e., messages with
type NLMSG_ERROR (0x2)), can be longer than sizeof(struct
nlmsgerr). In certain circumstances, the payload can be longer.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
That file should be sourced (.) from 'bashrc' (or 'bash_aliases').
It contains functions that are useful for the maintenance of this
project.
- grep_syscall()
- grep_syscall_def()
- man_section()
- man_lsfunc()
- pdfman()
- grep_glibc_prototype()
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
POSIX does NOT specify aio_suspend() to use 'restrict'.
However, glibc uses 'restrict'.
Users might be surprised by this! Let's use it here too!
......
.../glibc$ grep_glibc_prototype aio_suspend
rt/aio.h:167:
extern int aio_suspend (const struct aiocb *const __list[], int __nent,
const struct timespec *__restrict __timeout)
__nonnull ((1));
.../glibc$
Cc: libc-alpha@sourceware.org
Cc: Ulrich Drepper <drepper@redhat.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
POSIX specifies that [sig]longjmp() shall not return,
transferring control back to the caller of [sig]setjmp().
Glibc uses __attribute__((__noreturn__)) for [sig]longjmp().
Let's use standard C11 'noreturn' in the manual page.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
POSIX specifies that pthread_exit() shall not return.
Glibc uses __attribute__((__noreturn__)).
Let's use standard C11 'noreturn' in the manual page.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
POSIX specifies that exit() shall not return.
Glibc uses __attribute__((__noreturn__)).
Let's use standard C11 'noreturn' in the manual page.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Glibc uses __attribute__((__noreturn__)) for [v]err[x]().
These functions never return.
Let's use standard C11 'noreturn' in the manual page.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
POSIX specifies that _exit() and _Exit() shall not return.
Glibc uses __attribute__((__noreturn__)).
Let's use standard C11 'noreturn' in the manual page.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
POSIX specifies that abort() shall not return.
Glibc uses __attribute__((__noreturn__)).
Let's use standard C11 'noreturn' in the manual page.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Switching into the man? subdirectories when running man2html(1)
caused a bug where ".so dir/page.n" links were misinterpreted
(because the directory prefix was interpreted with respect to
the current directory)i, and consequently, the link files
were not correctly rendered. There's no need to switch into the
subdirectories.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This page uses some idiosyncratic mark-up involving the use of
a groff register. The mark-up actually makes no difference to
the formatted result, but does cause man2html(1) to emit error
messages, since it does not understand the mark-up. So, remove
that mark-up.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Use the glibc prototypes instead of the kernel ones.
Exception: use 'int' instead of 'enum'.
......
.../glibc$ grep_glibc_prototype pciconfig_read
sysdeps/unix/sysv/linux/alpha/sys/io.h:72:
extern int pciconfig_read (unsigned long int __bus,
unsigned long int __dfn,
unsigned long int __off,
unsigned long int __len,
unsigned char *__buf) __THROW;
sysdeps/unix/sysv/linux/ia64/sys/io.h:57:
extern int pciconfig_read (unsigned long int __bus, unsigned long int __dfn,
unsigned long int __off, unsigned long int __len,
unsigned char *__buf);
.../glibc$ grep_glibc_prototype pciconfig_write
sysdeps/unix/sysv/linux/alpha/sys/io.h:78:
extern int pciconfig_write (unsigned long int __bus,
unsigned long int __dfn,
unsigned long int __off,
unsigned long int __len,
unsigned char *__buf) __THROW;
sysdeps/unix/sysv/linux/ia64/sys/io.h:61:
extern int pciconfig_write (unsigned long int __bus, unsigned long int __dfn,
unsigned long int __off, unsigned long int __len,
unsigned char *__buf);
.../glibc$ grep_glibc_prototype pciconfig_iobase
sysdeps/unix/sysv/linux/alpha/sys/io.h:66:
extern long pciconfig_iobase(enum __pciconfig_iobase_which __which,
unsigned long int __bus,
unsigned long int __dfn)
__THROW __attribute__ ((const));
.../glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
All but the last parameters of t[g]kill() use 'pid_t',
both in the kernel and glibc. Fix them.
......
.../linux/linux$ grep_syscall tkill
kernel/signal.c:3870:
SYSCALL_DEFINE2(tkill, pid_t, pid, int, sig)
include/linux/syscalls.h:685:
asmlinkage long sys_tkill(pid_t pid, int sig);
.../linux/linux$
.../gnu/glibc$ grep_glibc_prototype tgkill
sysdeps/unix/sysv/linux/bits/signal_ext.h:29:
extern int tgkill (__pid_t __tgid, __pid_t __tid, int __signal);
.../gnu/glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The kernel syscall uses 'loff_t', but the glibc wrapper uses 'off64_t'.
Let's document the wrapper prototype, as in other pages.
......
.../glibc$ grep_glibc_prototype splice
sysdeps/unix/sysv/linux/bits/fcntl-linux.h:398:
extern __ssize_t splice (int __fdin, __off64_t *__offin, int __fdout,
__off64_t *__offout, size_t __len,
unsigned int __flags);
.../glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The type of fsgid is git_t, and not uid_t. Fix it.
......
.../glibc$ grep_glibc_prototype setfsgid
sysdeps/unix/sysv/linux/sys/fsuid.h:31:
extern int setfsgid (__gid_t __gid) __THROW;
.../glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
"Mibibytes" is a misspelling of "mebibytes",
but let's use more familiar "MiB" instead.
Signed-off-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
I just happened upon this inconsistent text while reading `man 2
execve`. The code in question landed in 2.6.23 as b6a2fea39318
("mm: variable length argument support").
Signed-off-by: Palmer Dabbelt <palmerdabbelt@google.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
POSIX specifies that the parameters of timer_settime()
shall be 'restrict'. Glibc uses 'restrict' too.
Let's use it here too.
......
.../glibc$ grep_glibc_prototype timer_settime
time/time.h:242:
extern int timer_settime (timer_t __timerid, int __flags,
const struct itimerspec *__restrict __value,
struct itimerspec *__restrict __ovalue) __THROW;
.../glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Glibc uses 'restrict' for the types of the parameters of statx().
Let's use it here too.
......
.../glibc$ grep_glibc_prototype statx
io/bits/statx-generic.h:60:
int statx (int __dirfd, const char *__restrict __path, int __flags,
unsigned int __mask, struct statx *__restrict __buf)
__THROW __nonnull ((2, 5));
.../glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
POSIX specifies that the parameters of sigaltstack()
shall be 'restrict'. Glibc uses 'restrict' too.
Let's use it here too.
......
.../glibc$ grep_glibc_prototype sigaltstack
signal/signal.h:320:
extern int sigaltstack (const stack_t *__restrict __ss,
stack_t *__restrict __oss) __THROW;
.../glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
POSIX specifies that the parameters of getsockopt()
shall be 'restrict'. Glibc uses 'restrict' too.
Let's use it here too.
......
.../glibc$ grep_glibc_prototype getsockopt
socket/sys/socket.h:208:
extern int getsockopt (int __fd, int __level, int __optname,
void *__restrict __optval,
socklen_t *__restrict __optlen) __THROW;
.../glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
POSIX specifies that the parameters of getpeername()
shall be 'restrict'. Glibc uses 'restrict' too.
Let's use it here too.
......
.../glibc$ grep_glibc_prototype getpeername
socket/sys/socket.h:130:
extern int getpeername (int __fd, __SOCKADDR_ARG __addr,
socklen_t *__restrict __len) __THROW;
.../glibc$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The page used 'hint' and 'advice' synonymously. This leaves the
reader wondering if the terms mean the same thing, or different
things. They mean the same thing, so use just one term.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Rather than repeating the description of MADV_COLD and MADV_PAGEOUT
in two pages, centralize the discussion in madvise(2), and refer
from process_madvise(2) ro madvise(2).
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Skimming open(2), I was surprised not to see tmpfs mentioned as a
filesystem supported by O_TMPFILE.
If I'm understanding correctly (I'm very possibly not!), tmpfs is
a filesystem built on shmem, so I think it's more correct (and
probably much more widely understandable) to refer to tmpfs here.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
There are many slightly different prototypes for this syscall,
but none of them is like the documented one.
Of all the different prototypes,
let's document the asm-generic one.
This manual page was actually using a prototype similar to
mmap(2), but there's no glibc wrapper function called mmap2(2),
as the wrapper for this syscall is mmap(2). Therefore, the
documented prototype should be the kernel one.
......
.../linux$ grep_syscall mmap2
arch/csky/kernel/syscall.c:17:
SYSCALL_DEFINE6(mmap2,
unsigned long, addr,
unsigned long, len,
unsigned long, prot,
unsigned long, flags,
unsigned long, fd,
off_t, offset)
arch/microblaze/kernel/sys_microblaze.c:46:
SYSCALL_DEFINE6(mmap2, unsigned long, addr, unsigned long, len,
unsigned long, prot, unsigned long, flags, unsigned long, fd,
unsigned long, pgoff)
arch/nds32/kernel/sys_nds32.c:12:
SYSCALL_DEFINE6(mmap2, unsigned long, addr, unsigned long, len,
unsigned long, prot, unsigned long, flags,
unsigned long, fd, unsigned long, pgoff)
arch/powerpc/kernel/syscalls.c:60:
SYSCALL_DEFINE6(mmap2, unsigned long, addr, size_t, len,
unsigned long, prot, unsigned long, flags,
unsigned long, fd, unsigned long, pgoff)
arch/riscv/kernel/sys_riscv.c:37:
SYSCALL_DEFINE6(mmap2, unsigned long, addr, unsigned long, len,
unsigned long, prot, unsigned long, flags,
unsigned long, fd, off_t, offset)
arch/s390/kernel/sys_s390.c:49:
SYSCALL_DEFINE1(mmap2, struct s390_mmap_arg_struct __user *, arg)
arch/sparc/kernel/sys_sparc_32.c:101:
SYSCALL_DEFINE6(mmap2, unsigned long, addr, unsigned long, len,
unsigned long, prot, unsigned long, flags, unsigned long, fd,
unsigned long, pgoff)
arch/ia64/include/asm/unistd.h:30:
asmlinkage unsigned long sys_mmap2(
unsigned long addr, unsigned long len,
int prot, int flags,
int fd, long pgoff);
arch/ia64/kernel/sys_ia64.c:139:
asmlinkage unsigned long
sys_mmap2 (unsigned long addr, unsigned long len, int prot, int flags, int fd, long pgoff)
arch/m68k/kernel/sys_m68k.c:40:
asmlinkage long sys_mmap2(unsigned long addr, unsigned long len,
unsigned long prot, unsigned long flags,
unsigned long fd, unsigned long pgoff)
arch/parisc/kernel/sys_parisc.c:275:
asmlinkage unsigned long sys_mmap2(unsigned long addr, unsigned long len,
unsigned long prot, unsigned long flags, unsigned long fd,
unsigned long pgoff)
arch/powerpc/include/asm/syscalls.h:15:
asmlinkage long sys_mmap2(unsigned long addr, size_t len,
unsigned long prot, unsigned long flags,
unsigned long fd, unsigned long pgoff);
arch/sh/include/asm/syscalls.h:8:
asmlinkage long sys_mmap2(unsigned long addr, unsigned long len,
unsigned long prot, unsigned long flags,
unsigned long fd, unsigned long pgoff);
arch/sh/kernel/sys_sh.c:41:
asmlinkage long sys_mmap2(unsigned long addr, unsigned long len,
unsigned long prot, unsigned long flags,
unsigned long fd, unsigned long pgoff)
arch/sparc/kernel/systbls.h:23:
asmlinkage long sys_mmap2(unsigned long addr, unsigned long len,
unsigned long prot, unsigned long flags,
unsigned long fd, unsigned long pgoff);
include/asm-generic/syscalls.h:14:
asmlinkage long sys_mmap2(unsigned long addr, unsigned long len,
unsigned long prot, unsigned long flags,
unsigned long fd, unsigned long pgoff);
.../linux$
function grep_syscall()
{
if ! [ -v 1 ]; then
>&2 echo "Usage: ${FUNCNAME[0]} <syscall>";
return ${EX_USAGE};
fi
find * -type f \
|grep '\.c$' \
|sort -V \
|xargs pcregrep -Mn "(?s)^\w*SYSCALL_DEFINE.\(${1},.*?\)" \
|sed -E 's/^[^:]+:[0-9]+:/&\n/';
find * -type f \
|grep '\.[ch]$' \
|sort -V \
|xargs pcregrep -Mn "(?s)^asmlinkage\s+[\w\s]+\**sys_${1}\s*\(.*?\)" \
|sed -E 's/^[^:]+:[0-9]+:/&\n/';
}
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The documented prototype for mlock2() was a mix of the
glibc wrapper prototype and the kernel syscall prototype.
Let's document the glibc wrapper prototype, which is shown below.
......
.../glibc$ grep_glibc_prototype mlock2
sysdeps/unix/sysv/linux/bits/mman-shared.h:55:
int mlock2 (const void *__addr, size_t __length, unsigned int __flags) __THROW;
.../glibc$
function grep_glibc_prototype()
{
if ! [ -v 1 ]; then
>&2 echo "Usage: ${FUNCNAME[0]} <func>";
return ${EX_USAGE};
fi
find * -type f \
|grep '\.h$' \
|sort -V \
|xargs pcregrep -Mn \
"(?s)^[^\s#][\w\s]+\s+\**${1}\s*\([\w\s()[\]*,]*?(...)?\)[\w\s()]*;" \
|sed -E 's/^[^:]+:[0-9]+:/&\n/';
}
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
There seems to be no reason <unistd.h> is shown here, so remove it.
Signed-off-by: Jonathan Wakely <jwakely@redhat.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
These pages have the odd wording 'the external variable errno',
which does not occur in other pages. Make these pages conform with
the norm.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
fileno(3) differs from the other functions in various ways.
For example, it is governed by different standards,
and can set 'errno'. Conversely, the other functions
are about examining the status of a stream, while
fileno(3) simply obtains the underlying file descriptor.
Furthermore, splitting this function out allows
for some cleaner upcoming changes in ferror(3).
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Calling ipc() directly would be a rather unusual thing to do,
so add some text to emphasize that point.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
I filed a bug against glibc
requesting the wrapper for the new syscall.
Glibc bug: <https://sourceware.org/bugzilla/show_bug.cgi?id=27359>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The 'advice' subsection fell in the middle of other text in the
DESCRIPTION, which is a little confusing. Instead, move that
subsection to the end of the DESCRIPTION, and make some other
minor text reorganization so that related details are placed in
the same paragraphs.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
'malloc_trim' was and is never called from the 'free' function.
see related bug in glibc tracker:
https://sourceware.org/bugzilla/show_bug.cgi?id=2531. or
'__int_free' function. Only the top part of the heap is trimmed
after some calls to 'free', which is different from 'malloc_trim'
which also releases memory in between chunks from all the
arenas/heaps.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Move the the text describing how to set environment variable before
the list(s) of variables in order to improve readability.
[mtk: rewrote commit message]
Signed-off-by: Bastien Roucariès <rouca@debian.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Clearly document that HOME, LOGNAME, SHELL and USER are set at
login time by a program like such as login(1).
Document also that using su could result in a mixed environment,
and point to the su(1) manual page.
[mtk: edited commit message]
Signed-off-by: Bastien Roucariès <rouca@debian.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Add more details of how PATH is used, and mention the legacy
use of an empty prefix.
Changed after a suggested patch by Bastien Roucariès.
Reported-by: Bastien Roucariès <rouca@debian.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Unlike SIOCGIFADDR and SIOCSIFADDR which are supported by many
protocol families, SIOCDIFADDR is supported by AF_INET6 and
AF_APPLETALK only.
Unlike other protocols, AF_INET6 uses struct in6_ifreq.
Cc: Dmitry V. Levin <ldv@altlinux.org>
Cc: <netdev@vger.kernel.org>
Signed-off-by: Pali Rohár <pali@kernel.org>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Document the name=value system and that nul byte is forbidden.
Signed-off-by: Bastien Roucariès <rouca@debian.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Say "execve(2)" instead of "exec(3)", and note that this step
starts a new program (not a new process!).
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Using _GNU_SOURCE to obtain the declaration of 'environ' is
nonstandard. Therefore, move the mention of this detail to NOTES.
At the same time, add a few words proposed by Bastien.
Cowritten-by: Bastien Roucariès <rouca@debian.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
In man-pages-5.11, a large number of pages were edited to achieve
greater consistency in the SYNOPIS, RETURN VALUE and ATTRIBUTES
sections. To avoid future inconsistencies, try to capture some of
the preferred conventions in text in man-pages(7).
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The msg_name field for recvmsg() call points to a caller-allocated buffer
nladdr that is used to return the source address of the (netlink) socket.
As recvmsg() does not read this buffer and fills it for a caller, do not
initialize it and instead check its value in the example.
Signed-off-by: Pali Rohár <pali@kernel.org>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Drop the reference to the Hacker Writing Guide (and the broken URL)
and simply note that the logical quoting style is the norm in
European languages also.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
A real minus can be cut and pasted...
THere are a few exceptions that gave been excluded in the this
change. For example, where there' is a string such as "<p1-name>",
where p1-name is soome sort of pseudo-identifier.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
It works both way, but this one feels more right. We are reading
four elements sizeof(*buffer) bytes each.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Verified from reading the kernel source and looking at the source
of mount(8). Surprisingly, this has not documented after so many
years.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
mtk: Enke later noted that this patch provides better documentation
of longstanding behavior (rather documenting a change in behavior).
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The environ(7) man page says:
SHELL The pathname of the user's login shell.
PAGER The user's preferred utility to display text files.
EDITOR/VISUAL
The user's preferred utility to edit text files.
but doesn't say whether the pathnames must be absolute or they can
be resolved using $PATH, or whether they can have options.
Note that at least for SHELL, this is not specified by POSIX.
This issue was raised in the Austin Group mailing-list, and the
answer is that "what constitutes a valid value for a platform
should be documented" [1].
Since OpenSSH assumes that $SHELL is an absolute pathname (when
set), it is supposed that the documentation should be:
SHELL The absolute pathname of the user's login shell.
For PAGER, POSIX says: "Any string acceptable as a command_string
operand to the sh -c command shall be valid."
For EDITOR, it does not need to be an absolute pathname since
POSIX gives the example:
EDITOR=vi fc
and since it is specified as "the name of a utility", It assumes
that arguments (options) must not be provided. Page 3013 about
"more", it is said: "If the last pathname component in EDITOR is
either vi or ex, [...]", thus again, it is assumed to be a
pathname.
For VISUAL, POSIX says: "Determine a pathname of a utility to
invoke when the visual command [...]", thus it is also a pathname.
It is not clear whether the pathname must be absolute, but for
consistency with EDITOR, it will be resolved using $PATH.
[1] https://www.mail-archive.com/austin-group-l@opengroup.org/msg01399.html
Reported-by: Vincent Lefevre <vincent@vinc17.net>
Signed-off-by: Bastien Roucaries <rouca@debian.org>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
When I inherited man-pages in 2004, it was a hodge-podge mix of
American vs British spelling. My native spelling is the latter,
but I value consistency and felt that things needed to be
standardized on one or other, and in computing, American is the
norm so that is what I settled on.
Among the changes was the substitution of various instances
of "acknowledgement" for "acknowledgment". The latter spelling is
not one I care for, but I believed it to be the American norm.
Alex Colomar proposed a patch to change the spelling back
to "acknowledgement", and some discussion and investigation
ensued, whereby I learned the following:
* The situation is not clear cut.
* Historically, "acknowledgment" was the norm in British English,
but was eclipsed by "acknowledgement" some decades ago.
* Even in American English, "acknowledgment" is not universal,
and "acknowledgement" has become more common in recent decades
(although it still remains minority usage) [2].
* The BSD license uses "acknowledgement" even though it was
(presumably) written in California.
* The POSIX standard uses "acknowledgement".
* The Debian BTS uses "acknowledgement".
* Looking at a corpus of manual pages from various systems
that I have assembled over the years, "acknowledgement" seems
a little more common than "acknowledgment".
Summary: the situation is not clear cut, but let's follow BSD,
POSIX, and the personal preference of the man-pages maintainers.
[1] https://books.google.com/ngrams/graph?content=acknowledgment%2Cacknowledgement&year_start=1800&year_end=2019&corpus=29&smoothing=3#
[2] https://books.google.com/ngrams/graph?content=acknowledgment%2Cacknowledgement&year_start=1800&year_end=2000&corpus=5&smoothing=3&
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
For the alternate signal stack to be cleared, CLONE_VM should and
CLONE_VFORK should not be specified.
[mtk: fixes my commit 52e5819c41]
Signed-off-by: Johannes Wellhöfer <johannes.wellhofer@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
man-pages bug: 211029
https://bugzilla.kernel.org/show_bug.cgi?id=211029
Complete workaround example
(it was too long for the page, but it may be useful here):
......
$ sudo ln -s -T /usr/bin/echo /usr/bin/-echo;
$ cc -o system_hyphen -x c - ;
#include <stdlib.h>
int
main(void)
{
system(" -echo Hello world!");
exit(EXIT_SUCCESS);
}
$ ./system_hyphen;
Hello world!
Reported-by: Ciprian Dorin Craciun <ciprian.craciun@gmail.com>
Cc: Florian Weimer <fweimer@redhat.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
NETLINK_CAP_ACK option was introduced in commit 0a6a3a23ea6e which first
appeared in Linux version 4.3 and not 4.2.
Signed-off-by: Pali Rohár <pali@kernel.org>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
rtnetlink is not only used for IPv4
Signed-off-by: Pali Rohár <pali@kernel.org>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The parentheses here make it look like a function rather than a
command.
This was a typo introduced by a script-assisted global edit.
Signed-off-by: Alyssa Ross <hi@alyssa.is>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
It's been a long time sine kernel 3.19.
There's still no glibc wrapper.
......
$ grep -rn 'execveat *(' glibc/
$
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Glibc uses 'void *' instead of 'char *'.
And the prototype is declared in <sys/cachectl.h>.
......
$ syscall='cacheflush';
$ ret='int';
$ find glibc/ -type f -name '*.h' \
|xargs pcregrep -Mn "(?s)^[\w\s]*${ret}\s*${syscall}\s*\(.*?;";
glibc/sysdeps/unix/sysv/linux/nios2/sys/cachectl.h:27:
extern int cacheflush (void *__addr, const int __nbytes, const int __op) __THROW;
glibc/sysdeps/unix/sysv/linux/mips/sys/cachectl.h:35:
extern int cacheflush (void *__addr, const int __nbytes, const int __op) __THROW;
glibc/sysdeps/unix/sysv/linux/arc/sys/cachectl.h:30:
extern int cacheflush (void *__addr, int __nbytes, int __op) __THROW;
glibc/sysdeps/unix/sysv/linux/csky/sys/cachectl.h:30:
extern int cacheflush (void *__addr, const int __nbytes,
const int __op) __THROW;
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Expand the epoll_wait() page with epoll_pwait2(), an epoll_wait()
variant that takes a struct timespec to enable nanosecond
resolution timeout.
Signed-off-by: Willem de Bruijn <willemb@google.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
A file descriptor is an int so it should be stored through an int
pointer while parent_tid should have the same type as child_tid
which is pid_t pointer.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
A more detailed notice is on realloc(3p).
......
$ man 3p realloc \
|sed -n \
-e '/APPLICATION USAGE/,/^$/p' \
-e '/FUTURE DIRECTIONS/,/^$/p';
APPLICATION USAGE
The description of realloc() has been modified from pre‐
vious versions of this standard to align with the
ISO/IEC 9899:1999 standard. Previous versions explicitly
permitted a call to realloc(p, 0) to free the space
pointed to by p and return a null pointer. While this be‐
havior could be interpreted as permitted by this version
of the standard, the C language committee have indicated
that this interpretation is incorrect. Applications
should assume that if realloc() returns a null pointer,
the space pointed to by p has not been freed. Since this
could lead to double-frees, implementations should also
set errno if a null pointer actually indicates a failure,
and applications should only free the space if errno was
changed.
FUTURE DIRECTIONS
This standard defers to the ISO C standard. While that
standard currently has language that might permit real‐
loc(p, 0), where p is not a null pointer, to free p while
still returning a null pointer, the committee responsible
for that standard is considering clarifying the language
to explicitly prohibit that alternative.
Bug: 211039 <https://bugzilla.kernel.org/show_bug.cgi?id=211039>
Reported-by: Johannes Pfister <johannes.pfister@josttech.ch>
Cc: libc-alpha@sourceware.org
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
.PP are redundant just after .SH or .SS.
Remove them.
$ find man? -type f \
|xargs sed -i '/^\.S[HS]/{n;/\.PP/d}';
Plus a couple manual edits.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This is implied in every other manual page. There is no need to
state it explicitly in these pages.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Fix a glitch in commit ff91beca5b.
Reported-by: Alejandro Colomar (man-pages) <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
.PP and .IP are redundant just before .SH or .SS.
Remove them.
$ find man? -type f \
|xargs sed -i '/^\.[IP]P$/{N;s/.*\n\(\.S[HS]\)/\1/}';
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Since kernel commit a280d6dc77eb
("ipc/sem: introduce semctl(SEM_STAT_ANY)"),
it only skips read access check when using SEM_STAT_ANY command.
And it should use the semid_ds struct instead of seminfo struct.
Fix this.
Signed-off-by: Yang Xu <xuyang2018.jy@cn.fujitsu.com>
Acked-by: Manfred Spraul <manfred@colorfullife.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
In the RETURN VALUE sections, a number of different wordings
are used in to describe the fact that 'errno' is set on error.
There's no reason for the difference in wordings, since the same
thing is being described in each case. Switch to a standard
wording that is the same as FreeBSD and similar to the wording
used in POSIX.1.
In this change, miscellaneous descriptions of the setting
of 'errno' are reworded to the norm of "is set to indicate
the error".
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
In the RETURN VALUE sections, a number of different wordings
are used in to describe the fact that 'errno' is set on error.
There's no reason for the difference in wordings, since the same
thing is being described in each case. Switch to a standard
wording that is the same as FreeBSD and similar to the wording
used in POSIX.1.
In this change, reword various cases saying that 'errno' is set
"appropriately" to "is set to indicate the error".
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
In the RETURN VALUE sections, a number of different wordings
are used in to describe the fact that 'errno' is set on error.
There's no reason for the difference in wordings, since the same
thing is being described in each case. Switch to a standard
wording that is the same as FreeBSD and similar to the wording
used in POSIX.1.
In this change, fix some instances stating that 'errno' is set
"appropriately" to instead say "to indicate the error".
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
In the RETURN VALUE sections, a number of different wordings
are used in to describe the fact that 'errno' is set on error.
There's no reason for the difference in wordings, since the same
thing is being described in each case. Switch to a standard
wording that is the same as FreeBSD and similar to the wording
used in POSIX.1.
In this change, "to indicate the cause of the error"
is changed to "to indicate the error".
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The current mark-up renders poorly. To resolve this, move
the type information into a separate line.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Since we are using .nf/.fi to bracket FTM info, escaping
space characters serves no space and clutters the source.
Reported-by: Alejandro Colomar (man-pages) <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
- Group macros by kinds.
- Align so that it's easiest to distinguish differences
between related macros.
(Align all continuations for consistency on PDF.)
- Fix minor typos.
- Remove redundant text:
'The macro xxx() ...':
The first paragraph already says that these are macros.
'circular|tail|... queue':
Don't need to repeat every time.
Generic text makes it easier to spot the differences.
- Fit lines into 78 columns.
- Reorder descriptions to match SYNOPSIS,
and add subsections to DESCRIPTION.
- srcfix: fix a few semantic newlines.
I noticed a bug which should be fixed next:
CIRCLEQ_LOOP_*() return a 'struct TYPE *'.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Change `RES_USE_EDNSO` to `RES_USE_EDNS0`, defined in
`resolv.h`. (This is written correctly in `man3/resolver.3` in this
same repo.) Helps with grepping and internet searches!
Signed-off-by: John Morris <john@zultron.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Various ATTRIBUTES table improvements following the previous
commit. In particular, make use of T{...T} to allow wrapping
in table cells that have a lot of text.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Make the formatting more consistent inside the tables in the
ATTRIBUTES sections. Make the source code more uniform; in
particular, eliminate the use of custom tweaks using
'lbwNN'/'lwNN' and .br macros. In addition, ensure that
hyphenation and text justification do not occur inside the tables.
This is a script-driven edit:
[[
PAGE_LIST=$(git grep -l 'SH ATTRIBUTES' man[23])
# Strip out any preexisting .sp/.br/.ad macros
sed -i '/SH ATTR/,/^\.SH/{/^\.sp/d; /^\.br/d; /\.ad/d}' $PAGE_LIST
# Eliminate any use of 'wNN' in tables; default first column
# to fill unused space
sed -i '/SH ATTR/,/^\.SH/s/lbw[0-9]*/lb/g' $PAGE_LIST
sed -i '/SH ATTR/,/^\.SH/s/lw[0-9]*/l/g' $PAGE_LIST
sed -i '/SH ATTR/,/^\.SH/s/^lb /lbx /' $PAGE_LIST
# Nest the tables inside ".ad l"+".nh" and ".hy"+".ad"+".sp 1"
# ".ad l" ==> no right justification of text in table cells
# ".nh" ==> No hyphenation in table cells
# ".sp 1" ==> ensure a blank line before the next section heading
sed -i '/SH ATTR/,/^\.SH/{/\.TS/i.ad l\n.nh
}' $PAGE_LIST
sed -i '/SH ATTR/,/^\.SH/{/\.TE/a.hy\n.ad\n.sp 1
}' $PAGE_LIST
# In a few of the tables, the third column has a lot of text, so
# make that column wide (rather than the first column)
sed -i '/^lbx/{s/lbx/lb/;s/lb$/lbx/}' \
man3/bindresvport.3 \
man3/fmtmsg.3 man3/gethostbyname.3 man3/getlogin.3 \
man3/getnetent.3 man3/getprotoent.3 man3/getpwent.3 \
man3/getservent.3 man3/getspnam.3 man3/getutent.3 man3/glob.3 \
man3/login.3 \
man3/setnetgrent.3 \
man3/wordexp.3
]]
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
In the SYNOPSIS, a long function prototype may need to be
continued over to the next line. The continuation line is
indented according to the following rules:
1. If there is a single such prototype that needs to be continued,
then align the continuation line so that when the page is
rendered on a fixed-width font device (e.g., on an xterm) the
continuation line starts just below the start of the argument
list in the line above. (Exception: the indentation may be
adjusted if necessary to prevent a very long continuation line
or a further continuation line where the function prototype is
very long.)
Thus:
int tcsetattr(int fd, int optional_actions,
const struct termios *termios_p);
2. But, where multiple functions in the SYNOPSIS require
continuation lines, and the function names have different
lengths, then align all continuation lines to start in the
same column. This provides a nicer rendering in PDF output
(because the SYNOPSIS uses a variable width font where
spaces render narrower than most characters).
Thus:
int getopt(int argc, char * const argv[],
const char *optstring);
int getopt_long(int argc, char * const argv[],
const char *optstring,
const struct option *longopts, int *longindex);
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Since _BSD_SOURCE is obsolete for quite some time now,
it should not be listed as the first FTM for lstat().
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
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>
Since glibc 2.29, there is a wrapper for getcpu(2).
The wrapper has only 2 arguments, omitting the unused
third system call argument. Rework the manual page
to reflect this.
Reported-by: Alejandro Colomar <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>
The Linux kernel uses 'unsigned int' instead of 'int' for the
'flags' parameter. As glibc provides no wrapper, use the same
type the kernel uses.
......
$ syscall='delete_module';
$ find linux/ -type f -name '*.c' \
|xargs pcregrep -Mn "(?s)^[\w_]*SYSCALL_DEFINE.\(${syscall},.*?\)";
linux/kernel/module.c:977:
SYSCALL_DEFINE2(delete_module, const char __user *, name_user,
unsigned int, flags)
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
See previous commit.
This commit normalizes texts under sections other than SYNOPSIS
(most of them in NOTES).
Signed-off-by: Ganimedes Colomar <gacoan.linux@gmail.com>
Cowritten-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
To easily distinguish documentation about glibc wrappers from
documentation about kernel syscalls, let's have a normalized
'Note' in the SYNOPSIS, and a further explanation in the page body
(NOTES in most of them), as already happened in many (but not all)
of the manual pages for syscalls without a wrapper. Furthermore,
let's normalize the messages, following membarrier.2 (because it's
already quite extended), so that it's easy to use grep to find
those pages.
To find these pages, we used:
$ grep -rn wrapper man? | sort -V
and
$ grep -rni support.*glibc | sort -V
delete_module.2, init_module.2: glibc 2.23 is no longer
maintained, so we changed the notes about wrappers, to say that
there are no glibc wrappers for these system calls; see NOTES.
We didn't fix some obsolete pages such as create_module.2.
Signed-off-by: Ganimedes Colomar <gacoan.linux@gmail.com>
Cowritten-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
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>
I noticed this while working on some silly "hello, world"
programs, see https://git.sr.ht/~phf/hello-again if you're
curious. Disassembling sh4 code showed trap #31 all over the
place but the syscall(2) man page talked about trap #0x17 and
friends. Checking the kernel sources I got lucky in
arch/sh/kernel/entry-common.S where in commit 3623d138213ae Rich
Felker clarifies the situation.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Michael Kerrisk