Hi Arsen, > Date: 2026-08-04 17:49:43+0200 > From: Arsen Arsenović > [...] > > man/man3/: Put first in SYNOPSIS, then comment about > > > > This is a compromise between the fact that 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 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" | 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 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 > 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 > #ifdef HAVE_MEMORY_H > # include > #endif Are there any systems without ? 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 #include Have a lovely day! Alex --