]> git.ipfire.org Git - thirdparty/man-pages.git/log
thirdparty/man-pages.git
5 years agofanotify_mark.2, fanotify.7: Document FAN_OPEN_EXEC and FAN_OPEN_EXEC_PERM
Matthew Bobrowski [Sat, 12 Jan 2019 01:56:15 +0000 (12:56 +1100)] 
fanotify_mark.2, fanotify.7: Document FAN_OPEN_EXEC and FAN_OPEN_EXEC_PERM

New event masks have been added to the fanotify API. Documentation to
support the use and behaviour of these new masks has been added
accordingly.

Signed-off-by: Matthew Bobrowski <mbobrowski@mbobrowski.org>
Reviewed-by: Amir Goldstein <amir73il@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoinotify.7: Minor tweaks
Michael Kerrisk [Tue, 26 Feb 2019 15:36:15 +0000 (16:36 +0100)] 
inotify.7: Minor tweaks

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoinotify_add_watch.2: Minor fixes to Henry Wilson's patch
Michael Kerrisk [Tue, 26 Feb 2019 14:43:25 +0000 (15:43 +0100)] 
inotify_add_watch.2: Minor fixes to Henry Wilson's patch

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoinotify_add_watch.2: Note errors that can occur for IN_MASK_CREATE
Henry Wilson [Thu, 31 May 2018 15:16:29 +0000 (15:16 +0000)] 
inotify_add_watch.2: Note errors that can occur for IN_MASK_CREATE

Note EEXIST error that occurs when requesting a watch on a path
which is already watched with IN_MASK_CREATE.

Note EINVAL error also occurs when requesting a watch specifying
both IN_MASK_CREATE and IN_MASK_ADD.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoinotify.7: Minor fixes to Henry Wilson's patch
Michael Kerrisk [Tue, 26 Feb 2019 14:45:07 +0000 (15:45 +0100)] 
inotify.7: Minor fixes to Henry Wilson's patch

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoinotify.7: Document IN_MASK_CREATE
Henry Wilson [Thu, 31 May 2018 15:16:28 +0000 (15:16 +0000)] 
inotify.7: Document IN_MASK_CREATE

Add documentation for new flag IN_MASK_CREATE for inotify_add_watch()
which is used to only allow new watches to be created.

Information obtained from a patch I submitted to the linux kernel
https://marc.info/?l=linux-fsdevel&m=152775980422847&w=2

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocgroups.7: Document the use of 'cgroup_no_v1=named' to disable v1 named hierarchies
Michael Kerrisk [Tue, 26 Feb 2019 12:51:50 +0000 (13:51 +0100)] 
cgroups.7: Document the use of 'cgroup_no_v1=named' to disable v1 named hierarchies

This feature was added in Linux 5.0.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agold.so.8: Bump timestamp to note Florian's review of --preload option
Michael Kerrisk [Tue, 26 Feb 2019 12:10:17 +0000 (13:10 +0100)] 
ld.so.8: Bump timestamp to note Florian's review of --preload option

Reported-by: Florian Weimer <fweimer@redhat.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoexec.3: execv(3) does not use execv(2) on sparc/sparc64
Michael Kerrisk [Tue, 26 Feb 2019 12:07:59 +0000 (13:07 +0100)] 
exec.3: execv(3) does not use execv(2) on sparc/sparc64

Reported-by: Eugene Syromyatnikov <evgsyr@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agold.so.8: Document the --preload command-line option added in glibc 2.30
Michael Kerrisk [Tue, 26 Feb 2019 11:46:47 +0000 (12:46 +0100)] 
ld.so.8: Document the --preload command-line option added in glibc 2.30

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agold.so.8: Place OPTIONS in alphabetical order
Michael Kerrisk [Tue, 26 Feb 2019 11:18:38 +0000 (12:18 +0100)] 
ld.so.8: Place OPTIONS in alphabetical order

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agold.so.8: LD_PRELOAD-ed objects are added to link map in left-to-right order
Michael Kerrisk [Tue, 26 Feb 2019 11:13:23 +0000 (12:13 +0100)] 
ld.so.8: LD_PRELOAD-ed objects are added to link map in left-to-right order

Remove any doubt, in case the reader might wrongly think that
objects are added in reverse order (which would mean that the
last listed object would be added at the front of the link map).

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agold.so.8: Minor rewording of LD_PRELOAD description, to ease readability
Michael Kerrisk [Tue, 26 Feb 2019 11:11:48 +0000 (12:11 +0100)] 
ld.so.8: Minor rewording of LD_PRELOAD description, to ease readability

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agold.so.8: Note delimiters for 'list' in --audit and --inhibit-rpath
Michael Kerrisk [Tue, 26 Feb 2019 10:06:24 +0000 (11:06 +0100)] 
ld.so.8: Note delimiters for 'list' in --audit and --inhibit-rpath

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agodes_crypt.3, encrypt.3: The functions described in these pages are removed in glibc...
Michael Kerrisk [Tue, 26 Feb 2019 09:28:24 +0000 (10:28 +0100)] 
des_crypt.3, encrypt.3: The functions described in these pages are removed in glibc 2.28

These functions were removed because they use DES, which is no
longer considered secure.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agonfsservctl.2: Add VERSIONS section noting that this system call no longer exists
Michael Kerrisk [Tue, 26 Feb 2019 09:14:33 +0000 (10:14 +0100)] 
nfsservctl.2: Add VERSIONS section noting that this system call no longer exists

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoustat.2: Starting with version 2.28, glibc no longer provides a wrapper function
Michael Kerrisk [Tue, 26 Feb 2019 09:12:18 +0000 (10:12 +0100)] 
ustat.2: Starting with version 2.28, glibc no longer provides a wrapper function

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoisatty.3: srcfix
Michael Kerrisk [Tue, 26 Feb 2019 08:24:42 +0000 (09:24 +0100)] 
isatty.3: srcfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agogetcpu.2: Note version where glibc wrapper was added
Michael Kerrisk [Mon, 25 Feb 2019 15:42:56 +0000 (16:42 +0100)] 
getcpu.2: Note version where glibc wrapper was added

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agogetcpu.2: getcpu() now has a glibc wrapper; remove mention of syscall(2)
Tobias Klauser [Wed, 6 Feb 2019 08:07:53 +0000 (09:07 +0100)] 
getcpu.2: getcpu() now has a glibc wrapper; remove mention of syscall(2)

The glibc wrapper was added in glibc 2.29, release on 1 Feb 2019.

Signed-off-by: Tobias Klauser <tklauser@distanz.ch>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agobpf.2: Fix bug in example
Oded Elisha [Sat, 9 Feb 2019 17:32:24 +0000 (19:32 +0200)] 
bpf.2: Fix bug in example

mtk: checked also against examples in samples/bpf
in kernel source to confirm.

Signed-off-by: Oded Elisha <oded123456@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agofsync.2: fix
Michael Kerrisk [Mon, 25 Feb 2019 15:05:40 +0000 (16:05 +0100)] 
fsync.2: fix

Reported-by: ruschein <ruschein@protonmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agosched_setaffinity.2: tfix in example shell session (s/grep/egrep)
Michael Kerrisk [Mon, 25 Feb 2019 15:01:28 +0000 (16:01 +0100)] 
sched_setaffinity.2: tfix in example shell session (s/grep/egrep)

Reported-by: Bernd Petrovitsch <bernd@petrovitsch.priv.at>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agommap.2: Fix description of treatment of the hint
Jann Horn [Thu, 14 Feb 2019 16:18:36 +0000 (17:18 +0100)] 
mmap.2: Fix description of treatment of the hint

The current manpage reads to me as if the kernel will always pick
a free space close to the requested address, but that's not the
case:

mmap(0x600000000000, 4096, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS,
-1, 0) = 0x600000000000
mmap(0x600000000000, 4096, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS,
-1, 0) = 0x7f5042859000

You can also see this in the various implementations of
->get_unmapped_area() - if the specified address isn't available,
the kernel basically ignores the hint (apart from the 5level
paging hack).

Clarify how this works a bit.

Acked-by: Michal Hocko <mhocko@suse.com>
Signed-off-by: Jann Horn <jannh@google.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agostat.2: SEE ALSO: add statx(2)
Benjamin Peterson [Mon, 18 Feb 2019 20:07:49 +0000 (12:07 -0800)] 
stat.2: SEE ALSO: add statx(2)

Signed-off-by: Benjamin Peterson <benjamin@python.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agomlock.2: tfix
Jakub Wilk [Tue, 19 Feb 2019 15:25:51 +0000 (16:25 +0100)] 
mlock.2: tfix

Signed-off-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoisatty.3: Most non-tty files nowadays result in the error ENOTTY
Michael Kerrisk [Mon, 25 Feb 2019 14:39:59 +0000 (15:39 +0100)] 
isatty.3: Most non-tty files nowadays result in the error ENOTTY

Historically, at least FIFOs and pipes yielded the error EINVAL.

Reported-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agogetrlimit.2: Correct information about large limits on 32-bit architectures
Eugene Syromyatnikov [Wed, 19 Sep 2018 17:12:22 +0000 (19:12 +0200)] 
getrlimit.2: Correct information about large limits on 32-bit architectures

Signed-off-by: Eugene Syromyatnikov <evgsyr@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agosyscalls.2: Comment out details of a few system calls that only ever briefly existed
Michael Kerrisk [Mon, 25 Feb 2019 13:22:12 +0000 (14:22 +0100)] 
syscalls.2: Comment out details of a few system calls that only ever briefly existed

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agosyscalls.2: Various edits of Eugene Syromyatnikov's patch
Michael Kerrisk [Mon, 25 Feb 2019 13:20:06 +0000 (14:20 +0100)] 
syscalls.2: Various edits of Eugene Syromyatnikov's patch

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agosyscalls.2: Update syscall table
Eugene Syromyatnikov [Mon, 25 Feb 2019 12:27:14 +0000 (13:27 +0100)] 
syscalls.2: Update syscall table

Added: arc_gettls, arc_settls, arc_usr_cmpxchg, arch_prctl,
atomic_barrier, atomic_cmpxchg_32, bfin_spinlock, breakpoint,
clone2, cmpxchg, cmpxchg_badaddr, dma_memcpy, execv, get_tls,
getdomainname, getdtablesize, gethostname, getxgid, getxpid,
getxuid, metag_get_tls, metag_set_fpu_flags,metag_set_tls,
metag_set_global_bit, newfstatat, old_adjtimex, oldumount,
or1k_atomic, pread, pwrite, riscv_flush_icache,
sched_get_affinity, sched_set_affinity, set_tls, setaltroot,
sethae, setpgrp, spill, sram_alloc, sram_free, swapcontext,
switch_endian, sys_debug_setcontext, syscall, sysmips, timerfd,
usr26, usr32, xtensa.

Uncommented: memory_ordering

Renamed: ppc_rtas to rtas (__NR_rtas), ppc_swapcontext to
swapcontext (__NR_swacontext).

Typo: s/remaed/renamed to/

Other: s/ia64/IA-64/, s/Sparc/SPARC/

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoexec.3: Note that SPARCC provides an execv() system call
Michael Kerrisk [Mon, 25 Feb 2019 11:52:33 +0000 (12:52 +0100)] 
exec.3: Note that SPARCC provides an execv() system call

Reported-by: Eugene Syromyatnikov <evgsyr@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agosocket.2: Remove notes concerning AF_ALG and AF_XDP
Nikola Forró [Fri, 22 Feb 2019 16:14:14 +0000 (17:14 +0100)] 
socket.2: Remove notes concerning AF_ALG and AF_XDP

All address families are now documented in address_families.7,
which is already present in SEE ALSO section. Also, the AF_ALG
note contains dead link to kernel HTML documentation.

Signed-off-by: Nikola Forró <nforro@redhat.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agofilesystems.5: Minor wording fixes
Michael Kerrisk [Mon, 25 Feb 2019 10:22:43 +0000 (11:22 +0100)] 
filesystems.5: Minor wording fixes

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agofilesystems.5: Minor tweaks to Eugene Syromyatnikov's patch
Michael Kerrisk [Mon, 25 Feb 2019 10:21:52 +0000 (11:21 +0100)] 
filesystems.5: Minor tweaks to Eugene Syromyatnikov's patch

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agofilesystems.5: Mention sysfs(2)
Eugene Syromyatnikov [Fri, 22 Feb 2019 16:26:23 +0000 (17:26 +0100)] 
filesystems.5: Mention sysfs(2)

* man5/filesystems.5 (.SH DESCRIPTION): Add a note that the
  information about available file systems can be obtained
  via sysfs() syscall.

Signed-off-by: Eugene Syromyatnikov <evgsyr@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoaddress_families.7: tfix
Eugene Syromyatnikov [Fri, 22 Feb 2019 16:26:21 +0000 (17:26 +0100)] 
address_families.7: tfix

Signed-off-by: Eugene Syromyatnikov <evgsyr@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agosocket.2: Reinstate AF_VSOCK mention
Eugene Syromyatnikov [Fri, 22 Feb 2019 16:26:16 +0000 (17:26 +0100)] 
socket.2: Reinstate AF_VSOCK mention

It has its own man page, so it probably makes sense to mention
it here.

* man2/socket.2 (.SH DESCRIPTION): Add mention of AF_VSOCK back.

Signed-off-by: Eugene Syromyatnikov <evgsyr@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agosocket.2: tfix
Eugene Syromyatnikov [Fri, 22 Feb 2019 16:26:13 +0000 (17:26 +0100)] 
socket.2: tfix

Signed-off-by: Eugene Syromyatnikov <evgsyr@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agosocket.2, address_families.7: Mention that address family names are Linux-specific
Eugene Syromyatnikov [Fri, 22 Feb 2019 16:26:11 +0000 (17:26 +0100)] 
socket.2, address_families.7: Mention that address family names are Linux-specific

* man2/socket.2 (.SH DESCRIPTION): Mention that the list of
  address families is Linux-specific.
* man7/address_families.7 (.SH DESCRIPTION): Likewise.

Signed-off-by: Eugene Syromyatnikov <evgsyr@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agosigaction.2: Minot tweaks to Eugene Syromyatnikov's patch
Michael Kerrisk [Mon, 25 Feb 2019 10:05:50 +0000 (11:05 +0100)] 
sigaction.2: Minot tweaks to Eugene Syromyatnikov's patch

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agosigaction.2: Describe obsolete usage of struct sigcontext as signal handler argument
Eugene Syromyatnikov [Fri, 22 Feb 2019 16:26:08 +0000 (17:26 +0100)] 
sigaction.2: Describe obsolete usage of struct sigcontext as signal handler argument

* man2/sigaction.2 (.SS Undocumented): Provide information about
  relation between the second argument of sa_handler and
  uc_mcontext field of the struct ucontext structure.

Signed-off-by: Eugene Syromyatnikov <evgsyr@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agofcntl.2: Briefly explain the meaning of the 'l_sysid' field in 'struct flock'
Michael Kerrisk [Mon, 25 Feb 2019 09:41:45 +0000 (10:41 +0100)] 
fcntl.2: Briefly explain the meaning of the 'l_sysid' field in 'struct flock'

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agofcntl.2: Mention that l_sysid is not used even if present
Eugene Syromyatnikov [Fri, 22 Feb 2019 16:26:05 +0000 (17:26 +0100)] 
fcntl.2: Mention that l_sysid is not used even if present

Some architectures do provide an 'l_sysid' declaration in
struct flock; however, it is not used anyway.

* man2/fcntl.2 (.SH NOTES): Note that l_sysid field is not used on
Linux even if present on some architectures.

Signed-off-by: Eugene Syromyatnikov <evgsyr@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoip.7: IP_RECVTTL error fixed
bert hubert [Sun, 24 Feb 2019 10:18:11 +0000 (11:18 +0100)] 
ip.7: IP_RECVTTL error fixed

I need to get the TTL of UDP datagrams from userspace, so I set
the IP_RECVTTL socket option.  And as promised by ip.7, I then get
IP_TTL messages from recvfrom.  However, unlike what the manpage
promises, the TTL field gets passed as a 32 bit integer.

The following userspace code works:

  uint32_t ttl32;
  for (cmsg = CMSG_FIRSTHDR(msgh); cmsg != NULL; cmsg = CMSG_NXTHDR(msgh,cmsg)) {
    if ((cmsg->cmsg_level == IPPROTO_IP) && (cmsg->cmsg_type == IP_TTL) &&
        CMSG_LEN(sizeof(ttl32)) == cmsg->cmsg_len) {

      memcpy(&ttl32, CMSG_DATA(cmsg), sizeof(ttl32));
      *ttl=ttl32;
      return true;
    }
    else
      cerr<<"Saw something else "<<(cmsg->cmsg_type == IP_TTL) <<
", "<<(int)cmsg->cmsg_level<<", "<<cmsg->cmsg_len<<", "<<
CMSG_LEN(1)<<endl;
  }

The 'else' field was used to figure out I go the length wrong.

Note from mtk:

Reading the source code also seems to confirm this, from
net/ipv4/ip_sockglue.c:

[[
static void ip_cmsg_recv_ttl(struct msghdr *msg, struct sk_buff *skb)
{
        int ttl = ip_hdr(skb)->ttl;
        put_cmsg(msg, SOL_IP, IP_TTL, sizeof(int), &ttl);
}
]]

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocapget.2: Remove first paragraph, which repeats details from capabilities(7)
Michael Kerrisk [Sat, 23 Feb 2019 20:20:39 +0000 (21:20 +0100)] 
capget.2: Remove first paragraph, which repeats details from capabilities(7)

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocapget.2: Relocate a misplaced sentence
Michael Kerrisk [Sat, 23 Feb 2019 20:19:08 +0000 (21:19 +0100)] 
capget.2: Relocate a misplaced sentence

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocapabilities.7: tfix
Michael Kerrisk [Sat, 23 Feb 2019 20:14:00 +0000 (21:14 +0100)] 
capabilities.7: tfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agogettid.2: Glibc provides a wrapper since version 2.30
Michael Kerrisk [Thu, 21 Feb 2019 13:00:32 +0000 (14:00 +0100)] 
gettid.2: Glibc provides a wrapper since version 2.30

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agosetns.2: When joining a user namespace, it must be a descendant user namespace
Michael Kerrisk [Thu, 21 Feb 2019 09:41:19 +0000 (10:41 +0100)] 
setns.2: When joining a user namespace, it must be a descendant user namespace

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocapabilities.7: CAP_SYS_CHROOT allows use of setns() to change the mount namespace
Michael Kerrisk [Fri, 15 Feb 2019 09:16:36 +0000 (10:16 +0100)] 
capabilities.7: CAP_SYS_CHROOT allows use of setns() to change the mount namespace

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocapabilities.7: srcfix
Michael Kerrisk [Fri, 15 Feb 2019 09:07:04 +0000 (10:07 +0100)] 
capabilities.7: srcfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocapabilities.7: Add a subsection on per-user-namespace "set-user-ID-root" programs
Michael Kerrisk [Thu, 14 Feb 2019 10:09:50 +0000 (11:09 +0100)] 
capabilities.7: Add a subsection on per-user-namespace "set-user-ID-root" programs

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocapabilities.7: Relocate the subsection "Interaction with user namespaces"
Michael Kerrisk [Thu, 14 Feb 2019 09:47:34 +0000 (10:47 +0100)] 
capabilities.7: Relocate the subsection "Interaction with user namespaces"

This best belongs at the end of the page, after the subsections
that already make some mention of user namespaces.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocapabilities.7: wfix
Michael Kerrisk [Thu, 14 Feb 2019 07:25:25 +0000 (08:25 +0100)] 
capabilities.7: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocapabilities.7: Substantially rework "Capabilities and execution of programs by root"
Michael Kerrisk [Tue, 12 Feb 2019 15:56:13 +0000 (16:56 +0100)] 
capabilities.7: Substantially rework "Capabilities and execution of programs by root"

Rework for improved clarity, and also to include missing details
on the case where (1) the binary that is being executed has
capabilities attached and (2) the real user ID of the process is
not 0 (root) and (3) the effective user ID of the process is 0
(root).

Kernel code analysis and some test code (GPLv3 licensed) below.

======

My analysis of security/commoncaps.c capabilities handling
(from Linux 4.20 source):

execve() eventually calls __do_execve_file():

__do_execve_file()
  |
  +-prepare_bprm_creds(&bprm)
  |  |
  |  +-prepare_exec_creds()
  |  |  |
  |  |  +-prepare_creds()
  |  |     |
  |  |     | // Returns copy of existing creds
  |  |     |
  |  |     +-security_prepare_creds()
  |  |        |
  |  |        +-cred_prepare() [via hook]
  |  |           // Seems to do nothing for commoncaps
  |  |
  |  // Returns creds provided by prepare_creds()
  |
  // Places creds returned by prepare_exec_creds() in bprm->creds
  |
  |
  +-prepare_binprm(&bprm) // bprm from prepare_bprm_creds()
     |
     +-bprm_fill_uid(&bprm)
     |
     |  // Places current credentials into bprm
     |
     |  // Performs set-UID & set-GID transitions if those file bits are set
     |
     +-security_bprm_set_creds(&bprm)
        |
        +-bprm_set_creds(&bprm) [via hook]
           |
           +-cap_bprm_set_creds(&bprm)
              |
              // effective = false
              |
              +-get_file_caps(&bprm, &effective, &has_fcap)
              |  |
              |  +-get_vfs_caps_from_disk(..., &vcaps)
              |  |
              |  |  // Fetches file capabilities from disk and places in vcaps
              |  |
              |  +-bprm_caps_from_vfs_caps(&vcaps, &bprm, &effective, &has_fcap)
              |
              |     // If file effective bit is set: effective = true
              |     //
              |     // If file has capabilities: has_fcap |= true
              |     //
              |     // Perform execve transformation:
              |     //     P'(perm) = F(inh) & P(Inh) | F(Perm) & P(bset)
              |
              +-handle_privileged_root(&bprm, has_fcap, &effective, root_uid)
              |
              |  // If has_fcap && (rUID != root && eUID == root) then
              |  //     return without doing anything
              |  //
              |  // If rUID == root || eUID == root then
              |  //    P'(perm) = P(inh) | P(bset)
              |  //
              |  // If eUID == root then
              |  //     effective = true
              |
              // Perform execve() transformation:
              //
              //     P'(Amb) = (privprog) ? 0 : P(Amb)
              //     P'(Perm) |= P'(Amb)
              //     P'(Eff) = effective ? P'(Perm) : P'(Amb)

Summary

1. Perform set-UID/set-GID transformations

2. P'(Amb) = (privprog) ? 0 : P(Amb)

3. If [process has nonzero UIDs] OR
   ([file has caps] && [rUID != root && eUID == root]), then

        P'(perm) = F(inh) & P(Inh) | F(Perm) & P(bset) | P'(Amb)

   else // ~ [process has rUID == root || eUID == root]

        P'(perm) = P(inh) | P(bset) | P'(Amb)

4. P'(Eff) = (F(eff) || eUID == root) ? P'(Perm) : P'(Amb)

======

$ cat show_creds_and_caps_long.c

int
main(int argc, char *argv[])
{
    uid_t ruid, euid, suid;
    gid_t rgid, egid, sgid;
    cap_t caps;
    char *s;

    if (getresuid(&ruid, &euid, &suid) == -1) {
        perror("getresuid");
        exit(EXIT_FAILURE);
    }

    if (getresgid(&rgid, &egid, &sgid) == -1) {
        perror("getresgid");
        exit(EXIT_FAILURE);
    }

    printf("UID: %5ld (real), %5ld (effective), %5ld (saved)\n",
            (long) ruid, (long) euid, (long) suid);
    printf("GID: %5ld (real), %5ld (effective), %5ld (saved)\n",
            (long) rgid, (long) egid, (long) sgid);

    caps = cap_get_proc();
    if (caps == NULL) {
        perror("cap_get_proc");
        exit(EXIT_FAILURE);
    }
    s = cap_to_text(caps, NULL);
    if (s == NULL) {
        perror("cap_to_text");
        exit(EXIT_FAILURE);
    }
    printf("Capabilities: %s\n", s);

    cap_free(caps);
    cap_free(s);

    exit(EXIT_SUCCESS);
}

$ cat cred_launcher.c

                        } while (0)

                        do { fprintf(stderr, "Usage: "); \
                             fprintf(stderr, msg, progName); \
                             exit(EXIT_FAILURE); } while (0)

int
main(int argc, char *argv[])
{
    uid_t r, e, s;

    if (argc != 5 || strcmp(argv[1], "--help") == 0)
        usageErr("%s rUID eUID sUID <prog>\n", argv[0]);

    r = atoi(argv[1]);
    e = atoi(argv[2]);
    s = atoi(argv[3]);

    if (setresuid(r, e, s) == -1)
        errExit("setresuid");

    if (getresuid(&r, &e, &s) == -1)
        errExit("getresuid");

    execv(argv[4], &argv[4]);
    errExit("execve");
}

$ cc -o cred_launcher cred_launcher.c
$ cc -o show_creds_and_caps_long show_creds_and_caps_long.c -lcap

$ sudo ./cred_launcher 1000 0 1000 ./show_creds_and_caps_long
UID:  1000 (real),     0 (effective),     0 (saved)
GID:     0 (real),     0 (effective),     0 (saved)
Capabilities: =ep

$ sudo setcap cap_kill=pe show_creds_and_caps_long
$ sudo ./cred_launcher 1000 0 1000 ./show_creds_and_caps_long
UID:  1000 (real),     0 (effective),     0 (saved)
GID:     0 (real),     0 (effective),     0 (saved)
Capabilities: = cap_kill+ep

The final program execution above shows the special casing
that occurs in handle_privileged_root() for the case where:

    rUID != root && eUID == root && [file has capabilities]

======

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocapabilities.7: tfix
Michael Kerrisk [Tue, 12 Feb 2019 13:36:32 +0000 (14:36 +0100)] 
capabilities.7: tfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocapabilities.7: Improve the discussion of when file capabilities are ignored
Michael Kerrisk [Tue, 12 Feb 2019 09:29:21 +0000 (10:29 +0100)] 
capabilities.7: Improve the discussion of when file capabilities are ignored

The text stated that the execve() capability transitions are not
performed for the same reasons that setuid and setgid mode bits
may be ignored (as described in execve(2)). But, that's not quite
correct: rather, the file capability sets are treated as empty
for the purpose of the capability transition calculations.

Also merge the new 'no_file_caps' kernel option text into the
same paragraph.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocapabilities.7: Document the 'no_file_caps' kernel command-line option
Michael Kerrisk [Tue, 12 Feb 2019 09:15:35 +0000 (10:15 +0100)] 
capabilities.7: Document the 'no_file_caps' kernel command-line option

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocapget.2: Remove crufty sentence suggesting use of deprecated functions
Michael Kerrisk [Sat, 23 Feb 2019 20:58:23 +0000 (21:58 +0100)] 
capget.2: Remove crufty sentence suggesting use of deprecated functions

Remove crufty sentence suggesting use of deprecated capsetp(3) and
capgetp(3); the manual page for those functions has long (at least
as far back as 2007) noted that they are deprecated.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agosetfsgid.2, setfsuid.2: wfix
Michael Kerrisk [Sat, 16 Feb 2019 06:52:30 +0000 (07:52 +0100)] 
setfsgid.2, setfsuid.2: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocapabilities.7: Rework discussion of exec and UID 0, correcting a couple of details
Michael Kerrisk [Sun, 10 Feb 2019 02:40:15 +0000 (03:40 +0100)] 
capabilities.7: Rework discussion of exec and UID 0, correcting a couple of details

Clarify the "Capabilities and execution of programs by root"
section, and correct a couple of details:

* If a process with rUID == 0 && eUID != 0 does an exec,
  the process will nevertheless gain effective capabilities
  if the file effective bit is set.
* Set-UID-root programs only confer a full set of capabilities
  if the binary does not also have attached capabilities.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocapabilities.7: srcfix
Michael Kerrisk [Thu, 7 Feb 2019 10:40:25 +0000 (11:40 +0100)] 
capabilities.7: srcfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agonamespaces.7: srcfix
Michael Kerrisk [Thu, 7 Feb 2019 01:07:28 +0000 (02:07 +0100)] 
namespaces.7: srcfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocgroups.7: wfix
Michael Kerrisk [Sat, 2 Feb 2019 18:48:15 +0000 (19:48 +0100)] 
cgroups.7: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoproc.5: SEE ALSO: add htop(1) and pstree(1)
Michael Kerrisk [Thu, 31 Jan 2019 04:36:00 +0000 (05:36 +0100)] 
proc.5: SEE ALSO: add htop(1) and pstree(1)

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoproc.5: Since Linux 4.5, "stack:" is no longer shown in /proc/PID/maps
Michael Kerrisk [Thu, 24 Jan 2019 20:08:57 +0000 (09:08 +1300)] 
proc.5: Since Linux 4.5, "stack:" is no longer shown in /proc/PID/maps

Reported-by: Nick Gregory <ghost@capsule8.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agofsync.2: tfix
Ignat Loskutov [Thu, 17 Jan 2019 17:46:33 +0000 (20:46 +0300)] 
fsync.2: tfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoio_submit.2: ffix
Michael Kerrisk [Thu, 24 Jan 2019 19:59:54 +0000 (08:59 +1300)] 
io_submit.2: ffix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoio_submit.2: Fix the description of aio_data
Jeff Moyer [Thu, 17 Jan 2019 20:32:44 +0000 (15:32 -0500)] 
io_submit.2: Fix the description of aio_data

aio_data is not a kernel-internal field.

Signed-off-by: Jeff Moyer <jmoyer@redhat.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoproc.5: Mention /proc/uptime includes time spent in suspend
Stephan Knauss [Tue, 22 Jan 2019 15:24:17 +0000 (16:24 +0100)] 
proc.5: Mention /proc/uptime includes time spent in suspend

fs/proc/uptime.c:uptime_proc_show() fetches time using
ktime_get_boottime which includes the time spent in suspend.

Signed-off-by: Stephan Knauss <linux@stephans-server.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocgroups.7: Reframe the text on delegation to include more details about cgroups v1
Michael Kerrisk [Wed, 23 Jan 2019 21:11:25 +0000 (22:11 +0100)] 
cgroups.7: Reframe the text on delegation to include more details about cgroups v1

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocgroups.7: wfix
Michael Kerrisk [Wed, 23 Jan 2019 21:04:31 +0000 (22:04 +0100)] 
cgroups.7: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocgroups.7: wfix
Michael Kerrisk [Wed, 23 Jan 2019 20:41:48 +0000 (21:41 +0100)] 
cgroups.7: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocgroups.7: Soften the discussion about delegation in cgroups v1
Michael Kerrisk [Wed, 23 Jan 2019 20:24:06 +0000 (21:24 +0100)] 
cgroups.7: Soften the discussion about delegation in cgroups v1

Balbir pointed out that v1 delegation was not an accidental
feature.

Reported-by: Balbir Singh <bsingharora@gmail.com>
Reported-by: Marcus Gelderie <redmnic@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocgroups.7: wfix
Michael Kerrisk [Wed, 23 Jan 2019 20:16:52 +0000 (21:16 +0100)] 
cgroups.7: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agotime.1: Update bug reporting address
Jakub Wilk [Tue, 15 Jan 2019 22:14:45 +0000 (23:14 +0100)] 
time.1: Update bug reporting address

Update the bug reporting email address to that shown by

     /bin/time --help

Signed-off-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoman.7: tfix
Jakub Wilk [Tue, 15 Jan 2019 22:07:30 +0000 (23:07 +0100)] 
man.7: tfix

Use \(aq for ASCII apostrophes and \(ga for backtick,
as recommended by groff_man(7).

Signed-off-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoclose.2: ffix
Lucas Werkmeister [Sun, 13 Jan 2019 17:49:00 +0000 (18:49 +0100)] 
close.2: ffix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agotime.1: Document the -q/--quiet option
Michael Kerrisk [Sat, 12 Jan 2019 20:50:00 +0000 (21:50 +0100)] 
time.1: Document the -q/--quiet option

Reported-by: Johannes Altmanninger <aclopte@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agolocaledef.1: Minor tweaks to Howard Johnson's patch
Michael Kerrisk [Thu, 10 Jan 2019 04:04:35 +0000 (17:04 +1300)] 
localedef.1: Minor tweaks to Howard Johnson's patch

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agolocaledef.1: Note that -f and -c, are reversed from what you might expect
Howard Johnson [Thu, 10 Jan 2019 04:01:46 +0000 (17:01 +1300)] 
localedef.1: Note that -f and -c, are reversed from what you might expect

I was reading the local-gen bash script, looking for why I'm
getting locale errors, when I noticed that localdef's -f and -c
options were named, in what I think, is a very confusing way.

   -c is the same as --force, and

   -f charmapfile is the same as --charmap=charmapfile.

Yes, it would have been better if they're names had been reversed,
like this:

   -f is the same as --force, and

   -c charmapfile is the same as --charmap=charmapfile.

But given what they are, I thought it would be helpful to give a
heads up to watch for their irregular naming.  I hope I've worded
it appropriately.

I'm not ccing this to anyone else, (i.e. developers, etc), as
these features work as described in the man page.  They're just
confusing.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agobstring.3: Correct argument list for memmem() prototype
Michael Kerrisk [Thu, 10 Jan 2019 00:32:05 +0000 (13:32 +1300)] 
bstring.3: Correct argument list for memmem() prototype

Reported-by: Emil Fihlman <emil.fihlman@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoChanges.old: tfix
Jakub Wilk [Mon, 31 Dec 2018 16:20:45 +0000 (17:20 +0100)] 
Changes.old: tfix

Signed-off-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agobsd_signal.3: Fix the wrong version of _POSIX_C_SOURCE
Xiao Yang [Fri, 21 Dec 2018 03:01:58 +0000 (11:01 +0800)] 
bsd_signal.3: Fix the wrong version of _POSIX_C_SOURCE

According to the latest glibc, the bsd_signal() function is just
declared when POSIX.1-2008 (or newer) instead of POSIX.1-2001 is
not set since glibc v2.26.

Please see the following code from signal/signal.h:
-----------------------------------------------------------------
/* The X/Open definition of `signal' conflicts with the BSD version.
   So they defined another function `bsd_signal'.  */
extern __sighandler_t bsd_signal (int __sig, __sighandler_t __handler)
     __THROW;
-----------------------------------------------------------------

Signed-off-by: Xiao Yang <yangx.jy@cn.fujitsu.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agofeature_test_macros.7: Add more detail on why FTMs must be defined before including...
Michael Kerrisk [Thu, 10 Jan 2019 00:01:03 +0000 (13:01 +1300)] 
feature_test_macros.7: Add more detail on why FTMs must be defined before including any header

Reported-by: Andreas Westfeld <andreas.westfeld@htw-dresden.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoMerge branch 'master' of ra.kernel.org:/pub/scm/docs/man-pages/man-pages
Michael Kerrisk [Wed, 9 Jan 2019 18:01:44 +0000 (07:01 +1300)] 
Merge branch 'master' of ra.kernel.org:/pub/scm/docs/man-pages/man-pages

5 years agoerrno.3: Mention that errno(1) is part of the 'moreutils' package
Michael Kerrisk [Sat, 5 Jan 2019 20:21:02 +0000 (21:21 +0100)] 
errno.3: Mention that errno(1) is part of the 'moreutils' package

Reported-by: Robert P. J. Day <rpjday@crashcourse.ca>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoopen.2: Minor fixes to Eugene's patch
Michael Kerrisk [Wed, 9 Jan 2019 17:38:52 +0000 (06:38 +1300)] 
open.2: Minor fixes to Eugene's patch

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoopen.2: Mention presence of unused O_RSYNC definition
Eugene Syromiatnikov [Fri, 4 Jan 2019 17:24:33 +0000 (18:24 +0100)] 
open.2: Mention presence of unused O_RSYNC definition

O_RSYNC is defined in <asm/fcntl.h> on HP PA-RISC, but is not
used anyway.

Signed-off-by: Eugene Syromiatnikov <esyr@redhat.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoopen.2: tfix
Michael Kerrisk [Wed, 9 Jan 2019 17:34:38 +0000 (06:34 +1300)] 
open.2: tfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoopen.2: Minor fixes to Eugene's patch
Michael Kerrisk [Wed, 9 Jan 2019 17:32:39 +0000 (06:32 +1300)] 
open.2: Minor fixes to Eugene's patch

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoopen.2: Document FASYNC usage in Linux UAPI headers
Eugene Syromiatnikov [Fri, 4 Jan 2019 17:24:29 +0000 (18:24 +0100)] 
open.2: Document FASYNC usage in Linux UAPI headers

Linux's <asm/fcntl.h> defines FASYNC instead of O_ASYNC; document
this peculiarity.

Signed-off-by: Eugene Syromiatnikov <esyr@redhat.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agorename.2: tfix
Michael Kerrisk [Wed, 9 Jan 2019 17:25:18 +0000 (06:25 +1300)] 
rename.2: tfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agorename.2: Some additional notes regarding RENAME_WHITEOUT
Eugene Syromiatnikov [Fri, 4 Jan 2019 15:35:45 +0000 (16:35 +0100)] 
rename.2: Some additional notes regarding RENAME_WHITEOUT

Add a note regarding other implementations of whiteout inodes
and update filesystem support information.

Signed-off-by: Eugene Syromiatnikov <esyr@redhat.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agogetgid.2, getpid.2, getuid.2, pipe.2: Remove mention of other syscalls that use secon...
Michael Kerrisk [Wed, 9 Jan 2019 17:21:17 +0000 (06:21 +1300)] 
getgid.2, getpid.2, getuid.2, pipe.2: Remove mention of other syscalls that use second retval register

This information is already summarized in syscall(2), so there's
no need to repeat it in each page.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agosyscall.2: tfix
Michael Kerrisk [Wed, 9 Jan 2019 17:16:24 +0000 (06:16 +1300)] 
syscall.2: tfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agosyscall.2: tfix
Michael Kerrisk [Wed, 9 Jan 2019 17:09:01 +0000 (06:09 +1300)] 
syscall.2: tfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agosyscall.2: ffix
Michael Kerrisk [Wed, 9 Jan 2019 17:08:08 +0000 (06:08 +1300)] 
syscall.2: ffix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agosyscall.2: Rework table to render within 80 columns
Michael Kerrisk [Wed, 9 Jan 2019 17:06:20 +0000 (06:06 +1300)] 
syscall.2: Rework table to render within 80 columns

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>