## GskStreamExternal

GskStreamExternal — streams which connect to another process.

## Synopsis

    void                (*GskStreamExternalTerminated)      (GskStreamExternal *external,
                                                             GskMainLoopWaitInfo *wait_info,
                                                             gpointer user_data);
    void                (*GskStreamExternalStderr)          (GskStreamExternal *external,
                                                             const char *error_text,
                                                             gpointer user_data);
                        GskStreamExternal;
    enum                GskStreamExternalFlags;
    GskStream *         gsk_stream_external_new             (GskStreamExternalFlags flags,
                                                             const char *stdin_filename,
                                                             const char *stdout_filename,
                                                             GskStreamExternalTerminated term_func,
                                                             GskStreamExternalStderr err_func,
                                                             gpointer user_data,
                                                             const char *path,
                                                             const char *argv[],
                                                             const char *env[],
                                                             GError **error);

## Description

These are streams where the input and output map to standard output and standard input for another process which is exec(2)'d from this one.

## Details

### GskStreamExternalTerminated ()

    void                (*GskStreamExternalTerminated)      (GskStreamExternal *external,
                                                             GskMainLoopWaitInfo *wait_info,
                                                             gpointer user_data);

Function to run when the process underlying the stream is terminated.

`external` : | the stream corresponding to the process.
`wait_info` : | information about why the process exited.
`user_data` : | passed in from `gsk_stream_external_new()`.

### GskStreamExternalStderr ()

    void                (*GskStreamExternalStderr)          (GskStreamExternal *external,
                                                             const char *error_text,
                                                             gpointer user_data);

Function to be run with single lines taken from standard-error of the subprocess. The line has had the newline chopped from it.

`external` : | the stream corresponding to the process.
`error_text` : | the NUL-terminated text from the subprocess.
`user_data` : | passed in from `gsk_stream_external_new()`.

### GskStreamExternal

    typedef struct {
      GskStream      stream;

      /* stdin for the process */
      int write_fd;
      GskSource *write_source;
      GskBuffer write_buffer;
      gsize max_write_buffer;

      /* stdout for the process */
      int read_fd;
      GskSource *read_source;
      GskBuffer read_buffer;
      gsize max_read_buffer;

      /* stderr for the process */
      int read_err_fd;
      GskSource *read_err_source;
      GskBuffer read_err_buffer;
      gsize max_err_line_length;

      /* process-termination notification */
      GskSource *process_source;
      glong pid;

      /* user-callback information */
      GskStreamExternalTerminated term_func;
      GskStreamExternalStderr err_func;
      gpointer user_data;
    } GskStreamExternal;

Instance of an object whose input and output come from another process.

GskStream `stream`; | parent instance.
int `write_fd`; | file-descriptor to write to (received as standard-input of the child process).
GskSource *`write_source`; | notification that it's ready to write.
GskBuffer `write_buffer`; | data pending to be written.
gsize `max_write_buffer`; | max data pending to be written.
int `read_fd`; | file-descriptor to read from (sent as standard-output of the child process).
GskSource *`read_source`; | notification that it's ready to read.
GskBuffer `read_buffer`; | data pending read from child.
gsize `max_read_buffer`; | max bytes data pending read from child.
int `read_err_fd`; | file-descriptor to read from (sent as standard-error of the child process).
GskSource *`read_err_source`; | notification that the error stream is ready-to-read.
GskBuffer `read_err_buffer`; | data pending from error stream.
gsize `max_err_line_length`; | maximum length of line for an error string.
GskSource *`process_source`; | process-termination notification.
glong `pid`; | process id.
GskStreamExternalTerminated `term_func`; | function to call when the child process dies.
GskStreamExternalStderr `err_func`; | function to call with standard error data.
gpointer `user_data`; | parameter to pass to `term_func` and `err_func`.

### enum GskStreamExternalFlags

    typedef enum
    {
      GSK_STREAM_EXTERNAL_ALLOCATE_PSEUDOTTY = (1<<2),
      GSK_STREAM_EXTERNAL_SEARCH_PATH        = (1<<3)
    } GskStreamExternalFlags;

Flags which affect the construction of the stream.

`GSK_STREAM_EXTERNAL_ALLOCATE_PSEUDOTTY` | Allocate a pseudo tty for the input and output of the child process.
`GSK_STREAM_EXTERNAL_SEARCH_PATH` | Search along $PATH for the binary.

### gsk_stream_external_new ()

    GskStream *         gsk_stream_external_new             (GskStreamExternalFlags flags,
                                                             const char *stdin_filename,
                                                             const char *stdout_filename,
                                                             GskStreamExternalTerminated term_func,
                                                             GskStreamExternalStderr err_func,
                                                             gpointer user_data,
                                                             const char *path,
                                                             const char *argv[],
                                                             const char *env[],
                                                             GError **error);

Allocates a stream which points to standard input and/or output of a newly forked process.

This forks, redirects the standard input from a file if `stdin_filename` is non-NULL, otherwise it uses a pipe to communicate the data to the main-loop. It redirects the standard output to a file if `stdout_filename` is non-NULL, otherwise it uses a pipe to communicate the data from the main-loop.

When the process terminates, `term_func` will be called. Until `term_func` is called, `err_func` may be called with lines of data from the standard-error of the process.

If `env` is non-NULL, then the environment for the subprocess will consist of nothing but the list given as `env`. If `env` is NULL, then the environment will be the same as the parent process's environment.

If GSK_STREAM_EXTERNAL_SEARCH_PATH is set, then the executable will be saught in the colon-separated list of paths in the $PATH environment-variable. Otherwise, `path` must be the exact path to the executable.

If the executable is not found, or exec otherwise fails, then `term_func` will be called with an exit status of 127.

`flags` : | whether to allocate a pseudo-tty and/or use $PATH.
`stdin_filename` : | file to redirect as standard input into the process. If NULL, then the returned stream will be writable, and data written in will appear as standard-input to the process.
`stdout_filename` : | file to redirect output from the process's standard-input. If NULL, then the returned stream will be readable; the data read will be the process's standard-output.
`term_func` : | function to call with the process's exit status.
`err_func` : | function to call with standard error output from the process, line-by-line.
`user_data` : | data to pass to term_func and err_func.
`path` : | name of the executable.
`argv` : | arguments to pass to the executable.
`env` : | environment variables, as a NULL-terminated key=value list of strings.
`error` : | optional error return location.
Returns : | the new stream.