9.2.2 Older C application programming interfaces

The current C API (application programming interface), which is thread-safe, is a revision of an older API that is not thread-safe. That is why most functions in the current API have names that end in "_r", which stands for `revised' or `reentrant'.

In the old C API, the Plotter on which an operation was performed is not specified as an argument of the function that was called to perform the operation. Instead, a Plotter is first `selected'. Then the API function is called. pl_openpl was one such function; it opens the currently selected Plotter, i.e., begins a page of graphics.

The old API is deprecated, but is still supported. The four functions in the old API that perform Plotter manipulation have the following semantics.

int pl_newpl (const char *type, FILE *infile, FILE *outfile, FILE *errfile);

Create a Plotter of type type, where type may be "X", "Xdrawable", "png", "pnm", "gif", "svg", "ai", "ps", "fig", "pcl", "hpgl", "regis", "tek", or "meta". The Plotter will have input stream infile, output stream outfile, and error stream errfile. The return value is a `handle': a nonnegative integer by which the newly created Plotter is referred to. A negative return value indicates the Plotter could not be created.

int pl_selectpl (int handle);

Select a Plotter, referred to by its handle, for use. Only one Plotter may be selected at a time. A negative return value indicates the specified Plotter could not be selected. Otherwise, the return value is the handle of the previously selected Plotter.

At startup, a single Metafile Plotter that writes to standard output (with handle `0') is automatically created and selected.

int pl_deletepl (int handle);

Delete a Plotter, specified by its handle. The Plotter must not be selected at the time it is deleted. A negative return value indicates the Plotter could not be deleted.

int pl_parampl (const char *parameter, void *value);

Set the global value of the Plotter parameter parameter to value. The parameter values in effect at the time any Plotter is created will be copied into it.

In the old API, selecting a Plotter with pl_selectpl and setting a value for a Plotter parameter with pl_parampl are global operations. That is why the old API is not thread-safe.

An even older C API omitted the prefix "pl_" from the names of libplot functions. The prefix "pl_" was added in part to distinguish GNU libplot from pre-GNU versions of libplot. If you need to compile code written for very early versions of GNU libplot or for pre-GNU libplot, you should include the header file plotcompat.h. plotcompat.h redefines openpl as pl_openpl, and so forth. See C Compiling and Linking.