subprocess Namespace Reference

Namespaces
namespace	details

Classes
struct	CalledProcessError
struct	CommandNotFoundError
struct	CompletedProcess
class	CwdGuard
class	EnvGuard
class	Environ
class	EnvironSetter
struct	OSError
struct	PipePair
struct	Popen
class	ProcessBuilder
struct	RunBuilder
struct	RunOptions
struct	SpawnError
class	StopWatch
struct	SubprocessError
struct	TimeoutExpired

Typedefs
typedef intptr_t	ssize_t
typedef int	PipeHandle
typedef ::pid_t	pid_t
typedef std::vector< std::string >	CommandLine
typedef std::map< std::string, std::string >	EnvMap
typedef std::variant< PipeOption, std::string, PipeHandle, std::istream *, std::ostream *, FILE * >	PipeVar

Enumerations
enum	SigNum {   PSIGHUP = 1 , PSIGINT = SIGINT , PSIGQUIT = 3 , PSIGILL = SIGILL ,   PSIGTRAP = 5 , PSIGABRT = SIGABRT , PSIGIOT = 6 , PSIGBUS = 7 ,   PSIGFPE = SIGFPE , PSIGKILL = 9 , PSIGUSR1 = 10 , PSIGSEGV = SIGSEGV ,   PSIGUSR2 = 12 , PSIGPIPE = 13 , PSIGALRM = 14 , PSIGTERM = SIGTERM ,   PSIGSTKFLT = 16 , PSIGCHLD = 17 , PSIGCONT = 18 , PSIGSTOP = 19 ,   PSIGTSTP = 20 , PSIGTTIN = 21 , PSIGTTOU = 22 , PSIGURG = 23 ,   PSIGXCPU = 24 , PSIGXFSZ = 25 , PSIGVTALRM = 26 , PSIGPROF = 27 ,   PSIGWINCH = 28 , PSIGIO = 29 }
enum class	PipeOption : int {   inherit , cout , cerr , specific ,   pipe , close }
enum class	PipeVarIndex {   option , string , handle , istream ,   ostream , file }

Functions
EnvMap	current_env_copy ()
ssize_t	pipe_peak_bytes (PipeHandle pipe)
bool	pipe_close (PipeHandle handle)
PipePair	pipe_create (bool inheritable=false)
void	pipe_set_inheritable (PipeHandle handle, bool inheritable)
ssize_t	pipe_read (PipeHandle, void *buffer, size_t size)
ssize_t	pipe_write (PipeHandle, const void *buffer, size_t size)
bool	pipe_set_blocking (PipeHandle, bool should_block)
void	pipe_ignore_and_close (PipeHandle handle)
std::string	pipe_read_all (PipeHandle handle)
int	pipe_wait_for_read (PipeHandle pipe, double seconds)
ssize_t	pipe_read_some (PipeHandle, void *buffer, size_t size)
PipeHandle	pipe_file (const char *filename, const char *mode)
PipeOption	get_pipe_option (const PipeVar &option)
CompletedProcess	run (Popen &popen, bool check=false)
CompletedProcess	run (CommandLine command, RunOptions options={})
double	monotonic_seconds ()
double	sleep_seconds (double seconds)
std::string	getenv (const std::string &var)
std::string	find_program (const std::string &name)
void	find_program_clear_cache ()
std::string	escape_shell_arg (std::string arg)
std::string	getcwd ()
void	setcwd (const std::string &path)
std::string	abspath (std::string dir, std::string relativeTo="")

Variables
constexpr bool	kIsWin32 = false
constexpr char	kPathDelimiter = ':'
const PipeHandle	kBadPipeValue = (PipeHandle)-1
constexpr int	kStdInValue = 0
constexpr int	kStdOutValue = 1
constexpr int	kStdErrValue = 2
constexpr int	kBadReturnCode = -1000
Environ	cenv

Typedef Documentation

CommandLine

typedef std::vector<std::string> subprocess::CommandLine

EnvMap

typedef std::map<std::string, std::string> subprocess::EnvMap

pid_t

typedef ::pid_t subprocess::pid_t

PipeHandle

typedef int subprocess::PipeHandle

PipeVar

typedef std::variant<PipeOption, std::string, PipeHandle, std::istream*, std::ostream*, FILE*> subprocess::PipeVar

ssize_t

typedef intptr_t subprocess::ssize_t

Enumeration Type Documentation

PipeOption

enum class subprocess::PipeOption : int

strong

Redirect destination

Enumerator
inherit	Inherits current process handle.
cout	Redirects to stdout.
cerr	redirects to stderr
specific	Redirects to provided pipe. You can open /dev/null. Pipe handle that you specify will be made inheritable and closed automatically.
pipe	Redirects to a new handle created for you.
close	Troll the child by providing a closed pipe.

PipeVarIndex

enum class subprocess::PipeVarIndex

strong

Enumerator
option
string
handle
istream
ostream
file

SigNum

enum subprocess::SigNum

Signals to send. they start with P because SIGX are macros, P stands for Posix as these values are as defined by Posix.

Enumerator
PSIGHUP
PSIGINT
PSIGQUIT
PSIGILL
PSIGTRAP
PSIGABRT
PSIGIOT
PSIGBUS
PSIGFPE
PSIGKILL
PSIGUSR1
PSIGSEGV
PSIGUSR2
PSIGPIPE
PSIGALRM
PSIGTERM
PSIGSTKFLT
PSIGCHLD
PSIGCONT
PSIGSTOP
PSIGTSTP
PSIGTTIN
PSIGTTOU
PSIGURG
PSIGXCPU
PSIGXFSZ
PSIGVTALRM
PSIGPROF
PSIGWINCH
PSIGIO

Function Documentation

abspath()

std::string subprocess::abspath	(	std::string	dir,
		std::string	relativeTo = ""
	)

Converts dir to be absolute path.

Parameters

dir	The path you want to be absolute.
relativeTo	If specified use this instead of the current working directory.

Returns

the absolute path.

current_env_copy()

EnvMap subprocess::current_env_copy

(

)

Creates a copy of current environment variables and returns the map

escape_shell_arg()

std::string subprocess::escape_shell_arg

(

std::string

arg

)

Escapes the argument suitable for use on command line.

find_program()

std::string subprocess::find_program

(

const std::string &

name

)

Searches for program in PATH environment variable.

on windows tries adding suffixes specified in PATHEXT environment variable.

on windows an input of "python3" will also search "python" executables and inspect their version to find an executable that offers python 3.x.

find_program_clear_cache()

void subprocess::find_program_clear_cache

(

)

Clears cache used by find_program.

find_program uses internal cache to find executables. If you modify PATH using subprocess::cenv this will be called automatically for you. If a new program is added to a folder with the same name as an existing program you may want to clear the cache so that the new program is found as expected instead of the old program being returned.

get_pipe_option()

PipeOption subprocess::get_pipe_option ( const PipeVar &  option )

inline

getcwd()

std::string subprocess::getcwd

(

)

Gets the current working directory of the process

getenv()

std::string subprocess::getenv

(

const std::string &

var

)

Get the value of environment variable

monotonic_seconds()

double subprocess::monotonic_seconds

(

)

Returns

seconds went by from some origin monotonically increasing.

pipe_close()

bool subprocess::pipe_close

(

PipeHandle

handle

)

Closes a pipe handle.

Parameters

handle

The handle to close.

Returns

true on success

pipe_create()

PipePair subprocess::pipe_create

(

bool

inheritable = false

)

Creates a pair of pipes for input/output

Parameters

inheritable

if true subprocesses will inherit the pipe.

Exceptions

OSError

if system call fails.

Returns

pipe pair. If failure returned pipes will have values of kBadPipeValue

Since

0.5.0 inheritable default is changed from true to false. The underlaying OS API's make inheritable true by default and so making it not inheritble is extra work which is why true was default here too. But practically this is annoying because you only want to inherit 1 end of the pipe. If this is not false the child will inherit the other end and will never get EOF if you close your end. The subprocess API's will automatically enforce the correct end of the pipe to be inheritable. Most of the time you never have to think about this, and likely this breaking change will fix bug for you. If you have an explicit reason to make both ends to be inheritble at creation then you likely have a bug.

pipe_file()

PipeHandle subprocess::pipe_file	(	const char *	filename,
		const char *	mode
	)

Opens a file and returns the handle.

You must call pipe_close() on the returned handle. When using as a parameter to Popen or run(), pipe_close should not be called as ownership will be taken.

Parameters

filename	The file path
mode	The mode as from fopen. Always binary mode. r - read only, will fail if file doesn't exist w - write only and will create or truncate the file - allow read/write

Returns

the handle to the opened file, or kBadPipeValue on error

pipe_ignore_and_close()

void subprocess::pipe_ignore_and_close

(

PipeHandle

handle

)

Spawns a thread to read from the pipe. When no more data available pipe will be closed.

pipe_peak_bytes()

ssize_t subprocess::pipe_peak_bytes

(

PipeHandle

pipe

)

Peak into how many bytes available in pipe to read.

pipe_read()

ssize_t subprocess::pipe_read	(	PipeHandle	,
		void *	buffer,
		size_t	size
	)

Returns

-1 on error. if 0 it could be the end, or perhaps wait for more data.

pipe_read_all()

std::string subprocess::pipe_read_all

(

PipeHandle

handle

)

Read contents of handle until no more data is available.

If the pipe is non-blocking this will end prematurely.

Returns

all data read from pipe as a string object. This works fine with binary data.

pipe_read_some()

ssize_t subprocess::pipe_read_some	(	PipeHandle	,
		void *	buffer,
		size_t	size
	)

Will read up to size and not block until buffer is filled.

pipe_set_blocking()

bool subprocess::pipe_set_blocking	(	PipeHandle	,
		bool	should_block
	)

Sets the blocking bit.

The handle state is first queried as to only change the blocking bit.

Parameters

should_block

If false then pipe_read/write will exit early if there is no blocking.

Returns

true on success

pipe_set_inheritable()

void subprocess::pipe_set_inheritable	(	PipeHandle	handle,
		bool	inheritable
	)

Set the pipe to be inheritable or not for subprocess.

Exceptions

OSError

if system call fails.

Parameters

inheritable

if true handle will be inherited in subprocess.

pipe_wait_for_read()

int subprocess::pipe_wait_for_read	(	PipeHandle	pipe,
		double	seconds
	)

Waits for the pipes to be change state.

Parameters

pipes	pointer to first pipe in an array
did_change	pointer to an output of the first pipe that changed state
count	number of pipes
seconds	The timeout in seconds to wait for. -1 for indefinate

pipe_write()

ssize_t subprocess::pipe_write	(	PipeHandle	,
		const void *	buffer,
		size_t	size
	)

Returns

-1 on error. if 0 it could be full, or perhaps wait for more data.

run() [1/2]

CompletedProcess subprocess::run	(	CommandLine	command,
		RunOptions	options = {}
	)

Run a command blocking until completion.

see subprocess::run(Popen&,bool) for more details about exceptions.

Parameters

command	The command to run. First element must be executable.
options	Options specifying how to run the command.

Returns

CompletedProcess containing details about execution.

run() [2/2]

CompletedProcess subprocess::run	(	Popen &	popen,
		bool	check = false
	)

If you have stuff to pipe this will run the process to completion.

This will read stdout/stderr if they exist and store in cout, cerr.

Parameters

popen	An already running process.
check	if true will throw CalledProcessException if process returns non-zero exit code.

Returns

a Filled out CompletedProcess.

Exceptions

CalledProcessError	if check=true and process returned non-zero error code
TimeoutExpired	if subprocess does not finish by timeout seconds.
OSError	for os level exceptions such as failing OS commands.
std::runtime_error	for various errors.
std::invalid_argument	if argument is invalid for current usage.
std::domain_error	when arguments don't make sense working together

Returns

a CompletedProcess once the command has finished.

setcwd()

void subprocess::setcwd

(

const std::string &

path

)

Sets the current working directory of process.

sleep_seconds()

double subprocess::sleep_seconds

(

double

seconds

)

Sleep for a number of seconds.

Parameters

seconds

The number of seconds to sleep for.

Returns

how many seconds have been slept.

Variable Documentation

cenv

Environ subprocess::cenv

extern

Makes it easy to get/set environment variables. e.g. like so subprocess::cenv["VAR"] = "Value";

kBadPipeValue

const PipeHandle subprocess::kBadPipeValue = (PipeHandle)-1

The value representing an invalid pipe

kBadReturnCode

constexpr int subprocess::kBadReturnCode = -1000

constexpr

The value representing an invalid exit code possible for a process.

kIsWin32

constexpr bool subprocess::kIsWin32 = false

constexpr

kPathDelimiter

constexpr char subprocess::kPathDelimiter = ':'

constexpr

The path seperator for PATH environment variable.

kStdErrValue

constexpr int subprocess::kStdErrValue = 2

constexpr

kStdInValue

constexpr int subprocess::kStdInValue = 0

constexpr

kStdOutValue

constexpr int subprocess::kStdOutValue = 1

constexpr