Hi Michael,
On 2/9/21 7:25 PM, Michael Kerrisk (man-pages) wrote:
> Hi Alex,
>
> On 2/8/21 11:36 PM, Alejandro Colomar (man-pages) wrote:
>> [CC += linux-man@]
>>
>> I forgot the list.
>>
>> On 2/8/21 11:34 PM, Alejandro Colomar (man-pages) wrote:
>>> Hi Michael,
>>>
>>> I think we should simplify the prototype of ptrace(2) from using 'enum
>>> __ptrace_request' to 'int'. It is an implementation detail that should
>>> be transparent to the user. Other pages where glibc uses an 'enum' are
>>> documented to use 'int' (I don't remember the names of those, but
>>> remember having seen them a few days ago. Otherwise, we might have to
>>> document 'enum' elsewhere, which I don't think adds any value. What do
>>> you think about it?
>
> I'm somewhat conservative on this point. It's been documented
> this way forever, so I'm inclined to pause before changing it.
Okay.
> I feel like we lack information. I'd like to know about some of
> the other cases where enums in glibc are documented instead as int.
> But, on the other hand, maybe this is not the highest priority,
> so it may not be worth too much effort to discover those examples.
I checked all of them ;)
It's more like 50/50.
Here are the glibc results (grepping though the kernel is taking much
longer, but I guess the command will have ended by tomorrow morning, and
I'll send you a follow-up.
.../gnu/glibc$ man_lsfunc ../../linux/man-pages/man2 \
|while read -r f; do \
grep_glibc_prototype $f;
done \
|grep enum;
extern long pciconfig_iobase(enum __pciconfig_iobase_which __which,
extern int prlimit (__pid_t __pid, enum __rlimit_resource __resource,
extern int prlimit (__pid_t __pid, enum __rlimit_resource __resource,
extern int prlimit (__pid_t __pid, enum __rlimit_resource __resource,
extern int prlimit (__pid_t __pid, enum __rlimit_resource __resource,
extern int ptrace (enum __ptrace_request __request, ...);
extern long int ptrace (enum __ptrace_request __request, ...) __THROW;
.../gnu/glibc$
Of the above, only ptrace(2) uses 'enum' in the manual page.
The others use 'int'.
.../gnu/glibc$ man_lsfunc ../../linux/man-pages/man3 \
|while read -r f; do \
grep_glibc_prototype $f;
done \
|grep enum;
extern int mcheck (void (*__abortfunc)(enum mcheck_status)) __THROW;
extern int mcheck_pedantic (void (*__abortfunc)(enum mcheck_status))
__THROW;
extern enum mcheck_status mprobe (void *__ptr) __THROW;
.../gnu/glibc$
All of the above use 'enum' in the manual page.
Cheers,
Alex
......
man_lsfunc prints a list of all C functions documented in the SYNOPSIS
of a directory such as man2 (it can also be used on a single manual
page, such as `man_lsfunc man2/open.2`).
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' \
|sort \
|uniq;
}
>
> Thanks,
>
> Michael
>
>
>
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
