occasionally ranting about programming, tech and life

In this study period one of my courses is “Unix network programming” and first week course assignments were exercises to play around with syscalls and signal handling in C. Because it has been quite a long time since I have done any userland C, I had to (re)read quite a lot of C standard library and Posix manpages. It was not pleasant. Here couple examples:

First documentation about return value in man 3 strcmp:

The strcmp() and strncmp() functions return an integer less than, equal to, or greater than zero if s1 (or the first n bytes thereof) is found, respectively, to be less than, to match, or be greater than s2.

Then first hit from google when searching with strcmp:

Returns an integral value indicating the relationship between the strings:

A zero value indicates that both strings are equal.

A value greater than zero indicates that the first character that does not match has a greater value in str1 than in str2; And a value less than zero indicates the opposite.

Difference between these two is obvious. First even has to be split into multiple lines so it is possible to even get idea what return values might be. Other gives short explanation about value value range and then emphasises most common use case! Sadly it usually gets even worse when you start reading manpages that begins with sentence “This manual page is part of the POSIX Programmer’s Manual”.

For example man 3 sigaction can be nicely described as “wall of text”, which would be mostly unnecessary with very small change. Compare these two:

First unmodified function signature from manpages:

c int sigaction(int sig, const struct sigaction *restrict act, struct sigaction *restrict oact);

Here slightly modified version with quite significantly increased information:

c int sigaction(int sig, const struct sigaction *restrict handler, struct sigaction *restrict old_handler);

I doubt latter leaves any doubt how to use that function for someone who has seen some C interfaces before. That modification was not too many characters! It really seems like that manpages are horrible even for refreshing memory when talking about C stdlib documentation.