The process handle. More...

#include <process.h>

Inheritance diagram for uvw::process_handle:

[legend]

Collaboration diagram for uvw::process_handle:

[legend]

Public Member Functions
int	init ()
	Initializes the handle.

int	spawn (const char file, char args, char *env=nullptr)
	spawn Starts the process.

int	kill (int signum)
	Sends the specified signal to the internal process handle.

int	pid () noexcept
	Gets the PID of the spawned process.

process_handle &	cwd (const std::string &path) noexcept
	Sets the current working directory for the subprocess.

process_handle &	flags (process_flags flags) noexcept
	Sets flags that control how `spawn()` behaves.

template<typename T, typename U, typename... E>
process_handle &	stdio (stream_handle< T, U, E... > &stream, stdio_flags flags)
	Makes a `stdio` handle available to the child process.

process_handle &	stdio (file_handle fd, stdio_flags flags)
	Makes a file descriptor available to the child process.

process_handle &	uid (uid_type id)
	Sets the child process' user id.

process_handle &	gid (gid_type id)
	Sets the child process' group id.

Public Member Functions inherited from uvw::handle< process_handle, uv_process_t, exit_event >
handle_category	category () const noexcept
	Gets the category of the handle.

handle_type	type () const noexcept
	Gets the type of the handle.

bool	active () const noexcept
	Checks if the handle is active.

bool	closing () const noexcept
	Checks if a handle is closing or closed.

void	close () noexcept
	Request handle to be closed.

void	reference () noexcept
	Reference the given handle.

void	unreference () noexcept
	Unreference the given handle.

bool	referenced () const noexcept
	Checks if the given handle referenced.

std::size_t	size () const noexcept
	Returns the size of the underlying handle type.

int	send_buffer_size ()
	Gets the size of the send buffer used for the socket.

int	send_buffer_size (int value)
	Sets the size of the send buffer used for the socket.

int	recv_buffer_size ()
	Gets the size of the receive buffer used for the socket.

int	recv_buffer_size (int value)
	Sets the size of the receive buffer used for the socket.

os_file_descriptor	fd () const
	Gets the platform dependent file descriptor equivalent.

Public Member Functions inherited from uvw::resource< process_handle, uv_process_t, close_event, E... >
std::shared_ptr< R >	data () const
	Gets user-defined data. `uvw` won't use this field in any case.

void	data (std::shared_ptr< void > udata)
	Sets arbitrary data. `uvw` won't use this field in any case.

Public Member Functions inherited from uvw::uv_type< uv_process_t >
loop &	parent () const noexcept
	Gets the loop from which the resource was originated.

const uv_process_t *	raw () const noexcept
	Gets the underlying raw data structure.

uv_process_t *	raw () noexcept
	Gets the underlying raw data structure.

Public Member Functions inherited from uvw::emitter< process_handle, E... >
void	on (listener_t< Type > f)
	Registers a long-lived listener with the event emitter.

void	reset () noexcept
	Disconnects the listener for the given event type.

void	reset () noexcept
	Disconnects all listeners.

bool	has () const noexcept
	Checks if there is a listener registered for the specific event.

Static Public Member Functions
static void	disable_stdio_inheritance () noexcept
	Disables inheritance for file descriptors/handles.

static bool	kill (int pid, int signum) noexcept
	kill Sends the specified signal to the given PID.

Detailed Description

The process handle.

Process handles will spawn a new process and allow the user to control it and establish communication channels with it using streams.

Definition at line 59 of file process.h.

Member Function Documentation

◆ cwd()

process_handle & uvw::process_handle::cwd ( const std::string & path )

noexcept

Sets the current working directory for the subprocess.

Parameters

path	The working directory to be used when `spawn()` is invoked.

Returns: A reference to this process handle.

◆ disable_stdio_inheritance()

static void uvw::process_handle::disable_stdio_inheritance ( )

staticnoexcept

Disables inheritance for file descriptors/handles.

Disables inheritance for file descriptors/handles that this process inherited from its parent. The effect is that child processes spawned by this process don’t accidentally inherit these handles.
It is recommended to call this function as early in your program as possible, before the inherited file descriptors can be closed or duplicated.

See the official documentation for further details.

◆ flags()

process_handle & uvw::process_handle::flags ( process_flags flags )

noexcept

Sets flags that control how spawn() behaves.

Available flags are:

process_handle::process_flags::SETUID
process_handle::process_flags::SETGID
process_handle::process_flags::WINDOWS_VERBATIM_ARGUMENTS
process_handle::process_flags::DETACHED
process_handle::process_flags::WINDOWS_HIDE
process_handle::process_flags::WINDOWS_HIDE_CONSOLE
process_handle::process_flags::WINDOWS_HIDE_GUI
process_handle::process_flags::WINDOWS_FILE_PATH_EXACT_NAME

See the official documentation for further details.

Parameters

flags A valid set of flags.

Returns: A reference to this process handle.

◆ gid()

process_handle & uvw::process_handle::gid ( gid_type id )

Sets the child process' group id.

Parameters

id	A valid group id to be used.

Returns: A reference to this process handle.

◆ init()

int uvw::process_handle::init ( )

Initializes the handle.

Returns: Underlying return value.

◆ kill() [1/2]

static bool uvw::process_handle::kill	(	int	pid,
		int	signum )

staticnoexcept

kill Sends the specified signal to the given PID.

Parameters

pid	A valid process id.
signum	A valid signal identifier.

Returns: True in case of success, false otherwise.

◆ kill() [2/2]

int uvw::process_handle::kill ( int signum )

Sends the specified signal to the internal process handle.

Parameters

signum A valid signal identifier.

Returns: Underlying return value.

◆ pid()

int uvw::process_handle::pid ( )

noexcept

Gets the PID of the spawned process.

It’s set after calling spawn().

Returns: The PID of the spawned process.

◆ spawn()

int uvw::process_handle::spawn	(	const char *	file,
		char **	args,
		char **	env = nullptr )

spawn Starts the process.

See the official documentation for further details.

Parameters

file	Path pointing to the program to be executed.
args	Command line arguments.
env	Optional environment for the new process.

Returns: Underlying return value.

◆ stdio() [1/2]

process_handle & uvw::process_handle::stdio	(	file_handle	fd,
		stdio_flags	flags )

Makes a file descriptor available to the child process.

Available flags are:

process_handle::stdio_flags::IGNORE_STREAM
process_handle::stdio_flags::CREATE_PIPE
process_handle::stdio_flags::INHERIT_FD
process_handle::stdio_flags::INHERIT_STREAM
process_handle::stdio_flags::READABLE_PIPE
process_handle::stdio_flags::WRITABLE_PIPE
process_handle::stdio_flags::OVERLAPPED_PIPE

Default file descriptors are:

uvw::std_in for stdin
uvw::std_out for stdout
uvw::std_err for stderr

See the official documentation for further details.

Parameters

fd	A valid file descriptor.
flags	A valid set of flags.

Returns: A reference to this process handle.

◆ stdio() [2/2]

template<typename T, typename U, typename... E>

process_handle & uvw::process_handle::stdio	(	stream_handle< T, U, E... > &	stream,
		stdio_flags	flags )

inline

Makes a stdio handle available to the child process.

Available flags are:

process_handle::stdio_flags::IGNORE_STREAM
process_handle::stdio_flags::CREATE_PIPE
process_handle::stdio_flags::INHERIT_FD
process_handle::stdio_flags::INHERIT_STREAM
process_handle::stdio_flags::READABLE_PIPE
process_handle::stdio_flags::WRITABLE_PIPE
process_handle::stdio_flags::OVERLAPPED_PIPE

See the official documentation for further details.

Parameters

stream	A valid `stdio` handle.
flags	A valid set of flags.

Returns: A reference to this process handle.

Definition at line 180 of file process.h.

◆ uid()

process_handle & uvw::process_handle::uid ( uid_type id )

Sets the child process' user id.

Parameters

id	A valid user id to be used.

Returns: A reference to this process handle.

The documentation for this class was generated from the following file:

src/uvw/process.h

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ cwd()

◆ disable_stdio_inheritance()

◆ flags()

◆ gid()

◆ init()

◆ kill() [1/2]

◆ kill() [2/2]

◆ pid()

◆ spawn()

◆ stdio() [1/2]

◆ stdio() [2/2]

◆ uid()