Man Linux: Main Page and Category List


       Libploticus - C language API library for ploticus


       This simple C language API has all of the funcionality of the  ploticus
       program and is similarly covered by the General Public License.

       libploticus is built using Makefile.

          make clean
          make FPIC=-fPIC libploticus-so

       Applications linking to libploticus may need additional libraries  such
       as  zlib,  but  this depends on exactly how libploticus was built.  The
       specifics are noted in Makefile.  The  externally  visible  symbols  in
       libploticus begin with these prefixes: ploticus, PL, TDH, DT, and GL.

       The header file libploticus.h is required to avoid compiler warnings.

       All functions return 0 when successful, or a non-zero error code.

       As  of version 2.11 multiple sequential plot "jobs" can be performed by
       a single OS process.  Each plot job should begin with a ploticus_init()
       call and terminate with a ploticus_end() call.

       No attempt has been made to write libploticus as thread-safe.

       As  of  version  2.40  script  lines  can no longer be passed as string


       Here’s a simple example (it may be found in ./pltestsuite/api_examp.c)
          int stat;
          char sln[80];
          stat = ploticus_init( "png", "hello.png" );
          stat += ploticus_arg( "-scale", "0.8" );
          if( stat != 0 ) {
            printf( "error in ploticus setup\n" );
          strcpy( sln, "#proc annotate" ); ploticus_execline( sln );
          strcpy( sln, "location: 2 2" ); ploticus_execline( sln );
          strcpy( sln, "text: hello" ); ploticus_execline( sln );
          strcpy( sln, " world." ); ploticus_execline( sln );

Multi-job example

       Another included example, which invokes a series of 25+ plot  jobs,  is
       in ./src/api_test.c To build:

          make clean
          make -f Makefile_api
          make api_test -f Makefile_api
       Then, go to the pltestsuite directory and type: ../src/api_test

libploticus API

       ploticus_init( char *device, char *outfilename )

              Initialize,  read your  ploticus config file if any, and set the
              output device to one of png, gif, x11, svg, jpeg, eps,  or  swf.
              (Not  all  devices  may  be  available, depending on the build.)
              outfilename is the pathname of the file where the result will be
              written.  Example:
                 stat = ploticus_init( "png", "bargraph.png" );
                 if( stat != 0 ) error

       ploticus_arg( name, value )

              Specify  a   pl  command  line  argument.   name  specifies  the
              argument name and value an  argument  value.   If  there  is  no
              argument value, value should be passed as "".  All arguments are
              supported  except  -f,  -prefab,  and  -ver.   If  needed,  this
              function  should  be called after ploticus_init() but before any
              other ploticus function.  It may be  called  as  many  times  as
              necessary.  Example:
                  stat = ploticus_arg( "-debug", "" );
                  stat += ploticus_arg( "-diagfile", "stdout" );
                  stat += ploticus_arg( "-scale", "0.8" );
                  if( stat != 0 ) error

       ploticus_begin( )

              This  function  is  no  longer necessary.  Old code that uses it
              will still be OK.

       ploticus_execline( char *line )

              Interpret one "raw"  ploticus  script  line.   Typically  called
              multiple  times,  allowing  ploticus  scripts  to  be  generated
              programatically.   Script   lines   can   contain   only   these
              directives:  #proc,  #procdef,
               #endproc,   #clone  and   #saveas.  You can’t use set, if/else,
              loops, or other flow-of-control directives (but these  types  of
              things can be handled by your host application).  Further, these
              script lines do  not  undergo  a  variable-evaluation  pass,  so
              variables  cannot  be  referenced,  and select statements (etc.)
              that reference data field names  should  use  one  at  sign  (@)
              instead of two (@@).  If your program needs to access a variable
              that has been set by the ploticus engine, use ploticus_getvar(),
              described below.  The script line may include a trailing newline
              or not.

              An alternative is to use ploticus_execscript() (described below)
              to   execute   an  entire  script  file.   You  can’t  use  both
              ploticus_execline()  and  ploticus_execscript()  in   the   same

              Caution  As  of ploticus version 2.40 string constants cannot be
              passed in this function.  See the  example  in  the  page  intro

       ploticus_execscript( char *scriptfile, int prefabflag )

              Interpret   an   entire    ploticus   script  file  or   prefab.
              scriptfile is the name of the ploticus script file.   There  are
              no  syntax  limitations as with ploticus_execline().  prefabflag
              is 1, then scriptfile is taken to be  a   ploticus  prefab  name
              such  as vbars.  If prefabflag is 0, then scriptfile should be a

              An alternative is to use ploticus_execline()  (described  above)
              to  execute  program-generated "raw" script lines one at a time.
              You can’t use both ploticus_execscript() and ploticus_execline()
              in the same application.

              Example: stat = ploticus_execscript( "vbars", 1 );
              Example:           stat          =          ploticus_execscript(
              "/home/steve/plfiles/", 0 );


              Finish up the graphic result, write it to the output  file,  and
              free up allocated memory.

These functions are also available:

       ploticus_getvar( char *name, char *value )

              Get  the  contents  of ploticus variable name.  Result is copied
              into value.
              Example: stat = ploticus_getvar( "XFINAL", xf );

       ploticus_setvar( char *name, char *value )

              Set ploticus variable name to value.

       gdImagePtr PLGG_getimg( int *width, int *height )

              Returns a pointer to the working GD image, for situations  where
              the  host  application wants to directly issue gd drawing calls.
              The width and height of the working image (in pixels)  are  also
              provided.  Note that the result image is generally cropped based
              on the extent of ploticus drawing actions, before being  written
              out.   Only  valid  in applications built with GD, when ploticus
              was initialized with one of the GD image  devices  (eg.  png  or

                11-MAR-2009   PLOTICUS libploticus(3)