subprocess.h File Reference

#include <stdio.h>
#include <string.h>
#include <signal.h>
#include <spawn.h>
#include <stdlib.h>
#include <sys/types.h>
#include <sys/wait.h>
#include <unistd.h>

Go to the source code of this file.

Classes
struct	subprocess_s

Macros
#define	SUBPROCESS_ATTRIBUTE(a)
#define	SUBPROCESS_CAST(type, x)
#define	SUBPROCESS_PTR_CAST(type, x)
#define	SUBPROCESS_CONST_CAST(type, x)
#define	SUBPROCESS_NULL   0
#define	SUBPROCESS_ZERO   0

Typedefs
typedef size_t	subprocess_size_t

Enumerations
enum	subprocess_option_e {   subprocess_option_combined_stdout_stderr = 0x1 , subprocess_option_inherit_environment = 0x2 , subprocess_option_enable_async = 0x4 , subprocess_option_no_window = 0x8 ,   subprocess_option_search_user_path = 0x10 }

Functions
subprocess_weak int	subprocess_create (const char *const command_line[], int options, struct subprocess_s *const out_process)
	Create a process.
subprocess_weak int	subprocess_create_ex (const char *const command_line[], int options, const char *const environment[], struct subprocess_s *const out_process)
	Create a process (extended create).
subprocess_pure subprocess_weak FILE *	subprocess_stdin (const struct subprocess_s *const process)
	Get the standard input file for a process.
subprocess_pure subprocess_weak FILE *	subprocess_stdout (const struct subprocess_s *const process)
	Get the standard output file for a process.
subprocess_pure subprocess_weak FILE *	subprocess_stderr (const struct subprocess_s *const process)
	Get the standard error file for a process.
subprocess_weak int	subprocess_join (struct subprocess_s *const process, int *const out_return_code)
	Wait for a process to finish execution.
subprocess_weak int	subprocess_destroy (struct subprocess_s *const process)
	Destroy a previously created process.
subprocess_weak int	subprocess_terminate (struct subprocess_s *const process)
	Terminate a previously created process.
subprocess_weak unsigned	subprocess_read_stdout (struct subprocess_s *const process, char *const buffer, unsigned size)
	Read the standard output from the child process.
subprocess_weak unsigned	subprocess_read_stderr (struct subprocess_s *const process, char *const buffer, unsigned size)
	Read the standard error from the child process.
subprocess_weak int	subprocess_alive (struct subprocess_s *const process)
	Returns if the subprocess is currently still alive and executing.

Macro Definition Documentation

SUBPROCESS_ATTRIBUTE

#define SUBPROCESS_ATTRIBUTE

(

a

)

Value:

__attribute__((a))

Definition at line 54 of file subprocess.h.

SUBPROCESS_CAST

#define SUBPROCESS_CAST	(		type,
			x )

Value:

((type)(x))

Definition at line 227 of file subprocess.h.

SUBPROCESS_CONST_CAST

#define SUBPROCESS_CONST_CAST	(		type,
			x )

Value:

((type)(x))

Definition at line 229 of file subprocess.h.

SUBPROCESS_NULL

#define SUBPROCESS_NULL   0

Definition at line 230 of file subprocess.h.

SUBPROCESS_PTR_CAST

#define SUBPROCESS_PTR_CAST	(		type,
			x )

Value:

((type)(x))

Definition at line 228 of file subprocess.h.

SUBPROCESS_ZERO

#define SUBPROCESS_ZERO   0

Definition at line 231 of file subprocess.h.

Typedef Documentation

subprocess_size_t

typedef size_t subprocess_size_t

Definition at line 397 of file subprocess.h.

Enumeration Type Documentation

subprocess_option_e

enum subprocess_option_e

Enumerator
subprocess_option_combined_stdout_stderr
subprocess_option_inherit_environment
subprocess_option_enable_async
subprocess_option_no_window
subprocess_option_search_user_path

Definition at line 75 of file subprocess.h.

Function Documentation

subprocess_alive()

int subprocess_alive

(

struct subprocess_s *const

process

)

Returns if the subprocess is currently still alive and executing.

Parameters

process

The process to check.

Returns

If the process is still alive non-zero is returned.

Definition at line 1151 of file subprocess.h.

subprocess_create()

int subprocess_create	(	const char *const	command_line[],
		int	options,
		struct subprocess_s *const	out_process )

Create a process.

Parameters

command_line	An array of strings for the command line to execute for this process. The last element must be NULL to signify the end of the array. The memory backing this parameter only needs to persist until this function returns.
options	A bit field of subprocess_option_e's to pass.
out_process	The newly created process.

Returns

On success zero is returned.

Definition at line 484 of file subprocess.h.

subprocess_create_ex()

int subprocess_create_ex	(	const char *const	command_line[],
		int	options,
		const char *const	environment[],
		struct subprocess_s *const	out_process )

Create a process (extended create).

Parameters

command_line	An array of strings for the command line to execute for this process. The last element must be NULL to signify the end of the array. The memory backing this parameter only needs to persist until this function returns.
options	A bit field of subprocess_option_e's to pass.
environment	An optional array of strings for the environment to use for a child process (each element of the form FOO=BAR). The last element must be NULL to signify the end of the array.
out_process	The newly created process.

Returns

On success zero is returned.

If options contains subprocess_option_inherit_environment, then environment must be NULL.

Definition at line 490 of file subprocess.h.

subprocess_destroy()

int subprocess_destroy

(

struct subprocess_s *const

process

)

Destroy a previously created process.

Parameters

process

The process to destroy.

Returns

On success zero is returned.

If the process to be destroyed had not finished execution, it may out live the parent process.

Definition at line 1004 of file subprocess.h.

subprocess_join()

int subprocess_join	(	struct subprocess_s *const	process,
		int *const	out_return_code )

Wait for a process to finish execution.

Parameters

process	The process to wait for.
out_return_code	The return code of the returned process (can be NULL).

Returns

On success zero is returned.

Joining a process will close the stdin pipe to the process.

Definition at line 944 of file subprocess.h.

subprocess_read_stderr()

unsigned subprocess_read_stderr	(	struct subprocess_s *const	process,
		char *const	buffer,
		unsigned	size )

Read the standard error from the child process.

Parameters

process	The process to read from.
buffer	The buffer to read into.
size	The maximum number of bytes to read.

Returns

The number of bytes actually read into buffer. Can only be 0 if the process has complete.

The only safe way to read from the standard error of a process during it's execution is to use the subprocess_option_enable_async option in conjunction with this method.

Definition at line 1106 of file subprocess.h.

subprocess_read_stdout()

unsigned subprocess_read_stdout	(	struct subprocess_s *const	process,
		char *const	buffer,
		unsigned	size )

Read the standard output from the child process.

Parameters

process	The process to read from.
buffer	The buffer to read into.
size	The maximum number of bytes to read.

Returns

The number of bytes actually read into buffer. Can only be 0 if the process has complete.

The only safe way to read from the standard output of a process during it's execution is to use the subprocess_option_enable_async option in conjunction with this method.

Definition at line 1061 of file subprocess.h.

subprocess_stderr()

FILE * subprocess_stderr

(

const struct subprocess_s *const

process

)

Get the standard error file for a process.

Parameters

process

The process to query.

Returns

The file for standard error of the process.

The file returned can be read from by the parent process to read data from the standard error of the child process.

If the process was created with the subprocess_option_combined_stdout_stderr option bit set, this function will return NULL, and the subprocess_stdout function should be used for both the standard output and error combined.

Definition at line 936 of file subprocess.h.

subprocess_stdin()

FILE * subprocess_stdin

(

const struct subprocess_s *const

process

)

Get the standard input file for a process.

Parameters

process

The process to query.

Returns

The file for standard input of the process.

The file returned can be written to by the parent process to feed data to the standard input of the process.

Definition at line 928 of file subprocess.h.

subprocess_stdout()

FILE * subprocess_stdout

(

const struct subprocess_s *const

process

)

Get the standard output file for a process.

Parameters

process

The process to query.

Returns

The file for standard output of the process.

The file returned can be read from by the parent process to read data from the standard output of the child process.

Definition at line 932 of file subprocess.h.

subprocess_terminate()

int subprocess_terminate

(

struct subprocess_s *const

process

)

Terminate a previously created process.

Parameters

process

The process to terminate.

Returns

On success zero is returned.

If the process to be destroyed had not finished execution, it will be terminated (i.e killed).

Definition at line 1043 of file subprocess.h.