spawn.h File Reference

Portable and convenient process spawning and communication. More...

Data Structures
struct	_SpawnWriteData
	A simple structure used by spawn_write_data() to write data to a channel. More...

Macros
#define	SPAWN_WEXITSTATUS(status)   WEXITSTATUS(status)
	exit status of a child if exited normally
#define	SPAWN_WIFEXITED(status)   WIFEXITED(status)
	non-zero if the child exited normally
#define	SPAWN_WIFSIGNALED(status)   WIFSIGNALED(status)
	non-zero if the child exited due to signal

Typedefs
typedef void(*	SpawnReadFunc) (GString *string, GIOCondition condition, gpointer data)
	Specifies the type of function passed to spawn_with_callbacks() as stdout or stderr callback. More...
typedef struct _SpawnWriteData	SpawnWriteData
	A simple structure used by spawn_write_data() to write data to a channel. More...

Enumerations
enum	SpawnFlags {   SPAWN_ASYNC = 0x00 , SPAWN_SYNC = 0x01 , SPAWN_LINE_BUFFERED = 0x00 , SPAWN_STDOUT_UNBUFFERED = 0x02 ,   SPAWN_STDERR_UNBUFFERED = 0x04 , SPAWN_UNBUFFERED = 0x06 , SPAWN_STDIN_RECURSIVE = 0x08 , SPAWN_STDOUT_RECURSIVE = 0x10 ,   SPAWN_STDERR_RECURSIVE = 0x20 , SPAWN_RECURSIVE = 0x38 }
	Flags passed to spawn_with_callbacks(), which see. More...

Functions
gboolean	spawn_async (const gchar *working_directory, const gchar *command_line, gchar **argv, gchar **envp, GPid *child_pid, GError **error)
	Executes a child asynchronously. More...
gboolean	spawn_check_command (const gchar *command_line, gboolean execute, GError **error)
	Checks whether a command line is valid. More...
gboolean	spawn_kill_process (GPid pid, GError **error)
	Kills a process. More...
gboolean	spawn_sync (const gchar *working_directory, const gchar *command_line, gchar **argv, gchar **envp, SpawnWriteData *stdin_data, GString *stdout_data, GString *stderr_data, gint *exit_status, GError **error)
	Executes a child synchronously. More...
gboolean	spawn_with_callbacks (const gchar *working_directory, const gchar *command_line, gchar **argv, gchar **envp, SpawnFlags spawn_flags, GIOFunc stdin_cb, gpointer stdin_data, SpawnReadFunc stdout_cb, gpointer stdout_data, gsize stdout_max_length, SpawnReadFunc stderr_cb, gpointer stderr_data, gsize stderr_max_length, GChildWatchFunc exit_cb, gpointer exit_data, GPid *child_pid, GError **error)
	Executes a child program and setups callbacks. More...
gboolean	spawn_write_data (GIOChannel *channel, GIOCondition condition, SpawnWriteData *data)
	Writes (a portion of) the data pointed by data->ptr to the channel. More...

Detailed Description

Portable and convenient process spawning and communication.

Typedef Documentation

SpawnReadFunc

typedef void(* SpawnReadFunc) (GString *string, GIOCondition condition, gpointer data)

Specifies the type of function passed to spawn_with_callbacks() as stdout or stderr callback.

In unbuffered mode, the string may contain nuls, while in line buffered mode, it may contain only a single nul as a line termination character at string->len - 1. In all cases, the string will be terminated with a nul character that is not part of the data at string->len.

If G_IO_IN or G_IO_PRI are set, the string will contain at least one character.

Parameters

string	contains the child data if G_IO_IN or G_IO_PRI are set.
condition	the I/O condition which has been satisfied.
data	the passed to spawn_with_callbacks() with the callback.

SpawnWriteData

typedef struct _SpawnWriteData SpawnWriteData

A simple structure used by spawn_write_data() to write data to a channel.

See spawn_write_data() for more information.

Enumeration Type Documentation

SpawnFlags

enum SpawnFlags

Flags passed to spawn_with_callbacks(), which see.

Enumerator
SPAWN_ASYNC	Asynchronous execution [default].
SPAWN_SYNC	Synchronous execution.
SPAWN_LINE_BUFFERED	stdout/stderr are line buffered [default].
SPAWN_STDOUT_UNBUFFERED	stdout is not buffered.
SPAWN_STDERR_UNBUFFERED	stderr is not buffered.
SPAWN_UNBUFFERED	stdout/stderr are not buffered.
SPAWN_STDIN_RECURSIVE	The stdin callback is recursive.
SPAWN_STDOUT_RECURSIVE	The stdout callback is recursive.
SPAWN_STDERR_RECURSIVE	The stderr callback is recursive.
SPAWN_RECURSIVE	All callbacks are recursive.

Function Documentation

spawn_async()

gboolean spawn_async	(	const gchar *	working_directory,
		const gchar *	command_line,
		gchar **	argv,
		gchar **	envp,
		GPid *	child_pid,
		GError **	error
	)

Executes a child asynchronously.

A command line or an argument vector must be passed. If both are present, the argument vector is appended to the command line. An empty command line is not allowed.

If a child_pid is passed, it's your responsibility to invoke g_spawn_close_pid().

Parameters

working_directory	child's current working directory, or NULL.
command_line	child program and arguments, or NULL.
argv	child's argument vector, or NULL.
envp	child's environment, or NULL.
child_pid	(out) return location for child process ID, or NULL.
error	return location for error.

Returns

TRUE on success, FALSE on error.

Since

1.25

spawn_check_command()

gboolean spawn_check_command	(	const gchar *	command_line,
		gboolean	execute,
		GError **	error
	)

Checks whether a command line is valid.

Checks if command_line is syntactically valid.

All OS:

• any leading spaces, tabs and new lines are skipped
• an empty command is invalid

Unix:

• the standard shell quoting and escaping rules are used, see g_shell_parse_argv()
• as a consequence, an unqouted # at the start of an argument comments to the end of line

Windows:

• leading carriage returns are skipped too
• a quoted program name must be entirely inside the quotes. No "C:\Foo\Bar".pdf or "C:\Foo\Bar".bat, which would be executed by Windows as C:\Foo\Bar.exe
• an unquoted program name may not contain spaces. Foo Bar Qux will not be considered "Foo Bar.exe" Qux or "Foo Bar Qux.exe", depending on what executables exist, as Windows normally does.
• the program name must be separated from the arguments by at least one space or tab
• the standard Windows quoting and escaping rules are used: double quote is escaped with backslash, and any literal backslashes before a double quote must be duplicated.

If execute is TRUE, also checks, using g_find_program_in_path(), if the program specified in command_line exists and is executable.

Parameters

command_line	the command line to check.
execute	whether to check if the command line is really executable.
error	return location for error.

Returns

TRUE on success, FALSE on error.

Since

1.25

spawn_kill_process()

gboolean spawn_kill_process	(	GPid	pid,
		GError **	error
	)

Kills a process.

Parameters

pid	id of the process to kill.
error	return location for error.

On Unix, sends a SIGTERM to the process.

On Windows, terminates the process with exit code 255 (used sometimes as "generic" error code, or for programs terminated with Ctrl+C / Ctrl+Break).

Returns

TRUE on success, FALSE on error.

Since

1.25

spawn_sync()

gboolean spawn_sync	(	const gchar *	working_directory,
		const gchar *	command_line,
		gchar **	argv,
		gchar **	envp,
		SpawnWriteData *	stdin_data,
		GString *	stdout_data,
		GString *	stderr_data,
		gint *	exit_status,
		GError **	error
	)

Executes a child synchronously.

A command line or an argument vector must be passed. If both are present, the argument vector is appended to the command line. An empty command line is not allowed.

The stdin_data is sent to the child with spawn_write_data().

All output from the child, including the nul characters, is stored in stdout_data and stderr_data (if non-NULL). Any existing data in these strings will be erased.

Parameters

working_directory	child's current working directory, or NULL.
command_line	child program and arguments, or NULL.
argv	child's argument vector, or NULL.
envp	child's environment, or NULL.
stdin_data	data to send to childs's stdin, or NULL.
stdout_data	GString location to receive the child's stdout, or NULL.
stderr_data	GString location to receive the child's stderr, or NULL.
exit_status	(out) return location for the child exit code, or NULL.
error	return location for error.

Returns

TRUE on success, FALSE on error.

Since

1.25

spawn_with_callbacks()

gboolean spawn_with_callbacks	(	const gchar *	working_directory,
		const gchar *	command_line,
		gchar **	argv,
		gchar **	envp,
		SpawnFlags	spawn_flags,
		GIOFunc	stdin_cb,
		gpointer	stdin_data,
		SpawnReadFunc	stdout_cb,
		gpointer	stdout_data,
		gsize	stdout_max_length,
		SpawnReadFunc	stderr_cb,
		gpointer	stderr_data,
		gsize	stderr_max_length,
		GChildWatchFunc	exit_cb,
		gpointer	exit_data,
		GPid *	child_pid,
		GError **	error
	)

Executes a child program and setups callbacks.

A command line or an argument vector must be passed. If both are present, the argument vector is appended to the command line. An empty command line is not allowed.

The synchronous execution may not be combined with recursive callbacks.

In line buffered mode, the child input is broken on \n, \r\n, \r, \0 and max length.

All I/O callbacks are guaranteed to be invoked at least once with G_IO_ERR, G_IO_HUP or G_IO_NVAL set (except for a stdin_cb which returns FALSE before that). For the non-recursive callbacks, this is guaranteed to be the last call, and may be used to free any resources associated with the callback.

The stdin_cb may write to channel only once per invocation, only if G_IO_OUT is set, and only a non-zero number of characters.

stdout_cb and stderr_cb may modify the received strings in any way, but must not free them.

The default max lengths are 24K for line buffered stdout, 8K for line buffered stderr, 4K for unbuffered input under Unix, and 2K for unbuffered input under Windows.

Due to a bug in some glib versions, the sources for recursive stdout/stderr callbacks may be converted from child watch to timeout(50ms). No callback changes are required.

exit_cb is always invoked last, after all I/O callbacks.

The child_pid will be closed automatically, after exit_cb is invoked.

Parameters

working_directory	child's current working directory, or NULL.
command_line	child program and arguments, or NULL.
argv	child's argument vector, or NULL.
envp	child's environment, or NULL.
spawn_flags	flags from SpawnFlags.
stdin_cb	callback to send data to childs's stdin, or NULL.
stdin_data	data to pass to stdin_cb.
stdout_cb	callback to receive child's stdout, or NULL.
stdout_data	data to pass to stdout_cb.
stdout_max_length	maximum data length to pass to stdout_cb, 0 = default.
stderr_cb	callback to receive child's stderr, or NULL.
stderr_data	data to pass to stderr_cb.
stderr_max_length	maximum data length to pass to stderr_cb, 0 = default.
exit_cb	callback to invoke when the child exits, or NULL.
exit_data	data to pass to exit_cb.
child_pid	(out) return location for child process ID, or NULL.
error	return location for error.

Returns

TRUE on success, FALSE on error.

Since

1.25

spawn_write_data()

gboolean spawn_write_data	(	GIOChannel *	channel,
		GIOCondition	condition,
		SpawnWriteData *	data
	)

Writes (a portion of) the data pointed by data->ptr to the channel.

If G_IO_OUT in condition is set, and the data->size is > 0, attempts to write data->ptr (or a portion of it, depending on the size) to the channel. On success, increases ptr and decreases size with the number of characters written.

This function may converted to GIOFunc and passed to spawn_with_callbacks() as stdin_cb, together with a SpawnWriteData for stdin_data. As with any other callback data, make sure that stdin_data exists while the child is being executed. (For example, on asynchronous execution, you can allocate the data in the heap, and free it in your spawn_with_callbacks() exit_cb callback.)

Parameters

channel	the channel to write data to.
condition	condition to check for G_IO_OUT.
data	SpawnWriteData to write to channel.

Returns

TRUE if the remaining size is > 0 and condition does not indicate any error, FALSE otherwise.

Since

1.25