when developing software, it’s always handy to have the manual pages for functions of the standard c library available on the system (e.g. “man strncpy” for example). On Haiku these are missing.
Is there a reason they are not shipped with the system?
We could offer a package for that, I think no one has written one. It may be a good idea to wait until the new 2024 version of POSIX is available.
We would have to complete that with documentation for Haiku extensions, but, usually we do that in HTML format. It would still be nice to have a convenient way to quickly access those from the command line, wether with man or some other tool (personally I would prefer for it to open in a graphical browser with hyperlinks)
What do you think about adding the opengroups docs to the haiku book? (Since those are already in a html format)
It looks like we need permission from them, but it would be a good start to add it there and move towards a build-in Documentation browser in the future. (maybe with a “textmode” too so people who really want it in the commandline can view it there)
I added that package right away, and I’m glad to have it, but in case at some point there are other choices that could be considered – these are not the real man pages I have used for lo these many years. They’re more like discussions.
Consider for example the page for “popen”, which illustrates this format, and also has an editorial error that isn’t unique to the collection, where it documents the calling convention for the wrong function execl(). Compare to “strdup”, which apparently comes from the Linux man pages and illustrates the normal man page format with a SYNOPSIS section etc.
Ideally, man popen should go straight to the point without a half page of disclaimers. They should look like this:
POPEN(3) BSD Library Functions Manual POPEN(3)
NAME
pclose, popen -- process I/O
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <stdio.h>
FILE *
popen(const char *command, const char *mode);
int
pclose(FILE *stream);
DESCRIPTION
The popen() function ``opens'' a process by creating a bidirectional
pope, forking, and invoking the shell. Any streams opened by previous
popen() calls in the parent process are closed in the new child process.
...
Instead, we get
POPEN(3P) POSIX Programmer's Manual POPEN(3P)
PROLOG
This manual page is part of the POSIX Programmer's Manual. This
interface might not be implemented on Haiku. execl(shell path, "sh",
"-c", command, (char *)0);
where shell path is an unspecified pathname for the sh utility.
The popen() function shall ensure that any streams from previous
popen() calls that remain open in the parent process are closed in the
new child process.
The mode argument to popen() is a string that specifies I/O mode:
1. If mode is r, when the child process is started, its file
descriptor STDOUT_FILENO shall be the writable end of the pipe, and
the file descriptor fileno(stream) in the calling process, where
stream is the stream pointer returned by popen(), shall be the
readable end of the pipe.
I mean, it’s great to have this documentation here, but just in case anyone has a line on the real thing.
There is not one single “real thing”. The one we package are from the POSIX specification.
Some C library implementations (glibc for Linux, the BSD ones) also come with their own manpages (where they will also document their own extensions to the base POSIX functions). On Linux you can usually install both.
Since our C library is a mix of implementations from various places, there isn’t a single set of manpages that would have all the info about our implementation. So, if the POSIX ones are not good enough, we’d have to write our own. That’s quite a lot of work to do.
OK, I tracked down the source - I think - and I think part of the problem is a bug in how the Haiku port system is patching the pages.
The popen.3p source is actually a legit man page, with a SYNOPSIS section and everything you need, if you don’t mind the PROLOG blurb at the top.
Here, that blurb says
… The Linux implementation of this interface may differ …
where our port has patched in
… This interface might not be implemented on Haiku.
But it clipped off 863 bytes of the text, losing the SYNOPSIS and starting in midstream with the business about execl.
Some pages seem to escape without harm, and when the top is chopped the amount of damage varies. Looks like we lose everything up to the first blank line in the nroff source. If any - if there’s no blank line, in the source, you get the original Linux version with no patch, e.g. strdup.
So I’d say there’s room for considerable improvement without a massive amount of work, just need to swap in something that works correctly, in place of the Perl code. Whatever it’s doing, I imagine it’s written with a formatted page in mind. Here’s something that would work using awk -
#!/bin/awk -f
{
if (prolog) {
if (/The Linux implementation/) {
print "This interface might not be implemented on Haiku."
skip = 1
} else if (/^\./) {
prolog = 0
print
} else if (!skip) {
print
}
} else if (/\.SH PROLOG/) {
prolog = 1
print
} else
print
}