uvw 2.12.1
Loading...
Searching...
No Matches
uvw::ProcessHandle Class Referencefinal

The ProcessHandle handle. More...

#include <process.h>

Inheritance diagram for uvw::ProcessHandle:
Collaboration diagram for uvw::ProcessHandle:

Public Member Functions

bool init ()
 Initializes the handle.
 
void spawn (const char *file, char **args, char **env=nullptr)
 spawn Starts the process.
 
void kill (int signum)
 Sends the specified signal to the internal process handle.
 
int pid () noexcept
 Gets the PID of the spawned process.
 
ProcessHandlecwd (const std::string &path) noexcept
 Sets the current working directory for the subprocess.
 
ProcessHandleflags (Flags< Process > flags) noexcept
 Sets flags that control how spawn() behaves.
 
template<typename T , typename U >
ProcessHandlestdio (StreamHandle< T, U > &stream, Flags< StdIO > flags)
 Makes a stdio handle available to the child process.
 
ProcessHandlestdio (FileHandle fd, Flags< StdIO > flags)
 Makes a file descriptor available to the child process.
 
ProcessHandleuid (Uid id)
 Sets the child process' user id.
 
ProcessHandlegid (Gid id)
 Sets the child process' group id.
 
- Public Member Functions inherited from uvw::Handle< ProcessHandle, uv_process_t >
HandleCategory category () const noexcept
 Gets the category of the handle.
 
HandleType 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 sendBufferSize ()
 Gets the size of the send buffer used for the socket.
 
bool sendBufferSize (int value)
 Sets the size of the send buffer used for the socket.
 
int recvBufferSize ()
 Gets the size of the receive buffer used for the socket.
 
bool recvBufferSize (int value)
 Sets the size of the receive buffer used for the socket.
 
OSFileDescriptor fd () const
 Gets the platform dependent file descriptor equivalent.
 
- Public Member Functions inherited from uvw::Resource< ProcessHandle, uv_process_t >
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::UnderlyingType< ProcessHandle, uv_process_t >
Looploop () 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< ProcessHandle >
Connection< E > on (Listener< E > f)
 Registers a long-lived listener with the event emitter.
 
Connection< E > once (Listener< E > f)
 Registers a short-lived listener with the event emitter.
 
void erase (Connection< E > conn) noexcept
 Disconnects a listener from the event emitter.
 
void clear () noexcept
 Disconnects all the listeners for the given event type.
 
void clear () noexcept
 Disconnects all the listeners.
 
bool empty () const noexcept
 Checks if there are listeners registered for the specific event.
 
bool empty () const noexcept
 Checks if there are listeners registered with the event emitter.
 

Static Public Member Functions

static void disableStdIOInheritance () noexcept
 Disables inheritance for file descriptors/handles.
 
static bool kill (int pid, int signum) noexcept
 kill Sends the specified signal to the given PID.
 
- Static Public Member Functions inherited from uvw::UnderlyingType< ProcessHandle, uv_process_t >
static std::shared_ptr< ProcessHandlecreate (Args &&...args)
 Creates a new resource of the given type.
 

Detailed Description

The ProcessHandle 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 58 of file process.h.

Member Function Documentation

◆ cwd()

ProcessHandle & uvw::ProcessHandle::cwd ( const std::string & path)
noexcept

Sets the current working directory for the subprocess.

Parameters
pathThe working directory to be used when spawn() is invoked.
Returns
A reference to this process handle.

◆ disableStdIOInheritance()

static void uvw::ProcessHandle::disableStdIOInheritance ( )
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()

ProcessHandle & uvw::ProcessHandle::flags ( Flags< Process > flags)
noexcept

Sets flags that control how spawn() behaves.

Available flags are:

  • ProcessHandle::Process::SETUID
  • ProcessHandle::Process::SETGID
  • ProcessHandle::Process::WINDOWS_VERBATIM_ARGUMENTS
  • ProcessHandle::Process::DETACHED
  • ProcessHandle::Process::WINDOWS_HIDE
  • ProcessHandle::Process::WINDOWS_HIDE_CONSOLE
  • ProcessHandle::Process::WINDOWS_HIDE_GUI

See the official documentation for further details.

Parameters
flagsA valid set of flags.
Returns
A reference to this process handle.

◆ gid()

ProcessHandle & uvw::ProcessHandle::gid ( Gid id)

Sets the child process' group id.

Parameters
idA valid group id to be used.
Returns
A reference to this process handle.

◆ init()

bool uvw::ProcessHandle::init ( )

Initializes the handle.

Returns
True in case of success, false otherwise.

◆ kill() [1/2]

static bool uvw::ProcessHandle::kill ( int pid,
int signum )
staticnoexcept

kill Sends the specified signal to the given PID.

Parameters
pidA valid process id.
signumA valid signal identifier.
Returns
True in case of success, false otherwise.

◆ kill() [2/2]

void uvw::ProcessHandle::kill ( int signum)

Sends the specified signal to the internal process handle.

Parameters
signumA valid signal identifier.

◆ pid()

int uvw::ProcessHandle::pid ( )
noexcept

Gets the PID of the spawned process.

It’s set after calling spawn().

Returns
The PID of the spawned process.

◆ spawn()

void uvw::ProcessHandle::spawn ( const char * file,
char ** args,
char ** env = nullptr )

spawn Starts the process.

If the process isn't successfully spawned, an ErrorEvent event will be emitted by the handle.

See the official documentation for further details.

Parameters
filePath pointing to the program to be executed.
argsCommand line arguments.
envOptional environment for the new process.

◆ stdio() [1/2]

ProcessHandle & uvw::ProcessHandle::stdio ( FileHandle fd,
Flags< StdIO > flags )

Makes a file descriptor available to the child process.

Available flags are:

  • ProcessHandle::StdIO::IGNORE_STREAM
  • ProcessHandle::StdIO::CREATE_PIPE
  • ProcessHandle::StdIO::INHERIT_FD
  • ProcessHandle::StdIO::INHERIT_STREAM
  • ProcessHandle::StdIO::READABLE_PIPE
  • ProcessHandle::StdIO::WRITABLE_PIPE
  • ProcessHandle::StdIO::OVERLAPPED_PIPE

Default file descriptors are:

See the official documentation for further details.

Parameters
fdA valid file descriptor.
flagsA valid set of flags.
Returns
A reference to this process handle.

◆ stdio() [2/2]

template<typename T , typename U >
ProcessHandle & uvw::ProcessHandle::stdio ( StreamHandle< T, U > & stream,
Flags< StdIO > flags )
inline

Makes a stdio handle available to the child process.

Available flags are:

  • ProcessHandle::StdIO::IGNORE_STREAM
  • ProcessHandle::StdIO::CREATE_PIPE
  • ProcessHandle::StdIO::INHERIT_FD
  • ProcessHandle::StdIO::INHERIT_STREAM
  • ProcessHandle::StdIO::READABLE_PIPE
  • ProcessHandle::StdIO::WRITABLE_PIPE
  • ProcessHandle::StdIO::OVERLAPPED_PIPE

See the official documentation for further details.

Parameters
streamA valid stdio handle.
flagsA valid set of flags.
Returns
A reference to this process handle.

Definition at line 179 of file process.h.

◆ uid()

ProcessHandle & uvw::ProcessHandle::uid ( Uid id)

Sets the child process' user id.

Parameters
idA valid user id to be used.
Returns
A reference to this process handle.

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