subprocess Namespace Reference

Namespaces
	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	PipeOption : int {   PipeOption::inherit, PipeOption::cout, PipeOption::cerr, PipeOption::specific,   PipeOption::pipe, PipeOption::close }
enum	PipeVarIndex {   PipeVarIndex::option, PipeVarIndex::string, PipeVarIndex::handle, PipeVarIndex::istream,   PipeVarIndex::ostream, PipeVarIndex::file }

Functions
EnvMap	current_env_copy ()
std::u16string	create_env_block (const EnvMap &map)
bool	pipe_close (PipeHandle handle)
PipePair	pipe_create (bool inheritable=true)
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)
void	pipe_ignore_and_close (PipeHandle handle)
std::string	pipe_read_all (PipeHandle handle)
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 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 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.

create_env_block()

std::u16string subprocess::create_env_block

(

const EnvMap &

map

)

Gives an environment block used in Windows APIs. Each item is null terminated, end of list is double null-terminated and conforms to expectations of various windows API.

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 = true

)

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

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_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_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_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

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