Re: Call for help on improving the documentation

[Russ Allbery]

Akim Demaille <address@hidden> writes:

> It's a pity that the Autoconf documentation gives hint about broken
> functions only for functions that have their own AC_FUNC_FOO, likewise
> for headers.  If you know a function which should be AC_CHECK_FUNC'd or
> AC_REPLACE_FUNC'd, please, submit so short words which describe where
> they are missing, what kind of bug you can meet, and the best strategy
> to work around these.

Here are the things that I've run into for INN:

 * Calls to inet_ntoa are miscomplied by gcc on IRIX systems due to a
   difference of opinion over the ABI for passing small structs on the
   stack.  I generally just test to see if inet_ntoa works and use my own
   replacement if it doesn't.  Test available if anyone wants it.

 * Many systems have an snprintf that isn't C99-compliant, including glibc
   2.0, Solaris prior to (I think) version 8 (maybe 7), and other systems.
   They return -1 rather than the total number of bytes needed for the
   output if the output was truncated, mishandle snprintf(NULL, 0, ...),
   or both.  Test available if anyone wants it.  I replace the standard
   version one based on address@hidden's (also used in Mutt) with some
   modifications to make it C99-compliant.

 * BSDI has 64-bit off_t but is missing fseeko and ftello.  They're
   possible to implement using fsetpos and fgetpos because fpos_t happens
   to be a typedef for off_t provided you're not using strict ANSI mode.
   Test and functions available.

 * SysV systems (e.g. Solaris) often don't have hstrerror.

 * BSD systems (e.g. BSDI) often don't have pread and pwrite, which can be
   faked provided you don't need atomicity across multiple threads.

 * SysV systems (e.g. Solaris) often don't have setenv, which can be
   implemented in terms of putenv.

 * AIX 4.1 doesn't have seteuid, but you can fake it using setreuid under
   some situations.

 * Ultrix didn't have strtok, IIRC.  I no longer have any Ultrix machines.

 * SunOS didn't have strerror, IIRC.  I no longer have any SunOS
   machines.

 * Really, really old BSD systems don't have the mem* functions.  Probably
   not worrying about except in *extremely* portable code any more.  I'm
   sure pretty much everyone here has seen the standard memcpy in terms of
   bcopy macros and the like, so I won't bother to repeat them.

 * Some really old systems may not have getopt; I'm not sure which ones
   fall into that category.

 * You can fake atexit on SunOS passably well, or so I've been told (not
   tested it myself) with:

   #ifndef HAVE_ATEXIT
   # define atexit(arg) on_exit((arg), 0)
   #endif

 * You can fake strtoul passably well with:

   #ifndef HAVE_STRTOUL
   # define strtoul(a, b, c) strtol((a), (b), (c))
   #endif

 * I'm currently using:

   #include <sys/types.h>
   #ifdef HAVE_STDINT_H
   # include <stdint.h>
   #endif
   #ifdef HAVE_SYS_BITYPES_H
   # include <sys/bitypes.h>
   #endif

   to try to find int32_t, uint32_t, and friends.  You still need to check
   for them since a lot of systems simply don't have them at all (IRIX,
   HP-UX, I think).  I do a bit of preliminary checking of the sizes of
   likely things to find a 4-byte data type and then define int32_t to
   that if needed; macros available if anyone wants them.  For SCO, you
   need to pick them up from sys/bitypes.h instead of creating your own
   because otherwise you'll conflict with the ones in sys/bitypes.h at the
   most annoying times.

 * getpagesize has a whole massive boatload of stuff that you can do to
   find the page size if it isn't found; the standard mmap test has a lot
   of it.

 * There are about six different ways to find the maximum number of open
   file descriptors, but thankfully pretty much everyone has getrlimit
   these days.  (If you don't, fall back on sysconf, then getdtabsize,
   then ulimit, then the #define in sys/param.h, then the POSIX
   guarantee.)  Use getrlimit in preference to sysconf; on Linux, sysconf
   can return the wrong value.

 * You can fake mkfifo with mknod; not sure if enough platforms still
   don't have mkfifo to care much.

 * Signal handling, figuring out if you have sigaction or have to use
   signal, trying to not have to reset your signal handlers in the signal
   handler, etc. is another large blob of stuff that I think most people
   here have seen.

 * statvfs vs. statfs and all its header files to find file system usage.
   GNU du has all this stuff; so does INN's inndf.

 * On really old systems, you may have to use wait3 instead of waitpid.

 * Some systems don't have gethostname and you have to use uname instead,
   or several other odd techniques.

 * Figuring out how to set a socket nonblocking involves various issues;
   in general, you want to avoid using O_NDELAY even if it's available and
   fall back on ioctl with FNDELAY if O_NONBLOCK isn't available.

 * File locking (fcntl vs. flock vs. lockf) is a whole different set of
   issues.

> Patches are definitely the most appreciated means to contribute,

I would, but the quarter is starting next week and I'm *horribly* busy.
Sorry.  :/

> nevertheless, plain text is accepted, we will integrate it into the
> documentation ourselves.

Thanks!

The above-referenced tests will make it into the autoconf macro archive as
soon as 2.50 is released so that I can break them out into separate files
without using automake; I don't have the time right now to do the work
twice or I would have submitted them already.  :/

-- 
Russ Allbery (address@hidden)             <http://www.eyrie.org/~eagle/>