Geany  dev
Data Structures | Macros | Typedefs | Enumerations | Functions
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
stringcontains the child data if G_IO_IN or G_IO_PRI are set.
conditionthe I/O condition which has been satisfied.
datathe passed to spawn_with_callbacks() with the callback.

◆ 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.
errorreturn 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_linethe command line to check.
executewhether to check if the command line is really executable.
errorreturn 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
pidid of the process to kill.
errorreturn 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.
errorreturn 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.

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_flagsflags from SpawnFlags.
stdin_cb callback to send data to childs's stdin, or NULL.
stdin_datadata to pass to stdin_cb.
stdout_cb callback to receive child's stdout, or NULL.
stdout_datadata to pass to stdout_cb.
stdout_max_lengthmaximum data length to pass to stdout_cb, 0 = default.
stderr_cb callback to receive child's stderr, or NULL.
stderr_datadata to pass to stderr_cb.
stderr_max_lengthmaximum data length to pass to stderr_cb, 0 = default.
exit_cb callback to invoke when the child exits, or NULL.
exit_datadata to pass to exit_cb.
child_pid (out) return location for child process ID, or NULL.
errorreturn 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
channelthe channel to write data to.
conditioncondition to check for G_IO_OUT.
dataSpawnWriteData to write to channel.
Returns
TRUE if the remaining size is > 0 and condition does not indicate any error, FALSE otherwise.
Since
1.25