process_madvise.2: Defer to madvise(2) for description of 'advice' flags

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>

madvise.2: Add descriptions of MADV_COLD and MADV_PAGEOUT

Taken from process_madvise(2).

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

process_madvise.2: Minor clarification regarding partial advice scenario

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

process_madvise.2: SYNOPSIS: Fix prototype parameter type

The type of vlen is 'size_t', and not 'unsigned int'.  Fix it.

......

$ grep_syscall process_madvise
mm/madvise.c:1161:
SYSCALL_DEFINE5(process_madvise, int, pidfd, const struct iovec __user *, vec,
size_t, vlen, int, behavior, unsigned int, flags)
include/linux/syscalls.h:887:
asmlinkage long sys_process_madvise(int pidfd, const struct iovec __user *vec,
size_t vlen, int behavior, unsigned int flags);

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>

process_madvise.2: Add note about missing glibc wrapper

Glibc bug: <https://sourceware.org/bugzilla/show_bug.cgi?id=27380>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

move_pages.2: Add notes about missing glibc wrappers

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

shm_overview.7: SEE ALSO: add memfd_create(2)

People interested POSIX shared memory may also be interested
in memfd and file sealing.

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

open.2, rename.2: Refer to tmpfs rather than shmem

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>

rename.2: wfix

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

netdevice.7: wfix

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

netdevice.7: ffix

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

mmap2.2: Fix prototype parameter types

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>

mlock.2: mlock2(): Fix prototype parameter types

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>

execveat.2: srcfix: add a link to glibc bug requesting wrapper

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

execveat.2: Fix prototype

It's been 6 years since execveat(2) was added to the kernel,
and there's still no glibc wrapper.  Let's document the kernel
syscall prototype.

I reported a bug against glibc requesting a wrapper;
when glibc adds the wrapper, this commit should probably be
reverted.

......

.../linux$ grep_syscall execveat
fs/exec.c:2062:
SYSCALL_DEFINE5(execveat,
int, fd, const char __user *, filename,
const char __user *const __user *, argv,
const char __user *const __user *, envp,
int, flags)
fs/exec.c:2083:
COMPAT_SYSCALL_DEFINE5(execveat, int, fd,
       const char __user *, filename,
       const compat_uptr_t __user *, argv,
       const compat_uptr_t __user *, envp,
       int,  flags)
include/linux/compat.h:815:
asmlinkage long compat_sys_execveat(int dfd, const char __user *filename,
     const compat_uptr_t __user *argv,
     const compat_uptr_t __user *envp, int flags);
include/linux/syscalls.h:980:
asmlinkage long sys_execveat(int dfd, const char __user *filename,
const char __user *const __user *argv,
const char __user *const __user *envp, int flags);
.../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/';
}

Glibc bug: <https://sourceware.org/bugzilla/show_bug.cgi?id=27364>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

ipc.2: Fix prototype parameter types

The types for some of the parameters are incorrect
(different than the kernel).  Fix them.
Below are shown the types that the kernel uses.

......

.../linux$ grep_syscall ipc
ipc/syscall.c:110:
SYSCALL_DEFINE6(ipc, unsigned int, call, int, first, unsigned long, second,
unsigned long, third, void __user *, ptr, long, fifth)
ipc/syscall.c:205:
COMPAT_SYSCALL_DEFINE6(ipc, u32, call, int, first, int, second,
u32, third, compat_uptr_t, ptr, u32, fifth)
include/linux/compat.h:874:
asmlinkage long compat_sys_ipc(u32, int, int, u32, compat_uptr_t, u32);
include/linux/syscalls.h:1221:
asmlinkage long sys_ipc(unsigned int call, int first, unsigned long second,
unsigned long third, void __user *ptr, long fifth);
.../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>

rpc.3: ffix

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

stat.2: Remove <unistd.h> from synopsis

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>

getpriority.2, recv.2, fts.3: wfix

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>

ferror.3: POSIX.1-2008: these functions won't change 'errno' if 'stream' is valid

See https://www.austingroupbugs.net/view.php?id=401.

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

ferror.3: Add a RETURN VALUE section

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

ferror.3: Remove fileno(3) content that was migrated to new fileno(3) page

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

fileno.3: Split fileno(3) content out of ferror(3) into new page

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>

ipc.2: Minor tweak to Alex's patch regarding use of syscall()

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>

bdflush.2, capget.2, get_mempolicy.2, ipc.2, lookup_dcookie.2, mbind.2, migrate_pages.2: Add notes about missing glibc wrappers

.../glibc$ grep_syscall_wrapper bdflush
.../glibc$ grep_syscall_wrapper capget
.../glibc$ grep_syscall_wrapper capset
.../glibc$ grep_syscall_wrapper get_mempolicy
.../glibc$ grep_syscall_wrapper ipc
.../glibc$ grep_syscall_wrapper lookup_dcookie
.../glibc$ grep_syscall_wrapper mbind
.../glibc$ grep_syscall_wrapper migrate_pages
.../glibc$

function grep_syscall_wrapper()
{
if ! [ -v 1 ]; then
>&2 echo "Usage: ${FUNCNAME[0]} <syscall>";
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>

getsockname.2: Use restrict in prototypes

POSIX specifies that the 2nd and 3rd parameters to getsockname()
shall be 'restrict'.  Glibc uses 'restrict' too.
Let's use it here too.

......

.../glibc$ grep_syscall_wrapper getsockname
socket/sys/socket.h:116:
extern int getsockname (int __fd, __SOCKADDR_ARG __addr,
socklen_t *__restrict __len) __THROW;
.../glibc$ grep -rn '# *define __SOCKADDR_ARG'
socket/sys/socket.h:58:
 # define __SOCKADDR_ARG struct sockaddr *__restrict
.../glibc$

function grep_syscall_wrapper()
{
if ! [ -v 1 ]; then
>&2 echo "Usage: ${FUNCNAME[0]} <syscall>";
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>

gettimeofday.2: Use restrict in prototypes

POSIX specifies that the parameters of gettimeofday() shall be
'restrict'.  Glibc uses 'restrict' too.
Let's use it here too.

......

.../glibc$ grep_syscall_wrapper gettimeofday
time/sys/time.h:66:
extern int gettimeofday (struct timeval *__restrict __tv,
 void *__restrict __tz) __THROW __nonnull ((1));
.../glibc$

function grep_syscall_wrapper()
{
if ! [ -v 1 ]; then
>&2 echo "Usage: ${FUNCNAME[0]} <syscall>";
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>

getitimer.2: Use restrict in prototypes

POSIX specifies that the 2nd and 3rd parameters to setitimer()
shall be 'restrict'.  Glibc uses 'restrict' too.
Let's use it here too.

......

.../glibc$ grep_syscall_wrapper setitimer
time/sys/time.h:129:
extern int setitimer (__itimer_which_t __which,
      const struct itimerval *__restrict __new,
      struct itimerval *__restrict __old) __THROW;
.../glibc$

function grep_syscall_wrapper()
{
if ! [ -v 1 ]; then
>&2 echo "Usage: ${FUNCNAME[0]} <syscall>";
return ${EX_USAGE};
fi

find * -type f \
|grep '\.h$' \
|sort -V \
|xargs pcregrep -Mn \
  "^[^\s][\w\s]+\s+\**${1}\s*\((?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>

epoll_wait.2: srcfix: glibc doesn't provide epoll_pwait2() yet

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>

getgid.2, getuid.2: Note that these interfaces never modify 'errno'

See https://www.austingroupbugs.net/view.php?id=511
and the POSIX.1-2008 specifications of the interfaces.

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

setbuf.3: POSIX doesn't require to errno to be unchanged after successful setbuf()

See https://www.austingroupbugs.net/view.php?id=397#c799

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

setbuf.3: tfix

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

s390_guarded_storage.2: tfix

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

process_madvise.2: Restructure the text in DESCRIPTION a little

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>

process_madvise.2: Minor edits to Suren Baghdasaryan's patch

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

madvise.2: SEE ALSO: add process_madvise(2)

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

pidfd_open.2: Note the process_madvise(2) use case for PID file descriptors

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

process_madvise.2: Document process_madvise(2)

Initial version of process_madvise(2) manual page. Initial text
was extracted from [1], amended after fix [2] and more details
added using man pages of madvise(2) and process_vm_readv(2) as
examples. It also includes the changes to required permission
proposed in [3].

[1] https://lore.kernel.org/patchwork/patch/1297933/
[2] https://lkml.org/lkml/2020/12/8/1282
[3] https://patchwork.kernel.org/project/selinux/patch/20210111170622.2613577-1-surenb@google.com/#23888311

Signed-off-by: Suren Baghdasaryan <surenb@google.com>
Reviewed-by: Michal Hocko <mhocko@suse.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

malloc_trim.3: Remove mention of free() call

'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>

environ.7: Minor tweaks to Bastien's patch

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

environ.7: Reorder the text

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>

environ.7: Note the default if PAGER is not defined

Reported-by: Bastien Roucariès <rouca@debian.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

environ.7: ffix + tfix

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

environ.7: Various edits to Bastien Roucariès's patch

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

environ.7: Document that HOME, LOGNAME, SHELL, USER are set at login time

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>

environ.7: wfix

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

environ.7: Improve the description of PATH

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>

environ.7: wfix in description of PATH

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

time.1: wfix: remove crufty sentence

Remove a sentence that should have been removed in
commit f0e173d6816895ba42c547643eca5904b0b38bf9.

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

tmpfile.3: wfix

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

netdevice.7: wfix

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

netdevice.7: Update documentation for SIOCGIFADDR SIOCSIFADDR SIOCDIFADDR

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>

man-pages.7: tfix

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

uri.7: tfix (logical quoting style)

Reported-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

man.7: tfix (logical quoting style)

Reported-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

rcmd.3: tfix (logical quoting style)

Reported-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

shmget.2: tfix

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

access.2: wfix

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

mmap.2: wfix

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

man-pages.7: tfix

Signed-off-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

environ.7: Minor tweaks to Bastien's patch

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

environ.7:  Document convention of string in environ

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>

environ.7: Minor fixes to Bastien's patch

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

environ.7: Add see also ld.so(8) for LD_ variables

Signed-off-by: Bastien Roucariès <rouca@debian.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

environ.7: Be a little more precise when discussing 'exec'

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>

environ.7: Relocate and reword the mention of _GNU_SOURCE

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>

man-pages.7: tfix

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

man-pages.7: Add a FORMATTING AND WORDING CONVENTIONS section

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>

sock_diag.7: Fix recvmsg() usage in the example

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>

semget.2, shm_open.3: tfix

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>

random.3: srcfix: Don't break proper names into different lines

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

kexec_load.2: srcfix: Don't break a line that doesn't get past the right margin

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

MAINTAINER_NOTES: tfix

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>

fopencookie.3: wsfix

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

uri.7: Note that 'logical' quoting is the norm in Europe

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>

man-pages.7: Note some rationale for the use of real minus signs

See:
https://lore.kernel.org/linux-man/20210121061158.5ul7226fgbrmodbt@localhost.localdomain/
    From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Cc: linux-man <linux-man@vger.kernel.org>, groff@gnu.org
    Subject: Re: Escaping hyphens ("real" minus signs in groff)
    Date: Thu, 21 Jan 2021 17:12:00 +1100

and also groff_char(7).

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

Various pages: use "\-" to generate real minus in circumstances where appropriate

Use \- for math formulas, pathnames, manual page cross references,
etc.

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

inotify.7: wfix

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

mq_overview.7: ffix

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

Various pages: use real minus signs in pathnames

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

confstr.3: ffix: Use real minus sign inside a string

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

Various pages: Inside code blocks (.EX/.EE) use \- to get real minus signs

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>

fread.3: Swap size and nmemb params

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>

mount.2: Note that the 'data' argument can be NULL

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>

tcp.7: Documentation revision for TCP_USER_TIMEOUT

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>

circleq.3: Fix CIRCLEQ_LOOP_*() return type

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

environ.7: Document valid values of pathnames for SHELL, PAGER and EDITOR/VISUAL

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>

man-pages.7: Document "acknowledgement" as the preferred spelling

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>

netlink.7, tcp.7: Spelling fix: s/acknowledgment/acknowledgement/

Signed-off-by: Alejandro Colomar (man-pages) <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

clone.2: tfix

For the alternate signal stack to be cleared, CLONE_VM should and
CLONE_VFORK should not be specified.

[mtk: fixes my commit 52e5819c4190c3f248df4b976e0a04cc561289e4]

Signed-off-by: Johannes Wellhöfer <johannes.wellhofer@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

cacheflush.2: tfix

Signed-off-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pipe.7: tfix

Escape hyphens in pathnames, as per man-pages(7)

Signed-off-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

system.3: ffix

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

system.3: Document bug and workaround when the command name starts with a hypen

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.7: Fix minimal Linux version for NETLINK_CAP_ACK

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.7: Remove IPv4 from description

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>

ulimit.3: tfix

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>

execveat.2: Normalize notes about missing wrappers

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>

cacheflush.2: Update SYNOPSIS for glibc wrapper

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>

crypt.3: Update crypt() FTM requirements to note glibc 2.28 changes

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