5. Existing Tests

These macros test for particular system features that packages might need or want to use. If you need to test for a kind of feature that none of these macros check for, you can probably do it by calling primitive test macros with appropriate arguments (see section 6. Writing Tests).

These tests print messages telling the user which feature they're checking for, and what they find. They cache their results for future configure runs (see section 7.3 Caching Results).

Some of these macros set output variables. See section 4.7 Substitutions in Makefiles, for how to get their values. The phrase "define name" is used below as a shorthand to mean "define C preprocessor symbol name to the value 1". See section 7.1 Defining C Preprocessor Symbols, for how to get those symbol definitions into your program.

5.1 Common Behavior		Macros' standard schemes
5.2 Alternative Programs		Selecting between alternative programs
5.3 Files		Checking for the existence of files
5.4 Library Files		Library archives that might be missing
5.5 Library Functions		C library functions that might be missing
5.6 Header Files		Header files that might be missing
5.7 Declarations		Declarations that may be missing
5.8 Structures		Structures or members that might be missing
5.9 Types		Types that might be missing
5.10 Compilers and Preprocessors		Checking for compiling programs
5.11 System Services		Operating system services
5.12 UNIX Variants		Special kludges for specific UNIX variants

5.1 Common Behavior

Much effort has been expended to make Autoconf easy to learn. The most obvious way to reach this goal is simply to enforce standard interfaces and behaviors, avoiding exceptions as much as possible. Because of history and inertia, unfortunately, there are still too many exceptions in Autoconf; nevertheless, this section describes some of the common rules.

5.1.1 Standard Symbols		Symbols defined by the macros
5.1.2 Default Includes		Includes used by the generic macros

5.1.1 Standard Symbols

All the generic macros that AC_DEFINE a symbol as a result of their test transform their arguments to a standard alphabet. First, argument is converted to upper case and any asterisks (`*') are each converted to `P'. Any remaining characters that are not alphanumeric are converted to underscores.

For instance,

AC_CHECK_TYPES(struct $Expensive*)

will define the symbol `HAVE_STRUCT__EXPENSIVEP' if the check succeeds.

5.1.2 Default Includes

Several tests depend upon a set of header files. Since these headers are not universally available, tests actually have to provide a set of protected includes, such as:

#if TIME_WITH_SYS_TIME # include <sys/time.h> # include <time.h> #else # if HAVE_SYS_TIME_H # include <sys/time.h> # else # include <time.h> # endif #endif

Unless you know exactly what you are doing, you should avoid using unconditional includes, and check the existence of the headers you include beforehand (see section 5.6 Header Files).

Most generic macros provide the following default set of includes:

#include <stdio.h> #if HAVE_SYS_TYPES_H # include <sys/types.h> #endif #if HAVE_SYS_STAT_H # include <sys/stat.h> #endif #if STDC_HEADERS # include <stdlib.h> # include <stddef.h> #else # if HAVE_STDLIB_H # include <stdlib.h> # endif #endif #if HAVE_STRING_H # if !STDC_HEADERS && HAVE_MEMORY_H # include <memory.h> # endif # include <string.h> #endif #if HAVE_STRINGS_H # include <strings.h> #endif #if HAVE_INTTYPES_H # include <inttypes.h> #else # if HAVE_STDINT_H # include <stdint.h> # endif #endif #if HAVE_UNISTD_H # include <unistd.h> #endif

If the default includes are used, then Autoconf will automatically check for the presence of these headers and their compatibility, i.e., you don't need to run AC_HEADERS_STDC, nor check for `stdlib.h' etc.

These headers are checked for in the same order as they are included. For instance, on some systems `string.h' and `strings.h' both exist, but conflict. Then HAVE_STRING_H will be defined, but HAVE_STRINGS_H won't.

5.2 Alternative Programs

These macros check for the presence or behavior of particular programs. They are used to choose between several alternative programs and to decide what to do once one has been chosen. If there is no macro specifically defined to check for a program you need, and you don't need to check for any special properties of it, then you can use one of the general program-check macros.

5.2.1 Particular Program Checks		Special handling to find certain programs
5.2.2 Generic Program and File Checks		How to find other programs

5.2.1 Particular Program Checks

These macros check for particular programs--whether they exist, and in some cases whether they support certain features.

Macro: AC_PROG_AWK

Check for gawk, mawk, nawk, and awk, in that order, and set output variable AWK to the first one that is found. It tries gawk first because that is reported to be the best implementation.

Macro: AC_PROG_INSTALL

Set output variable INSTALL to the path of a BSD compatible install program, if one is found in the current PATH. Otherwise, set INSTALL to `dir/install-sh -c', checking the directories specified to AC_CONFIG_AUX_DIR (or its default directories) to determine dir (see section 4.4 Outputting Files). Also set the variables INSTALL_PROGRAM and INSTALL_SCRIPT to `${INSTALL}' and INSTALL_DATA to `${INSTALL} -m 644'.

This macro screens out various instances of install known not to work. It prefers to find a C program rather than a shell script, for speed. Instead of `install-sh', it can also use `install.sh', but that name is obsolete because some make programs have a rule that creates `install' from it if there is no `Makefile'.

Autoconf comes with a copy of `install-sh' that you can use. If you use AC_PROG_INSTALL, you must include either `install-sh' or `install.sh' in your distribution, or configure will produce an error message saying it can't find them--even if the system you're on has a good install program. This check is a safety measure to prevent you from accidentally leaving that file out, which would prevent your package from installing on systems that don't have a BSD-compatible install program.

If you need to use your own installation program because it has features not found in standard install programs, there is no reason to use AC_PROG_INSTALL; just put the file name of your program into your `Makefile.in' files.

Macro: AC_PROG_LEX

If flex is found, set output variable LEX to `flex' and LEXLIB to `-lfl', if that library is in a standard place. Otherwise set LEX to `lex' and LEXLIB to `-ll'.

Define YYTEXT_POINTER if yytext is a `char *' instead of a `char []'. Also set output variable LEX_OUTPUT_ROOT to the base of the file name that the lexer generates; usually `lex.yy', but sometimes something else. These results vary according to whether lex or flex is being used.

You are encouraged to use Flex in your sources, since it is both more pleasant to use than plain Lex and the C source it produces is portable. In order to ensure portability, however, you must either provide a function yywrap or, if you don't use it (e.g., your scanner has no `#include'-like feature), simply include a `%noyywrap' statement in the scanner's source. Once this done, the scanner is portable (unless you felt free to use nonportable constructs) and does not depend on any library. In this case, and in this case only, it is suggested that you use this Autoconf snippet:

AC_PROG_LEX if test "$LEX" != flex; then LEX="$SHELL $missing_dir/missing flex" AC_SUBST(LEX_OUTPUT_ROOT, lex.yy) AC_SUBST(LEXLIB, '') fi

The shell script missing can be found in the Automake distribution.

To ensure backward compatibility, Automake's AM_PROG_LEX invokes (indirectly) this macro twice, which will cause an annoying but benign "AC_PROG_LEX invoked multiple times" warning. Future versions of Automake will fix this issue, meanwhile, just ignore this message.

Macro: AC_PROG_LN_S

If `ln -s' works on the current file system (the operating system and file system support symbolic links), set the output variable LN_S to `ln -s'; otherwise, if `ln' works, set LN_S to `ln' and otherwise set it to `cp -p'.

If you make a link a directory other than the current directory, its meaning depends on whether `ln' or `ln -s' is used. To safely create links using `$(LN_S)', either find out which form is used and adjust the arguments, or always invoke ln in the directory where the link is to be created.

In other words, it does not work to do:

$(LN_S) foo /x/bar

Instead, do:

(cd /x && $(LN_S) foo bar)

Macro: AC_PROG_RANLIB

Set output variable RANLIB to `ranlib' if ranlib is found, and otherwise to `:' (do nothing).

Macro: AC_PROG_YACC

If bison is found, set output variable YACC to `bison -y'. Otherwise, if byacc is found, set YACC to `byacc'. Otherwise set YACC to `yacc'.

5.2.2 Generic Program and File Checks

These macros are used to find programs not covered by the "particular" test macros. If you need to check the behavior of a program as well as find out whether it is present, you have to write your own test for it (see section 6. Writing Tests). By default, these macros use the environment variable PATH. If you need to check for a program that might not be in the user's PATH, you can pass a modified path to use instead, like this:

AC_PATH_PROG([INETD], [inetd], [/usr/libexec/inetd], [$PATH:/usr/libexec:/usr/sbin:/usr/etc:etc])

You are strongly encouraged to declare the variable passed to AC_CHECK_PROG etc. as precious, See section 7.2 Setting Output Variables, AC_ARG_VAR, for more details.

Macro: AC_CHECK_PROG (variable, prog-to-check-for, value-if-found, [value-if-not-found], [path], [reject])

Check whether program prog-to-check-for exists in PATH. If it is found, set variable to value-if-found, otherwise to value-if-not-found, if given. Always pass over reject (an absolute file name) even if it is the first found in the search path; in that case, set variable using the absolute file name of the prog-to-check-for found that is not reject. If variable was already set, do nothing. Calls AC_SUBST for variable.

Macro: AC_CHECK_PROGS (variable, progs-to-check-for, [value-if-not-found], [path])

Check for each program in the whitespace-separated list progs-to-check-for exists on the PATH. If it is found, set variable to the name of that program. Otherwise, continue checking the next program in the list. If none of the programs in the list are found, set variable to value-if-not-found; if value-if-not-found is not specified, the value of variable is not changed. Calls AC_SUBST for variable.

Macro: AC_CHECK_TOOL (variable, prog-to-check-for, [value-if-not-found], [path])

Like AC_CHECK_PROG, but first looks for prog-to-check-for with a prefix of the host type as determined by AC_CANONICAL_HOST, followed by a dash (see section 11.2 Getting the Canonical System Type). For example, if the user runs `configure --host=i386-gnu', then this call:

AC_CHECK_TOOL(RANLIB, ranlib, :)

sets RANLIB to `i386-gnu-ranlib' if that program exists in PATH, or otherwise to `ranlib' if that program exists in PATH, or to `:' if neither program exists.

Macro: AC_CHECK_TOOLS (variable, progs-to-check-for, [value-if-not-found], [path])

Like AC_CHECK_TOOL, each of the tools in the list progs-to-check-for are checked with a prefix of the host type as determined by AC_CANONICAL_HOST, followed by a dash (see section 11.2 Getting the Canonical System Type). If none of the tools can be found with a prefix, then the first one without a prefix is used. If a tool is found, set variable to the name of that program. If none of the tools in the list are found, set variable to value-if-not-found; if value-if-not-found is not specified, the value of variable is not changed. Calls AC_SUBST for variable.

Macro: AC_PATH_PROG (variable, prog-to-check-for, [value-if-not-found], [path])

Like AC_CHECK_PROG, but set variable to the entire path of prog-to-check-for if found.

Macro: AC_PATH_PROGS (variable, progs-to-check-for, [value-if-not-found], [path])

Like AC_CHECK_PROGS, but if any of progs-to-check-for are found, set variable to the entire path of the program found.

Macro: AC_PATH_TOOL (variable, prog-to-check-for, [value-if-not-found], [path])

Like AC_CHECK_TOOL, but set variable to the entire path of the program if it is found.

5.3 Files

You might also need to check for the existence of files. Before using these macros, ask yourself whether a run time test might not be a better solution. Be aware that, like most Autoconf macros, they test a feature of the host machine, and therefore, they die when cross-compiling.

Macro: AC_CHECK_FILE (file, [action-if-found], [action-if-not-found])

Check whether file file exists on the native system. If it is found, execute action-if-found, otherwise do action-if-not-found, if given.

Macro: AC_CHECK_FILES (files, [action-if-found], [action-if-not-found])

Executes AC_CHECK_FILE once for each file listed in files. Additionally, defines `HAVE_file' (see section 5.1.1 Standard Symbols) for each file found.

5.4 Library Files

The following macros check for the presence of certain C, C++ or Fortran 77 library archive files.

Macro: AC_CHECK_LIB (library, function, [action-if-found], [action-if-not-found], [other-libraries])

Depending on the current language(see section 6.7 Language Choice), try to ensure that the C, C++, or Fortran 77 function function is available by checking whether a test program can be linked with the library library to get the function. library is the base name of the library; e.g., to check for `-lmp', use `mp' as the library argument.

action-if-found is a list of shell commands to run if the link with the library succeeds; action-if-not-found is a list of shell commands to run if the link fails. If action-if-found is not specified, the default action will prepend `-llibrary' to LIBS and define `HAVE_LIBlibrary' (in all capitals). This macro is intended to support building of LIBS in a right-to-left (least-dependent to most-dependent) fashion such that library dependencies are satisfied as a natural side-effect of consecutive tests. Some linkers are very sensitive to library ordering so the order in which LIBS is generated is important to reliable detection of libraries.

If linking with library results in unresolved symbols that would be resolved by linking with additional libraries, give those libraries as the other-libraries argument, separated by spaces: e.g. `-lXt -lX11'. Otherwise, this macro will fail to detect that library is present, because linking the test program will always fail with unresolved symbols. The other-libraries argument should be limited to cases where it is desirable to test for one library in the presence of another that is not already in LIBS.

Macro: AC_SEARCH_LIBS (function, search-libs, [action-if-found], [action-if-not-found], [other-libraries])

Search for a library defining function if it's not already available. This equates to calling AC_TRY_LINK_FUNC first with no libraries, then for each library listed in search-libs.

Add `-llibrary' to LIBS for the first library found to contain function, and run action-if-found. If the function is not found, run action-if-not-found.

If linking with library results in unresolved symbols that would be resolved by linking with additional libraries, give those libraries as the other-libraries argument, separated by spaces: e.g. `-lXt -lX11'. Otherwise, this macro will fail to detect that function is present, because linking the test program will always fail with unresolved symbols.

5.5 Library Functions

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.

5.5.1 Portability of C Functions		Pitfalls with usual functions
5.5.2 Particular Function Checks		Special handling to find certain functions
5.5.3 Generic Function Checks		How to find other functions

5.5.1 Portability of C Functions

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.

snprintf

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).

sprintf

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.

sscanf

On various old systems, e.g. HP-UX 9, sscanf requires that its input string is 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 (see section `Incompatibilities' in Using and Porting the GNU Compiler Collection). Apparently in some cases even having format strings read-only can be a problem.

strnlen

AIX 4.3 provides a broken version which produces funny 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

unlink

The POSIX spec says that unlink causes the given files to be removed only after there are no more open file handles for it. Not all OS's support this behaviour 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.

va_copy

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

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).

Signed >>

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 behaviour. 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.

5.5.2 Particular Function Checks

These macros check for particular C functions--whether they exist, and in some cases how they respond when given certain arguments.

Macro: AC_FUNC_ALLOCA

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

Macro: AC_FUNC_CHOWN

If the chown function is available and works (in particular, it should accept `-1' for uid and gid), define HAVE_CHOWN.

Macro: AC_FUNC_CLOSEDIR_VOID

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.

Macro: AC_FUNC_ERROR_AT_LINE

If the error_at_line function is not found, require an AC_LIBOBJ replacement of `error'.

Macro: AC_FUNC_FNMATCH

If the fnmatch function is available and works (unlike the one on Solaris 2.4), define HAVE_FNMATCH.

Macro: AC_FUNC_FORK

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

Macro: AC_FUNC_FSEEKO

If the fseeko function is available, define HAVE_FSEEKO. Define _LARGEFILE_SOURCE if necessary.

Macro: AC_FUNC_GETGROUPS

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.

Macro: AC_FUNC_GETLOADAVG

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:

1. Define C_GETLOADAVG.

2. Define SVR4, DGUX, UMAX, or UMAX4_3 if on those systems.

3. If `nlist.h' is found, define NLIST_STRUCT.

4. 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.

5. 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.

Macro: AC_FUNC_GETMNTENT

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.

Macro: AC_FUNC_GETPGRP

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.

Macro: AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK

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.

Macro: AC_FUNC_MALLOC

If the malloc works correctly (`malloc (0)' returns a valid pointer), define HAVE_MALLOC.

Macro: AC_FUNC_MEMCMP

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'.

Macro: AC_FUNC_MKTIME

If the mktime function is not available, or does not work correctly, require an AC_LIBOBJ replacement for `mktime'.

Macro: AC_FUNC_MMAP

If the mmap function exists and works correctly, define HAVE_MMAP. Only checks private fixed mapping of already-mapped memory.

Macro: AC_FUNC_OBSTACK

If the obstacks are found, define HAVE_OBSTACK, else require an AC_LIBOBJ replacement for `obstack'.

Macro: AC_FUNC_SELECT_ARGTYPES

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 *'.

Macro: AC_FUNC_SETPGRP

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.

Macro: AC_FUNC_STAT

Macro: AC_FUNC_LSTAT

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.

Macro: AC_FUNC_SETVBUF_REVERSED

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.

Macro: AC_FUNC_STRCOLL

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.

Macro: AC_FUNC_STRTOD

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.

Macro: AC_FUNC_STRERROR_R

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.

Macro: AC_FUNC_STRFTIME

Check for strftime in the `intl' library, for SCO UNIX. Then, if strftime is available, define HAVE_STRFTIME.

Macro: AC_FUNC_STRNLEN

Check for a working strnlen, and ask for its replacement. Some architectures are know to provide broken versions of strnlen, such as AIX 4.3.

Macro: AC_FUNC_UTIME_NULL

If `utime(file, NULL)' sets file's timestamp to the present, define HAVE_UTIME_NULL.

Macro: AC_FUNC_VPRINTF

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.)

5.5.3 Generic Function Checks

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 (see section 6. Writing Tests).

Macro: AC_CHECK_FUNC (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++. (see section 6.7 Language Choice, for more information about selecting the language for checks.)

Macro: AC_CHECK_FUNCS (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.

Macro: AC_LIBOBJ (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.

Macro: AC_LIBSOURCE (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.

Macro: AC_LIBSOURCES (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)

Macro: AC_REPLACE_FUNCS (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.

5.6 Header Files

The following macros check for the presence of certain C header files. If there is no macro specifically defined to check for a header file you need, and you don't need to check for any special properties of it, then you can use one of the general header-file check macros.

5.6.1 Particular Header Checks		Special handling to find certain headers
5.6.2 Generic Header Checks		How to find other headers

5.6.1 Particular Header Checks

These macros check for particular system header files--whether they exist, and in some cases whether they declare certain symbols.

Macro: AC_HEADER_DIRENT

Check for the following header files. For the first one that is found and defines `DIR', define the listed C preprocessor macro:

`dirent.h'	HAVE_DIRENT_H
`sys/ndir.h'	HAVE_SYS_NDIR_H
`sys/dir.h'	HAVE_SYS_DIR_H
`ndir.h'	HAVE_NDIR_H

The directory-library declarations in your source code should look something like the following:

#if HAVE_DIRENT_H # include <dirent.h> # define NAMLEN(dirent) strlen((dirent)->d_name) #else # define dirent direct # define NAMLEN(dirent) (dirent)->d_namlen # if HAVE_SYS_NDIR_H # include <sys/ndir.h> # endif # if HAVE_SYS_DIR_H # include <sys/dir.h> # endif # if HAVE_NDIR_H # include <ndir.h> # endif #endif

Using the above declarations, the program would declare variables to be of type struct dirent, not struct direct, and would access the length of a directory entry name by passing a pointer to a struct dirent to the NAMLEN macro.

This macro also checks for the SCO Xenix `dir' and `x' libraries.

Macro: AC_HEADER_MAJOR

If `sys/types.h' does not define major, minor, and makedev, but `sys/mkdev.h' does, define MAJOR_IN_MKDEV; otherwise, if `sys/sysmacros.h' does, define MAJOR_IN_SYSMACROS.

Macro: AC_HEADER_STAT

If the macros S_ISDIR, S_ISREG et al. defined in `sys/stat.h' do not work properly (returning false positives), define STAT_MACROS_BROKEN. This is the case on Tektronix UTekV, Amdahl UTS and Motorola System V/88.

Macro: AC_HEADER_STDC

Define STDC_HEADERS if the system has ANSI C header files. Specifically, this macro checks for `stdlib.h', `stdarg.h', `string.h', and `float.h'; if the system has those, it probably has the rest of the ANSI C header files. This macro also checks whether `string.h' declares memchr (and thus presumably the other mem functions), whether `stdlib.h' declare free (and thus presumably malloc and other related functions), and whether the `ctype.h' macros work on characters with the high bit set, as ANSI C requires.

Use STDC_HEADERS instead of __STDC__ to determine whether the system has ANSI-compliant header files (and probably C library functions) because many systems that have GCC do not have ANSI C header files.

On systems without ANSI C headers, there is so much variation that it is probably easier to declare the functions you use than to figure out exactly what the system header files declare. Some systems contain a mix of functions ANSI and BSD; some are mostly ANSI but lack `memmove'; some define the BSD functions as macros in `string.h' or `strings.h'; some have only the BSD functions but `string.h'; some declare the memory functions in `memory.h', some in `string.h'; etc. It is probably sufficient to check for one string function and one memory function; if the library has the ANSI versions of those then it probably has most of the others. If you put the following in `configure.ac':

AC_HEADER_STDC AC_CHECK_FUNCS(strchr memcpy)

then, in your code, you can put declarations like this:

#if STDC_HEADERS # include <string.h> #else # if !HAVE_STRCHR # define strchr index # define strrchr rindex # endif char *strchr (), *strrchr (); # if !HAVE_MEMCPY # define memcpy(d, s, n) bcopy ((s), (d), (n)) # define memmove(d, s, n) bcopy ((s), (d), (n)) # endif #endif

If you use a function like memchr, memset, strtok, or strspn, which have no BSD equivalent, then macros won't suffice; you must provide an implementation of each function. An easy way to incorporate your implementations only when needed (since the ones in system C libraries may be hand optimized) is to, taking memchr for example, put it in `memchr.c' and use `AC_REPLACE_FUNCS(memchr)'.

Macro: AC_HEADER_SYS_WAIT

If `sys/wait.h' exists and is compatible with POSIX.1, define HAVE_SYS_WAIT_H. Incompatibility can occur if `sys/wait.h' does not exist, or if it uses the old BSD union wait instead of int to store a status value. If `sys/wait.h' is not POSIX.1 compatible, then instead of including it, define the POSIX.1 macros with their usual interpretations. Here is an example:

#include <sys/types.h> #if HAVE_SYS_WAIT_H # include <sys/wait.h> #endif #ifndef WEXITSTATUS # define WEXITSTATUS(stat_val) ((unsigned)(stat_val) >> 8) #endif #ifndef WIFEXITED # define WIFEXITED(stat_val) (((stat_val) & 255) == 0) #endif

_POSIX_VERSION is defined when `unistd.h' is included on POSIX.1 systems. If there is no `unistd.h', it is definitely not a POSIX.1 system. However, some non-POSIX.1 systems do have `unistd.h'.

The way to check if the system supports POSIX.1 is:

#if HAVE_UNISTD_H # include <sys/types.h> # include <unistd.h> #endif #ifdef _POSIX_VERSION /* Code for POSIX.1 systems. */ #endif

Macro: AC_HEADER_TIME

If a program may include both `time.h' and `sys/time.h', define TIME_WITH_SYS_TIME. On some older systems, `sys/time.h' includes `time.h', but `time.h' is not protected against multiple inclusion, so programs should not explicitly include both files. This macro is useful in programs that use, for example, struct timeval or struct timezone as well as struct tm. It is best used in conjunction with HAVE_SYS_TIME_H, which can be checked for using AC_CHECK_HEADERS(sys/time.h).

#if TIME_WITH_SYS_TIME # include <sys/time.h> # include <time.h> #else # if HAVE_SYS_TIME_H # include <sys/time.h> # else # include <time.h> # endif #endif

Macro: AC_HEADER_TIOCGWINSZ

If the use of TIOCGWINSZ requires `<sys/ioctl.h>', then define GWINSZ_IN_SYS_IOCTL. Otherwise TIOCGWINSZ can be found in `<termios.h>'.

Use:

#if HAVE_TERMIOS_H # include <termios.h> #endif #if GWINSZ_IN_SYS_IOCTL # include <sys/ioctl.h> #endif

5.6.2 Generic Header Checks

These macros are used to find system header files not covered by the "particular" test macros. If you need to check the contents of a header as well as find out whether it is present, you have to write your own test for it (see section 6. Writing Tests).

Macro: AC_CHECK_HEADER (header-file, [action-if-found], [action-if-not-found], [includes = `default-includes'])

If the system header file header-file is usable, execute shell commands action-if-found, otherwise execute action-if-not-found. If you just want to define a symbol if the header file is available, consider using AC_CHECK_HEADERS instead.

The meaning of "usable" depends upon the content of includes:

if includes is empty

check whether

header-file

can be preprocessed without error.

if include is set

Check whether

includes #include <header-file>

can be compiled without error. You may use AC_CHECK_HEADER (and AC_CHECK_HEADERS) to check whether two headers are compatible.

You may pass any kind of dummy content for includes, such as a single space, a comment, to check whether header-file compiles with success.

Macro: AC_CHECK_HEADERS (header-file..., [action-if-found], [action-if-not-found], [includes = `default-includes'])

For each given system header file header-file in the whitespace-separated argument list that exists, define HAVE_header-file (in all capitals). If action-if-found is given, it is additional shell code to execute when one of the header files 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 header files is not found.

Be sure to read the documentation of AC_CHECK_HEADER to understand the influence of includes.

5.7 Declarations

The following macros check for the declaration of variables and functions. If there is no macro specifically defined to check for a symbol you need, then you can use the general macros (see section 5.7.2 Generic Declaration Checks) or, for more complex tests, you may use AC_TRY_COMPILE (see section 6.2 Examining Syntax).

5.7.1 Particular Declaration Checks		Macros to check for certain declarations
5.7.2 Generic Declaration Checks		How to find other declarations

5.7.1 Particular Declaration Checks

The following macros check for certain declarations.

Macro: AC_DECL_SYS_SIGLIST

Define SYS_SIGLIST_DECLARED if the variable sys_siglist is declared in a system header file, either `signal.h' or `unistd.h'.

5.7.2 Generic Declaration Checks

These macros are used to find declarations not covered by the "particular" test macros.

Macro: AC_CHECK_DECL (symbol, [action-if-found], [action-if-not-found], [includes = `default-includes'])

If symbol (a function or a variable) is not declared in includes and a declaration is needed, run the shell commands action-if-not-found, otherwise action-if-found. If no includes are specified, the default includes are used (see section 5.1.2 Default Includes).

This macro actually tests whether it is valid to use symbol as an r-value, not if it is really declared, because it is much safer to avoid introducing extra declarations when they are not needed.

Macro: AC_CHECK_DECLS (symbols, [action-if-found], [action-if-not-found], [includes = `default-includes'])

For each of the symbols (comma-separated list), define HAVE_DECL_symbol (in all capitals) to `1' if symbol is declared, otherwise to `0'. If action-if-not-found is given, it is additional shell code to execute when one of the function declarations is needed, otherwise action-if-found is executed.

This macro uses an m4 list as first argument:

AC_CHECK_DECLS(strdup) AC_CHECK_DECLS([strlen]) AC_CHECK_DECLS([malloc, realloc, calloc, free])

Unlike the other `AC_CHECK_*S' macros, when a symbol is not declared, HAVE_DECL_symbol is defined to `0' instead of leaving HAVE_DECL_symbol undeclared. When you are sure that the check was performed, use HAVE_DECL_symbol just like any other result of Autoconf:

#if !HAVE_DECL_SYMBOL extern char *symbol; #endif

If the test may have not been performed, however, because it is safer not to declare a symbol than to use a declaration that conflicts with the system's one, you should use:

#if defined HAVE_DECL_MALLOC && !HAVE_DECL_MALLOC char *malloc (size_t *s); #endif

You fall into the second category only in extreme situations: either your files may be used without being configured, or they are used during the configuration. In most cases the traditional approach is enough.

5.8 Structures

The following macros check for the presence of certain members in C structures. If there is no macro specifically defined to check for a member you need, then you can use the general structure-member macro (see section 5.8.2 Generic Structure Checks) or, for more complex tests, you may use AC_TRY_COMPILE (see section 6.2 Examining Syntax).

5.8.1 Particular Structure Checks		Macros to check for certain structure members
5.8.2 Generic Structure Checks		How to find other structure members

5.8.1 Particular Structure Checks

The following macros check for certain structures or structure members.

Macro: AC_STRUCT_ST_BLKSIZE

If struct stat contains an st_blksize member, define HAVE_STRUCT_STAT_ST_BLKSIZE. The former name, HAVE_ST_BLKSIZE is to be avoided, as its support will cease in the future. This macro is obsoleted, and should be replaced by

AC_CHECK_MEMBERS([struct stat.st_blksize])

Macro: AC_STRUCT_ST_BLOCKS

If struct stat contains an st_blocks member, define HAVE_STRUCT STAT_ST_BLOCKS. Otherwise, require an AC_LIBOBJ replacement of `fileblocks'. The former name, HAVE_ST_BLOCKS is to be avoided, as its support will cease in the future.

Macro: AC_STRUCT_ST_RDEV

If struct stat contains an st_rdev member, define HAVE_STRUCT_STAT_ST_RDEV. The former name for this macro, HAVE_ST_RDEV, is to be avoided as it will cease to be supported in the future. Actually, even the new macro is obsolete, and should be replaced by:

AC_CHECK_MEMBERS([struct stat.st_rdev])

Macro: AC_STRUCT_TM

If `time.h' does not define struct tm, define TM_IN_SYS_TIME, which means that including `sys/time.h' had better define struct tm.

Macro: AC_STRUCT_TIMEZONE

Figure out how to get the current timezone. If struct tm has a tm_zone member, define HAVE_STRUCT_TM_TM_ZONE (and the obsoleted HAVE_TM_ZONE). Otherwise, if the external array tzname is found, define HAVE_TZNAME.

5.8.2 Generic Structure Checks

These macros are used to find structure members not covered by the "particular" test macros.

Macro: AC_CHECK_MEMBER (aggregate.member, [action-if-found], [action-if-not-found], [includes = `default-includes'])

Check whether member is a member of the aggregate aggregate. If no includes are specified, the default includes are used (see section 5.1.2 Default Includes).

AC_CHECK_MEMBER(struct passwd.pw_gecos,, [AC_MSG_ERROR([We need `passwd.pw_gecos'!])], [#include <pwd.h>])

You can use this macro for sub-members:

AC_CHECK_MEMBER(struct top.middle.bot)

Macro: AC_CHECK_MEMBERS (members, [action-if-found], [action-if-not-found], [includes = `default-includes'])

Check for the existence of each `aggregate.member' of members using the previous macro. When member belongs to aggregate, define HAVE_aggregate_member (in all capitals, with spaces and dots replaced by underscores).

This macro uses m4 lists:

AC_CHECK_MEMBERS([struct stat.st_rdev, struct stat.st_blksize])

5.9 Types

The following macros check for C types, either builtin or typedefs. If there is no macro specifically defined to check for a type you need, and you don't need to check for any special properties of it, then you can use a general type-check macro.

5.9.1 Particular Type Checks		Special handling to find certain types
5.9.2 Generic Type Checks		How to find other types

5.9.1 Particular Type Checks

These macros check for particular C types in `sys/types.h', `stdlib.h' and others, if they exist.

Macro: AC_TYPE_GETGROUPS

Define GETGROUPS_T to be whichever of gid_t or int is the base type of the array argument to getgroups.

Macro: AC_TYPE_MODE_T

Equivalent to `AC_CHECK_TYPE(mode_t, int)'.

Macro: AC_TYPE_OFF_T

Equivalent to `AC_CHECK_TYPE(off_t, long)'.

Macro: AC_TYPE_PID_T

Equivalent to `AC_CHECK_TYPE(pid_t, int)'.

Macro: AC_TYPE_SIGNAL

If `signal.h' declares signal as returning a pointer to a function returning void, define RETSIGTYPE to be void; otherwise, define it to be int.

Define signal handlers as returning type RETSIGTYPE:

RETSIGTYPE hup_handler () { ... }

Macro: AC_TYPE_SIZE_T

Equivalent to `AC_CHECK_TYPE(size_t, unsigned)'.

Macro: AC_TYPE_UID_T

If uid_t is not defined, define uid_t to be int and gid_t to be int.

5.9.2 Generic Type Checks

These macros are used to check for types not covered by the "particular" test macros.

Macro: AC_CHECK_TYPE (type, [action-if-found], [action-if-not-found], [includes = `default-includes'])

Check whether type is defined. It may be a compiler builtin type or defined by the includes (see section 5.1.2 Default Includes).

Macro: AC_CHECK_TYPES (types, [action-if-found], [action-if-not-found], [includes = `default-includes'])

For each type of the types that is defined, define HAVE_type (in all capitals). If no includes are specified, the default includes are used (see section 5.1.2 Default Includes). If action-if-found is given, it is additional shell code to execute when one of the types is found. If action-if-not-found is given, it is executed when one of the types is not found.

This macro uses m4 lists:

AC_CHECK_TYPES(ptrdiff_t) AC_CHECK_TYPES([unsigned long long, uintmax_t])

Autoconf, up to 2.13, used to provide to another version of AC_CHECK_TYPE, broken by design. In order to keep backward compatibility, a simple heuristics, quite safe but not totally, is implemented. In case of doubt, read the documentation of the former AC_CHECK_TYPE, see 15.4 Obsolete Macros.

5.10 Compilers and Preprocessors

All the tests for compilers (AC_PROG_CC, AC_PROG_CXX, AC_PROG_F77) define the output variable EXEEXT based on the output of the 1compiler, typically to the empty string if Unix and `.exe' if Win32 or OS/2.

They also define the output variable OBJEXT based on the output of the compiler, after .c files have been excluded, typically to `o' if Unix, `obj' if Win32.

If the compiler being used does not produce executables, they fail. If the executables can't be run, and cross-compilation is not enabled, they fail too. See section 11. Manual Configuration, for more on support for cross compiling.

5.10.1 Specific Compiler Characteristics		Some portability issues
5.10.2 Generic Compiler Characteristics		Language independent tests
5.10.3 C Compiler Characteristics		Checking its characteristics
5.10.4 C++ Compiler Characteristics		Likewise
5.10.5 Fortran 77 Compiler Characteristics		Likewise

5.10.1 Specific Compiler Characteristics

Some compilers exhibit different behaviors.

Static/Dynamic Expressions

Autoconf relies on a trick to extract one bit of information from the C compiler: using negative array sizes. For instance the following excerpt of a C source demonstrates how to test whether `int's are 4 bytes long:

int main (void) { static int test_array [sizeof (int) == 4 ? 1 : -1]; test_array [0] = 0 return 0; }

To our knowledge, there is a single compiler that does not support this trick: the HP C compilers (the real one, not only the "bundled") on HP-UX 11.00:

$ cc -c -Ae +O2 +Onolimit conftest.c cc: "conftest.c": error 1879: Variable-length arrays cannot \ have static storage.

Autoconf works around this problem by casting sizeof (int) to long before comparing it.

5.10.2 Generic Compiler Characteristics

Macro: AC_CHECK_SIZEOF (type, [unused], [includes = `default-includes'])

Define SIZEOF_type (see section 5.1.1 Standard Symbols) to be the size in bytes of type. If `type' is unknown, it gets a size of 0. If no includes are specified, the default includes are used (see section 5.1.2 Default Includes). If you provide include, make sure to include `stdio.h' which is required for this macro to run.

This macro now works even when cross-compiling. The unused argument was used when cross-compiling.

For example, the call

AC_CHECK_SIZEOF(int *)

defines SIZEOF_INT_P to be 8 on DEC Alpha AXP systems.

5.10.3 C Compiler Characteristics

Macro: AC_PROG_CC ([compiler-search-list])

Determine a C compiler to use. If CC is not already set in the environment, check for gcc and cc, then for other C compilers. Set output variable CC to the name of the compiler found.

This macro may, however, be invoked with an optional first argument which, if specified, must be a space separated list of C compilers to search for. This just gives the user an opportunity to specify an alternative search list for the C compiler. For example, if you didn't like the default order, then you could invoke AC_PROG_CC like this:

AC_PROG_CC(cl egcs gcc cc)

If using the GNU C compiler, set shell variable GCC to `yes'. If output variable CFLAGS was not already set, set it to `-g -O2' for the GNU C compiler (`-O2' on systems where GCC does not accept `-g'), or `-g' for other compilers.

Macro: AC_PROG_CC_C_O

If the C compiler does not accept the `-c' and `-o' options simultaneously, define NO_MINUS_C_MINUS_O. This macro actually tests both the compiler found by AC_PROG_CC, and, if different, the first cc in the path. The test fails if one fails. This macro was created for GNU Make to choose the default C compilation rule.

Macro: AC_PROG_CC_STDC

If the C compiler is not in ANSI C mode by default, try to add an option to output variable CC to make it so. This macro tries various options that select ANSI C on some system or another. It considers the compiler to be in ANSI C mode if it handles function prototypes correctly.

If you use this macro, you should check after calling it whether the C compiler has been set to accept ANSI C; if not, the shell variable ac_cv_prog_cc_stdc is set to `no'. If you wrote your source code in ANSI C, you can make an un-ANSIfied copy of it by using the program ansi2knr, which comes with Automake.

Macro: AC_PROG_CPP

Set output variable CPP to a command that runs the C preprocessor. If `$CC -E' doesn't work, `/lib/cpp' is used. It is only portable to run CPP on files with a `.c' extension.

If the current language is C (see section 6.7 Language Choice), many of the specific test macros use the value of CPP indirectly by calling AC_TRY_CPP, AC_CHECK_HEADER, AC_EGREP_HEADER, or AC_EGREP_CPP.

Some preprocessors don't indicate missing include files by the error status. For such preprocessors an internal variable is set that causes other macros to check the standard error from the preprocessor and consider the test failed if any warnings have been reported.

The following macros check for C compiler or machine architecture features. To check for characteristics not listed here, use AC_TRY_COMPILE (see section 6.2 Examining Syntax) or AC_TRY_RUN (see section 6.4 Checking Run Time Behavior)

Macro: AC_C_BIGENDIAN ([action-if-true], [action-if-false], [action-if-unknown])

If words are stored with the most significant byte first (like Motorola and SPARC CPUs), execute action-if-true. If words are stored with the less significant byte first (like Intel and VAX CPUs), execute action-if-false.

This macro runs a test-case if endianness cannot be determined from the system header files. When cross-compiling the test-case is not run but grep'ed for some magic values. action-if-unknown is executed if the latter case fails to determine the byte sex of the host system.

The default for action-if-true is to define `WORDS_BIGENDIAN'. The default for action-if-false is to do nothing. And finally, the default for action-if-unknown is to abort configure and tell the installer which variable he should preset to bypass this test.

Macro: AC_C_CONST

If the C compiler does not fully support the ANSI C qualifier const, define const to be empty. Some C compilers that do not define __STDC__ do support const; some compilers that define __STDC__ do not completely support const. Programs can simply use const as if every C compiler supported it; for those that don't, the `Makefile' or configuration header file will define it as empty.

Occasionally installers use a C++ compiler to compile C code, typically because they lack a C compiler. This causes problems with const, because C and C++ treat const differently. For example:

const int foo;

is valid in C but not in C++. These differences unfortunately cannot be papered over by defining const to be empty.

If autoconf detects this situation, it leaves const alone, as this generally yields better results in practice. However, using a C++ compiler to compile C code is not recommended or supported, and installers who run into trouble in this area should get a C compiler like GCC to compile their C code.

Macro: AC_C_VOLATILE

If the C compiler does not understand the keyword volatile, define volatile to be empty. Programs can simply use volatile as if every C compiler supported it; for those that do not, the `Makefile' or configuration header will define it as empty.

If the correctness of your program depends on the semantics of volatile, simply defining it to be empty does, in a sense, break your code. However, given that the compiler does not support volatile, you are at its mercy anyway. At least your program will compile, when it wouldn't before.

In general, the volatile keyword is a feature of ANSI C, so you might expect that volatile is available only when __STDC__ is defined. However, Ultrix 4.3's native compiler does support volatile, but does not defined __STDC__.

Macro: AC_C_INLINE

If the C compiler supports the keyword inline, do nothing. Otherwise define inline to __inline__ or __inline if it accepts one of those, otherwise define inline to be empty.

Macro: AC_C_CHAR_UNSIGNED

If the C type char is unsigned, define __CHAR_UNSIGNED__, unless the C compiler predefines it.

Macro: AC_C_LONG_DOUBLE

If the C compiler supports a working long double type with more range or precision than the double type, define HAVE_LONG_DOUBLE.

Macro: AC_C_STRINGIZE

If the C preprocessor supports the stringizing operator, define HAVE_STRINGIZE. The stringizing operator is `#' and is found in macros such as this:

#define x(y) #y

Macro: AC_C_PROTOTYPES

Check to see if function prototypes are understood by the compiler. If so, define PROTOTYPES and __PROTOTYPES. In the case the compiler does not handle prototypes, you should use ansi2knr, which comes with the Automake distribution, to unprotoize function definitions. For function prototypes, you should first define PARAMS:

#ifndef PARAMS # if PROTOTYPES # define PARAMS(protos) protos # else /* no PROTOTYPES */ # define PARAMS(protos) () # endif /* no PROTOTYPES */ #endif

then use it this way:

size_t my_strlen PARAMS ((const char *));

This macro also defines __PROTOTYPES; this is for the benefit of header files that cannot use macros that infringe on user name space.

Macro: AC_PROG_GCC_TRADITIONAL

Add `-traditional' to output variable CC if using the GNU C compiler and ioctl does not work properly without `-traditional'. That usually happens when the fixed header files have not been installed on an old system. Since recent versions of the GNU C compiler fix the header files automatically when installed, this is becoming a less prevalent problem.

5.10.4 C++ Compiler Characteristics

Macro: AC_PROG_CXX ([compiler-search-list])

Determine a C++ compiler to use. Check if the environment variable CXX or CCC (in that order) is set; if so, then set output variable CXX to its value.

Otherwise, if the macro is invoked without an argument, then search for a C++ compiler under the likely names (first g++ and c++ then other names). If none of those checks succeed, then as a last resort set CXX to g++.

This macro may, however, be invoked with an optional first argument which, if specified, must be a space separated list of C++ compilers to search for. This just gives the user an opportunity to specify an alternative search list for the C++ compiler. For example, if you didn't like the default order, then you could invoke AC_PROG_CXX like this:

AC_PROG_CXX(cl KCC CC cxx cc++ xlC aCC c++ g++ egcs gcc)

If using the GNU C++ compiler, set shell variable GXX to `yes'. If output variable CXXFLAGS was not already set, set it to `-g -O2' for the GNU C++ compiler (`-O2' on systems where G++ does not accept `-g'), or `-g' for other compilers.

Macro: AC_PROG_CXXCPP

Set output variable CXXCPP to a command that runs the C++ preprocessor. If `$CXX -E' doesn't work, `/lib/cpp' is used. It is only portable to run CXXCPP on files with a `.c', `.C', or `.cc' extension.

If the current language is C++ (see section 6.7 Language Choice), many of the specific test macros use the value of CXXCPP indirectly by calling AC_TRY_CPP, AC_CHECK_HEADER, AC_EGREP_HEADER, or AC_EGREP_CPP.

Some preprocessors don't indicate missing include files by the error status. For such preprocessors an internal variable is set that causes other macros to check the standard error from the preprocessor and consider the test failed if any warnings have been reported. However, it is not known whether such broken preprocessors exist for C++.

5.10.5 Fortran 77 Compiler Characteristics

Macro: AC_PROG_F77 ([compiler-search-list])

Determine a Fortran 77 compiler to use. If F77 is not already set in the environment, then check for g77 and f77, and then some other names. Set the output variable F77 to the name of the compiler found.

This macro may, however, be invoked with an optional first argument which, if specified, must be a space separated list of Fortran 77 compilers to search for. This just gives the user an opportunity to specify an alternative search list for the Fortran 77 compiler. For example, if you didn't like the default order, then you could invoke AC_PROG_F77 like this:

AC_PROG_F77(fl32 f77 fort77 xlf cf77 g77 f90 xlf90)

If using g77 (the GNU Fortran 77 compiler), then AC_PROG_F77 will set the shell variable G77 to `yes'. If the output variable FFLAGS was not already set in the environment, then set it to `-g -02' for g77 (or `-O2' where g77 does not accept `-g'). Otherwise, set FFLAGS to `-g' for all other Fortran 77 compilers.

Macro: AC_PROG_F77_C_O

Test if the Fortran 77 compiler accepts the options `-c' and `-o' simultaneously, and define F77_NO_MINUS_C_MINUS_O if it does not.

The following macros check for Fortran 77 compiler characteristics. To check for characteristics not listed here, use AC_TRY_COMPILE (see section 6.2 Examining Syntax) or AC_TRY_RUN (see section 6.4 Checking Run Time Behavior), making sure to first set the current language to Fortran 77 AC_LANG(Fortran 77) (see section 6.7 Language Choice).

Macro: AC_F77_LIBRARY_LDFLAGS

Determine the linker flags (e.g. `-L' and `-l') for the Fortran 77 intrinsic and run-time libraries that are required to successfully link a Fortran 77 program or shared library. The output variable FLIBS is set to these flags.

This macro is intended to be used in those situations when it is necessary to mix, e.g. C++ and Fortran 77 source code into a single program or shared library (see section `Mixing Fortran 77 With C and C++' in GNU Automake).

For example, if object files from a C++ and Fortran 77 compiler must be linked together, then the C++ compiler/linker must be used for linking (since special C++-ish things need to happen at link time like calling global constructors, instantiating templates, enabling exception support, etc.).

However, the Fortran 77 intrinsic and run-time libraries must be linked in as well, but the C++ compiler/linker doesn't know by default how to add these Fortran 77 libraries. Hence, the macro AC_F77_LIBRARY_LDFLAGS was created to determine these Fortran 77 libraries.

The macro AC_F77_DUMMY_MAIN or AC_F77_MAIN will probably also be necessary to link C/C++ with Fortran; see below.

Macro: AC_F77_DUMMY_MAIN ([action-if-found], [action-if-not-found])

With many compilers, the Fortran libraries detected by AC_F77_LIBRARY_LDFLAGS provide their own main entry function that initializes things like Fortran I/O, and which then calls a user-provided entry function named e.g. MAIN__ to run the user's program. The AC_F77_DUMMY_MAIN or AC_F77_MAIN macro figures out how to deal with this interaction.

When using Fortran for purely numerical functions (no I/O, etcetera), users often prefer to provide their own main and skip the Fortran library initializations. In this case, however, one may still need to provide a dummy MAIN__ routine in order to prevent linking errors on some systems. AC_F77_DUMMY_MAIN detects whether any such routine is required for linking, and what its name is; the shell variable F77_DUMMY_MAIN holds this name, unknown when no solution was found, and none when no such dummy main is needed.

By default, action-if-found defines F77_DUMMY_MAIN to the name of this routine (e.g. MAIN__) if it is required. [action-if-not-found] defaults to exiting with an error.

In order to link with Fortran routines, the user's C/C++ program should then include the following code to define the dummy main if it is needed:

#ifdef F77_DUMMY_MAIN # ifdef __cplusplus extern "C" # endif int F77_DUMMY_MAIN() { return 1; } #endif

Note that AC_F77_DUMMY_MAIN is called automatically from AC_F77_WRAPPERS; there is generally no need to call it explicitly unless one wants to change the default actions.

Macro: AC_F77_MAIN

As discussed above for AC_F77_DUMMY_MAIN, many Fortran libraries allow you to provide an entry point called e.g. MAIN__ instead of the usual main, which is then called by a main function in the Fortran libraries that initializes things like Fortran I/O. The AC_F77_MAIN macro detects whether it is possible to utilize such an alternate main function, and defines F77_MAIN to the name of the function. (If no alternate main function name is found, F77_MAIN is simply defined to main.)

Thus, when calling Fortran routines from C that perform things like I/O, one should use this macro and name the "main" function F77_MAIN instead of main.

Macro: AC_F77_WRAPPERS

Defines C macros F77_FUNC(name,NAME) and F77_FUNC_(name,NAME) to properly mangle the names of C/C++ identifiers, and identifiers with underscores, respectively, so that they match the name-mangling scheme used by the Fortran 77 compiler.

Fortran 77 is case-insensitive, and in order to achieve this the Fortran 77 compiler converts all identifiers into a canonical case and format. To call a Fortran 77 subroutine from C or to write a C function that is callable from Fortran 77, the C program must explicitly use identifiers in the format expected by the Fortran 77 compiler. In order to do this, one simply wraps all C identifiers in one of the macros provided by AC_F77_WRAPPERS. For example, suppose you have the following Fortran 77 subroutine:

subroutine foobar(x,y) double precision x, y y = 3.14159 * x return end

You would then declare its prototype in C or C++ as:

#define FOOBAR_F77 F77_FUNC(foobar,FOOBAR) #ifdef __cplusplus extern "C" /* prevent C++ name mangling */ #endif void FOOBAR_F77(double *x, double *y);

Note that we pass both the lowercase and uppercase versions of the function name to F77_FUNC so that it can select the right one. Note also that all parameters to Fortran 77 routines are passed as pointers (see section `Mixing Fortran 77 With C and C++' in GNU Automake).

Although Autoconf tries to be intelligent about detecting the name-mangling scheme of the Fortran 77 compiler, there may be Fortran 77 compilers that it doesn't support yet. In this case, the above code will generate a compile-time error, but some other behavior (e.g. disabling Fortran-related features) can be induced by checking whether the F77_FUNC macro is defined.

Now, to call that routine from a C program, we would do something like:

{ double x = 2.7183, y; FOOBAR_F77(&x, &y); }

If the Fortran 77 identifier contains an underscore (e.g. foo_bar), you should use F77_FUNC_ instead of F77_FUNC (with the same arguments). This is because some Fortran 77 compilers mangle names differently if they contain an underscore.

Macro: AC_F77_FUNC (name, [shellvar])

Given an identifier name, set the shell variable shellvar to hold the mangled version name according to the rules of the Fortran 77 linker (see also AC_F77_WRAPPERS). shellvar is optional; if it is not supplied, the shell variable will be simply name. The purpose of this macro is to give the caller a way to access the name-mangling information other than through the C preprocessor as above; for example, to call Fortran routines from some language other than C/C++.

5.11 System Services

The following macros check for operating system services or capabilities.

Macro: AC_PATH_X

Try to locate the X Window System include files and libraries. If the user gave the command line options `--x-includes=dir' and `--x-libraries=dir', use those directories. If either or both were not given, get the missing values by running xmkmf on a trivial `Imakefile' and examining the `Makefile' that it produces. If that fails (such as if xmkmf is not present), look for them in several directories where they often reside. If either method is successful, set the shell variables x_includes and x_libraries to their locations, unless they are in directories the compiler searches by default.

If both methods fail, or the user gave the command line option `--without-x', set the shell variable no_x to `yes'; otherwise set it to the empty string.

Macro: AC_PATH_XTRA

An enhanced version of AC_PATH_X. It adds the C compiler flags that X needs to output variable X_CFLAGS, and the X linker flags to X_LIBS. Define X_DISPLAY_MISSING if X is not available.

This macro also checks for special libraries that some systems need in order to compile X programs. It adds any that the system needs to output variable X_EXTRA_LIBS. And it checks for special X11R6 libraries that need to be linked with before `-lX11', and adds any found to the output variable X_PRE_LIBS.

Macro: AC_SYS_INTERPRETER

Check whether the system supports starting scripts with a line of the form `#! /bin/csh' to select the interpreter to use for the script. After running this macro, shell code in configure.ac can check the shell variable interpval; it will be set to `yes' if the system supports `#!', `no' if not.

Macro: AC_SYS_LARGEFILE

Arrange for \title\{http://www.sas.com/standards/large.file/x_open.20Mar96.html, large-file support}. On some hosts, one must use special compiler options to build programs that can access large files. Append any such options to the output variable CC. Define _FILE_OFFSET_BITS and _LARGE_FILES if necessary.

Large-file support can be disabled by configuring with the `--disable-largefile' option.

If you use this macro, check that your program works even when off_t is longer than long, since this is common when large-file support is enabled. For example, it is not correct to print an arbitrary off_t value X with printf ("%ld", (long) X).

Macro: AC_SYS_LONG_FILE_NAMES

If the system supports file names longer than 14 characters, define HAVE_LONG_FILE_NAMES.

Macro: AC_SYS_POSIX_TERMIOS

Check to see if POSIX termios headers and functions are available on the system. If so, set the shell variable am_cv_sys_posix_termios to `yes'. If not, set the variable to `no'.

5.12 UNIX Variants

The following macros check for certain operating systems that need special treatment for some programs, due to exceptional oddities in their header files or libraries. These macros are warts; they will be replaced by a more systematic approach, based on the functions they make available or the environments they provide.

Macro: AC_AIX

If on AIX, define _ALL_SOURCE. Allows the use of some BSD functions. Should be called before any macros that run the C compiler.

Macro: AC_ISC_POSIX

For INTERACTIVE UNIX (ISC), add `-lcposix' to output variable LIBS if necessary for POSIX facilities. Call this after AC_PROG_CC and before any other macros that use POSIX interfaces. INTERACTIVE UNIX is no longer sold, and Sun says that they will drop support for it on 2006-07-23, so this macro is becoming obsolescent.

Macro: AC_MINIX

If on Minix, define _MINIX and _POSIX_SOURCE and define _POSIX_1_SOURCE to be 2. This allows the use of POSIX facilities. Should be called before any macros that run the C compiler.