System process access and management functions. More...

#include "gate/gate_core_api.h"
#include "gate/gatetypes.h"
#include "gate/strings.h"
#include "gate/streams.h"

Macros
#define	GATE_PROCESS_ENUM_NAME ((gate_uint16_t)0x0001)
#define	GATE_PROCESS_ENUM_PATH ((gate_uint16_t)0x0002)
#define	GATE_PROCESS_ENUM_OWNER ((gate_uint16_t)0x0004)
#define	GATE_PROCESS_ENUM_MEMORY ((gate_uint16_t)0x0008)
#define	GATE_PROCESS_ENUM_TIMES ((gate_uint16_t)0x0010)
#define	GATE_PROCESS_ENUM_RESOURCES ((gate_uint16_t)0x0020)
#define	GATE_PROCESS_ENUM_ALL ((gate_uint16_t)0xffff)
#define	GATE_PROCESS_START_NEWTERMINAL 0x0001
#define	GATE_PROCESS_START_NEWSESSION 0x0002
#define	GATE_PROCESS_START_USESTDERR 0x0004
#define	GATE_PROCESS_START_NOTERMINAL 0x0100
#define	GATE_PROCESS_START_NOINHERIT 0x0200
#define	GATE_PROCESS_START_SERVICECONTEXT 0x1000
#define	GATE_PROCESS_START_DEFAULTLOCATIONLOGON 0x2000
#define	GATE_PROCESS_START_PRIVILEGED 0x4000
#define	GATE_PROCESS_WAIT_INFINITE ((gate_uint32_t)0xffffffff)

Functions
GATE_CORE_API gate_result_t	gate_process_get_id (gate_process_id_t *pid)
	Retrieves the native process ID of the running process.
GATE_CORE_API void	gate_process_quit (int exitcode)
	Forces the currently running process to immediately terminate.
GATE_CORE_API gate_result_t	gate_process_enum (gate_process_enum_callback_t callback, void *userparam, gate_enumint_t flags)
	Enumerate all running processes and invoke callback with process informations.
GATE_CORE_API gate_result_t	gate_process_getinfo (gate_process_infobuffer_t *dest_buffer, gate_process_id_t proc_id, gate_enumint_t flags)
	Retrieves informations about a single process identified by its PID.
GATE_CORE_API gate_result_t	gate_process_start (gate_string_t const executablepath, gate_string_t const args, gate_size_t argcount, gate_string_t const workdir, gate_string_t const envvars, gate_size_t envvarcount, gate_enumint_t flags, gate_process_handle_t result_handle, gate_process_id_t result_pid, gate_process_stream_t **result_stream)
	Starts a new process.
GATE_CORE_API gate_result_t	gate_process_start_ex (gate_string_t const executablepath, gate_string_t const args, gate_size_t argcount, gate_string_t const workdir, gate_string_t const envvars, gate_size_t envvarcount, gate_enumint_t flags, char const sessionlocation, char const username, char const password, gate_process_handle_t result_handle, gate_process_id_t result_pid, gate_process_stream_t *result_stream)
	Starts a new child process in a different session or user context.
GATE_CORE_API gate_result_t	gate_process_run (gate_string_t const executablepath, gate_string_t const args, gate_size_t argcount, gate_string_t const workdir, gate_string_t const envvars, gate_size_t envvarcount, gate_enumint_t flags, gate_stream_t output, int exit_code)
	Starts a child process and awaits its completion.
GATE_CORE_API gate_result_t	gate_process_close (gate_process_handle_t *handle)
	Closes an opened handle to a child process.
GATE_CORE_API gate_result_t	gate_process_get_exitcode (gate_process_handle_t handle, int exitcode)
	Returns the exit code of a terminated child process.
GATE_CORE_API gate_result_t	gate_process_wait (gate_process_handle_t *handle, gate_uint32_t timeoutms)
	Waits until a process has terminated.
GATE_CORE_API gate_result_t	gate_process_wait_pid (gate_process_id_t pid, gate_uint32_t timeoutms)
	Waits until a process has terminated.
GATE_CORE_API gate_result_t	gate_process_terminate (gate_process_handle_t *handle, gate_bool_t system_request)
	Sends a termination request to process.
GATE_CORE_API gate_result_t	gate_process_terminate_pid (gate_process_id_t pid, gate_bool_t system_request)
	Sends a termination request to process.
GATE_CORE_API gate_result_t	gate_process_kill (gate_process_handle_t *handle)
	Immediately kills a process.
GATE_CORE_API gate_result_t	gate_process_kill_pid (gate_process_id_t pid)
	Immediately kills a process.
GATE_CORE_API gate_result_t	gate_process_suspend (gate_process_handle_t *handle)
	Suspends execution of a running process.
GATE_CORE_API gate_result_t	gate_process_suspend_pid (gate_process_id_t pid)
	Suspends execution of a running process.
GATE_CORE_API gate_result_t	gate_process_resume (gate_process_handle_t *handle)
	Resumes execution of a suspended process.
GATE_CORE_API gate_result_t	gate_process_resume_pid (gate_process_id_t pid)
	Resumes execution of a suspended process.
GATE_CORE_API gate_size_t	gate_process_print_pid (gate_process_id_t pid, char *text, gate_size_t textlen)
	Prints a process ID as readable text.
GATE_CORE_API gate_size_t	gate_process_parse_pid (char const text, gate_size_t textlen, gate_process_id_t pid)
	Parses a text buffer to get a contained printed PID back.

Detailed Description

System process access and management functions.

Macro Definition Documentation

◆ GATE_PROCESS_ENUM_NAME

#define GATE_PROCESS_ENUM_NAME ((gate_uint16_t)0x0001)

retrieve name of process

◆ GATE_PROCESS_ENUM_PATH

#define GATE_PROCESS_ENUM_PATH ((gate_uint16_t)0x0002)

retrieve executable path of process

◆ GATE_PROCESS_ENUM_OWNER

#define GATE_PROCESS_ENUM_OWNER ((gate_uint16_t)0x0004)

retrieve name of user account that owns the process

◆ GATE_PROCESS_ENUM_MEMORY

#define GATE_PROCESS_ENUM_MEMORY ((gate_uint16_t)0x0008)

retrieve memory usage of process

◆ GATE_PROCESS_ENUM_TIMES

#define GATE_PROCESS_ENUM_TIMES ((gate_uint16_t)0x0010)

retrieve up-times of process

◆ GATE_PROCESS_ENUM_RESOURCES

#define GATE_PROCESS_ENUM_RESOURCES ((gate_uint16_t)0x0020)

retrieve amount resources accessed by process

◆ GATE_PROCESS_ENUM_ALL

#define GATE_PROCESS_ENUM_ALL ((gate_uint16_t)0xffff)

retriev all supported process informations

◆ GATE_PROCESS_START_NEWTERMINAL

#define GATE_PROCESS_START_NEWTERMINAL 0x0001

creates a new terminal host for the process

◆ GATE_PROCESS_START_NEWSESSION

#define GATE_PROCESS_START_NEWSESSION 0x0002

new process leads a session (group of processes)

◆ GATE_PROCESS_START_USESTDERR

#define GATE_PROCESS_START_USESTDERR 0x0004

enables std-err, otherwise stderr == stdout

◆ GATE_PROCESS_START_NOTERMINAL

#define GATE_PROCESS_START_NOTERMINAL 0x0100

creates the process without a hosting terminal

◆ GATE_PROCESS_START_NOINHERIT

#define GATE_PROCESS_START_NOINHERIT 0x0200

new process does not inherit handles and file descriptors

◆ GATE_PROCESS_START_SERVICECONTEXT

#define GATE_PROCESS_START_SERVICECONTEXT 0x1000

host runs in service/root context and applies special states

◆ GATE_PROCESS_START_DEFAULTLOCATIONLOGON

#define GATE_PROCESS_START_DEFAULTLOCATIONLOGON 0x2000

applies the default logon of the selected session-location

◆ GATE_PROCESS_START_PRIVILEGED

#define GATE_PROCESS_START_PRIVILEGED 0x4000

applies the highest privileges of the selected session-location

◆ GATE_PROCESS_WAIT_INFINITE

#define GATE_PROCESS_WAIT_INFINITE ((gate_uint32_t)0xffffffff)

wait for an infinit amount of time for a process event

Function Documentation

◆ gate_process_get_id()

GATE_CORE_API gate_result_t gate_process_get_id ( gate_process_id_t * pid )

Retrieves the native process ID of the running process.

Parameters

[out] pid pointer to variable that receives process ID

Returns: GATE_RESULT_* result codes

◆ gate_process_quit()

GATE_CORE_API void gate_process_quit ( int exitcode )

Forces the currently running process to immediately terminate.

Parameters

[in] exitcode Process exit code to return to the OS or parent process

◆ gate_process_enum()

GATE_CORE_API gate_result_t gate_process_enum	(	gate_process_enum_callback_t	callback,
		void *	userparam,
		gate_enumint_t	flags )

Enumerate all running processes and invoke callback with process informations.

Parameters

[in]	callback	Callback to invoke for each process entry
[in]	userparam	User parameter to be passed to callback
[in]	flags	GATE_PROCESS_ENUM_* flags to select which informations are retrieved

Returns: GATE_RESULT_* result codes

◆ gate_process_getinfo()

GATE_CORE_API gate_result_t gate_process_getinfo	(	gate_process_infobuffer_t *	dest_buffer,
		gate_process_id_t	proc_id,
		gate_enumint_t	flags )

Retrieves informations about a single process identified by its PID.

Parameters

[out]	dest_buffer	pointer to process_infobuffer that receives info fields
[in]	proc_id	process ID of process to be queried
[in]	flags	GATE_PROCESS_ENUM_* flags tos select which informations are retrieved

Returns: GATE_RESULT_* result codes

◆ gate_process_start()

GATE_CORE_API gate_result_t gate_process_start	(	gate_string_t const *	executablepath,
		gate_string_t const *	args,
		gate_size_t	argcount,
		gate_string_t const *	workdir,
		gate_string_t const *	envvars,
		gate_size_t	envvarcount,
		gate_enumint_t	flags,
		gate_process_handle_t *	result_handle,
		gate_process_id_t *	result_pid,
		gate_process_stream_t **	result_stream )

Starts a new process.

Parameters

[in]	executablepath	Path to executable file to be started as new child process
[in]	args	Pointer to first argument string in an array of arguments
[in]	argcount	Amount of elements in args array
[in]	workdir	Path of current working directory
[in]	envvars	pointer to first string in an array of environment variables (format: key=value)
[in]	envvarcount	Amount of elements in envvars array
[in]	flags	start bit flags GATE_PROCESS_START_*
[out]	result_handle	pointer to variable that receives handle to control the new child process
[out]	result_pid	pointer to variable that receives the process ID of the new child process
[out]	result_stream	pointer to process_stream pointer that represents IO streams of the new child process

Returns: GATE_RESULT_* result codes

◆ gate_process_start_ex()

GATE_CORE_API gate_result_t gate_process_start_ex	(	gate_string_t const *	executablepath,
		gate_string_t const *	args,
		gate_size_t	argcount,
		gate_string_t const *	workdir,
		gate_string_t const *	envvars,
		gate_size_t	envvarcount,
		gate_enumint_t	flags,
		char const *	sessionlocation,
		char const *	username,
		char const *	password,
		gate_process_handle_t *	result_handle,
		gate_process_id_t *	result_pid,
		gate_process_stream_t **	result_stream )

Starts a new child process in a different session or user context.

Parameters

[in]	executablepath	Path to executable file to be started as new child process
[in]	args	Pointer to first argument string in an array of arguments
[in]	argcount	Amount of elements in args array
[in]	workdir	Path of current working directory
[in]	envvars	pointer to first string in an array of environment variables (format: key=value)
[in]	envvarcount	Amount of elements in envvars array
[in]	flags	start bit flags GATE_PROCESS_START_*
[in]	sessionlocation	string that identifies the target session context of the new process
[in]	username	name of account the process shall run as
[in]	password	password of the account to login for the new process
[out]	result_handle	pointer to variable that receives handle to control the new child process
[out]	result_pid	pointer to variable that receives the process ID of the new child process
[out]	result_stream	pointer to process_stream pointer that represents IO streams of the new child process

Returns: GATE_RESULT_* result codes

◆ gate_process_run()

GATE_CORE_API gate_result_t gate_process_run	(	gate_string_t const *	executablepath,
		gate_string_t const *	args,
		gate_size_t	argcount,
		gate_string_t const *	workdir,
		gate_string_t const *	envvars,
		gate_size_t	envvarcount,
		gate_enumint_t	flags,
		gate_stream_t *	output,
		int *	exit_code )

Starts a child process and awaits its completion.

Parameters

[in]	executablepath	Path to executable file to be started as new child process
[in]	args	Pointer to first argument string in an array of arguments
[in]	argcount	Amount of elements in args array
[in]	workdir	Path of current working directory
[in]	envvars	pointer to first string in an array of environment variables (format: key=value)
[in]	envvarcount	Amount of elements in envvars array
[in]	flags	start bit flags GATE_PROCESS_START_*
[out]	output	pointer to stream that receives output of process (write() is invoked)
[out]	exit_code	pointer to variable that receives exit code when the process completes

Returns: GATE_RESULT_* result codes

◆ gate_process_close()

GATE_CORE_API gate_result_t gate_process_close ( gate_process_handle_t * handle )

Closes an opened handle to a child process.

Parameters

[in] handle Handle to child process to be closed

Returns: GATE_RESULT_* result codes

◆ gate_process_get_exitcode()

GATE_CORE_API gate_result_t gate_process_get_exitcode	(	gate_process_handle_t *	handle,
		int *	exitcode )

Returns the exit code of a terminated child process.

Parameters

[in]	handle	Handle to child process to be accessed
[out]	exitcode	Pointer to variable that receives exit code of terminated child process

Returns: GATE_RESULT_* result codes

◆ gate_process_wait()

GATE_CORE_API gate_result_t gate_process_wait	(	gate_process_handle_t *	handle,
		gate_uint32_t	timeoutms )

Waits until a process has terminated.

Parameters

[in]	handle	Handle to process to be accessed
[in]	timeoutms	Timeout in milliseconds to wait for process termination

Returns: GATE_RESULT_* result codes

◆ gate_process_wait_pid()

GATE_CORE_API gate_result_t gate_process_wait_pid	(	gate_process_id_t	pid,
		gate_uint32_t	timeoutms )

Waits until a process has terminated.

Parameters

[in]	pid	Process ID of process to be accessed
[in]	timeoutms	Timeout in milliseconds to wait for process termination

Returns: GATE_RESULT_* result codes

◆ gate_process_terminate()

GATE_CORE_API gate_result_t gate_process_terminate	(	gate_process_handle_t *	handle,
		gate_bool_t	system_request )

Sends a termination request to process.

Parameters

[in]	handle	Handle of process to be accessed
[in]	system_request	If "true" the process is killed by a system call, otherwise a user-initiated termination is performed

Returns: GATE_RESULT_* result codes

◆ gate_process_terminate_pid()

GATE_CORE_API gate_result_t gate_process_terminate_pid	(	gate_process_id_t	pid,
		gate_bool_t	system_request )

Sends a termination request to process.

Parameters

[in]	pid	Process Id of process to be accessed
[in]	system_request	If "true" the process is killed by a system call, otherwise a user-initiated termination is performed

Returns: GATE_RESULT_* result codes

◆ gate_process_kill()

GATE_CORE_API gate_result_t gate_process_kill ( gate_process_handle_t * handle )

Immediately kills a process.

Parameters

[in] handle Handle of process to be killed

Returns: GATE_RESULT_* result codes

◆ gate_process_kill_pid()

GATE_CORE_API gate_result_t gate_process_kill_pid ( gate_process_id_t pid )

Immediately kills a process.

Parameters

[in] pid Process ID of process to be killed

Returns: GATE_RESULT_* result codes

◆ gate_process_suspend()

GATE_CORE_API gate_result_t gate_process_suspend ( gate_process_handle_t * handle )

Suspends execution of a running process.

Parameters

[in] handle Handle of process to be accessed

Returns: GATE_RESULT_* result codes

◆ gate_process_suspend_pid()

GATE_CORE_API gate_result_t gate_process_suspend_pid ( gate_process_id_t pid )

Suspends execution of a running process.

Parameters

[in] pid Process ID of process to be accessed

Returns: GATE_RESULT_* result codes

◆ gate_process_resume()

GATE_CORE_API gate_result_t gate_process_resume ( gate_process_handle_t * handle )

Resumes execution of a suspended process.

Parameters

[in] handle Handle of process to be accessed

Returns: GATE_RESULT_* result codes

◆ gate_process_resume_pid()

GATE_CORE_API gate_result_t gate_process_resume_pid ( gate_process_id_t pid )

Resumes execution of a suspended process.

Parameters

[in] pid Process ID of process to be accessed

Returns: GATE_RESULT_* result codes

◆ gate_process_print_pid()

GATE_CORE_API gate_size_t gate_process_print_pid	(	gate_process_id_t	pid,
		char *	text,
		gate_size_t	textlen )

Prints a process ID as readable text.

Parameters

[in]	pid	Process ID to be printed
[out]	text	Text output buffer to be filled
[in]	textlen	Capacity of text buffer

Returns: Amount of filled bytes in output buffer

◆ gate_process_parse_pid()

GATE_CORE_API gate_size_t gate_process_parse_pid	(	char const *	text,
		gate_size_t	textlen,
		gate_process_id_t *	pid )

Parses a text buffer to get a contained printed PID back.

Parameters

[in]	text	Text input buffer to be parsed
[in]	textlen	Length of text input buffer
[out]	pid	Pointer to process ID to be filled

Returns: Amount of bytes parsed from input buffer

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ GATE_PROCESS_ENUM_NAME

◆ GATE_PROCESS_ENUM_PATH

◆ GATE_PROCESS_ENUM_OWNER

◆ GATE_PROCESS_ENUM_MEMORY

◆ GATE_PROCESS_ENUM_TIMES

◆ GATE_PROCESS_ENUM_RESOURCES

◆ GATE_PROCESS_ENUM_ALL

◆ GATE_PROCESS_START_NEWTERMINAL

◆ GATE_PROCESS_START_NEWSESSION

◆ GATE_PROCESS_START_USESTDERR

◆ GATE_PROCESS_START_NOTERMINAL

◆ GATE_PROCESS_START_NOINHERIT

◆ GATE_PROCESS_START_SERVICECONTEXT

◆ GATE_PROCESS_START_DEFAULTLOCATIONLOGON

◆ GATE_PROCESS_START_PRIVILEGED

◆ GATE_PROCESS_WAIT_INFINITE

Function Documentation

◆ gate_process_get_id()

◆ gate_process_quit()

◆ gate_process_enum()

◆ gate_process_getinfo()

◆ gate_process_start()

◆ gate_process_start_ex()

◆ gate_process_run()

◆ gate_process_close()

◆ gate_process_get_exitcode()

◆ gate_process_wait()

◆ gate_process_wait_pid()

◆ gate_process_terminate()

◆ gate_process_terminate_pid()

◆ gate_process_kill()

◆ gate_process_kill_pid()

◆ gate_process_suspend()

◆ gate_process_suspend_pid()

◆ gate_process_resume()

◆ gate_process_resume_pid()

◆ gate_process_print_pid()

◆ gate_process_parse_pid()