[PATCH] getitimer.2: Use restrict in prototypes

[PATCH] getitimer.2: Use restrict in prototypes

[Alejandro Colomar]

POSIX specifies that the 2nd and 3rd parameters to setitimer()
shall be 'restrict'.  Glibc uses 'restrict' too.
Let's use it here too.

......

.../glibc$ grep_syscall_wrapper setitimer
time/sys/time.h:129:
extern int setitimer (__itimer_which_t __which,
		      const struct itimerval *__restrict __new,
		      struct itimerval *__restrict __old) __THROW;
.../glibc$

function grep_syscall_wrapper()
{
	if ! [ -v 1 ]; then
		>&2 echo "Usage: ${FUNCNAME[0]} <syscall>";
		return ${EX_USAGE};
	fi

	find * -type f \
	|grep '\.h$' \
	|sort -V \
	|xargs pcregrep -Mn \
	  "^[^\s][\w\s]+\s+\**${1}\s*\((?s)[\w\s()[\]*,]*?(...)?\)[\w\s()]*;" \
	|sed -E 's/^[^:]+:[0-9]+:/&\n/';
}

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/getitimer.2 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/man2/getitimer.2 b/man2/getitimer.2
index b435c343e..9ec32e836 100644
--- a/man2/getitimer.2
+++ b/man2/getitimer.2
@@ -18,8 +18,8 @@ getitimer, setitimer \- get or set value of an interval timer
 .B #include <sys/time.h>
 .PP
 .BI "int getitimer(int " which ", struct itimerval *" curr_value );
-.BI "int setitimer(int " which ", const struct itimerval *" new_value ,
-.BI "              struct itimerval *" old_value );
+.BI "int setitimer(int " which ", const struct itimerval *restrict " new_value ,
+.BI "              struct itimerval *restrict " old_value );
 .fi
 .SH DESCRIPTION
 These system calls provide access to interval timers, that is,
-- 
2.30.0

Re: [PATCH] getitimer.2: Use restrict in prototypes

[Michael Kerrisk (man-pages)]

Hi Alex,

On Wed, 3 Feb 2021 at 20:45, Alejandro Colomar <alx.manpages@gmail.com> wrote:
>
> POSIX specifies that the 2nd and 3rd parameters to setitimer()
> shall be 'restrict'.  Glibc uses 'restrict' too.
> Let's use it here too.

I'm not against this change. But, as we know, 'restrict' is not used
at all so far in the SYNOPSIS sections of the manual pages. DO you
have an overall plan here?

Thanks,

Michael

> ......
>
> .../glibc$ grep_syscall_wrapper setitimer
> time/sys/time.h:129:
> extern int setitimer (__itimer_which_t __which,
>                       const struct itimerval *__restrict __new,
>                       struct itimerval *__restrict __old) __THROW;
> .../glibc$
>
> function grep_syscall_wrapper()
> {
>         if ! [ -v 1 ]; then
>                 >&2 echo "Usage: ${FUNCNAME[0]} <syscall>";
>                 return ${EX_USAGE};
>         fi
>
>         find * -type f \
>         |grep '\.h$' \
>         |sort -V \
>         |xargs pcregrep -Mn \
>           "^[^\s][\w\s]+\s+\**${1}\s*\((?s)[\w\s()[\]*,]*?(...)?\)[\w\s()]*;" \
>         |sed -E 's/^[^:]+:[0-9]+:/&\n/';
> }
>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
>  man2/getitimer.2 | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/man2/getitimer.2 b/man2/getitimer.2
> index b435c343e..9ec32e836 100644
> --- a/man2/getitimer.2
> +++ b/man2/getitimer.2
> @@ -18,8 +18,8 @@ getitimer, setitimer \- get or set value of an interval timer
>  .B #include <sys/time.h>
>  .PP
>  .BI "int getitimer(int " which ", struct itimerval *" curr_value );
> -.BI "int setitimer(int " which ", const struct itimerval *" new_value ,
> -.BI "              struct itimerval *" old_value );
> +.BI "int setitimer(int " which ", const struct itimerval *restrict " new_value ,
> +.BI "              struct itimerval *restrict " old_value );
>  .fi
>  .SH DESCRIPTION
>  These system calls provide access to interval timers, that is,
> --
> 2.30.0
>


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH] getitimer.2: Use restrict in prototypes

[Alejandro Colomar (man-pages)]

Hi Michael,

On 2/6/21 10:58 AM, Michael Kerrisk (man-pages) wrote:
> Hi Alex,
> 
> On Wed, 3 Feb 2021 at 20:45, Alejandro Colomar <alx.manpages@gmail.com> wrote:
>>
>> POSIX specifies that the 2nd and 3rd parameters to setitimer()
>> shall be 'restrict'.  Glibc uses 'restrict' too.
>> Let's use it here too.
> 
> I'm not against this change. But, as we know, 'restrict' is not used
> at all so far in the SYNOPSIS sections of the manual pages. DO you
> have an overall plan here?

Yes, I do.  My plan is to fix all the prototypes that use restrict by
adding the keyword.

I'm using the man_section function I showed you to see all the man2 and
man3 prototypes on one side, and grep_syscall_wrapper/grep_syscall on
the other side to do it fast, so expect just a few weeks to do the
change completely.

Heinrich also proposed this change some time ago (I already had in my
to-do list, but that reminded me to do it) here:
<https://lore.kernel.org/linux-man/105b8883-d6a8-b3c3-3aff-ee1d6e88980a@gmail.com/T/>.

Cheers,

Alex

> 
> Thanks,
> 
> Michael
> 
>> ......
>>
>> .../glibc$ grep_syscall_wrapper setitimer
>> time/sys/time.h:129:
>> extern int setitimer (__itimer_which_t __which,
>>                       const struct itimerval *__restrict __new,
>>                       struct itimerval *__restrict __old) __THROW;
>> .../glibc$
>>
>> function grep_syscall_wrapper()
>> {
>>         if ! [ -v 1 ]; then
>>                 >&2 echo "Usage: ${FUNCNAME[0]} <syscall>";
>>                 return ${EX_USAGE};
>>         fi
>>
>>         find * -type f \
>>         |grep '\.h$' \
>>         |sort -V \
>>         |xargs pcregrep -Mn \
>>           "^[^\s][\w\s]+\s+\**${1}\s*\((?s)[\w\s()[\]*,]*?(...)?\)[\w\s()]*;" \
>>         |sed -E 's/^[^:]+:[0-9]+:/&\n/';
>> }
>>
>> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
>> ---
>>  man2/getitimer.2 | 4 ++--
>>  1 file changed, 2 insertions(+), 2 deletions(-)
>>
>> diff --git a/man2/getitimer.2 b/man2/getitimer.2
>> index b435c343e..9ec32e836 100644
>> --- a/man2/getitimer.2
>> +++ b/man2/getitimer.2
>> @@ -18,8 +18,8 @@ getitimer, setitimer \- get or set value of an interval timer
>>  .B #include <sys/time.h>
>>  .PP
>>  .BI "int getitimer(int " which ", struct itimerval *" curr_value );
>> -.BI "int setitimer(int " which ", const struct itimerval *" new_value ,
>> -.BI "              struct itimerval *" old_value );
>> +.BI "int setitimer(int " which ", const struct itimerval *restrict " new_value ,
>> +.BI "              struct itimerval *restrict " old_value );
>>  .fi
>>  .SH DESCRIPTION
>>  These system calls provide access to interval timers, that is,
>> --
>> 2.30.0
>>
> 
> 


-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: [PATCH] getitimer.2: Use restrict in prototypes

[Michael Kerrisk (man-pages)]

Hi Alex,

On 2/6/21 11:47 AM, Alejandro Colomar (man-pages) wrote:
> Hi Michael,
> 
> On 2/6/21 10:58 AM, Michael Kerrisk (man-pages) wrote:
>> Hi Alex,
>>
>> On Wed, 3 Feb 2021 at 20:45, Alejandro Colomar <alx.manpages@gmail.com> wrote:
>>>
>>> POSIX specifies that the 2nd and 3rd parameters to setitimer()
>>> shall be 'restrict'.  Glibc uses 'restrict' too.
>>> Let's use it here too.
>>
>> I'm not against this change. But, as we know, 'restrict' is not used
>> at all so far in the SYNOPSIS sections of the manual pages. DO you
>> have an overall plan here?
> 
> Yes, I do.  My plan is to fix all the prototypes that use restrict by
> adding the keyword.

It's not a pretty or glamorous job. So thank you very much for doing it!

Thanks for this patch. I've applied it.

Cheers,

Michael

> I'm using the man_section function I showed you to see all the man2 and
> man3 prototypes on one side, and grep_syscall_wrapper/grep_syscall on
> the other side to do it fast, so expect just a few weeks to do the
> change completely.
> 
> Heinrich also proposed this change some time ago (I already had in my
> to-do list, but that reminded me to do it) here:
> <https://lore.kernel.org/linux-man/105b8883-d6a8-b3c3-3aff-ee1d6e88980a@gmail.com/T/>.
> 
> Cheers,
> 
> Alex
> 
>>
>> Thanks,
>>
>> Michael
>>
>>> ......
>>>
>>> .../glibc$ grep_syscall_wrapper setitimer
>>> time/sys/time.h:129:
>>> extern int setitimer (__itimer_which_t __which,
>>>                       const struct itimerval *__restrict __new,
>>>                       struct itimerval *__restrict __old) __THROW;
>>> .../glibc$
>>>
>>> function grep_syscall_wrapper()
>>> {
>>>         if ! [ -v 1 ]; then
>>>                 >&2 echo "Usage: ${FUNCNAME[0]} <syscall>";
>>>                 return ${EX_USAGE};
>>>         fi
>>>
>>>         find * -type f \
>>>         |grep '\.h$' \
>>>         |sort -V \
>>>         |xargs pcregrep -Mn \
>>>           "^[^\s][\w\s]+\s+\**${1}\s*\((?s)[\w\s()[\]*,]*?(...)?\)[\w\s()]*;" \
>>>         |sed -E 's/^[^:]+:[0-9]+:/&\n/';
>>> }
>>>
>>> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
>>> ---
>>>  man2/getitimer.2 | 4 ++--
>>>  1 file changed, 2 insertions(+), 2 deletions(-)
>>>
>>> diff --git a/man2/getitimer.2 b/man2/getitimer.2
>>> index b435c343e..9ec32e836 100644
>>> --- a/man2/getitimer.2
>>> +++ b/man2/getitimer.2
>>> @@ -18,8 +18,8 @@ getitimer, setitimer \- get or set value of an interval timer
>>>  .B #include <sys/time.h>
>>>  .PP
>>>  .BI "int getitimer(int " which ", struct itimerval *" curr_value );
>>> -.BI "int setitimer(int " which ", const struct itimerval *" new_value ,
>>> -.BI "              struct itimerval *" old_value );
>>> +.BI "int setitimer(int " which ", const struct itimerval *restrict " new_value ,
>>> +.BI "              struct itimerval *restrict " old_value );
>>>  .fi
>>>  .SH DESCRIPTION
>>>  These system calls provide access to interval timers, that is,
>>> --
>>> 2.30.0
>>>
>>
>>
> 
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/