CMUTIL_Process Struct Reference

structure for managing external processes. More...

Data Fields
CMBool(*	Start )(CMUTIL_Process *proc, CMProcStreamType type)
	Start the process.
pid_t(*	GetPid )(CMUTIL_Process *proc)
	Retrieves the process identifier (PID) of the specified process.
const char *(*	GetCommand )(CMUTIL_Process *proc)
	Function pointer to retrieve the command associated with a given process.
const char *(*	GetWorkDir )(CMUTIL_Process *proc)
	Function pointer to retrieve the working directory of a given process.
const CMUTIL_StringArray *(*	GetArgs )(CMUTIL_Process *proc)
	Function pointer to retrieve the argument list of a process.
const CMUTIL_Map *(*	GetEnv )(CMUTIL_Process *proc)
	Retrieves the environment map for a specified process.
void(*	Suspend )(CMUTIL_Process *proc)
	Suspends the execution of the specified process.
void(*	Resume )(CMUTIL_Process *proc)
	Resumes the execution of the specified process.
CMBool(*	PipeTo )(CMUTIL_Process *proc, CMUTIL_Process *target)
	Establishes a unidirectional pipe between two processes.
ssize_t(*	Write )(CMUTIL_Process *proc, const void *buf, size_t count)
	Write data to the process's stdin.
ssize_t(*	Read )(CMUTIL_Process *proc, CMUTIL_ByteBuffer *buf, size_t count)
	Read data from the process's stdout.
int(*	Wait )(CMUTIL_Process *proc, long millis)
	Waits for the specified process to complete.
void(*	Kill )(CMUTIL_Process *proc)
	Terminates the specified process.
void(*	Destroy )(CMUTIL_Process *proc)
	Frees resources associated with the specified process.
ssize_t(*	ReadErr )(CMUTIL_Process *proc, CMUTIL_ByteBuffer *buf, size_t count)
	Read data from the process's stderr.

Detailed Description

structure for managing external processes.

Field Documentation

Start

CMBool(* CMUTIL_Process::Start) (CMUTIL_Process *proc, CMProcStreamType type)

Start the process.

If the process is already running, this function will return CMFalse.

Parameters

proc	The process to start.
type	The combination of the type of stream to use for the process.

Returns

CMTrue if the process started successfully, CMFalse otherwise.

GetPid

pid_t(* CMUTIL_Process::GetPid) (CMUTIL_Process *proc)

Retrieves the process identifier (PID) of the specified process.

This function returns the PID of the process represented by the given CMUTIL_Process instance. If the process is not running or is in an invalid state, the behavior is implementation-defined.

Parameters

proc	The process from which to retrieve the PID.

Returns

The PID of the specified process, or an appropriate error indicator if the PID cannot be retrieved.

GetCommand

const char *(* CMUTIL_Process::GetCommand) (CMUTIL_Process *proc)

Function pointer to retrieve the command associated with a given process.

This variable points to a function that, given a process instance, returns the associated command in the form of a null-terminated string.

Parameters

proc	Pointer to a CMUTIL_Process instance representing the process.

Returns

const char* Null-terminated string representing the command associated with the specified process. Returns nullptr if the command cannot be retrieved or is not available.

GetWorkDir

const char *(* CMUTIL_Process::GetWorkDir) (CMUTIL_Process *proc)

Function pointer to retrieve the working directory of a given process.

This function takes a pointer to a CMUTIL_Process structure and returns a constant character pointer representing the working directory of the specified process.

Parameters

proc	A pointer to a CMUTIL_Process structure representing the process whose working directory is to be retrieved.

Returns

A constant character pointer pointing to the working directory of the given process.

GetArgs

const CMUTIL_StringArray *(* CMUTIL_Process::GetArgs) (CMUTIL_Process *proc)

Function pointer to retrieve the argument list of a process.

This function pointer takes a CMUTIL_Process object as input and returns a pointer to a CMUTIL_StringArray containing the arguments associated with the specified process.

Parameters

proc	A pointer to a CMUTIL_Process object whose arguments are to be retrieved.

Returns

A pointer to a CMUTIL_StringArray containing the process arguments.

GetEnv

const CMUTIL_Map *(* CMUTIL_Process::GetEnv) (CMUTIL_Process *proc)

Retrieves the environment map for a specified process.

This function pointer allows access to the environment variables associated with the given process.

Parameters

proc	A pointer to a CMUTIL_Process object whose environment variables are to be retrieved.

Returns

A pointer to a CMUTIL_Map containing the process environment variables.

Suspend

void(* CMUTIL_Process::Suspend) (CMUTIL_Process *proc)

Suspends the execution of the specified process.

This function halts the execution of the given process until it is explicitly resumed. If the process is not running or is in an invalid state, this function does nothing and returns without error.

Parameters

proc	The process to suspend.

Resume

void(* CMUTIL_Process::Resume) (CMUTIL_Process *proc)

Resumes the execution of the specified process.

This function resumes a previously suspended process, allowing it to continue its execution. If the process is not in a suspended state or is in an invalid state, this function does nothing and returns without error.

Parameters

proc	The process to resume.

PipeTo

CMBool(* CMUTIL_Process::PipeTo) (CMUTIL_Process *proc, CMUTIL_Process *target)

Establishes a unidirectional pipe between two processes.

This function creates a communication channel between the stdout of the source process (proc) and the stdin of the target process (target). It facilitates data transfer from one process to another. Both proc and target must be valid, and the state of both processes must not be started for the operation to succeed. This process must be started with CMProcStreamRead or CMProcStreamReadWrite stream type, and the target process must be started with CMProcStreamWrite or CMProcStreamReadWrite stream type.

Parameters

proc	The source process whose stdout will be piped.
target	The target process whose stdin will receive the piped data.

Returns

CMTrue if the pipe was successfully established, CMFalse otherwise.

Write

ssize_t(* CMUTIL_Process::Write) (CMUTIL_Process *proc, const void *buf, size_t count)

Write data to the process's stdin.

If the process is not running, or the stream type is not CMProcStreamWrite or CMProcStreamReadWrite, this function will return -1.

Parameters

proc	The process to write to.
buf	The buffer containing data to write.
count	The number of bytes to write.

Returns

The number of bytes written, or -1 on error.

Read

ssize_t(* CMUTIL_Process::Read) (CMUTIL_Process *proc, CMUTIL_ByteBuffer *buf, size_t count)

Read data from the process's stdout.

If the process is not running, or the stream type is not CMProcStreamRead or CMProcStreamReadWrite, this function will return -1.

Parameters

proc	The process to read from.
buf	The buffer to store the read data.
count	The maximum number of bytes to read.

Returns

The number of bytes read, or -1 on error.

Wait

int(* CMUTIL_Process::Wait) (CMUTIL_Process *proc, long millis)

Waits for the specified process to complete.

This function blocks the calling thread until the specified process finishes execution.

Parameters

proc	The process to wait for.
millis	The maximum time to wait in milliseconds, or -1 to wait infinitely.

Returns

An exit status code from the process, or -1 on error.

Kill

void(* CMUTIL_Process::Kill) (CMUTIL_Process *proc)

Terminates the specified process.

This function attempts to terminate the specified process. If the process is not running, this function will do nothing.

Parameters

proc	The process to terminate.

Destroy

void(* CMUTIL_Process::Destroy) (CMUTIL_Process *proc)

Frees resources associated with the specified process.

This function releases any memory or resources allocated for the given CMUTIL_Process instance. After this function is called, the specified process object should no longer be used.

Parameters

proc	The process whose resources should be freed.

ReadErr

ssize_t(* CMUTIL_Process::ReadErr) (CMUTIL_Process *proc, CMUTIL_ByteBuffer *buf, size_t count)

Read data from the process's stderr.

If the process is not running, or the stream type does not contain CMProcStreamReadErr flag, this function will return -1.

Parameters

proc	The process to read from.
buf	The buffer to store the read data.
count	The maximum number of bytes to read.

Returns

The number of bytes read, or -1 on error.

---

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

• /home/runner/work/libcmutils/libcmutils/src/libcmutils.h