## GvaProcess

GvaProcess — An abstraction of a UNIX process

## Synopsis

                        GvaProcess;
    GvaProcess *        gva_process_new                     (GPid pid,
                                                             gint priority,
                                                             gint standard_input,
                                                             gint standard_output,
                                                             gint standard_error);
    GvaProcess *        gva_process_spawn                   (const gchar *command_line,
                                                             gint priority,
                                                             GError **error);
    GPid                gva_process_get_pid                 (GvaProcess *process);
    gboolean            gva_process_write_stdin             (GvaProcess *process,
                                                             const gchar *data,
                                                             gssize length,
                                                             GError **error);
    guint               gva_process_stdout_num_lines        (GvaProcess *process);
    guint               gva_process_stderr_num_lines        (GvaProcess *process);
    gchar *             gva_process_stdout_read_line        (GvaProcess *process);
    gchar *             gva_process_stderr_read_line        (GvaProcess *process);
    gchar **            gva_process_stdout_read_lines       (GvaProcess *process);
    gchar **            gva_process_stderr_read_lines       (GvaProcess *process);
    guint               gva_process_get_progress            (GvaProcess *process);
    void                gva_process_inc_progress            (GvaProcess *process);
    void                gva_process_set_progress            (GvaProcess *process,
                                                             guint progress);
    gboolean            gva_process_has_exited              (GvaProcess *process,
                                                             gint *status);
    void                gva_process_kill                    (GvaProcess *process);
    void                gva_process_kill_all                (void);
    void                gva_process_get_time_elapsed        (GvaProcess *process,
                                                             GTimeVal *time_elapsed);

## Object Hierarchy

      GObject
       +----GvaProcess
             +----GvaMameProcess

## Properties

      "pid"                      guint                 : Read / Write / Construct Only
      "priority"                 gint                  : Read / Write / Construct Only
      "progress"                 guint                 : Read / Write
      "stderr"                   gint                  : Read / Write / Construct Only
      "stdin"                    gint                  : Read / Write / Construct Only
      "stdout"                   gint                  : Read / Write / Construct Only

## Signals

      "exited"                                         : Run First
      "stderr-ready"                                   : Run Last
      "stdout-ready"                                   : Run Last

## Description

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

## Details

### GvaProcess

    typedef struct _GvaProcess GvaProcess;

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

### 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.

`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`.

`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`.

`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`.

`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`.

`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`.

`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.

`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.

`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.

`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.

`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()`.

`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.

`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.

`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.

`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.

`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`.

`process` : | a GvaProcess
`time_elapsed` : | location to put the time elapsed

## Property Details

### The `"pid"` property

      "pid"                      guint                 : Read / Write / Construct Only

The ID of the child process.

Default value: 0

### The `"priority"` property

      "priority"                 gint                  : Read / Write / Construct Only

Priority of the event sources that watch for incoming data.

Default value: 200

### The `"progress"` property

      "progress"                 guint                 : Read / Write

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

Default value: 0

### The `"stderr"` property

      "stderr"                   gint                  : Read / Write / Construct Only

The file descriptor for the child process' stderr pipe.

Allowed values: >= -1

Default value: -1

### The `"stdin"` property

      "stdin"                    gint                  : Read / Write / Construct Only

The file descriptor for the child process' stdin pipe.

Allowed values: >= -1

Default value: -1

### The `"stdout"` property

      "stdout"                   gint                  : Read / Write / Construct Only

The file descriptor for the child process' stdout pipe.

Allowed values: >= -1

Default value: -1

## Signal Details

### The `"exited"` signal

    void                user_function                      (GvaProcess *process,
                                                            gint        status,
                                                            gpointer    user_data)      : Run First

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

`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.

### The `"stderr-ready"` signal

    void                user_function                      (GvaProcess *process,
                                                            gpointer    user_data)      : Run Last

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

`process` : | the GvaProcess that received the signal
`user_data` : | user data set when the signal handler was connected.

### The `"stdout-ready"` signal

    void                user_function                      (GvaProcess *process,
                                                            gpointer    user_data)      : Run Last

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

`process` : | the GvaProcess that received the signal
`user_data` : | user data set when the signal handler was connected.