Re: ptrace.2: Simplify signature? s/enum \w*/int/

["Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>]

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/