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.