Why stdio manpage, but not stdlib manpage

[decuser]

Why is there a manpage for stdio, but not for stdlib in section 3? Linux has one, but not FreeBSD. Seems odd and is quite annoying as I'm trying to learn more about systems programming and I'd like to know what functions are readily available for writing such programs, even on barebones systems. At this point, I'm crawling around in manpages and doing ls /usr/share/man/man2 and /usr/share/man/man3, but that includes a lot of additional functions that aren't in the base system. Is there a better way to figure out what functions can be relied on in a basic system?

 

[a6h]

I understand your question, but let me share my procedure for exploring C library functionalities with you: lets forget stdlib.h for a moment and and consider stdio.h: I rarely refer to man stdio(3). Generally, I read the header file itself: less /usr/include/stdio.h . Suppose I want to learn more about feof(3): I read the related manpage: man -a feof. Sometime I explore more with different commands e.g. grep -r "eof" /usr/include. But you're right. It's nice to have a section 3 man page for stdlib.h too.

 

[mark_j]

It's odd because NetBSD has one, and has had one for a long time. Mind you, it doesn't tell you much. As vigole says you'll get more information out of the header file.

 

[Bobi B.]

In C there are C standard library, C POSIX library, and myriad of more. While you can dig the details in manpages you better pick a book and start from there.

 

[olli@]

First of all, it should be noted that you can read the standard specification of stdlib.h at the Open Group who maintains the POSIX standard.

Actually I think there isn’t really much need to have a manual page on stdlib.h. Basically it would just list the definitions from that header file, but why would you need that? Usually it’s the other way round: You want to use a library function – say, atexit() or realpath() – and you have to find out which header file you need to include. The atexit(3) and realpath(3) manual pages will tell you that.

Even if you do want to know what’s in stdlib.h – for whatever reason –, well, then type less /usr/include/stdlib.h, or consult the reference standard at the Open Group linked above.

In the case of stdio.h it’s a little different. All the functions in this header file cover a common topic, namely buffered I/O streams, so it makes sense to have a manual page that documents the “big picture” of this. This is what the stdio(3) manual page is good for. Conversely, stdlib.h is just a collection of mostly unrelated functions, so there is no such thing as a big picture. In those cases where some functions are related, they do have a common manual page, for example see the getenv(3) manual page that documents the *env() familiy of functions from stdlib.h.

On a final note, UNIX manual pages are intended to provide a reference documentation. They are not intended as “howto” or tutorial or introduction to a certain topic (although some manual pages go into that direction). If you want that, then look for one on the internet using your search engine of choice. Also, my personal recommendation are the classic books by W. Richard Stevens, such as the renowned APUE (Advanced Programming in the UNIX Environment). If everybody read through that book before touching a C compiler, the bug density of software would be considerably lower.

 

[mark_j]

Looking at the stdio man page, perhaps the OP wants a list of all the functions encompassed by stdlib.h? In which case, there's an opportunity to produce one. This used to be the realm of info, but I'm not sure it's used much in Linux these days. (I personally never liked it).

 

[decuser]

Looking at the stdio man page, perhaps the OP wants a list of all the functions encompassed by stdlib.h? In which case, there's an opportunity to produce one. This used to be the realm of info, but I'm not sure it's used much in Linux these days. (I personally never liked it).

This is exactly what I was looking for. I know that I can grep or vi /usr/include/stdlib.h, but I find the man pages handy. There may be some debate on the utility of such a page, but I gather it's useful enough for some folks to warrant inclusion (Linux, OpenBSD, and so on). I don't like info either.

 

[decuser]

First of all, it should be noted that you can read the standard specification of stdlib.h at the Open Group who maintains the POSIX standard.

The standard is actually the best single source of information related to this topic that I've found. However, it's unwieldy. I like the manpages, they're accessible and they provide just enough information to the programmer to correctly use the functionality they document.

In the course I'm teaching, I am following Bruce Molay's and Stewart Weiss's approach of investigating and emulating existing system tools such as who, ls, cp, etc, and the manpages provide exceptionally good information about both the commands themselves, in section 1, and the system functions that facilitate their functionality in sections 2 and 3. In the course, I am not introducing the source code of the system right away, although, headers are fair game, in the hopes of helping my students have an aha moment when they see the actual code that they have been trying to emulate. The main challenge that I've seen amongst the students has been they have very limited knowledge of what functions are readily available in a base system.

The system that I created for them is a virtual 12.1 install w/4 cpus and 32gb ram on UFS and included source. But, I also installed bash, vim, and a few other programs when I did the installation and I know these added quite a few libraries and functions that wouldn't be present in a bare bones install. I figured that the manpages might list the system functions (in section 2, system calls) and library functions (in section 3, library functions), but that wasn't the case... exactly. Those sections do pretty much contain relevant manpages, but they also contain many, many pages that are not part of the base system. If there's an index for each section, I'm not aware of it.

I'll pass along the tips of reading the classics to my students.

 

[decuser]

Bobi B.'s answer is quite helpful. The C Standard Library and C POSIX Library provide a nice list of headers that document the functions provided by the base environment. It'd be swell if there were a manpage for libc , but at least the lists are concise and as others have pointed out, looking at the includes directly is as good as, if not better than a potentially out of date manpage.

 

[olli@]

I figured that the manpages might list the system functions (in section 2, system calls) and library functions (in section 3, library functions), but that wasn't the case... exactly. Those sections do pretty much contain relevant manpages, but they also contain many, many pages that are not part of the base system. If there's an index for each section, I'm not aware of it.

Well, if you want an index of section 2 pages, then ls /usr/share/man/man2 should do exactly that. Similarly for section 3. The output is huge (section 3 has about 6,000 pages), so you might want to pipe it through less. Note that these commands will only list pages from the base system, because pages from additional packages are installed in /usr/local/man, not /usr/share/man.

By the way, every section has an “intro” manual page, for example intro(2) and intro(3). They give a short introduction of the section and its purpose. They don’t list functions or system calls, though.