[Bug 216876] New: prototype for execveat() in the documentation appears wrong

[Bug 216876] New: prototype for execveat() in the documentation appears wrong

[bugzilla-daemon]

https://bugzilla.kernel.org/show_bug.cgi?id=216876

            Bug ID: 216876
           Summary: prototype for execveat() in the documentation appears
                    wrong
           Product: Documentation
           Version: unspecified
          Hardware: All
                OS: Linux
            Status: NEW
          Severity: low
          Priority: P1
         Component: man-pages
          Assignee: documentation_man-pages@kernel-bugs.osdl.org
          Reporter: markgaleck@gmail.com
        Regression: No

prototype for execveat() in the documentation is:

int execveat(int dirfd, const char *pathname,
                    const char *const argv[], const char *const envp[],
                    int flags);


This appears to be inconsistent with similar functions, other documentation,
and my sources (latest Ubuntu distribution). 


I think two of the "const" should be dropped so that we should have:

int execveat(int dirfd, const char *pathname,
                    char *const argv[], char *const envp[],
                    int flags);

-- 
You may reply to this email to add a comment.

You are receiving this mail because:
You are watching the assignee of the bug.

[Bug 216876] prototype for execveat() in the documentation appears wrong

[bugzilla-daemon]

https://bugzilla.kernel.org/show_bug.cgi?id=216876

--- Comment #1 from Florian Weimer (fweimer@redhat.com) ---
* Alejandro Colomar via Libc-alpha:

> It seems that glibc added a wrapper recently, and I didn't check that
> the prototype changed:
>
> alx@asus5775:~/src/gnu/glibc$ grepc execveat
> ./posix/unistd.h:300:
> extern int execveat (int __fd, const char *__path, char *const __argv[],
>                      char *const __envp[], int __flags)
>     __THROW __nonnull ((2, 3));
>
>
> ./sysdeps/unix/sysv/linux/execveat.c:25:
> int
> execveat (int dirfd, const char *path, char *const argv[], char *const
> envp[],
>           int flags)
> {
>   /* Avoid implicit array coercion in syscall macros.  */
>   return INLINE_SYSCALL_CALL (execveat, dirfd, path, &argv[0], &envp[0],
>                             flags);
> }
>
>
> I CCd glibc so that they can comment.

POSIX uses these types for fexecve and execve, and it seemed right to be
consistent with that.

There are several more manual pages which do not specify the correct
prototype: open, openat, prctl.  I have received compiler bug reports
when people used function pointers modeled after the declarations of
open and prctl in the manual pages because of the ABI mismatch with the
glibc implementations.  The execveat difference is harmless in
comparison.

Thanks,
Florian

-- 
You may reply to this email to add a comment.

You are receiving this mail because:
You are watching the assignee of the bug.

[Bug 216876] prototype for execveat() in the documentation appears wrong

[bugzilla-daemon]

https://bugzilla.kernel.org/show_bug.cgi?id=216876

--- Comment #2 from Alejandro Colomar (alx@kernel.org) ---
Fixed:
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/man2/execveat.2?id=0c884c2c515d20c8ecf246eef5208dc748b98e65>

-- 
You may reply to this email to add a comment.

You are receiving this mail because:
You are watching the assignee of the bug.

[Bug 216876] prototype for execveat() in the documentation appears wrong

[bugzilla-daemon]

https://bugzilla.kernel.org/show_bug.cgi?id=216876

Alejandro Colomar (alx@kernel.org) changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|NEW                         |RESOLVED
         Resolution|---                         |DOCUMENTED

-- 
You may reply to this email to add a comment.

You are receiving this mail because:
You are watching the assignee of the bug.

Re: [Bug 216876] New: prototype for execveat() in the documentation appears wrong

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 3456 bytes --]

Hi,

On 1/2/23 04:47, bugzilla-daemon@kernel.org wrote:
> https://bugzilla.kernel.org/show_bug.cgi?id=216876
> 
>              Bug ID: 216876
>             Summary: prototype for execveat() in the documentation appears
>                      wrong
>             Product: Documentation
>             Version: unspecified
>            Hardware: All
>                  OS: Linux
>              Status: NEW
>            Severity: low
>            Priority: P1
>           Component: man-pages
>            Assignee: documentation_man-pages@kernel-bugs.osdl.org
>            Reporter: markgaleck@gmail.com
>          Regression: No
> 
> prototype for execveat() in the documentation is:
> 
> int execveat(int dirfd, const char *pathname,
>                      const char *const argv[], const char *const envp[],
>                      int flags);
> 
> 
> This appears to be inconsistent with similar functions, other documentation,
> and my sources (latest Ubuntu distribution).
> 
> 
> I think two of the "const" should be dropped so that we should have:
> 
> int execveat(int dirfd, const char *pathname,
>                      char *const argv[], char *const envp[],
>                      int flags);

Thanks for the report!

This was introduced in commit 71a25d4c79b1ccf538f6b813c834bbc4197f6370
"execveat.2: Fix prototype".

The reason is that the kernel uses the const:

alx@asus5775:~/src/linux/linux$ grepc execveat
./include/linux/compat.h:851:
asmlinkage long compat_sys_execveat(int dfd, const char __user *filename,
		     const compat_uptr_t __user *argv,
		     const compat_uptr_t __user *envp, int flags);


./include/linux/syscalls.h:1011:
asmlinkage long sys_execveat(int dfd, const char __user *filename,
			const char __user *const __user *argv,
			const char __user *const __user *envp, int flags);


./fs/exec.c:2096:
SYSCALL_DEFINE5(execveat,
		int, fd, const char __user *, filename,
		const char __user *const __user *, argv,
		const char __user *const __user *, envp,
		int, flags)
{
	return do_execveat(fd,
			   getname_uflags(filename, flags),
			   argv, envp, flags);
}


./fs/exec.c:2115:
COMPAT_SYSCALL_DEFINE5(execveat, int, fd,
		       const char __user *, filename,
		       const compat_uptr_t __user *, argv,
		       const compat_uptr_t __user *, envp,
		       int,  flags)
{
	return compat_do_execveat(fd,
				  getname_uflags(filename, flags),
				  argv, envp, flags);
}


It seems that glibc added a wrapper recently, and I didn't check that the 
prototype changed:

alx@asus5775:~/src/gnu/glibc$ grepc execveat
./posix/unistd.h:300:
extern int execveat (int __fd, const char *__path, char *const __argv[],
                      char *const __envp[], int __flags)
     __THROW __nonnull ((2, 3));


./sysdeps/unix/sysv/linux/execveat.c:25:
int
execveat (int dirfd, const char *path, char *const argv[], char *const envp[],
           int flags)
{
   /* Avoid implicit array coercion in syscall macros.  */
   return INLINE_SYSCALL_CALL (execveat, dirfd, path, &argv[0], &envp[0],
			      flags);
}


I CCd glibc so that they can comment.

Cheers,

Alex

P.S.:  There's some problem in bugzilla that it's not receiving my replies, so I 
CCed everyone involved so we can keep the discussion in the mailing list.

P.S.2:  Ping, Konstantin, please check that.

-- 
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [Bug 216876] New: prototype for execveat() in the documentation appears wrong

[Florian Weimer]

* Alejandro Colomar via Libc-alpha:

> It seems that glibc added a wrapper recently, and I didn't check that
> the prototype changed:
>
> alx@asus5775:~/src/gnu/glibc$ grepc execveat
> ./posix/unistd.h:300:
> extern int execveat (int __fd, const char *__path, char *const __argv[],
>                      char *const __envp[], int __flags)
>     __THROW __nonnull ((2, 3));
>
>
> ./sysdeps/unix/sysv/linux/execveat.c:25:
> int
> execveat (int dirfd, const char *path, char *const argv[], char *const envp[],
>           int flags)
> {
>   /* Avoid implicit array coercion in syscall macros.  */
>   return INLINE_SYSCALL_CALL (execveat, dirfd, path, &argv[0], &envp[0],
> 			      flags);
> }
>
>
> I CCd glibc so that they can comment.

POSIX uses these types for fexecve and execve, and it seemed right to be
consistent with that.

There are several more manual pages which do not specify the correct
prototype: open, openat, prctl.  I have received compiler bug reports
when people used function pointers modeled after the declarations of
open and prctl in the manual pages because of the ABI mismatch with the
glibc implementations.  The execveat difference is harmless in
comparison.

Thanks,
Florian

Re: [Bug 216876] New: prototype for execveat() in the documentation appears wrong

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 1575 bytes --]

Hi Florian,

On 1/2/23 16:26, Florian Weimer wrote:
> * Alejandro Colomar via Libc-alpha:
> 
>> It seems that glibc added a wrapper recently, and I didn't check that
>> the prototype changed:
>>
>> alx@asus5775:~/src/gnu/glibc$ grepc execveat
>> ./posix/unistd.h:300:
>> extern int execveat (int __fd, const char *__path, char *const __argv[],
>>                       char *const __envp[], int __flags)
>>      __THROW __nonnull ((2, 3));
>>
>>
>> ./sysdeps/unix/sysv/linux/execveat.c:25:
>> int
>> execveat (int dirfd, const char *path, char *const argv[], char *const envp[],
>>            int flags)
>> {
>>    /* Avoid implicit array coercion in syscall macros.  */
>>    return INLINE_SYSCALL_CALL (execveat, dirfd, path, &argv[0], &envp[0],
>> 			      flags);
>> }
>>
>>
>> I CCd glibc so that they can comment.
> 
> POSIX uses these types for fexecve and execve, and it seemed right to be
> consistent with that.
> 
> There are several more manual pages which do not specify the correct
> prototype: open, openat, prctl.  I have received compiler bug reports
> when people used function pointers modeled after the declarations of
> open and prctl in the manual pages because of the ABI mismatch with the
> glibc implementations.  The execveat difference is harmless in
> comparison.

That makes sense, and is what I guessed.  I just wanted to make sure that it was 
intentional.  I've updated the page to reflect the glibc wrapper.

Cheers,

Alex

> 
> Thanks,
> Florian
> 

-- 
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]