Re: [musl] [PATCH] memmem.3: Added list of known systems where this is available

[enh <enh@google.com>]

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

On Wed, Nov 23, 2022 at 7:33 AM Shiz <hi@shiz.me> wrote:

> Hi there,
>
> > On 23 Nov Reiwa 4, at 14:16, Alejandro Colomar <alx.manpages@gmail.com>
> wrote:
> >
> >>>> -  Android is not a real Unix system, in that you can't even program
> in C in
> >>>> there, unless you're Google or have hacked your system.  It's not
> friendly
> >>>> to us programmers, so we don't need to be friendly to it.  I don't
> want to
> >>>> be cluttering the pages with information that is irrelevant to normal
> users.
> >>>
> >>> I'm assuming bionic is being used in some of the Android free
> >>> alternatives too, but then I'm not sure how usable for programming
> those
> >>> are either. And, well musl libc is not a real Unix system you can
> program
> >>> against either. :)
> >
> > The difference is only that bionic is not in use in useful systems
> (AFAIK).  :)
> >
> > So we have to do some decission here (and also about newlib, as reported
> by Brian).
>
> I’d like to chime in here and note that, valuations of usefulness aside,
> it *is*
> possible to develop in C against an Android device, without needing any
> hacks,
> using the NDK[1]. As someone who has occasionally worked on big codebases
> written
> in C and C++ for Android devices, I would argue there’s value to be had
> there. :-)
>

plus i think bionic is the only libc that explicitly links to man7.org as
the canonical source for documentation in its header files :-)

funnily enough, this topic ("should the man pages talk about availability
in libcs other than glibc?") came up before, and specifically for bionic
mkerrisk seemed to think it was a reasonable idea ... but i (bionic
maintainer) was less convinced. although i think that, yes, if someone's
reading that part of the page, realistically they're either interested in
macOS/iOS or Android (sorry, AIX or IRIX fans!), but specifically for those
two systems the header files already contain machine-readable availability
information via __attribute__((__available__)).

fwiw, here's an example from bionic's <unistd.h> illustrating both of those
points:

```
/**
 * [copy_file_range(2)](
https://man7.org/linux/man-pages/man2/copy_file_range.2.html) copies
 * a range of data from one file descriptor to another.
 *
 * Returns the number of bytes copied on success, and returns -1 and sets
`errno`
 * on failure.
 *
 * Available since API level 34.
 */
ssize_t copy_file_range(int __fd_in, off64_t* __off_in, int __fd_out,
off64_t* __off_out, size_t __length, unsigned int __flags)
__INTRODUCED_IN(34);
```

(if there's anything android-specific to note, we also mention that, but
there are relatively few examples of those, and it's mostly just "SELinux
means that only system processes can enable/disable swap" or whatever.)

so it wasn't clear to me whether -- unless you automated it -- there was
much value to duplicating that in the man pages? if you try to compile,
you're going to get a clear compiler error saying "you need to be targeting
OS version $whatever" anyway.

i think the real question is "aye, but will they get that far?". for my
part, i think the most value would come from cases that talk about "GNU
extension" being a bit clearer whether that's "unique to glibc" (which a
lot of people assume is what it means) or "initially in glibc, but a good
enough idea that it's effectively ubiquitous now, even if it's not in POSIX
because Solaris will never add it". and maybe the best way to clarify stuff
like that is just to explicitly state "Available on macOS since 10.4.
Available on Android since API level 23."? dunno.

if anyone _does_ want to go that route, i'd be happy to help with the "raw
data" side. (and certainly if anyone does start adding that, you'll force
me to care about maintaining it :-) )

but my biggest problem right now is that man7.org isn't being updated, and
i can't get hold of mkerrisk to try to offer him money to do it :-( (i do
hope he's okay, wherever he is!)


> > Cheers,
> >
> > Alex
>
> - Shiz
>
> [1]: https://developer.android.com/ndk

[-- Attachment #2: Type: text/html, Size: 5417 bytes --]