The goal of the Linux man-pages project

[Alejandro Colomar <alx@kernel.org>]

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

Hi Arsen,

> Date: 2026-08-04 17:49:43+0200
> From: Arsen Arsenović <arsen@aarsen.me>
>
[...]
> >     man/man3/: Put first <string.h> in SYNOPSIS, then comment about <memory.h>
> >     
> >     This is a compromise between the fact that <string.h> is the standard
> >     header and (only slightly) most portable header file for these
> >     functions, while hinting at the fact that it might be more appropriate
> >     to use <memory.h> where possible.
> >     
> >     Remove the STANDARDS and NOTES about this, since now the SYNOPSIS
> >     contains all the necessary information.  The extra info is in
> >     memory.h(3head), which is linked to in the SYNOPSIS.
> >
> > What do you think?
> 
> Why, though?

To help guide programmers to understand these APIs, and consequentially
be able to write better code.  That's the goal of this project.  It's
the Linux Programmer's Manual, and its purpose is that programmers on
a Linux system are able to write correct programs.

The purpose of this documentation is not, and was never supposed to be,
a technical specification of the implementation.

Branden asked me yesterday:

| Date: 2026-08-03 11:09:02-0500
| From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
| Message-ID: <20260803160902.5edjmpxaqr5uudbu@illithid>
|
| What is the overall mission of the Linux man-pages project as you
| conceive it?

Here's my reply.

A programmer should be able to write correct code.

A piece of documentation that describes an API in detail --as if it were
reverse-engineering it from its binary code-- but doesn't tell me how
to use it correctly is useless.

Let's take an example.  Here's the description of strncpy(3) as of
man-pages-5.05 (right before my first patch to the project):

     The strcpy() function copies the string pointed to by src,
     including  the terminating null byte ('\0'), to the buffer
     pointed to by dest.  The strings may not overlap, and  the
     destination  string  dest  must be large enough to receive
     the copy.  Beware of buffer overruns!  (See BUGS.)

     The strncpy() function is similar, except that at  most  n
     bytes  of  src  are  copied.  Warning: If there is no null
     byte among the first n bytes of src, the string placed  in
     dest will not be null‐terminated.

     If  the length of src is less than n, strncpy() writes ad‐
     ditional null bytes to dest to ensure that a  total  of  n
     bytes are written.

Okay, we have an algorithm.  I'm sure you can implement strncpy(3) from
that description.  But what is it useful for?  Why would I want to call
it?  How do I even call it?

The page even continues with an actual implementation.

     A simple implementation of strncpy() might be:

         char *
         strncpy(char *dest, const char *src, size_t n)
         {
             size_t i;

             for (i = 0; i < n && src[i] != '\0'; i++)
                 dest[i] = src[i];
             for ( ; i < n; i++)
                 dest[i] = '\0';

             return dest;
         }

Well, if someone misunderstood the reverse-engineered description, now
they should have it clear.  Still, as a user, I don't give a shit about
any of the text I've read.  What is this good for?  How do I use it?
Should I use it at all?  This is the 'Linux Programmer’s Manual', as the
page says at the top, but as a programmer, I don't know what to do with
this.  How am I supposed to write programs in a Linux system?

Branden continued with more questions:

| Take some time to draft one, if you haven't already and I missed it.
| Here are some points you might consider.
|
| *  Is delivery of factual information more or less important than
|    advocacy of correct methods and accepted idioms?

I continue with my reply:

Factual information is useless if it can't be interpreted.  The only
thing that matters is that the programmer is able to, well, program.
Of course, the program should be correct, and as safe/simple as
possible/reasonable.

'Accepted' idioms is something that doesn't strike me as an
unconditionally good thing.  Back in the times of Galileo, it was
accepted that the Earth didn't move.  Good documentation might need to
exceptionally reject accepted idioms, even if most of the time they'll
be good.

So, maybe correct methods would be the priority, with accepted idioms
and factual information being secondary to it.

> I think that, in the thread, it was already demonstrated (by Bionic
> having an empty memory.h for a time) that nobody includes <memory.h> on
> its own and expects to see these functions.

This is part of 'factual information', which is only a secondary goal of
this documentation project, as stated above.

The purpose of this change is to help form a mental model of how these
memory and string functions relate to each other, and how they behave.

> (not that Bionic is that
> widely-used; a better test would be checking something like Debian
> codesearch)
> 
> As I've noted before, what header provides what declaration is also
> largely inconsequential.

If it is largely inconsequential, I expect this change shouldn't be as
controversial as it seemed to be.

> So, the only effect of this can be to create new cases where <memory.h>
> is included, for no gain.

I don't agree with the 'for no gain' claim.  But yes, the first part of
the sentence is certainly true.

> It doesn't really matter that memory.h is only slightly less portable,
> IMO.  It is unused, to the point where Autoconf recommends not using it,
> and no longer bothers checking whether 'mem*' functions are also present
> in string.h.

It doesn't really matter that it is unused.  What matters is that it can
be used just fine, and will help --IMO-- understand these functions
better.

> Is suddenly reviving a dead header to copy a few declarations of
> functions well known to be part of string.h into it not just unneeded
> churn?  Especially as program code would (nearly?) always need to do:
> 
>   #include <string.h>
>   #ifdef HAVE_MEMORY_H
>   # include <memory.h>
>   #endif

Are there any systems without <memory.h>?  We've been seeing in this
thread that most systems have it.  Even Microsoft has it.  I bet most
programs can live without that conditional.

I'd say most programs would be portable enough with this:

	#include <string.h>
	#include <memory.h>


Have a lovely day!
Alex

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

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