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.