(OLD, NEEDS DOCUMENTATION UPDATING)
The argument types given in this manual (PLFLT and PLINT) are typedefs for
the actual argument type. A PLINT is actually a type
long
and should not be changed. A PLFLT can be either a
float
or double
; this choice is made
when the package is installed and on a Unix system (for example) may result
in a PLplot library named libplplot.a
in single
precision and libplplotd.a
in double precision.
These and other constants used by PLplot are defined in the main header file
plplot.h
, which must be included by the user program. This file also
contains all of the function prototypes, machine dependent defines, and
redefinition of the C-language bindings that conflict with the Fortran names
(more on this later). plplot.h
obtains its values for PLFLT, PLINT,
and PLARGS (a macro for conditionally generating prototype argument lists)
from FLOAT (typedef), INT (typedef), and PROTO (macro), respectively.
The latter are defined in the file
chdr.h
. The user is encouraged to use FLOAT, INT, and PROTO in
his/her own code, and modify chdr.h
according to taste. It is not
actually necessary to declare variables as FLOAT and INT except when they
are pointers, as automatic conversion to the right type will otherwise occur
(if using a Standard C compiler; else K&R style automatic promotion will
occur). The only code in plplot.h
that directly depends on these
settings is as follows:
#include "plplot/chdr.h" /* change from chdr.h conventions to plplot ones */ typedef FLOAT PLFLT; typedef INT PLINT; #define PLARGS(a) PROTO(a)
PLplot is capable of being compiled with Standard C (ANSI) mode on or off.
This is toggled via the macro PLSTDC, and set automatically if __STDC__
is defined. If PLSTDC is defined, all functions are prototyped as allowed
under Standard C, and arguments passed exactly as specified in the
prototype. If PLSTDC is not defined, however, function prototypes are
turned off and K&R automatic argument promotion will occur, e.g.
float → double, int → long
.
There is no middle ground! A PLplot
library built with PLSTDC defined will not work (in general) with a program
built with PLSTDC undefined, and vice versa. It is possible in principle to
build a library that will work under both Standard C and K&R compilers
simultaneously (i.e. by duplicating the K&R promotion with the Standard C
prototype), but this seems to violate the spirit of the C standard and can
be confusing. Eventually we will drop support for non-standard C compilers
but for now have adopted this compromise.
In summary, PLplot will work using either a Standard or non-standard C compiler, provided that you :
Include the PLplot main header file plplot.h
.
Make sure all pointer arguments are of the correct type (the compiler should warn you if you forget, so don't worry, be happy).
Do not link a code compiled with PLSTDC defined to a PLplot library compiled with PLSTDC undefined, or vice versa.
Use prototypes whenever possible to reduce type errors.
Note that some Standard C compilers will give warnings when converting a constant function argument to whatever is required by the prototype. These warnings can be ignored.
The one additional complicating factor concerns the use of stub routines to interface with Fortran (see the following section for more explanation). On some systems, the Fortran and C name spaces are set up to clobber each other. More reasonable (from our viewpoint) is to agree on a standard map between name spaces, such as the appending of an underscore to Fortran routine names as is common on many Unix-like systems. The only case where the shared Fortran/C name spaces do any good is when passing a pointer to a like data type, which represents only a small fraction of the cases that need to be handled (which includes constant values passed on the stack, strings, and two-dimensional arrays).
There are several ways to deal with this situation, but the least messy from
a user's perspective is to redefine those PLplot C function names which
conflict with the Fortran-interface stub routines. The actual function
names are the same as those described in this document, but with a
“c_”
prepended. These macro definitions appear in the
plplot.h
header file
and are otherwise harmless. Therefore you can (and should) forget that most
of the names are being redefined to avoid the conflict and simply adhere to
the bindings as described in this manual. Codes written under old versions
of PLplot (previous to 5.0) will require a recompile, however.
For more information on calling PLplot from C, please see the example C
programs (x01c.c
through x19c.c
)
distributed with PLplot.