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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
Reported-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Cc: Martin Sebor <msebor@redhat.com>
Cc: Dave Martin <Dave.Martin@arm.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The Linux kernel uses 'int' instead of 'long' for the return type.
As glibc provides no wrapper, use the same type the kernel uses.
......
$ grep -n wrapper man-pages/man2/subpage_prot.2
40:There is no glibc wrapper for this system call; see NOTES.
99:Glibc does not provide a wrapper for this system call; call it using
$ grep -rn SYSCALL_DEFINE.*subpage_prot linux/;
linux/arch/powerpc/mm/book3s64/subpage_prot.c:190:
SYSCALL_DEFINE3(subpage_prot, unsigned long, addr,
$ sed -n /SYSCALL.*subpage_prot/,/^}/p \
linux/arch/powerpc/mm/book3s64/subpage_prot.c \
|grep return;
return -ENOENT;
return -EINVAL;
return -EINVAL;
return 0;
return -EFAULT;
return -EFAULT;
return err;
$ sed -n /SYSCALL.*subpage_prot/,/^}/p \
linux/arch/powerpc/mm/book3s64/subpage_prot.c \
|grep '\<err\>';
int err;
err = -ENOMEM;
err = -ENOMEM;
err = 0;
return err;
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This paragraph is a little bit hidden at the end of DESCRIPTION;
make it a little more prominent.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Linux kernel commit aae8a97d3ec30788790d1720b71d76fd8eb44b73 (part
of kernel release v2.6.39) added a check to disallow creating a
hardlink to an unlinked file.
The manual page already describes the trick of using
AT_SYMLINK_FOLLOW as an alternative to AT_EMPTY_PATH, and for
AT_EMPTY_PATH the manual page already notes that it "will
generally not work if the file has a link count of zero". However,
the precise error (ENOENT) is not mentioned, and the error case
isn't mentioned in the ERRORS section at all.
This makes it easy to overlook the fact that the AT_SYMLINK_FOLLOW
trick on /proc/self/fd/NN won't work on deleted files, as
evidenced by the follow message (which turns up when googling
"linkat deleted ENOENT"):
https://groups.google.com/g/linux.kernel/c/zZO4lqqwp64
Signed-off-by: Mathias Rav <m@git.strova.dk>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The Linux kernel uses 'pid_t' instead of 'long' for the return type.
As glibc provides no wrapper, use the same types the kernel uses.
$ sed -n 34,36p man-pages/man2/set_tid_address.2
.PP
.IR Note :
There is no glibc wrapper for this system call; see NOTES.
$ grep -rn 'SYSCALL_DEFINE.*set_tid_address' linux/
linux/kernel/fork.c:1632:
SYSCALL_DEFINE1(set_tid_address, int __user *, tidptr)
$ sed -n 1632,1638p linux/kernel/fork.c
SYSCALL_DEFINE1(set_tid_address, int __user *, tidptr)
{
current->clear_child_tid = tidptr;
return task_pid_vnr(current);
}
$ grep -rn 'task_pid_vnr(struct' linux/
linux/include/linux/sched.h:1374:
static inline pid_t task_pid_vnr(struct task_struct *tsk)
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
{.IR var [x]} -> {.I var[x]}
There were around 15 entries of the former,
and around 360 of the latter.
Found using:
$ grep -rn '^\.I[ |R].* \[.*\]' |sort
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
In the comment of the example program, the peer blocks on fwait()
rather than fpost().
Signed-off-by: Jing Peng <pj.hades@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
With this change, there remain almost no vestiges of information
about the long defunct Linux libc.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
faccessat2() was added in Linux 5.8 and enables a fix to
longstanding bugs in the faccessat() wrapper function.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The include path is linux/openat2, so fix the manual to reference
this correct path.
Signed-off-by: Colin Ian King <colin.king@canonical.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The Linux kernel uses a long as the return type for this syscall.
As glibc provides no wrapper, use the same types the kernel uses.
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
In the kernel sources (kernel/fork.c::copy_process()), we have:
/*
* sigaltstack should be cleared when sharing the same VM
*/
if ((clone_flags & (CLONE_VM|CLONE_VFORK)) == CLONE_VM)
sas_ss_reset(p);
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
See https://bugzilla.kernel.org/show_bug.cgi?id=12665.
The fix by Thomas Gleixner was in kernel commit
78c9c4dfbf8c04883941445a195276bb4bb92c76.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Linux kernel commit 2a36ab717e8fe678d98f81c14a0b124712719840
(part of 5.10 release) changed sys_membarrier prototype/parameters
and added two new commands [MEMBARRIER_CMD_PRIVATE_EXPEDITED_RSEQ
and MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED_RSEQ]. This
man-pages patch reflects these changes, by mostly copying comments
from the kernel patch into the man-page ([Peter Oskolkov] was also
the author of the kernel change).
[mtk: commit message tweaked]
Signed-off-by: Peter Oskolkov <posk@google.com>
Cowritten-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Linux uses aio_context_t for these syscalls,
and it's the type provided by <linux/aio_abi.h>.
Use it in the SYNOPSIS.
libaio uses 'io_context_t', but that difference is already noted
in NOTES.
[mtk: patch slightly tweaked]
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The Linux kernel uses long as the return type for this syscall.
As glibc provides no wrapper, use the same type the kernel uses.
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
That comment wrapped on an 80-column terminal.
Divide it into two lines.
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The Linux kernel uses the following:
kernel/futex.c:3778:
SYSCALL_DEFINE6(futex, u32 __user *, uaddr, int, op, u32, val,
struct __kernel_timespec __user *, utime, u32 __user *, uaddr2,
u32, val3)
Since there is no glibc wrapper, use the same types the kernel uses.
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
[mtk: Applied patch manually]
getdents():
This function has no glibc wrapper.
As such, we should use the same types the Linux kernel uses:
Use 'long' as the return type.
getdents64():
The glibc wrapper uses:
ssize_t getdents64(int, void *, size_t);
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The text in NOTES doesn't really relate specifically to
the #include, so remove the comment on the #include.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Michael Kerrisk