gnuplot_i.h File Reference

C interface to gnuplot. More...

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>
#include <stdarg.h>
#include <fcntl.h>
#include <time.h>

Go to the source code of this file.

Data Structures
struct	_GNUPLOT_CTRL_
struct	_GNUPLOT_POINT_

Macros
#define	GP_MAX_TMP_FILES   64
#define	GP_TMP_NAME_SIZE   512

Typedefs
typedef struct _GNUPLOT_CTRL_	gnuplot_ctrl
	gnuplot session handle (opaque type).
typedef struct _GNUPLOT_POINT_	gnuplot_point

Functions
char *	gnuplot_get_program_path (char *pname)
	Find out where a command lives in your PATH.
gnuplot_ctrl *	gnuplot_init (void)
	Opens up a gnuplot session, ready to receive commands.
void	gnuplot_close (gnuplot_ctrl *handle)
	Closes a gnuplot session previously opened by gnuplot_init()
void	gnuplot_cmd (gnuplot_ctrl *handle, char *cmd,...)
	Sends a command to an active gnuplot session.
void	gnuplot_prompt (gnuplot_ctrl *handle)
	Read commands from standard in and send them to gnuplot handle.
void	gnuplot_setstyle (gnuplot_ctrl *h, char *plot_style)
	Change the plotting style of a gnuplot session.
void	gnuplot_setaxes (gnuplot_ctrl *h, char *plot_axes)
	Change the plotting axes of a gnuplot session.
void	gnuplot_setterm (gnuplot_ctrl *h, char *terminal)
	Change the terminal of a gnuplot session.
void	gnuplot_set_xlabel (gnuplot_ctrl *h, char *label)
	Sets the x label of a gnuplot session.
void	gnuplot_set_ylabel (gnuplot_ctrl *h, char *label)
	Sets the y label of a gnuplot session.
void	gnuplot_set_zlabel (gnuplot_ctrl *h, char *label)
	Sets the z label of a gnuplot session.
void	gnuplot_resetplot (gnuplot_ctrl *h)
	Resets a gnuplot session (next plot will erase previous ones).
void	gnuplot_plot_x (gnuplot_ctrl *handle, double *d, int n, char *title)
	Plots a 2d graph from a list of doubles.
void	gnuplot_plot_xy (gnuplot_ctrl *handle, double *x, double *y, int n, char *title)
	Plot a 2d graph from a list of points.
int	gnuplot_splot (gnuplot_ctrl *handle, double *x, double *y, double *z, int n, char *title)
	Plot a 3d graph from a list of points.
int	gnuplot_splot_grid (gnuplot_ctrl *handle, double *points, int rows, int cols, char *title)
	Plot a 3d graph from a grid of points.
int	gnuplot_contour_plot (gnuplot_ctrl *handle, double *x, double *y, double *z, int nx, int ny, char *title)
	Plot contours from a list of points.
int	gnuplot_splot_obj (gnuplot_ctrl *handle, void *obj, void(*getPoint)(void *, gnuplot_point *, int, int), int n, char *title)
	Plot a 3d graph using callback functions to return the points.
int	gnuplot_plot_obj_xy (gnuplot_ctrl *handle, void *obj, void(*getPoint)(void *, gnuplot_point *, int, int), int n, char *title)
void	gnuplot_plot_once (char *title, char *style, char *label_x, char *label_y, double *x, double *y, int n)
	Open a new session, plot a signal, close the session.
void	gnuplot_plot_slope (gnuplot_ctrl *handle, double a, double b, char *title)
	Plot a slope on a gnuplot session.
void	gnuplot_plot_equation (gnuplot_ctrl *h, char *equation, char *title)
	Plot a curve of given equation y=f(x).
void	gnuplot_hardcopy (gnuplot_ctrl *h, char *filename)
	Save a graph as a postscript file on the hard disk.
void	gnuplot_hardcopy_colour (gnuplot_ctrl *h, char *filename)
	Save a graph in colour as a postscript file on the hard disk.

Detailed Description

C interface to gnuplot.

Author

N. Devillard

Date

Sep 1998, Oct 2004, Sept 2005, Nov 2005, Apr 2006, Dec 2009

Version

Revision:

1.11.4

gnuplot is a freely available, command-driven graphical display tool for Unix. It compiles and works quite well on a number of Unix flavours as well as other operating systems. The following module enables sending display requests to gnuplot through simple C calls.

set_zlabel, splot and hardcopy_colour functions are based on existing code, and added on 12 October 2004 by Robert Bradley (rober.nosp@m.t.br.nosp@m.adley.nosp@m.@mer.nosp@m.ton.o.nosp@m.x.ac.nosp@m..uk). OS X and limited Windows support added 11-13th September 2005 - on Windows, pgnuplot and wgnuplot.exe must be in the current directory.

gnuplot_splot_grid added 2nd April 2006 (R. Bradley).

gnuplot_set_axes ported from modifications to original 1.11 script Dec 2009 (R. Higgins)

gnuplot_prompt Apr 2010 (R. Higgins)

Definition in file gnuplot_i.h.

Macro Definition Documentation

#define GP_MAX_TMP_FILES   64

Maximal number of simultaneous temporary files

Definition at line 52 of file gnuplot_i.h.

#define GP_TMP_NAME_SIZE   512

Maximal size of a temporary file name

Definition at line 54 of file gnuplot_i.h.

Typedef Documentation

gnuplot_ctrl

gnuplot session handle (opaque type).

This structure holds all necessary information to talk to a gnuplot session. It is built and returned by gnuplot_init() and later used by all functions in this module to communicate with the session, then meant to be closed by gnuplot_close().

This structure is meant to remain opaque, you normally do not need to know what is contained in there.

typedef struct _GNUPLOT_POINT_ gnuplot_point

Function Documentation

void gnuplot_close

(

gnuplot_ctrl *

handle

)

Closes a gnuplot session previously opened by gnuplot_init()

Parameters

handle

Gnuplot session control handle.

Returns

void

Kills the child PID and deletes all opened temporary files. It is mandatory to call this function to close the handle, otherwise temporary files are not cleaned and child process might survive.

Definition at line 261 of file gnuplot_i.c.

void gnuplot_cmd	(	gnuplot_ctrl *	handle,
		char *	cmd,
			...
	)

Sends a command to an active gnuplot session.

Parameters

handle	Gnuplot session control handle
cmd	Command to send, same as a printf statement.

This sends a string to an active gnuplot session, to be executed. There is strictly no way to know if the command has been successfully executed or not. The command syntax is the same as printf.

Examples:

gnuplot_cmd(g, "plot %d*x", 23.0);
gnuplot_cmd(g, "plot %g * cos(%g * x)", 32.0, -3.0);

Since the communication to the gnuplot process is run through a standard Unix pipe, it is only unidirectional. This means that it is not possible for this interface to query an error status back from gnuplot.

Definition at line 313 of file gnuplot_i.c.

int gnuplot_contour_plot	(	gnuplot_ctrl *	handle,
		double *	x,
		double *	y,
		double *	z,
		int	nx,
		int	ny,
		char *	title
	)

Plot contours from a list of points.

Parameters

handle	Gnuplot session control handle.
x	Pointer to a list of x coordinates. (length=nx*ny)
y	Pointer to a list of y coordinates. (length=nx*ny)
z	Pointer to a list of z coordinates. (length=nx*ny)
nx	Number of doubles in x-direction
ny	Number of doubles in y-direction
title	Title of the plot.

Returns

void

gnuplot_contour_plot(handle,x,y,z,n,title); Based on gnuplot_splot, modifications by Robert Bradley 23/11/2005

Plots a contour plot from a list of points, passed in the form of three arrays x, y and z.

gnuplot_ctrl    *h ;
double x[50] ; y[50] ; z[50];
int i ;

h = gnuplot_init() ;
int count=100;
double x[count*count],y[count*count],z[count*count];
int i,j;
for (i=0;i<count;i++) {
    for (j=0;j<count;j++) {
        x[count*i+j]=i;
        y[count*i+j]=j;
        z[count*i+j]=1000*sqrt(square(i-count/2)+square(j-count/2));
    }
}
gnuplot_setstyle(h,"lines");
gnuplot_contour_plot(h,x,y,z,count,count,"Points");
sleep(2) ;
gnuplot_close(h) ;

Definition at line 989 of file gnuplot_i.c.

char* gnuplot_get_program_path

(

char *

pname

)

Find out where a command lives in your PATH.

Parameters

pname

Name of the program to look for.

Returns

pointer to statically allocated character string.

This is the C equivalent to the 'which' command in Unix. It parses out your PATH environment variable to find out where a command lives. The returned character string is statically allocated within this function, i.e. there is no need to free it. Beware that the contents of this string will change from one call to the next, though (as all static variables in a function).

The input character string must be the name of a command without prefixing path of any kind, i.e. only the command name. The returned string is the path in which a command matching the same name was found.

Examples (assuming there is a prog named 'hello' in the cwd):

gnuplot_get_program_path("hello") returns "."
gnuplot_get_program_path("ls") returns "/bin"
gnuplot_get_program_path("csh") returns "/usr/bin"
gnuplot_get_program_path("/bin/ls") returns NULL

Definition at line 137 of file gnuplot_i.c.

void gnuplot_hardcopy	(	gnuplot_ctrl *	h,
		char *	filename
	)

Save a graph as a postscript file on the hard disk.

Parameters

h	Gnuplot session control handle.
filename	Filname to save as

Returns

void

A wrapper for the gnuplot_cmd function that sets the terminal the terminal to postscript, replots the raph and then resets the terminal to x11.

Example:

gnuplot_ctrl    *h ;
char            eq[80] ;

h = gnuplot_init() ;
strcpy(eq, "sin(x) * cos(2*x)") ;
gnuplot_plot_equation(h, eq, "sine wave", normal) ;
gnuplot_hardcopy(h, "sinewave.ps");
gnuplot_close(h) ;

Parameters

h	Gnuplot session control handle.
filename	Filename to save as

Returns

void

A wrapper for the gnuplot_cmd function that sets the terminal the terminal to postscript, replots the graph and then resets the terminal to x11.

Example:

gnuplot_ctrl    *h ;
char            eq[80] ;

h = gnuplot_init() ;
strcpy(eq, "sin(x) * cos(2*x)") ;
gnuplot_plot_equation(h, eq, "sine wave", normal) ;
gnuplot_hardcopy(h, "sinewave.ps");
gnuplot_close(h) ;

Definition at line 1475 of file gnuplot_i.c.

void gnuplot_hardcopy_colour	(	gnuplot_ctrl *	h,
		char *	filename
	)

Save a graph in colour as a postscript file on the hard disk.

Parameters

h	Gnuplot session control handle.
filename	Filename to save as

Returns

void

Added by Robert Bradley on 12th october 2004

This function is identical in syntax (and implementation) to gnuplot_hardcopy, but the resulting PostScript file retains colour information.

Definition at line 1503 of file gnuplot_i.c.

gnuplot_ctrl* gnuplot_init

(

void

)

Opens up a gnuplot session, ready to receive commands.

Returns

Newly allocated gnuplot control structure.

This opens up a new gnuplot session, ready for input. The struct controlling a gnuplot session should remain opaque and only be accessed through the provided functions.

The session must be closed using gnuplot_close().

Definition at line 196 of file gnuplot_i.c.

void gnuplot_plot_equation	(	gnuplot_ctrl *	h,
		char *	equation,
		char *	title
	)

Plot a curve of given equation y=f(x).

Parameters

h	Gnuplot session control handle.
equation	Equation to plot.
title	Title of the plot.

Returns

void

Plots out a curve of given equation. The general form of the equation is y=f(x), you only provide the f(x) side of the equation.

Example:

gnuplot_ctrl    *h ;
char            eq[80] ;

h = gnuplot_init() ;
strcpy(eq, "sin(x) * cos(2*x)") ;
gnuplot_plot_equation(h, eq, "sine wave", normal) ;
gnuplot_close(h) ;

Definition at line 1422 of file gnuplot_i.c.

int gnuplot_plot_obj_xy	(	gnuplot_ctrl *	handle,
		void *	obj,
		void(*)(void *, gnuplot_point *, int, int)	getPoint,
		int	n,
		char *	title
	)

Definition at line 1201 of file gnuplot_i.c.

void gnuplot_plot_once	(	char *	title,
		char *	style,
		char *	label_x,
		char *	label_y,
		double *	x,
		double *	y,
		int	n
	)

Open a new session, plot a signal, close the session.

Parameters

title	Plot title
style	Plot style
label_x	Label for X
label_y	Label for Y
x	Array of X coordinates
y	Array of Y coordinates (can be NULL)
n	Number of values in x and y.

Returns

This function opens a new gnuplot session, plots the provided signal as an X or XY signal depending on a provided y, waits for a carriage return on stdin and closes the session.

It is Ok to provide an empty title, empty style, or empty labels for X and Y. Defaults are provided in this case.

Definition at line 1297 of file gnuplot_i.c.

void gnuplot_plot_slope	(	gnuplot_ctrl *	handle,
		double	a,
		double	b,
		char *	title
	)

Plot a slope on a gnuplot session.

Parameters

handle	Gnuplot session control handle.
a	Slope.
b	Intercept.
title	Title of the plot.

Returns

void

Plot a slope on a gnuplot session. The provided slope has an equation of the form y=ax+b

Example:

gnuplot_ctrl    *   h ;
double              a, b ;

h = gnuplot_init() ;
gnuplot_plot_slope(h, 1.0, 0.0, "unity slope") ;
sleep(2) ;
gnuplot_close(h) ;

Parameters

handle	Gnuplot session control handle.
a	Slope.
b	Intercept.
title	Title of the plot.

Returns

void

Plot a slope on a gnuplot session. The provided slope has an equation of the form y=ax+b

Example:

gnuplot_ctrl    *   h ;
double              a, b ;

h = gnuplot_init() ;
gnuplot_plot_slope(h, 1.0, 0.0, "unity slope") ;
sleep(2) ;
gnuplot_close(h) ;

Definition at line 1368 of file gnuplot_i.c.

void gnuplot_plot_x	(	gnuplot_ctrl *	handle,
		double *	d,
		int	n,
		char *	title
	)

Plots a 2d graph from a list of doubles.

Parameters

handle	Gnuplot session control handle.
d	Array of doubles.
n	Number of values in the passed array.
title	Title of the plot.

Returns

void

Plots out a 2d graph from a list of doubles. The x-coordinate is the index of the double in the list, the y coordinate is the double in the list.

Example:

gnuplot_ctrl    *h ;
double          d[50] ;
int             i ;

h = gnuplot_init() ;
for (i=0 ; i<50 ; i++) {
    d[i] = (double)(i*i) ;
}
gnuplot_plot_x(h, d, 50, "parabola") ;
sleep(2) ;
gnuplot_close(h) ;

Definition at line 577 of file gnuplot_i.c.

void gnuplot_plot_xy	(	gnuplot_ctrl *	handle,
		double *	x,
		double *	y,
		int	n,
		char *	title
	)

Plot a 2d graph from a list of points.

Parameters

handle	Gnuplot session control handle.
x	Pointer to a list of x coordinates.
y	Pointer to a list of y coordinates.
n	Number of doubles in x (assumed the same as in y).
title	Title of the plot.

Returns

void

Plots out a 2d graph from a list of points. Provide points through a list of x and a list of y coordinates. Both provided arrays are assumed to contain the same number of values.

gnuplot_ctrl    *h ;
double          x[50] ;
double          y[50] ;
int             i ;

h = gnuplot_init() ;
for (i=0 ; i<50 ; i++) {
    x[i] = (double)(i)/10.0 ;
    y[i] = x[i] * x[i] ;
}
gnuplot_plot_xy(h, x, y, 50, "parabola") ;
sleep(2) ;
gnuplot_close(h) ;

Definition at line 684 of file gnuplot_i.c.

void gnuplot_prompt

(

gnuplot_ctrl *

handle

)

Read commands from standard in and send them to gnuplot handle.

Parameters

handle

Gnuplot session control handle

This reads commands from a simple interactive prompt and sends them to be executed via the gnuplot handle. There is no indicatio nof whether a command is executed successfully or not and no checking of input command syntax.

Ctrl+D ends the interactive session.

Definition at line 342 of file gnuplot_i.c.

void gnuplot_resetplot

(

gnuplot_ctrl *

h

)

Resets a gnuplot session (next plot will erase previous ones).

Parameters

h	Gnuplot session control handle.

Returns

void

Resets a gnuplot session, i.e. the next plot will erase all previous ones.

Definition at line 531 of file gnuplot_i.c.

void gnuplot_set_xlabel	(	gnuplot_ctrl *	h,
		char *	label
	)

Sets the x label of a gnuplot session.

Parameters

h	Gnuplot session control handle.
label	Character string to use for X label.

Returns

void

Sets the x label for a gnuplot session.

Definition at line 470 of file gnuplot_i.c.

void gnuplot_set_ylabel	(	gnuplot_ctrl *	h,
		char *	label
	)

Sets the y label of a gnuplot session.

Parameters

h	Gnuplot session control handle.
label	Character string to use for Y label.

Returns

void

Sets the y label for a gnuplot session.

Definition at line 491 of file gnuplot_i.c.

void gnuplot_set_zlabel	(	gnuplot_ctrl *	h,
		char *	label
	)

Sets the z label of a gnuplot session.

Parameters

h	Gnuplot session control handle.
label	Character string to use for Z label.

Returns

void

Sets the z label for a gnuplot session.

Parameters

h	Gnuplot session control handle.
label	Character string to use for Z label.

Returns

void

Sets the z label for a gnuplot session. (Added by Robert Bradley 12 October 2004)

Definition at line 511 of file gnuplot_i.c.

void gnuplot_setaxes	(	gnuplot_ctrl *	h,
		char *	plot_axes
	)

Change the plotting axes of a gnuplot session.

Parameters

h	Gnuplot session control handle
plot_axes	Plotting-axes to use (character string)

Returns

void

The provided plotting axes is a character string. It must be one of the following:

• x1y1
• x1y2
• x2y1
• x2y2

Change the plotting axes of a gnuplot session.

Parameters

h	Gnuplot session control handle
plot_axes	Plotting-axes to use (character string)

Returns

void

The provided plotting axes is a character string. It must be one of the following:

• x1y1
• x1y2
• x2y1
• x2y2

Definition at line 422 of file gnuplot_i.c.

void gnuplot_setstyle	(	gnuplot_ctrl *	h,
		char *	plot_style
	)

Change the plotting style of a gnuplot session.

Parameters

h	Gnuplot session control handle
plot_style	Plotting-style to use (character string)

Returns

void

The provided plotting style is a character string. It must be one of the following:

• lines
• points
• linespoints
• impulses
• dots
• steps
• errorbars
• boxes
• boxeserrorbars

Definition at line 385 of file gnuplot_i.c.

void gnuplot_setterm	(	gnuplot_ctrl *	h,
		char *	terminal
	)

Change the terminal of a gnuplot session.

Parameters

h	Gnuplot session control handle
terminal	Terminal name (character string)

Returns

void

No attempt is made to check the validity of the terminal name. This function simply makes a note of it and calls gnuplot_cmd to change the name

Definition at line 449 of file gnuplot_i.c.

int gnuplot_splot	(	gnuplot_ctrl *	handle,
		double *	x,
		double *	y,
		double *	z,
		int	n,
		char *	title
	)

Plot a 3d graph from a list of points.

Parameters

handle	Gnuplot session control handle.
x	Pointer to a list of x coordinates.
y	Pointer to a list of y coordinates.
z	Pointer to a list of z coordinates.
n	Number of doubles in x (assumed the same as in y and z).
title	Title of the plot.

Returns

void

Plots out a 3d graph from a list of points. Provide points through lists of x, y and z coordinates. Both provided arrays are assumed to contain the same number of values.

Parameters

handle	Gnuplot session control handle.
x	Pointer to a list of x coordinates.
y	Pointer to a list of y coordinates.
z	Pointer to a list of z coordinates.
n	Number of doubles in x (y and z must be the the same).
title	Title of the plot.

Returns

void

gnuplot_splot(handle,x,y,z,n,title); Based on gnuplot_plot_xy, modifications by Robert Bradley 12/10/2004

Plots a 3d graph from a list of points, passed in the form of three arrays x, y and z. All arrays are assumed to contain the same number of values.

gnuplot_ctrl    *h ;
double x[50] ; y[50] ; z[50];
int i ;

h = gnuplot_init() ;
for (i=0 ; i<50 ; i++) {
    x[i] = (double)(i)/10.0 ;
    y[i] = x[i] * x[i] ;
    z[i] = x[i] * x[i]/2.0;
}
gnuplot_splot(h, x, y, z, 50, "parabola") ;
sleep(2) ;
gnuplot_close(h) ;

Definition at line 792 of file gnuplot_i.c.

int gnuplot_splot_grid	(	gnuplot_ctrl *	handle,
		double *	points,
		int	rows,
		int	cols,
		char *	title
	)

Plot a 3d graph from a grid of points.

Parameters

handle	Gnuplot session control handle.
points	Pointer to a grid of points (rows,cols).
rows	Number of rows (y points).
cols	Number of columns (x points).
title	Title of the plot.

Returns

void

gnuplot_splot_grid(handle,(double *) points,rows,cols,title); Based on gnuplot_splot, modifications by Robert Bradley 2/4/2006

Plots a 3d graph from a grid of points, passed in the form of a 2D array [x,y].

Parameters

handle	Gnuplot session control handle.
points	Pointer to a grid of points (rows,cols).
rows	Number of rows (y points).
cols	Number of columns (x points).
title	Title of the plot.

Returns

void

gnuplot_splot_grid(handle,(double*) points,rows,cols,title); Based on gnuplot_splot, modifications by Robert Bradley 2/4/2006

Plots a 3d graph from a grid of points, passed in the form of a 2D array [x,y].

Definition at line 871 of file gnuplot_i.c.

int gnuplot_splot_obj	(	gnuplot_ctrl *	handle,
		void *	obj,
		void(*)(void *, gnuplot_point *, int, int)	getPoint,
		int	n,
		char *	title
	)

Plot a 3d graph using callback functions to return the points.

Parameters

handle	Gnuplot session control handle.
obj	Pointer to an arbitrary object.
getPoint	Pointer to a callback function.
n	Number of doubles in x (y and z must be the the same).
title	Title of the plot.

Returns

void

Calback:

void getPoint(void *object,gnuplot_point *point,int index,int pointCount);

Parameters

obj	Pointer to an arbitrary object
point	Pointer to the returned point struct (double x,y,z)
i	Index of the current point (0 to n-1)
n	Number of points

Returns

void

Definition at line 1091 of file gnuplot_i.c.