🚀 go-pugleaf

In article <59881@sun.uucp>, guy@gorodish.Sun.COM (Guy Harris) writes:
> As such, I would avoid all pointer casts except the unavoidable ones (such as
> the -1 to "result of 'sbrk' type" casts).

To anyone that is documenting such functions:

Please be explicit about how to test the return value.

The man pages almost always say "returns -1 ...",
and too often I've seen code that tests the value with
something like:       if ((int)function() == -1) ...

This happens to work sometimes, but it is still wrong.
It should be:         if (function() == (type*)-1) ...

The man page should explicitly mention this cast,
and not assume that it is obvious to everyone.

(To see that it should be obvious, consider the source for
 the function.  It must "return (type*)-1;", so you want to
 compare the result with (type*)-1.  Doing it the other way
 compares -1 with (int)(type*)-1, and there is no guarantee
 that the double cast will result in -1.)