(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 namespaces are set up to clobber each other. More reasonable (from our viewpoint) is to agree on a standard map between namespaces, 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 namespaces 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.