The following macros check for particular C library functions. If there is no macro specifically defined to check for a function you need, and you don't need to check for any special properties of it, then you can use one of the general function-check macros.
Most usual functions can either be missing, or be buggy, or be limited on some architectures. This section tries to make an inventory of these portability issues. By definition, this list will always require additions. Please help us keeping it as complete as possible.
The ISO C99 standard says that if the output array isn't big enough and if no other errors occur, snprintf and vsnprintf truncate the output and return the number of bytes that ought to have been produced. Some older systems return the truncated length (e.g., GNU C Library 2.0.x or IRIX 6.5), some a negative value (e.g., earlier GNU C Library versions), and some the buffer length without truncation (e.g., 32-bit Solaris 7). Also, some buggy older systems ignore the length and overrun the buffer (e.g., 64-bit Solaris 7).
The ISO C standard says sprintf and vsprintf return the number of bytes written, but on some old systems (SunOS 4 for instance) they return the buffer pointer instead.
On various old systems, e.g. HP-UX 9, sscanf requires that its input string be writable (though it doesn't actually change it). This can be a problem when using gcc since it normally puts constant strings in read-only memory (). Apparently in some cases even having format strings read-only can be a problem.
AIX 4.3 provides a broken version which produces the following results:
strnlen ("foobar", 0) = 0 strnlen ("foobar", 1) = 3 strnlen ("foobar", 2) = 2 strnlen ("foobar", 3) = 1 strnlen ("foobar", 4) = 0 strnlen ("foobar", 5) = 6 strnlen ("foobar", 6) = 6 strnlen ("foobar", 7) = 6 strnlen ("foobar", 8) = 6 strnlen ("foobar", 9) = 6
The posix spec says that unlink causes the given file to be removed only after there are no more open file handles for it. Not all OS's support this behavior though. So even on systems that provide unlink, you cannot portably assume it is OK to call it on files that are open. For example, on Windows 9x and ME, such a call would fail; on DOS it could even lead to file system corruption, as the file might end up being written to after the OS has removed it.
The ISO C99 standard provides va_copy for copying va_list variables. It may be available in older environments too, though possibly as __va_copy (eg. gcc in strict C89 mode). These can be tested with #ifdef. A fallback to memcpy (dst, src, sizeof(va_list)) will give maximum portability.
va_list is not necessarily just a pointer. It can be a struct (eg. gcc on Alpha), which means NULL is not portable. Or it can be an array (eg. gcc in some PowerPC configurations), which means as a function parameter it can be effectively call-by-reference and library routines might modify the value back in the caller (eg. vsnprintf in the GNU C Library 2.1).
Normally the C right shift of a signed type replicates the high bit, giving a so-called "arithmetic" shift. But care should be taken since the ISO C standard doesn't require that behavior. On those few processors without a native arithmetic shift (for instance Cray vector systems) zero bits may be shifted in, the same as a shift of an unsigned type.
These macros check for particular C functions--whether they exist, and in some cases how they respond when given certain arguments.
function>AC_FUNC_ALLOCA/function> Check how to get alloca. Tries to get a builtin version by checking for alloca.h or the predefined C preprocessor macros __GNUC__ and _AIX. If this macro finds alloca.h, it defines HAVE_ALLOCA_H.
If those attempts fail, it looks for the function in the standard C library. If any of those methods succeed, it defines HAVE_ALLOCA. Otherwise, it sets the output variable ALLOCA to alloca.o and defines C_ALLOCA (so programs can periodically call alloca(0) to garbage collect). This variable is separate from LIBOBJS so multiple programs can share the value of ALLOCA without needing to create an actual library, in case only some of them use the code in LIBOBJS.
This macro does not try to get alloca from the System V R3 libPW or the System V R4 libucb because those libraries contain some incompatible functions that cause trouble. Some versions do not even contain alloca or contain a buggy version. If you still want to use their alloca, use ar to extract alloca.o from them instead of compiling alloca.c.
Source files that use alloca should start with a piece of code like the following, to declare it properly. In some versions of AIX, the declaration of alloca must precede everything else except for comments and preprocessor directives. The #pragma directive is indented so that pre-ansi C compilers will ignore it, rather than choke on it.
/* AIX requires this to be the first thing in the file. */ #ifndef __GNUC__ # if HAVE_ALLOCA_H # include alloca.h # else # ifdef _AIX #pragma alloca # else # ifndef alloca /* predefined by HP cc +Olibcalls */ char *alloca (); # endif # endif # endif #endif
function>AC_FUNC_CHOWN/function> If the chown function is available and works (in particular, it should accept -1 for uid and gid), define HAVE_CHOWN.
function>AC_FUNC_CLOSEDIR_VOID/function> If the closedir function does not return a meaningful value, define CLOSEDIR_VOID. Otherwise, callers ought to check its return value for an error indicator.
function>AC_FUNC_ERROR_AT_LINE/function> If the error_at_line function is not found, require an AC_LIBOBJ replacement of error.
function>AC_FUNC_FNMATCH/function> If the fnmatch function is available and works (unlike the one on Solaris 2.4), define HAVE_FNMATCH.
function>AC_FUNC_FORK/function> This macro checks for the fork and vfork functions. If a working fork is found, define HAVE_WORKING_FORK. This macro checks whether fork is just a stub by trying to run it.
If vfork.h is found, define HAVE_VFORK_H. If a working vfork is found, define HAVE_WORKING_VFORK. Otherwise, define vfork to be fork for backward compatibility with previous versions of autoconf. This macro checks for several known errors in implementations of vfork and considers the system to not have a working vfork if it detects any of them. It is not considered to be an implementation error if a child's invocation of signal modifies the parent's signal handler, since child processes rarely change their signal handlers.
Since this macro defines vfork only for backward compatibility with previous versions of autoconf you're encouraged to define it yourself in new code:
#if !HAVE_WORKING_VFORK # define vfork fork #endif
function>AC_FUNC_FSEEKO/function> If the fseeko function is available, define HAVE_FSEEKO. Define _LARGEFILE_SOURCE if necessary.
function>AC_FUNC_GETGROUPS/function> If the getgroups function is available and works (unlike on Ultrix 4.3, where getgroups (0, 0) always fails), define HAVE_GETGROUPS. Set GETGROUPS_LIBS to any libraries needed to get that function. This macro runs AC_TYPE_GETGROUPS.
function>AC_FUNC_GETLOADAVG/function> Check how to get the system load averages. If the system has the getloadavg function, define HAVE_GETLOADAVG, and set GETLOADAVG_LIBS to any libraries needed to get that function. Also add GETLOADAVG_LIBS to LIBS.
Otherwise, require an AC_LIBOBJ replacement (getloadavg.c) of getloadavg, and possibly define several other C preprocessor macros and output variables:
Define C_GETLOADAVG.
Define SVR4, DGUX, UMAX, or UMAX4_3 if on those systems.
If nlist.h is found, define NLIST_STRUCT.
If struct nlist has an n_un.n_name member, define HAVE_STRUCT_NLIST_N_UN_N_NAME. The obsolete symbol NLIST_NAME_UNION is still defined, but do not depend upon it.
Programs may need to be installed setgid (or setuid) for getloadavg to work. In this case, define GETLOADAVG_PRIVILEGED, set the output variable NEED_SETGID to true (and otherwise to false), and set KMEM_GROUP to the name of the group that should own the installed program.
function>AC_FUNC_GETMNTENT/function> Check for getmntent in the sun, seq, and gen libraries, for Irix 4, PTX, and Unixware, respectively. Then, if getmntent is available, define HAVE_GETMNTENT.
function>AC_FUNC_GETPGRP/function> Define GETPGRP_VOID if it is an error to pass 0 to getpgrp; this is the posix.1 behavior. On older BSD systems, you must pass 0 to getpgrp, as it takes an argument and behaves like posix.1's getpgid.
#if GETPGRP_VOID pid = getpgrp (); #else pid = getpgrp (0); #endif
This macro does not check whether getpgrp exists at all; if you need to work in that situation, first call AC_CHECK_FUNC for getpgrp.
function>AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK/function> If link is a symbolic link, then lstat should treat link/ the same as link/.. However, many older lstat implementations incorrectly ignore trailing slashes.
It is safe to assume that if lstat incorrectly ignores trailing slashes, then other symbolic-link-aware functions like unlink and unlink also incorrectly ignore trailing slashes.
If lstat behaves properly, define LSTAT_FOLLOWS_SLASHED_SYMLINK, otherwise require an AC_LIBOBJ replacement of lstat.
function>AC_FUNC_MALLOC/function> If the malloc works correctly (malloc (0) returns a valid pointer), define HAVE_MALLOC.
function>AC_FUNC_MEMCMP/function> If the memcmp function is not available, or does not work on 8-bit data (like the one on SunOS 4.1.3), or fails when comparing 16 bytes or more and with at least one buffer not starting on a 4-byte boundary (such as the one on NeXT x86 OpenStep), require an AC_LIBOBJ replacement for memcmp.
function>AC_FUNC_MKTIME/function> If the mktime function is not available, or does not work correctly, require an AC_LIBOBJ replacement for mktime.
function>AC_FUNC_MMAP/function> If the mmap function exists and works correctly, define HAVE_MMAP. Only checks private fixed mapping of already-mapped memory.
function>AC_FUNC_OBSTACK/function> If the obstacks are found, define HAVE_OBSTACK, else require an AC_LIBOBJ replacement for obstack.
function>AC_FUNC_SELECT_ARGTYPES/function> Determines the correct type to be passed for each of the select function's arguments, and defines those types in SELECT_TYPE_ARG1, SELECT_TYPE_ARG234, and SELECT_TYPE_ARG5 respectively. SELECT_TYPE_ARG1 defaults to int, SELECT_TYPE_ARG234 defaults to int *, and SELECT_TYPE_ARG5 defaults to struct timeval *.
function>AC_FUNC_SETPGRP/function> If setpgrp takes no argument (the posix.1 version), define SETPGRP_VOID. Otherwise, it is the bsd version, which takes two process IDs as arguments. This macro does not check whether setpgrp exists at all; if you need to work in that situation, first call AC_CHECK_FUNC for setpgrp.
function>AC_FUNC_STAT/function> function>AC_FUNC_LSTAT/function> Determine whether stat or lstat have the bug that it succeeds when given the zero-length file name argument. The stat and lstat from SunOS 4.1.4 and the Hurd (as of 1998-11-01) do this.
If it does, then define HAVE_STAT_EMPTY_STRING_BUG (or HAVE_LSTAT_EMPTY_STRING_BUG) and ask for an AC_LIBOBJ replacement of it.
function>AC_FUNC_SETVBUF_REVERSED/function> If setvbuf takes the buffering type as its second argument and the buffer pointer as the third, instead of the other way around, define SETVBUF_REVERSED.
function>AC_FUNC_STRCOLL/function> If the strcoll function exists and works correctly, define HAVE_STRCOLL. This does a bit more than AC_CHECK_FUNCS(strcoll), because some systems have incorrect definitions of strcoll that should not be used.
function>AC_FUNC_STRTOD/function> If the strtod function does not exist or doesn't work correctly, ask for an AC_LIBOBJ replacement of strtod. In this case, because strtod.c is likely to need pow, set the output variable POW_LIB to the extra library needed.
function>AC_FUNC_STRERROR_R/function> If strerror_r is available, define HAVE_STRERROR_R, and if it is declared, define HAVE_DECL_STRERROR_R. If it returns a char * message, define STRERROR_R_CHAR_P; otherwise it returns an int error number. The Thread-Safe Functions option of posix-200x requires strerror_r to return int, but many systems (including, for example, version 2.2.4 of the GNU C Library) return a char * value that is not necessarily equal to the buffer argument.
function>AC_FUNC_STRFTIME/function> Check for strftime in the intl library, for SCO unix. Then, if strftime is available, define HAVE_STRFTIME.
function>AC_FUNC_STRNLEN/function> If the strnlen function is not available, or is buggy (like the one from AIX 4.3), require an AC_LIBOBJ replacement for it.
function>AC_FUNC_UTIME_NULL/function> If utime(file, NULL) sets file's timestamp to the present, define HAVE_UTIME_NULL.
function>AC_FUNC_VPRINTF/function> If vprintf is found, define HAVE_VPRINTF. Otherwise, if _doprnt is found, define HAVE_DOPRNT. (If vprintf is available, you may assume that vfprintf and vsprintf are also available.)
These macros are used to find functions not covered by the "particular" test macros. If the functions might be in libraries other than the default C library, first call AC_CHECK_LIB for those libraries. If you need to check the behavior of a function as well as find out whether it is present, you have to write your own test for it (Chapter 7).
function>AC_CHECK_FUNC/function> (function, [action-if-found], [action-if-not-found]) If C function function is available, run shell commands action-if-found, otherwise action-if-not-found. If you just want to define a symbol if the function is available, consider using AC_CHECK_FUNCS instead. This macro checks for functions with C linkage even when AC_LANG(C++) has been called, since C is more standardized than C++. (the section called “Language Choice”, for more information about selecting the language for checks.)
function>AC_CHECK_FUNCS/function> (function…, [action-if-found], [action-if-not-found]) For each function in the whitespace-separated argument list, define HAVE_function (in all capitals) if it is available. If action-if-found is given, it is additional shell code to execute when one of the functions is found. You can give it a value of break to break out of the loop on the first match. If action-if-not-found is given, it is executed when one of the functions is not found.
Autoconf follows a philosophy that was formed over the years by those who have struggled for portability: isolate the portability issues in specific files, and then program as if you were in a posix environment. Some functions may be missing or unfixable, and your package must be ready to replace them.
Use the first three of the following macros to specify a function to be replaced, and the last one (AC_REPLACE_FUNCS) to check for and replace the function if needed.
function>AC_LIBOBJ/function> (function) Specify that function.c must be included in the executables to replace a missing or broken implementation of function.
Technically, it adds function.$ac_objext to the output variable LIBOBJS and calls AC_LIBSOURCE for function.c. You should not directly change LIBOBJS, since this is not traceable.
function>AC_LIBSOURCE/function> (file) Specify that file might be needed to compile the project. If you need to know what files might be needed by a configure.ac, you should trace AC_LIBSOURCE. file must be a literal.
This macro is called automatically from AC_LIBOBJ, but you must call it explicitly if you pass a shell variable to AC_LIBOBJ. In that case, since shell variables cannot be traced statically, you must pass to AC_LIBSOURCE any possible files that the shell variable might cause AC_LIBOBJ to need. For example, if you want to pass a variable $foo_or_bar to AC_LIBOBJ that holds either "foo" or "bar", you should do:
AC_LIBSOURCE(foo.c) AC_LIBSOURCE(bar.c) AC_LIBOBJ($foo_or_bar)
There is usually a way to avoid this, however, and you are encouraged to simply call AC_LIBOBJ with literal arguments.
Note that this macro replaces the obsolete AC_LIBOBJ_DECL, with slightly different semantics: the old macro took the function name, e.g. foo, as its argument rather than the file name.
function>AC_LIBSOURCES/function> (files) Like AC_LIBSOURCE, but accepts one or more files in a comma-separated M4 list. Thus, the above example might be rewritten:
AC_LIBSOURCES([foo.c, bar.c]) AC_LIBOBJ($foo_or_bar)
function>AC_REPLACE_FUNCS/function> (function…) Like AC_CHECK_FUNCS, but uses AC_LIBOBJ(function) as action-if-not-found. You can declare your replacement function by enclosing the prototype in #if !HAVE_function. If the system has the function, it probably declares it in a header file you should be including, so you shouldn't redeclare it lest your declaration conflict.