Hi Alex,
On 2/12/21 6:56 PM, Alejandro Colomar (man-pages) wrote:
> 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!
> 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?)
> 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
> 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/';
> }
>
>
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
