man2: SYNOPSIS: prototype fixes
Hi Michael,
I fixed all of the man2 prototypes to use 'restrict', and also fixed those with incorrect types and missing 'const'.
There are quite a few commits (see below). How would you prefer it? A patch set with all of them? Separate patches for each of them? A patch set for restrict, and the rest separately? I could reorder them too. Right now they are as I wrote them (alphabetical order).
BTW, it was quite easy and fast thanks to the consistency fixes in the SYNOPSIS :-)
Commit list:
[[
* b55125c38 - Fri, 12 Feb 2021 18:28:46 +0100 (11 minutes ago) (HEAD -> devel)
| vmsplice.2: SYNOPSIS: Fix prototype parameter type -
Alejandro Colomar
* 34d9dd72b - Fri, 12 Feb 2021 17:53:17 +0100 (46 minutes ago)
| tkill.2: SYNOPSIS: Fix prototype parameter types - Alejandro
Colomar
* 4e42b38c5 - Fri, 12 Feb 2021 17:45:38 +0100 (54 minutes ago)
| timer_settime.2: SYNOPSIS: Use 'restrict' in prototypes -
Alejandro Colomar
* 51e62f8b2 - Fri, 12 Feb 2021 17:42:52 +0100 (57 minutes ago)
| timer_create.2: SYNOPSIS: Use 'restrict' in prototypes -
Alejandro Colomar
* 3e571e917 - Fri, 12 Feb 2021 17:24:52 +0100 (75 minutes ago)
| stat.2: SYNOPSIS: Use 'restrict' in prototypes - Alejandro
Colomar
* f3c8d2b4d - Fri, 12 Feb 2021 17:12:37 +0100 (87 minutes ago)
| statx.2: SYNOPSIS: Use 'restrict' in prototypes - Alejandro
Colomar
* bfbd4b4d7 - Fri, 12 Feb 2021 17:08:44 +0100 (2 hours ago)
| spu_run.2: SYNOPSIS: Fix prototype parameter types -
Alejandro Colomar
* 1fb014a27 - Fri, 12 Feb 2021 17:02:36 +0100 (2 hours ago)
| spu_create.2: SYNOPSIS: Fix prototype parameter type -
Alejandro Colomar
* ae642106c - Fri, 12 Feb 2021 16:56:16 +0100 (2 hours ago)
| splice.2: Use 'off64_t' instead of 'loff_t' - Alejandro Colomar
* 2078af674 - Fri, 12 Feb 2021 16:46:46 +0100 (2 hours ago)
| socketcall.2: Add note about missing glibc wrapper -
Alejandro Colomar
* 01b4bfbd5 - Fri, 12 Feb 2021 16:39:13 +0100 (2 hours ago)
| sigwaitinfo.2: SYNOPSIS: Use 'restrict' in prototypes -
Alejandro Colomar
* bb7808087 - Fri, 12 Feb 2021 16:30:47 +0100 (2 hours ago)
| sigprocmask.2: SYNOPSIS: Use 'restrict' in prototypes -
Alejandro Colomar
* 48d241968 - Fri, 12 Feb 2021 16:01:17 +0100 (3 hours ago)
| sigaltstack.2: SYNOPSIS: Use 'restrict' in prototypes -
Alejandro Colomar
* 36428c48c - Fri, 12 Feb 2021 15:52:37 +0100 (3 hours ago)
| sigaction.2: SYNOPSIS: Use 'restrict' in prototypes -
Alejandro Colomar
* 16b7a5f97 - Fri, 12 Feb 2021 15:04:40 +0100 (4 hours ago)
| setfsgid.2: tfix - Alejandro Colomar
* af7affdd2 - Fri, 12 Feb 2021 14:48:43 +0100 (4 hours ago)
| select.2: SYNOPSIS: Use 'restrict' in prototypes - Alejandro
Colomar
* 1e336e93b - Fri, 12 Feb 2021 14:31:38 +0100 (4 hours ago)
| sched_setattr.2: Add note about missing glibc wrappers -
Alejandro Colomar
* f2602e04a - Fri, 12 Feb 2021 13:04:24 +0100 (6 hours ago)
| s390_pci_mmio_write.2: SYNOPSIS: Add 'const' qualifier -
Alejandro Colomar
* 3423c9e83 - Fri, 12 Feb 2021 12:42:40 +0100 (6 hours ago)
| recv.2: SYNOPSIS: Use 'restrict' in prototypes - Alejandro
Colomar
* 138c3ac1c - Fri, 12 Feb 2021 12:20:21 +0100 (6 hours ago)
| readlink.2: SYNOPSIS: Use 'restrict' in prototypes -
Alejandro Colomar
]]
If you ever need to do something like this again, the following commands may be useful (I'll need them for section 3 soon):
For reading the man_pages SYNOPSIS:
.../linux/man-pages$ man_section man2 SYNOPSIS |less;
For reading the glibc prototypes:
.../gnu/glibc$ man_lsfunc ../../linux/man-pages/man2 \
|while read -r syscall; do
echo "============================= ${syscall}";
grep_glibc_prototype ${syscall}; done \
|sed -e 's/\bextern //' -e 's/\b_*//g' \
|less;
For reading the kernel prototypes:
.../linux/linux$ man_lsfunc ../man-pages/man2/ \
|while read -r syscall; do
echo "============================= ${syscall}";
grep_syscall ${syscall}; done \
|less;
......
Functions (I've improved these a bit over time):
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/';
}function man_section()
{
if ! [ -v 2 ]; then
>&2 echo "Usage: ${FUNCNAME[0]} <dir> <section>";
return ${EX_USAGE}
fi
find "${1}" -type f \
|xargs grep -l "\.SH ${2}" \
|sort -V \
|while read -r manpage; do
<${manpage} \
sed -n \
-e '/^\.TH/,/^\.SH/{/^\.SH/!p}' \
-e "/^\.SH ${2}/p" \
-e "/^\.SH ${2}/,/^\.SH/{/^\.SH/!p}" \
|man -P cat -l - 2>/dev/null;
done;
}function man_lsfunc()
{
if ! [ -v 1 ]; then
>&2 echo "Usage: ${FUNCNAME[0]} <dir>";
return ${EX_USAGE};
fi
find "${1}" -type f \
|xargs grep -l "\.SH SYNOPSIS" \
|sort -V \
|while read -r manpage; do
<${manpage} \
sed -n \
-e '/^\.TH/,/^\.SH/{/^\.SH/!p}' \
-e "/^\.SH SYNOPSIS/p" \
-e "/^\.SH SYNOPSIS/,/^\.SH/{/^\.SH/!p}" \
|sed \
-e '/Feature/,$d' \
-e '/{/,/}/d' \
|man -P cat -l - 2>/dev/null;
done \
|sed -n "/^SYNOPSIS/,/^\w/p" \
|grep '^ \w' \
|grep -v ':' \
|sed 's/^[^(]* \**\(\w*\)(.*/\1/' \
|grep '^\w' \
|uniq;
}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/';
}Signature · 3 lines
Alejandro Colomar Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/ http://www.alejandro-colomar.es/
Hi Alex,
Quoted 3 lines · Alejandro Colomar (man-pages)
Hi Michael,
I fixed all of the man2 prototypes to use 'restrict', and also fixed> those with incorrect types and missing 'const'.
That's great!
Quoted 3 lines
There are quite a few commits (see below). How would you prefer it? A patch set with all of them? Separate patches for each of them? A patch set for restrict, and the rest separately?
I think the last option is best. (I assume you mean separate patches for each of the rest of the changes?)
Quoted 5 lines
I could reorder them too.
Right now they are as I wrote them (alphabetical order).BTW, it was quite easy and fast thanks to the consistency fixes in the SYNOPSIS :-)
Yes, I can imagine it would have helped....
Thanks,
Michael
Quoted 181 lines
Commit list:
[[
*b55125c38- Fri, 12 Feb 2021 18:28:46 +0100 (11 minutes ago) (HEAD -> devel)
| vmsplice.2: SYNOPSIS: Fix prototype parameter type -
Alejandro Colomar
*34d9dd72b- Fri, 12 Feb 2021 17:53:17 +0100 (46 minutes ago)
| tkill.2: SYNOPSIS: Fix prototype parameter types - Alejandro
Colomar
*4e42b38c5- Fri, 12 Feb 2021 17:45:38 +0100 (54 minutes ago)
| timer_settime.2: SYNOPSIS: Use 'restrict' in prototypes -
Alejandro Colomar
*51e62f8b2- Fri, 12 Feb 2021 17:42:52 +0100 (57 minutes ago)
| timer_create.2: SYNOPSIS: Use 'restrict' in prototypes -
Alejandro Colomar
*3e571e917- Fri, 12 Feb 2021 17:24:52 +0100 (75 minutes ago)
| stat.2: SYNOPSIS: Use 'restrict' in prototypes - Alejandro
Colomar
*f3c8d2b4d- Fri, 12 Feb 2021 17:12:37 +0100 (87 minutes ago)
| statx.2: SYNOPSIS: Use 'restrict' in prototypes - Alejandro
Colomar
*bfbd4b4d7- Fri, 12 Feb 2021 17:08:44 +0100 (2 hours ago)
| spu_run.2: SYNOPSIS: Fix prototype parameter types -
Alejandro Colomar
*1fb014a27- Fri, 12 Feb 2021 17:02:36 +0100 (2 hours ago)
| spu_create.2: SYNOPSIS: Fix prototype parameter type -
Alejandro Colomar
*ae642106c- Fri, 12 Feb 2021 16:56:16 +0100 (2 hours ago)
| splice.2: Use 'off64_t' instead of 'loff_t' - Alejandro Colomar
*2078af674- Fri, 12 Feb 2021 16:46:46 +0100 (2 hours ago)
| socketcall.2: Add note about missing glibc wrapper -
Alejandro Colomar
*01b4bfbd5- Fri, 12 Feb 2021 16:39:13 +0100 (2 hours ago)
| sigwaitinfo.2: SYNOPSIS: Use 'restrict' in prototypes -
Alejandro Colomar
*bb7808087- Fri, 12 Feb 2021 16:30:47 +0100 (2 hours ago)
| sigprocmask.2: SYNOPSIS: Use 'restrict' in prototypes -
Alejandro Colomar
*48d241968- Fri, 12 Feb 2021 16:01:17 +0100 (3 hours ago)
| sigaltstack.2: SYNOPSIS: Use 'restrict' in prototypes -
Alejandro Colomar
*36428c48c- Fri, 12 Feb 2021 15:52:37 +0100 (3 hours ago)
| sigaction.2: SYNOPSIS: Use 'restrict' in prototypes -
Alejandro Colomar
*16b7a5f97- Fri, 12 Feb 2021 15:04:40 +0100 (4 hours ago)
| setfsgid.2: tfix - Alejandro Colomar
*af7affdd2- Fri, 12 Feb 2021 14:48:43 +0100 (4 hours ago)
| select.2: SYNOPSIS: Use 'restrict' in prototypes - Alejandro
Colomar
*1e336e93b- Fri, 12 Feb 2021 14:31:38 +0100 (4 hours ago)
| sched_setattr.2: Add note about missing glibc wrappers -
Alejandro Colomar
*f2602e04a- Fri, 12 Feb 2021 13:04:24 +0100 (6 hours ago)
| s390_pci_mmio_write.2: SYNOPSIS: Add 'const' qualifier -
Alejandro Colomar
*3423c9e83- Fri, 12 Feb 2021 12:42:40 +0100 (6 hours ago)
| recv.2: SYNOPSIS: Use 'restrict' in prototypes - Alejandro
Colomar
*138c3ac1c- Fri, 12 Feb 2021 12:20:21 +0100 (6 hours ago)
| readlink.2: SYNOPSIS: Use 'restrict' in prototypes -
Alejandro Colomar]]
If you ever need to do something like this again, the following commands may be useful (I'll need them for section 3 soon):
For reading the
man_pagesSYNOPSIS:.../linux/man-pages$
man_sectionman2 SYNOPSIS |less;For reading the glibc prototypes:
.../gnu/glibc$
man_lsfunc../../linux/man-pages/man2 \
|while read -r syscall; doecho "============================= ${syscall}"; grep_glibc_prototype ${syscall};done \
|sed -e 's/\bextern //' -e 's/\b_*//g' \
|less;For reading the kernel prototypes:
.../linux/linux$
man_lsfunc../man-pages/man2/ \
|while read -r syscall; doecho "============================= ${syscall}"; grep_syscall ${syscall};done \
|less;......
Functions (I've improved these a bit over time):
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/'; }function
man_section(){ if ! [ -v 2 ]; then >&2 echo "Usage: ${FUNCNAME[0]} <dir> <section>"; return ${EX_USAGE} fi find "${1}" -type f \ |xargs grep -l "\.SH ${2}" \ |sort -V \ |while read -r manpage; do <${manpage} \ sed -n \ -e '/^\.TH/,/^\.SH/{/^\.SH/!p}' \ -e "/^\.SH ${2}/p" \ -e "/^\.SH ${2}/,/^\.SH/{/^\.SH/!p}" \ |man -P cat -l - 2>/dev/null; done; }function
man_lsfunc(){ if ! [ -v 1 ]; then >&2 echo "Usage: ${FUNCNAME[0]} <dir>"; return ${EX_USAGE}; fi find "${1}" -type f \ |xargs grep -l "\.SH SYNOPSIS" \ |sort -V \ |while read -r manpage; do <${manpage} \ sed -n \ -e '/^\.TH/,/^\.SH/{/^\.SH/!p}' \ -e "/^\.SH SYNOPSIS/p" \ -e "/^\.SH SYNOPSIS/,/^\.SH/{/^\.SH/!p}" \ |sed \ -e '/Feature/,$d' \ -e '/{/,/}/d' \ |man -P cat -l - 2>/dev/null; done \ |sed -n "/^SYNOPSIS/,/^\w/p" \ |grep '^ \w' \ |grep -v ':' \ |sed 's/^[^(]* \**\(\w*\)(.*/\1/' \ |grep '^\w' \ |uniq; }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/'; }
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/