[musl] Re: [libc-coord] Re: regression in man pages for interfaces using loff_t

[Sam James <sam@gentoo.org>]

Jonathan Wakely via Libc-alpha <libc-alpha@sourceware.org> writes:

> On Fri, 30 Jun 2023 at 09:02, Jonathan Wakely wrote:
>>
>> On Fri, 30 Jun 2023 at 08:11, Paul Eggert wrote:
>>>
>>> On 2023-06-28 12:15, Rich Felker wrote:
>>>
>>> > There's also the problem that off64_t is "exactly 64-bit" which makes
>>> > it unsuitable as an interface type for cross-platform functions where
>>> > one could imagine the native type being larger (rather horrifying but
>>> > possible).
>>>
>>> Although we won't have files with 2**63 bytes any time soon, this is the
>>> best argument for preferring "loff_t" to "off64_t".
>>>
>>> But come to think of it, it'd be better to document the type simply as
>>> "off_t", with a footnote saying the equivalent of "this assumes that on
>>> 32-bit glibc platforms you compile with -DFILE_OFFSET_BITS=64 like any
>>> sane person would." The intent really is off_t here, and that will
>>> remain true even if off_t ever widens past 64 bits.
>>>
>>> All the apps I know that use the syscalls in question simply pass
>>> values that fit in off_t to these functions, and this will work
>>> regardless of whether these apps are compiled with 64- or (horrors!)
>>> 32-bit off_t. Admittedly the footnote solution would not be perfect, but
>>> it's good enough, and it would sidestep the loff_t vs off64_t confusion.
>>
>>
>> For APIs like copy_file_range(2) and splice(2) the arguments are
>> loff_t* so you can't just "pass arguments that fit in off_t" to
>> them. You have to get the pointer type correct, because writing
>> 64-bits through a 32-bit off_t would be bad. And in C++ it won't
>> even compile unless you get the pointer types exactly right (C
>> compilers will typically allow the mismatch with just a warning).
>>
>> People miss footnotes. I would really prefer if the signature shown
>> in the man page used a type that will actually compile. If it shows
>> off_t, that won't compile for 32-bit systems without LFS support
>> enabled.
>
> Apologies for sending the mail above as HTML - replying as text/plain
> for those it didn't reach.

Yes, please. The footnote is likely to be misunderstood at best (if
people even see it, they'll think it's some obscure portability issue
and try to #ifdef or something).

Apparently we got confused by this before as well: https://github.com/gentoo/portage/commit/1a7aeb58c4e687e4d4012054b56373f27941a067
(https://bugs.gentoo.org/617778), so I'll need to look at that now too.