glibc and linux-man disagrees about pkey_alloc

glibc and linux-man disagrees about pkey_alloc

[Szabolcs Nagy]

glibc sysdeps/unix/sysv/linux/bits/mman-shared.h:

int pkey_alloc (unsigned int __flags, unsigned int __access_rights) __THROW;

linux-man http://man7.org/linux/man-pages/man2/pkey_alloc.2.html :

int pkey_alloc(unsigned long flags, unsigned long access_rights);

i assume the documentation should be fixed (as the glibc
code is already in use)

Re: glibc and linux-man disagrees about pkey_alloc

[Dmitry V. Levin]

[-- Attachment #1: Type: text/plain, Size: 574 bytes --]

On Wed, May 16, 2018 at 12:10:40PM +0100, Szabolcs Nagy wrote:
> glibc sysdeps/unix/sysv/linux/bits/mman-shared.h:
> 
> int pkey_alloc (unsigned int __flags, unsigned int __access_rights) __THROW;
> 
> linux-man http://man7.org/linux/man-pages/man2/pkey_alloc.2.html :
> 
> int pkey_alloc(unsigned long flags, unsigned long access_rights);
> 
> i assume the documentation should be fixed (as the glibc
> code is already in use)

Note that pkey_alloc syscall takes arguments of type "unsigned long"
and explicitly tests them for unsupported bits.


-- 
ldv

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 801 bytes --]

Re: glibc and linux-man disagrees about pkey_alloc

[Szabolcs Nagy]

On 16/05/18 12:19, Dmitry V. Levin wrote:
> On Wed, May 16, 2018 at 12:10:40PM +0100, Szabolcs Nagy wrote:
>> glibc sysdeps/unix/sysv/linux/bits/mman-shared.h:
>>
>> int pkey_alloc (unsigned int __flags, unsigned int __access_rights) __THROW;
>>
>> linux-man http://man7.org/linux/man-pages/man2/pkey_alloc.2.html :
>>
>> int pkey_alloc(unsigned long flags, unsigned long access_rights);
>>
>> i assume the documentation should be fixed (as the glibc
>> code is already in use)
> 
> Note that pkey_alloc syscall takes arguments of type "unsigned long"
> and explicitly tests them for unsupported bits.
> 
> 

i see, but this is a general bug in the way the syscalls are
documented: a syscall is not a c function, so a c declaration
is not the right way to document it (the pcs does not even
work for syscalls and the linux uapi headers do not provide
magic inline wrappers usable from freestanding c code).

the libc api is in c so that is reasonable to document using
the c language (using c/posix types).

so i recommend making the distinction between kernel uapi,
syscall abi and libc api clear when they disagree about types.

in this case the man says '#include <sys/mman.h>' which is
a libc header, so the declaration has to match whatever is
in there otherwise it's misleading.

Re: glibc and linux-man disagrees about pkey_alloc

[Florian Weimer]

On 05/16/2018 01:10 PM, Szabolcs Nagy wrote:
> glibc sysdeps/unix/sysv/linux/bits/mman-shared.h:
> 
> int pkey_alloc (unsigned int __flags, unsigned int __access_rights) 
> __THROW;
> 
> linux-man http://man7.org/linux/man-pages/man2/pkey_alloc.2.html :
> 
> int pkey_alloc(unsigned long flags, unsigned long access_rights);
> 
> i assume the documentation should be fixed (as the glibc
> code is already in use)

unsigned long on the kernel side is unsigned long long in userspace for 
the x32 variant of x86-64, so the kernel types aren't that helpful for 
describing the user-space interface in an architecture-independent 
fashion.  I expect the flags to be consistent across architectures, so 
there can only be 32 of them anyway, and access rights currently use two 
bits on x86 (and three on POWER, I think).

Thanks,
Florian

Re: glibc and linux-man disagrees about pkey_alloc

[Rich Felker]

On Wed, May 16, 2018 at 04:36:03PM +0200, Florian Weimer wrote:
> On 05/16/2018 01:10 PM, Szabolcs Nagy wrote:
> >glibc sysdeps/unix/sysv/linux/bits/mman-shared.h:
> >
> >int pkey_alloc (unsigned int __flags, unsigned int
> >__access_rights) __THROW;
> >
> >linux-man http://man7.org/linux/man-pages/man2/pkey_alloc.2.html :
> >
> >int pkey_alloc(unsigned long flags, unsigned long access_rights);
> >
> >i assume the documentation should be fixed (as the glibc
> >code is already in use)
> 
> unsigned long on the kernel side is unsigned long long in userspace
> for the x32 variant of x86-64, so the kernel types aren't that
> helpful for describing the user-space interface in an
> architecture-independent fashion.  I expect the flags to be
> consistent across architectures, so there can only be 32 of them
> anyway, and access rights currently use two bits on x86 (and three
> on POWER, I think).

There's possibly some argument to be made that by the time 32 bits are
filled, 32-bit archs will be legacy-only and won't be getting new pkey
hardware features, in which case having the full 64 bits available
would be nice... But I don't really care what decision is made as long
as it's consistent.

Rich

Re: glibc and linux-man disagrees about pkey_alloc

[Michael Kerrisk (man-pages)]

On 05/16/2018 01:33 PM, Szabolcs Nagy wrote:
> On 16/05/18 12:19, Dmitry V. Levin wrote:
>> On Wed, May 16, 2018 at 12:10:40PM +0100, Szabolcs Nagy wrote:
>>> glibc sysdeps/unix/sysv/linux/bits/mman-shared.h:
>>>
>>> int pkey_alloc (unsigned int __flags, unsigned int __access_rights) __THROW;
>>>
>>> linux-man http://man7.org/linux/man-pages/man2/pkey_alloc.2.html :
>>>
>>> int pkey_alloc(unsigned long flags, unsigned long access_rights);
>>>
>>> i assume the documentation should be fixed (as the glibc
>>> code is already in use)
>>
>> Note that pkey_alloc syscall takes arguments of type "unsigned long"
>> and explicitly tests them for unsupported bits.
>>
>>
> 
> i see, but this is a general bug in the way the syscalls are
> documented: a syscall is not a c function, so a c declaration
> is not the right way to document it (the pcs does not even
> work for syscalls and the linux uapi headers do not provide
> magic inline wrappers usable from freestanding c code).
> 
> the libc api is in c so that is reasonable to document using
> the c language (using c/posix types).
> 
> so i recommend making the distinction between kernel uapi,
> syscall abi and libc api clear when they disagree about types.
> 
> in this case the man says '#include <sys/mman.h>' which is
> a libc header, so the declaration has to match whatever is
> in there otherwise it's misleading.

In cases like these, the section 2 man pages tend to document
the libc interface. The reason that "unsigned long" was shown
was that until now there was no libc interface. I've amended
the manual page to use "unsigned int" for both arguments.
Thanks for CCing linux-man@

Cheers,

Michael



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