head	1.1;
branch	1.1.1;
access;
symbols
	SFIO_1999:1.1.1.1
	SFIO_1998:1.1.1.1
	ATT:1.1.1;
locks; strict;
comment	@.\" @;


1.1
date	98.03.10.22.03.40;	author rse;	state Exp;
branches
	1.1.1.1;
next	;

1.1.1.1
date	98.03.10.22.03.40;	author rse;	state Exp;
branches;
next	;


desc
@@


1.1
log
@Initial revision
@
text
@.de X		\" fixed width font
.ft 5
.it 1 }N
.if !\\$1 \&\\$1 \\$2 \\$3 \\$4 \\$5 \\$6
..
.de XR
.}S 5 1 \& "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.de RX
.}S 1 5 \& "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.de XI
.}S 5 2 \& "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.de IX
.}S 2 5 \& "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.de EX		\" start example
.ta 1i 2i 3i 4i 5i 6i
.PP
.RS 
.PD 0
.ft 5
.nf
..
.de EE		\" end example
.fi
.ft
.PD
.RE
.PP
..
.TH IFFE 1
.SH NAME \" @@(#)iffe.1 (AT&T Labs Research) 1998-03-11
iffe \- C compilation environment feature probe
.SH SYNOPSIS
iffe [\-] \fIop\fP[,\fIop\fP...] [\fIarg\fP[,\fIarg\fP...]] [\fIprereq\fP ...] [: \fIop\fP ...]
.SH DESCRIPTION
.I iffe
is a command interpreter that
probes the C compilation environment for features.
A feature is any file, option or symbol that controls or is controlled by
the C compiler.
.I iffe
tests features by generating and compiling C programs and observing the
behavior of the C compiler.
.PP
.I iffe
commands are line oriented.
Command lines may be
.I iffe
command arguments with the argument
.B :
as the line delimiter or they may be newline terminated lines from input files.
The command syntax is
.EX
\fIop\fP[,\fIop\fP...] [\fIarg\fP[,\fIarg\fP...]] [\fIprereq\fP ...] [\fIblock\fP{ ... }end ...]
.EE
.IR op s
and
.IR arg s
may be combined, separated by commas, to perform a set of
operations on a set of arguments.
.I prerequisites
are compiler options
.RB ( "\-D* \-L*" )
and library
.RB ( \-l* )
and header
.RB ( *.h )
references to be used when applying the
.X op
feature tests.
A
.B \-
arg by itself groups prerequisites into separate feature tests.
The prerequisites before the first
.B \-
be passed to the compiler for all feature tests;
the groups after the first
.B \-
will be attempted in left-to-right order, and the
first group that provides a successful feature test
result terminates the test.
.IR block s
are multi-line code blocks that override or augment the default code
provided by
.IR iffe .
User supplied code blocks should be compatible with the
K&R, ANSI, and C++ C language dialects.
All generated code contains the following at the top to hide
dialect differences:
.EX
#if defined(__STDC__) || defined(__cplusplus) || defined(c_plusplus)
#define _STD_		1
#define _ARG_(x)	x
#define _VOID_		void
#else
#define _STD_		0
#define _ARG_(x)	()
#define _VOID_		char
#endif
#if defined(__cplusplus)
#define _BEGIN_EXTERNS_	extern "C" {
#define _END_EXTERNS_	}
#else
#define _BEGIN_EXTERNS_
#define _END_EXTERNS_
#endif
#define _NIL_(x)	((x)0)
.EE
Also included at the top are macro defintions for tests already performed.
.PP
The output file is a C language header that contains macro defintions,
comments, and other text corresponding to the feature test commands.
.EX
#ifndef _def_\fIname\fP_\fIdirectory\fP
.B ...
#endif
.EE
guards the header from multiple
.XR #include s,
where
.I name
is determined by either the input file name from the
.X run
command,
if any, or the first
.I op
of the first command, and directory is basname component of either the 
.X run
command, if any, or the current working directory.
The output file name is determined in this order:
.TP
\fB\-\fP option
Output is
.BR stdout .
.TP
\f5set out\fP \fIfile\fP
Output is
.IR file .
.TP
\f5run\fP [\fIdirectory/\fP]\fIbase\fP[\fI.suffix\fP]
Output is \f5FEATURE/\fP\fIbase\fP.
.PP
Generated
.I iffe
headers are often referenced in C source as:
.EX
#include "FEATURE/\fIfile\fP"
.EE
The
.IR nmake (1)
base rules contain metarules for generating
.XI FEATURE/ file
from
.XI features/ file [ suffix ],
where
.I suffix
may be omitted,
.XR .c ,
or
.X .sh
(see the
.X run
feature test op below).
Because
.X #include
prerequisites are automatically detected,
.IR nmake (1)
ensures that all prerequisite
.I iffe
headers are generated before compilation.
Note that the directories are deliberately named
.X FEATURE
and
.X features
to keep case-insensitive file systems happy.
.PP
The feature test ops are:
.TP
\f5#\fP \fIcomment\fP
Comment line.
.TP
\f5cmd\fP \fIname\fP
Defines
\f5_cmd_\fP\fIname\fP
if
.I name
is an executable in one of the standard system directories
(\f5/bin, /etc, /usr/bin, /usr/etc, /usr/ucb\fP).
\f5_\fP\fIdirectory\fP\f5_\fP\fIname\fP is defined for
.I directory
in which
.I name
is found (with
.X /
translated to
.XR _ ).
.TP
\f5dat\fP \fIname\fP
Defines
\f5_dat_\fP\fIname\fP
if
.I name
is a data symbol in the C library.
.TP
\f5def\fP \fIname\fP
Equivalent to \f5cmd,dat,hdr,key,lib,mth,sys,typ\fP \fIname\fP.
.TP
\f5hdr\fP \fIname\fP
Defines
\f5_hdr_\fP\fIname\fP
if the header
\f5<\fP\fIname\fP\f5.h>\fP
exists.
.TP
\f5iff\fP \fIname\fP
The generated header \f5#ifndef-#endif\fP macro guard is
\f5_\fP\fIname\fP\f5_H\fP.
.TP
\f5key\fP \fIname\fP
Defines
\f5_key_\fP\fIname\fP
if
.I name
is a reserved word (keyword).
.TP
\f5lcl\fP \fIname\fP
Generates a
.X #include
statement for the local version of either the header
\f5<\fP\fIname\fP\f5.h>\fP
if it exists or the header
\f5<sys/\fP\fIname\fP\f5.h>\fP
if it exists.
Defines
\f5_lcl_\fP\fIname\fP
on success.
.TP
\f5lib\fP \fIname\fP
Defines
\f5_lib_\fP\fIname\fP
if
.I name
is an external symbol in the C library.
.TP
\f5mac\fP \fIname\fP
Defines
\f5_mac_\fP\fIname\fP
if
.I name
is a macro.
.TP
\f5mem\fP \fIstruct.member\fP
Defines
\f5_mem_\fP\fImember\fP\f5_\fP\fIstruct\fP
if
.I member
is a member of the structure
.IR struct .
.TP
\f5mth\fP \fIname\fP
Defines
\f5_mth_\fP\fIname\fP
if
.I name
is an external symbol in the math library.
.TP
\f5nop\fP \fIname\fP
No-op.
.TP
\f5npt\fP \fIname\fP
Defines
\f5_npt_\fP\fIname\fP
if the
.I name
function requires a prototype.
.TP
\f5one\fP \fIheader\fP ...
Generates a
.X #include
statement for the first header found in the
.I header
list.
.TP
\f5run\fP \fIfile\fP
Runs the tests in
.I file
based on
.IR file 's
suffix:
.RS
.TP
\f5.c\fP
.I file
is compiled and executed and the output is copied to the
.I iffe
output file.
.TP
\f5.sh\fP
.I file
is executed as a shell script and the output is copied to the
.I iffe
output file.
.TP
\fIno suffix\fP
.PD 0
.TP
\f5.iff\fP
.TP
\f5.iffe\fP
.I file
contains
.I iffe
commands.
.PD
.RE
.TP
\f5set\fP \fIoption\fP \fIvalue\fP
Sets option values.
The options are
.RS
.TP
\f5cc\fP \fIC-compiler-name\fP [ \fIC-compiler-flags\fP ]
Sets the C compiler name and flags to be used in the feature tests.
.TP
\f5debug\fP \fIlevel\fP
Sets the debug level.
Level 0 inhibits most error messages, level 1 shows compiler messages,
and level 2 traces internal
.I iffe
actions.
.TP
\f5in\fP \fIfile\fP
Sets the input file name to
.IR file .
.I file
must contain
.I iffe
commands.
.TP
\f5out\fP \fIfile\fP
Sets the output file name to
.IR file .
.TP
\f5prototyped\fP
Emits
.X "#pragma prototyped"
at the top of the output file.
See
.IR proto (1).
.TP
\f5pragma\fP \fIpragma-text\fP
Emits
\f5#pragma\fP \fIpragma-text\fP
at the top of the output file.
.TP
\f5shell\fP \fIname\fP
Sets the internal shell name to
.IR name .
Used for debugging Bourne shell compatibility
(otherwise
.I iffe
uses
.I ksh
constructs if available).
.TP
\f5static\fP [ \fIflags\fP ]
Sets the C compiler flags that force static linking.
If not set then 
.I iffe
probes the compiler to determine the flags.
.I iffe
must use static linking (no shared libraries) because on some systems
missing library symbols are only detected when referenced at runtime.
.RE
.TP
\f5sym\fP \fIname\fP
Defines \f5_ary_\fP\fIname\fP if \fIname\fP is an array,
\f5_fun_\fP\fIname\fP if \fIname\fP is a function pointer,
\f5_ptr_\fP\fIname\fP if \fIname\fP is a pointer,
or \f5_reg_\fP\fIname\fP if \fIname\fP is a scalar.
In most cases
.I name
is part of a macro expansion.
.TP
\f5sys\fP \fIname\fP
Defines
\f5_sys_\fP\fIname\fP
if the header
\f5<sys/\fP\fIname\fP\f5.h>\fP
exists.
.TP
\f5tst\fP \fIname\fP
A user defined test on name.
A source block must be supplied.
Defines \f5_\fP\fIname\fP on success.
.TP
\f5typ\fP \fIname\fP
Defines
\f5_typ_\fP\fIname\fP
if
.I name
is a type in any of
.XR "<sys/types.h>, <times.h>, <stddef.h>, <stdlib.h>" .
Any
.X .
characters in
.I name
are translated to space before testing and are translated to
.X _
in the output macro.
.TP
\f5val\fP \fIname\fP
Code block names may be prefixed by
.X no
to invert the test sense.
The block names are:
.TP
.X cat
The block is copied to the output file.
.TP
.X compile
The block is compiled
.RX ( "cc \-c" ).
.TP
.X execute
The block is compiled, linked, and executed.
.X 0
exit status means success.
.TP
.X fail
If the test fails then the fail block text is copied to the output file.
.TP
.X link
The block is compiled and linked
.RX ( "cc \-o" ).
.TP
.X macro
The block is preprocessed
.RX ( cc \-E )
and text bracketed by
.XR "<< " ... " >>"
is copied to the output file.
.TP
.X menu
.RI [ "NOT YET" ]
.TP
.X note
If the test succeeds then the note block is copied to the output as a
.XR "/* " ... " */"
comment.
.TP
.X output
The block is compiled, linked, and executed, and the output
is copied to the output file.
.TP
.X pass
If the test succeeds then the pass block text is copied to the output file.
.TP
.X preprocess
The block is preprocessed
.RX ( cc \-E ).
.TP
.X prompt
.RI [ "NOT YET" ]
.TP
.X run
The block is executed as a shell script and the output is copied to
the output file.
.SH EXAMPLES
The first examples show
.I iffe
command line tests.
The command line is preceded by \f5$\fP and the output follows.
Test if \f5volatile\fP or \f5alias\fP are reserved words:
.EX
$ iffe - key and
/* : : generated by iffe version 1998-01-23 : : */
#ifndef _def_volatile_tmp
#define _def_volatile_tmp       1
#define _key_volatile   1       /* volatile is a reserved keyword */
#endif
.EE
Check for \f5<stdlib.h>\fP or \f5<sys/stdlib.h>\fP:
.EX
$ iffe - hdr,sys stdlib
/* : : generated by iffe version 1998-01-23 : : */
#ifndef _def_stdlib_pp
#define _def_stdlib_pp  1
#define _hdr_stdlib     1       /* #include <stdlib.h> ok */
#endif
.EE
The remaining examples may be placed in a \fIfile\fP.iff and run by:
.EX
$ iffe - run \fIfile\fP.iff
.EE
\f5_tst_errno\fP will be defined \f51\fP if \f5errno\fP can be assigned:
.EX
tst errno errno.h note{ errno can be assigned }end link{
    _BEGIN_EXTERNS_
    extern int errno;
    error() { }
    strerror() { }
    _END_EXTERNS_
    main() { errno = 0; error(); strerror(); return 0; }
}end
.EE
\f5_ptr_dd_buf\fP will be defined \f51\fP if the \f5DIR\fP struct member
\f5dd_buf\fP exists and is a pointer.
The test will be done as many as 3 times, first with \f5<dirent.h>\fP,
next with \f5<ndir.h>\fP, and finally with \f5<sys/dir.h>\fP.
.EX
tst ptr_dd_buf sys/types.h - dirent.h - ndir.h - sys/dir.h compile{
    main() {
        DIR* dirp;
        dirp->dd_buf = 0;
        return 0;
    }
}end
.EE
Due to limitations in the interpreter, tests scripts containing C escapes
must specify \e as \e\e.
This example defines \f5CODE_alert\fP to be the character code value for
\f5'\ea'\fP.
.EX
tst output{
    _BEGIN_EXTERNS_
    extern int printf _ARG_((const char*, ...));
    _END_EXTERNS_
    main() {
        printf("#define CODE_alert    %d\e\en", '\e\ea');
        return 0;
    }
}end
.EE
.SH FILES
.PD 0
.TP 1.5i
\fBfeatures/\fP\fIop\fP\fB.c\fP
C program to compile and run for
.IR op .
Execution output copied to the FEATURE output file.
.TP 1.5i
\fBfeatures/\fP\fIop\fP\fB.sh\fP
.IR sh (1)
script to run for
.IR op .
Execution output copied to the FEATURE output file.
.TP 1.5i
\fBfeatures/\fP\fIop\fP\fB\fP
.I iffe
override tests for
.IR op .
.PD
.SH SEE ALSO
cc(1), cpp(1), nmake(1), probe(1)
.SH AUTHOR
Glenn Fowler	gsf@@research.att.com
.br
K. Phong Vo	kpv@@research.att.com
.br
AT&T Labs Research
@


1.1.1.1
log
@Import of Sfio1998
@
text
@@