GvaProcess

GvaProcess — An abstraction of a UNIX process

Functions

Properties

guint pid Read / Write / Construct Only
int priority Read / Write / Construct Only
guint progress Read / Write
int stderr Read / Write / Construct Only
int stdin Read / Write / Construct Only
int stdout Read / Write / Construct Only

Signals

Types and Values

struct GvaProcess

Object Hierarchy

    GObject
    ╰── GvaProcess
        ╰── GvaMameProcess

Description

A GvaProcess provides a convenient interface for communicating with a child process through pipes.

Functions

gva_process_new ()

GvaProcess *
gva_process_new (GPid pid,
                 gint priority,
                 gint standard_input,
                 gint standard_output,
                 gint standard_error);

Creates a new GvaProcess from the given parameters. A GSource is created at the given priority for each of the file descriptors. The internal progress value is initialized to zero.

Parameters

pid

child process ID

 

priority

priority for the event sources

 

standard_input

file descriptor for the child's stdin

 

standard_output

file descriptor for the child's stdout

 

standard_error

file descriptor for the child's stderr

 

Returns

a new GvaProcess


gva_process_spawn ()

GvaProcess *
gva_process_spawn (const gchar *command_line,
                   gint priority,
                   GError **error);

Spawns a child process with command_line and returns the resulting GvaProcess. If an error occurs while spawning, the function returns NULL and sets error .

Parameters

command_line

a command line

 

priority

priority for the event sources

 

error

return location for a GError, or NULL

 

Returns

a new GvaProcess, or NULL if an error occurred


gva_process_get_pid ()

GPid
gva_process_get_pid (GvaProcess *process);

Returns the process ID for process .

Parameters

process

a GvaProcess

 

Returns

process ID for process


gva_process_write_stdin ()

gboolean
gva_process_write_stdin (GvaProcess *process,
                         const gchar *data,
                         gssize length,
                         GError **error);

Writes data to the stdin pipe of a child process represented by process . If an error occurs, it returns FALSE and sets error .

Parameters

process

a GvaProcess

 

data

the data to write to the child process

 

length

length of the data, or -1 if the data is nul-terminated

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE if an error occurred


gva_process_stdout_num_lines ()

guint
gva_process_stdout_num_lines (GvaProcess *process);

Returns the number of lines available for reading from the stdout pipe of the child process represented by process .

Parameters

process

a GvaProcess

 

Returns

number of lines available for reading


gva_process_stderr_num_lines ()

guint
gva_process_stderr_num_lines (GvaProcess *process);

Returns the number of lines available for reading from the stderr pipe of the child process represented by process .

Parameters

process

a GvaProcess

 

Returns

number of lines available for reading


gva_process_stdout_read_line ()

gchar *
gva_process_stdout_read_line (GvaProcess *process);

Reads a line from the stdout pipe of the child process represented by process . This function does not block; it returns NULL if no lines are available. Use gva_process_stdout_num_lines() to peek at whether any lines are available. The line should be freed with g_free() when no longer needed.

Parameters

process

a GvaProcess

 

Returns

a line from the child process' stdout, or NULL


gva_process_stderr_read_line ()

gchar *
gva_process_stderr_read_line (GvaProcess *process);

Reads a line from the stderr pipe of the child process represented by process . This function does not block; it returns NULL if no lines are available. Use gva_process_stderr_num_lines() to peek at whether any lines are available. The line should be freed with g_free() when no longer needed.

Parameters

process

a GvaProcess

 

Returns

a line from the child process' stderr, or NULL


gva_process_stdout_read_lines ()

gchar **
gva_process_stdout_read_lines (GvaProcess *process);

Returns a NULL-terminated array of lines from the stdout pipe of the child process represented by process . This function does not block; it returns NULL if no lines are available. Use gva_process_stdout_num_lines() to peek at the number of lines available. The array should be freed with g_strfreev() when no longer needed.

Parameters

process

a GvaProcess

 

Returns

a NULL-terminated array of lines from the child process' stdout, or NULL


gva_process_stderr_read_lines ()

gchar **
gva_process_stderr_read_lines (GvaProcess *process);

Returns a NULL-terminated array of lines from the stderr pipe of the child process represented by process . This function does not block; it returns NULL if no lines are available. Use gva_process_stderr_num_lines() to peek at the number of lines available. The array should be freed with g_strfreev() when no longer needed.

Parameters

process

a GvaProcess

 

Returns

a NULL-terminated array of lines from the child process' stderr, or NULL


gva_process_get_progress ()

guint
gva_process_get_progress (GvaProcess *process);

Returns the current progress value for process . It is up to the application to set this value using gva_process_set_progress() or gva_process_inc_progress().

Parameters

process

a GvaProcess

 

Returns

progress value


gva_process_inc_progress ()

void
gva_process_inc_progress (GvaProcess *process);

Increments the progress value for process . The progress value is just a counter; it is up to the application to establish an upper bound for the value.

Parameters

process

a GvaProcess

 

gva_process_set_progress ()

void
gva_process_set_progress (GvaProcess *process,
                          guint progress);

Sets the progress value for process . The progress value is just a counter; it is up to the application to establish an upper bound for the value.

Parameters

process

a GvaProcess

 

progress

progress value

 

gva_process_has_exited ()

gboolean
gva_process_has_exited (GvaProcess *process,
                        gint *status);

Returns TRUE if the child process represented by process has exited and writes the exit status to the location pointed to by status , if status is non-NULL. There may still be lines available for reading even after the child process has exited.

Parameters

process

a GvaProcess

 

status

return location for the exit status, or NULL

 

Returns

TRUE if the child process has exited, FALSE otherwise


gva_process_kill ()

void
gva_process_kill (GvaProcess *process);

Kills the child process represented by process by sending it a "kill" signal.

Parameters

process

a GvaProcess

 

gva_process_kill_all ()

void
gva_process_kill_all (void);

Kills all active child processes represented by GvaProcess instances by sending them "kill" signals.


gva_process_get_time_elapsed ()

void
gva_process_get_time_elapsed (GvaProcess *process,
                              GTimeVal *time_elapsed);

Writes the time elapsed since process (the GvaProcess instance, not necessarily the child process it represents) was created to time_elapsed .

Parameters

process

a GvaProcess

 

time_elapsed

location to put the time elapsed

 

Types and Values

struct GvaProcess

struct GvaProcess;

Contains only private data that should be read and manipulated using the functions below.

Property Details

The “pid” property

  “pid”                      guint

The ID of the child process.

Owner: GvaProcess

Flags: Read / Write / Construct Only

Default value: 0


The “priority” property

  “priority”                 int

Priority of the event sources that watch for incoming data.

Owner: GvaProcess

Flags: Read / Write / Construct Only

Default value: 200


The “progress” property

  “progress”                 guint

Progress value, the meaning of which is defined by the application.

Owner: GvaProcess

Flags: Read / Write

Default value: 0


The “stderr” property

  “stderr”                   int

The file descriptor for the child process' stderr pipe.

Owner: GvaProcess

Flags: Read / Write / Construct Only

Allowed values: >= -1

Default value: -1


The “stdin” property

  “stdin”                    int

The file descriptor for the child process' stdin pipe.

Owner: GvaProcess

Flags: Read / Write / Construct Only

Allowed values: >= -1

Default value: -1


The “stdout” property

  “stdout”                   int

The file descriptor for the child process' stdout pipe.

Owner: GvaProcess

Flags: Read / Write / Construct Only

Allowed values: >= -1

Default value: -1

Signal Details

The “exited” signal

void
user_function (GvaProcess *process,
               int         status,
               gpointer    user_data)

The ::exited signal is emitted when the child process exits.

Parameters

process

the GvaProcess that received the signal

 

status

the exit status of the child process

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “stderr-ready” signal

void
user_function (GvaProcess *process,
               gpointer    user_data)

The ::stderr-ready signal is emitted when one or more lines from the child process' stderr pipe are available for reading.

Parameters

process

the GvaProcess that received the signal

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “stdout-ready” signal

void
user_function (GvaProcess *process,
               gpointer    user_data)

The ::stdout-ready signal is emitted when one or more lines from the child process' stdout pipe are available for reading.

Parameters

process

the GvaProcess that received the signal

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last