Eric Biederman notes that the change in commit f646ac88ef was
not strictly necessary for this example, since one of the already
documented requirements is that various mount points must not have
shared propagation, or else pivot_root() will fail. So, simplify
the example.
Reported-by: Eric W. Biederman <ebiederm@xmission.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Update with all the missing errors the syscall can return, the
behaviour the syscall should have w.r.t. to copies within single
files, etc.
[Amir] updates for final released version.
Signed-off-by: Dave Chinner <dchinner@redhat.com>
Signed-off-by: Amir Goldstein <amir73il@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
In RETURN VALUE, point reader at subsection noting that the return
value of the raw sched_setaffinity() system call differs from the
wrapper function in glibc.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Using signalfd(2) with epoll(7) and fork(2) can lead to some head
scratching.
It seems that when a signalfd file descriptor is added to epoll
you will only get notifications for signals sent to the process
that added the file descriptor to epoll.
So if you have a signalfd fd registered with epoll and then call
fork(2), perhaps by way of daemon(3) for example. Then you will
find that you no longer get notifications for signals sent to the
newly forked process.
User kentonv on ycombinator[0] explained it thus
"One place where the inconsistency gets weird is when you
use signalfd with epoll. The epoll will flag events on the
signalfd based on the process where the signalfd was
registered with epoll, not the process where the epoll is
being used. One case where this can be surprising is if you
set up a signalfd and an epoll and then fork() for the
purpose of daemonizing -- now you will find that your epoll
mysteriously doesn't deliver any events for the signalfd
despite the signalfd otherwise appearing to function as
expected."
And another post from the same person[1].
And then there is this snippet from this kernel commit message[2]
"If you share epoll fd which contains our sigfd with another
process you should blame yourself. signalfd is "really
special"."
So add a note to the man page that points this out where people
will hopefully find it sooner rather than later!
[0]: https://news.ycombinator.com/item?id=9564975
[1]: https://stackoverflow.com/questions/26701159/sending-signalfd-to-another-process/29751604#29751604
[2]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=d80e731ecab420ddcb79ee9d0ac427acbc187b4b
Signed-off-by: Andrew Clayton <andrew@digital-domain.net>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Eric Biederman noted that my list of directories that could not
have shared propagation was incorrect. I had written that
new_root could not be shared; rather it should be: the parent of
the current root mount point.
Reported-by: Eric W. Biederman <ebiederm@xmission.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Quoting Eric Biederman:
The concern from our conversation at the container
mini-summit was that there is a pathology if in your initial
mount namespace all of the mounts are marked MS_SHARED like
systemd does (and is almost necessary if you are going to
use mount propagation), that if new_root itself is MS_SHARED
then unmounting the old_root could propagate.
So I believe the desired sequence is:
>>> chdir(new_root);
+++ mount("", ".", MS_SLAVE | MS_REC, NULL);
>>> pivot_root(".", ".");
>>> umount2(".", MNT_DETACH);
The change to new new_root could be either MS_SLAVE or
MS_PRIVATE. So long as it is not MS_SHARED the mount won't
propagate back to the parent mount namespace.
Reported-by: Eric W. Biederman <ebiederm@xmission.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
LXC uses this [1]. I tested, to double-check, and it works.
The fchdir() dance done by LXC is not needed though:
fchdir(old_root); umount(".", MNT_DETACH); fchdir(new_root);
As far as I can see, just the umount() is sufficient, since,
after pivot_root(), oldi_root is at the top of the stack
of mounts at "/" and thus (so long as CWD is at "/")
the umount will remove the mount at the top of the stack.
Eric Biederman confirmed my understanding by mail, and
Philipp Wendler verified my results by experiment.
[1] See the following commit in LXC:
commit 2d489f9e87fa0cccd8a1762680a43eeff2fe1b6e
Author: Serge Hallyn <serge.hallyn@ubuntu.com>
Date: Sat Sep 20 03:15:44 2014 +0000
pivot_root: switch to a new mechanism (v2)
Helped-by: Eric W. Biederman <ebiederm@xmission.com>
Helped-by: Philipp Wendler <ml@philippwendler.de>
Helped-by: Aleksa Sarai <asarai@suse.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
After around 19 years, the behavior of pivot_root() has not been
changed, and will almost certainly not change in the future.
So, reword to remove the suggestion that the behavior may change.
Also, more clearly document the effect of pivot_root() on
the calling process's current working directory.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The reference of "Note that this also applies" was vague. So
combine this paragraph with an earlier one to make the linkage
clearer.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The idea that there might one day be a mechanism for kernel
threads to explicitly relinquish access to the filesystem never
came to pass (after 20 years), and the presence of text
describing this idea is, IMO, a distraction. So, remove it.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
One kernel printk() later, my suspicions seem confirmed: the text
describing the situation where the current root is not a mount
point (because of a chroot()) seems to be bogus. (Perhaps it was
true once upon a time.) In my testing, if the current root is not
a mount point, an EINVAL error results.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
In this text:
If the current root is not a mount point (e.g., after an
earlier chroot(2) or pivot_root())...
mention of pivot_root() makes no sense, since (as noted in an
earlier commit message for this page) 'new_root' in a previous
pivot_root() must (since Linux 2.4.5) have been a mount point.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
One of these "bugs" is a philosophical point already covered
elsewhere in the page, while the other is a somewhat obscure joke.
Both pieces are a bit of a distraction, really.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The note that EBUSY is given if a filesystem is already mounted
on 'Iput_old' was never really true. That restriction was in
Linux 2.3.14, but removed in Linux 2.3.99-pre6 so it never made
it to mainline.
The relevant diff in pivot_root() was:
error = -EBUSY;
- if (d_new_root->d_sb == root->d_sb || d_put_old->d_sb == root->d_sb)
+ if (new_nd.mnt == root_mnt || old_nd.mnt == root_mnt)
goto out2; /* loop */
- if (d_put_old != d_put_old->d_covers)
- goto out2; /* mount point is busy */
error = -EINVAL;
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Some of the text was written long ago, and hinted that things
might change in the future. However, 20 years have passed
and these details have not changed, so rework the text to
hint at that fact.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
As far as I can see from the source code, the statement that
"No other filesystem may be mounted on 'put_old'" is incorrect.
Even looking at the 2.4.0 source code, there I can't see such
a restriction. In addition, some testing on a 5.0 kernel
(mounting 'put_old' in the new mount namespace just before
pivot_root()) did not result in an error for this case when
calling pivot_root().
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
pivot_root() only affects the current working directory and root
directory of other processes in the same mount namespace as the
caller.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The restriction on what values may be specified in 'si_code'
apply only when sending a signal to a process other than the
caller itself.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Threads are allowed to switch mount namespaces if the filesystem
details aren't being shared. That's the purpose of the check in
the kernel quoted by the comment:
if (fs->users != 1)
return -EINVAL;
It's been this way since the code was originally merged in v3.8.
Signed-off-by: Mike Frysinger <vapier@gentoo.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Since introduction of MAP_SHARED_VALIDATE, in case flags contain
both MAP_PRIVATE and MAP_SHARED, mmap() doesn't fail with EINVAL,
it succeeds.
The reason for that is that MAP_SHARED_VALIDATE is in fact equal
to MAP_PRIVATE | MAP_SHARED.
This is intended behavior, see:
https://lwn.net/Articles/758594/https://lwn.net/Articles/758598/
Signed-off-by: Nikola Forró <nforro@redhat.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Even though the RFW_* flags were first introduced in Linux 4.6,
they could not be used with aio until 4.13 where the aio_rw_flags
field was added to struct iocb (9830f4be159b "fs: Use RWF_* flags
for AIO operations"). Correct the stated version for each flag.
Fixes: 2f72816f86 ("io_submit.2: Add kernel version numbers for various 'aio_rw_flags' flags")
Signed-off-by: Matti Möll <Matti.Moell@opensynergy.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
E2BIG was removed in 2.6.29, we should mark it as deprecated.
Signed-off-by: Yang Xu <xuyang2018.jy@cn.fujitsu.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Add powerpc64 to the calling convention tables.
Signed-off-by: Shawn Anastasio <shawn@anastas.io>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
PTRACE_GET_SYSCALL_INFO request was introduced by Linux kernel
commit 201766a20e30f982ccfe36bebfad9602c3ff574a aka
v5.3-rc1~65^2~23.
Signed-off-by: Dmitry V. Levin <ldv@altlinux.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
As reported by Florin:
In the first table, for the riscv Arch/ABI, the instruction
should be ecall instead of scall.
According the official manual, the instruction has been
renamed.
https://content.riscv.org/wp-content/uploads/2017/05/riscv-spec-v2.2.pdf
"The SCALL and SBREAK instructions have been renamed to
ECALL and EBREAK, respectively. Their encoding and
functionality are unchanged."
Reported-by: Florin Blanaru <florin.blanaru96@gmail.com>
Reviewed-by: Adam Borowski <kilobyte@angband.pl>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
As reported by Simone:
I was looking at version from 2017-09-15 but it's the same
on: http://man7.org/linux/man-pages/man2/statx.2.html
(2019-03-06)
There is reported (about the mask argument) after the list
of constants:
> Note that the kernel does not reject values in mask other
> than the above. Instead, it simply informs the caller which
> values are sup‐ ported by this kernel and filesystem via the
> statx.stx_mask field.
But as reported in the error values, there can be EINVAL if
mask has a reserved valued, and I found a check against
STATX__RESERVED in fs/stat.c for this. So if you use a that
bit (0x80000000U) the kernel will reject the value.
Probably is better to say that the kernel do not enforce the
use of only the listed values, but there are anyway reserved
values so and so you cannot put whatever you want on mask
(that apply to more values than UINT_MAX).
Reported-by: Simone Piccardi <piccardi@truelite.it>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Hi,
Both the Ext2 filesystem handler and the Ext4 filesystem handler will
return the ERANGE error code. Ext2 will return it if the name or value is
too long to be able to be stored, Ext4 will return it if the name is too
long. For reference, the relevant files/lines (with excerpts) are:
fs/ext2/xattr.c: lines 394 to 396 in ext2_xattr_set
> 394 name_len = strlen(name);
> 395 if (name_len > 255 || value_len > sb->s_blocksize)
> 396 return -ERANGE;
fs/ext4/xattr.c: lines 2317 to 2318 in ext4_xattr_set_handle
> 2317 if (strlen(name) > 255)
> 2318 return -ERANGE;
Other filesystems also return this code:
xfs/libxfs/xfs_attr.h: lines 53 to 55
> * The maximum size (into the kernel or returned from the kernel) of an
> * attribute value or the buffer used for an attr_list() call. Larger
> * sizes will result in an ERANGE return code.
It's possible that more filesystem handlers do this, a cursory grep shows
that most of the filesystem xattr handler files mention ERANGE in some
form. A suggested patch is below (I'm not 100% sure on the wording through).
Thanks
--
- Finn
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
In kernel/sys.c, arg2 is an unsigned long value and it will never
less than 0. Also, since kernel commit id da8b44d5a9f8 (Linux
4.6), timer_slack_ns and default timer_slack_ns have been
converted into u64, the return value of PR_GET_TIMERSLACK has been
limited under ULONG_MAX.
The timer slack value also can be inherited by a child created via
fork(2).
Reviewed-by: Cyrill Gorcunov <gorcunov@gmail.com>
Signed-off-by: Yang Xu <xuyang2018.jy@cn.fujitsu.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
As reported by Alan Stern:
Here are two extracts from the man page for ppoll(2):
Specifying a negative value in timeout means an infinite
timeout.
Other than the difference in the precision of the timeout
argument, the following ppoll() call:
ready = ppoll(&fds, nfds, tmo_p, &sigmask);
is equivalent to atomically executing the following calls:
sigset_t origmask;
int timeout;
timeout = (tmo_p == NULL) ? -1 :
(tmo_p->tv_sec * 1000 + tmo_p->tv_nsec / 1000000);
pthread_sigmask(SIG_SETMASK, &sigmask, &origmask);
ready = poll(&fds, nfds, timeout);
pthread_sigmask(SIG_SETMASK, &origmask, NULL);
But if tmo_p->tv_sec is negative, the ppoll() call is not
equivalent to the corresponding poll() call. The kernel rejects
negative values of tv_sec with an EINVAL error; it does not
interpret the value as meaning an infinite timeout.
(Yes, the kernel interprets tmo_p == NULL as an infinite timeout,
but the man page is still wrong for the case tmo_p->tv_sec < 0.)
Suggested fix: Following the end of the second extract above, add:
except that negative time values in tmo_p are not
interpreted as an infinite timeout.
Also, in the ERRORS section, change the text for EINVAL to:
EINVAL The nfds value exceeds the RLIMIT_NOFILE value or
*tmo_p contains an invalid (negative) time value.
Reported-by: Alan Stern <stern@rowland.harvard.edu>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
It appears that 'new_root' may not have needed to be a mount
point on ancient kernels, but already in Linux 2.4.5, there
was the diff shown below. Verified also by testing.
@@ -1631,8 +1605,9 @@
* - we don't move root/cwd if they are not at the root (reason: if something
* cared enough to change them, it's probably wrong to force them elsewhere)
* - it's okay to pick a root that isn't the root of a file system, e.g.
- * /nfs/my_root where /nfs is the mount point. Better avoid creating
- * unreachable mount points this way, though.
+ * /nfs/my_root where /nfs is the mount point. It must be a mountpoint,
+ * though, so you may need to say mount --bind /nfs/my_root /nfs/my_root
+ * first.
*/
asmlinkage long sys_pivot_root(const char *new_root, const char *put_old)
@@ -1640,7 +1615,7 @@
struct dentry *root;
struct vfsmount *root_mnt;
struct vfsmount *tmp;
- struct nameidata new_nd, old_nd;
+ struct nameidata new_nd, old_nd, parent_nd, root_parent;
char *name;
int error;
@@ -1688,6 +1663,10 @@
if (new_nd.mnt == root_mnt || old_nd.mnt == root_mnt)
goto out2; /* loop */
error = -EINVAL;
+ if (root_mnt->mnt_root != root)
+ goto out2;
+ if (new_nd.mnt->mnt_root != new_nd.dentry)
+ goto out2; /* not a mountpoint */
tmp = old_nd.mnt; /* make sure we can reach put_old from new_root */
spin_lock(&dcache_lock);
if (tmp != new_nd.mnt) {
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
To get the pkey_alloc, pkey_free and pkey_mprotect functions
_GNU_SOURCE needs to be defined before including sys/mman.h.
Reviewed-by: Florian Weimer <fweimer@redhat.com>
Signed-off-by: Mark Wielaard <mark@klomp.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The mprotect.2 NOTES say:
On systems that do not support protection keys in
hardware, pkey_mprotect() may still be used, but pkey must
be set to 0. When called this way, the operation of
pkey_mprotect() is equivalent to mprotect().
But this is not what the glibc manual says:
It is also possible to call pkey_mprotect with a key value
of -1, in which case it will behave in the same way as
mprotect.
Which is correct. Both the glibc implementation and the
kernel check whether pkey is -1. 0 is not a valid pkey when
memory protection keys are not supported in hardware.
Signed-off-by: Mark Wielaard <mark@klomp.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Details relating to the new initialization flag FAN_REPORT_FID has been
added. As part of the FAN_REPORT_FID feature, a new set of event masks are
available and have been documented accordingly.
A simple example program has been added to also support the understanding
and use of FAN_REPORT_FID and directory modification events.
Signed-off-by: Matthew Bobrowski <mbobrowski@mbobrowski.org>
Reviewed-by: Amir Goldstein <amir73il@gmail.com>
Reviewed-by: Jan Kara <jack@suse.cz>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The removed text long ago ceased to be accurate. Nowadays, the
dispatch table is autogenerated when building the kernel (via
the kernel makefile, arch/x86/entry/syscalls/Makefile).
Reported-by: Andreas Korb <andreas.d.korb@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Rewrite for improved clarity and defer to setfsuid(2) for the
rationale of the fsGID rather than repeating the same details
in this page.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The current text reads somewhat clumsily. Rewrite it to introduce
the eUID and fsUID in parallel, and more clearly hint at the the
historical rationale for the fsUID, which is detailed lower in
the page.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Michael Kerrisk