GATE
Classes | Macros | Typedefs | Functions
processes.h File Reference
GATE Core Library

System process access and management functions. More...

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

Classes

struct  gate_process_class
 
struct  gate_process_infobuffer_class
 

Macros

#define GATE_PROCESS_ID_INVALID   0
 
#define GATE_PROCESS_HANDLE_INVALID   NULL
 
#define GATE_INTERFACE_NAME_PROCESSSTREAM   GATE_INTERFACE_NAME_RESOURCESTREAM GATE_INTERFACE_NAME_SEPARATOR "process"
 
#define GATE_STREAM_RESOURCE_STDIN   0x01
 
#define GATE_STREAM_RESOURCE_STDOUT   0x02
 
#define GATE_STREAM_RESOURCE_STDERR   0x03
 
#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)
 

Typedefs

typedef gate_int64_t gate_process_id_t
 
typedef void * gate_process_handle_t
 
typedef struct gate_process_class gate_process_t
 
typedef struct gate_process_infobuffer_class gate_process_infobuffer_t
 
typedef gate_bool_t(* gate_process_enum_callback_t) (gate_process_t *process, void *userparam)
 

Functions

 GATE_INTERFACE (gate_process_stream)
 
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_ALL

#define GATE_PROCESS_ENUM_ALL   ((gate_uint16_t)0xffff)

retriev all supported process informations

◆ GATE_PROCESS_ENUM_MEMORY

#define GATE_PROCESS_ENUM_MEMORY   ((gate_uint16_t)0x0008)

retrieve memory usage of process

◆ GATE_PROCESS_ENUM_NAME

#define GATE_PROCESS_ENUM_NAME   ((gate_uint16_t)0x0001)

retrieve name 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_PATH

#define GATE_PROCESS_ENUM_PATH   ((gate_uint16_t)0x0002)

retrieve executable path of process

◆ GATE_PROCESS_ENUM_RESOURCES

#define GATE_PROCESS_ENUM_RESOURCES   ((gate_uint16_t)0x0020)

retrieve amount resources accessed by process

◆ GATE_PROCESS_ENUM_TIMES

#define GATE_PROCESS_ENUM_TIMES   ((gate_uint16_t)0x0010)

retrieve up-times of process

◆ GATE_PROCESS_START_DEFAULTLOCATIONLOGON

#define GATE_PROCESS_START_DEFAULTLOCATIONLOGON   0x2000

applies the default logon of the selected session-location

◆ GATE_PROCESS_START_NEWSESSION

#define GATE_PROCESS_START_NEWSESSION   0x0002

new process leads a session (group of processes)

◆ GATE_PROCESS_START_NEWTERMINAL

#define GATE_PROCESS_START_NEWTERMINAL   0x0001

creates a new terminal host for the process

◆ GATE_PROCESS_START_NOINHERIT

#define GATE_PROCESS_START_NOINHERIT   0x0200

new process does not inherit handles and file descriptors

◆ GATE_PROCESS_START_NOTERMINAL

#define GATE_PROCESS_START_NOTERMINAL   0x0100

creates the process without a hosting terminal

◆ GATE_PROCESS_START_PRIVILEGED

#define GATE_PROCESS_START_PRIVILEGED   0x4000

applies the highest privileges of the selected session-location

◆ GATE_PROCESS_START_SERVICECONTEXT

#define GATE_PROCESS_START_SERVICECONTEXT   0x1000

host runs in service/root context and applies special states

◆ GATE_PROCESS_START_USESTDERR

#define GATE_PROCESS_START_USESTDERR   0x0004

enables std-err, otherwise stderr == stdout

◆ 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_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]handleHandle to child process to be closed
Returns
GATE_RESULT_* result codes

◆ 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]callbackCallback to invoke for each process entry
[in]userparamUser parameter to be passed to callback
[in]flagsGATE_PROCESS_ENUM_* flags to select which informations are retrieved
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]handleHandle to child process to be accessed
[out]exitcodePointer to variable that receives exit code of terminated child process
Returns
GATE_RESULT_* result codes

◆ 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]pidpointer to variable that receives process ID
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_bufferpointer to process_infobuffer that receives info fields
[in]proc_idprocess ID of process to be queried
[in]flagsGATE_PROCESS_ENUM_* flags tos select which informations are retrieved
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]handleHandle 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]pidProcess ID of process to be killed
Returns
GATE_RESULT_* result codes

◆ 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]textText input buffer to be parsed
[in]textlenLength of text input buffer
[out]pidPointer to process ID to be filled
Returns
Amount of bytes parsed from input buffer

◆ 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]pidProcess ID to be printed
[out]textText output buffer to be filled
[in]textlenCapacity of text buffer
Returns
Amount of filled bytes in output buffer

◆ gate_process_quit()

GATE_CORE_API void gate_process_quit ( int exitcode)

Forces the currently running process to immediately terminate.

Parameters
[in]exitcodeProcess exit code to return to the OS or parent process

◆ 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]handleHandle 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]pidProcess ID of process to be accessed
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]executablepathPath to executable file to be started as new child process
[in]argsPointer to first argument string in an array of arguments
[in]argcountAmount of elements in args array
[in]workdirPath of current working directory
[in]envvarspointer to first string in an array of environment variables (format: key=value)
[in]envvarcountAmount of elements in envvars array
[in]flagsstart bit flags GATE_PROCESS_START_*
[out]outputpointer to stream that receives output of process (write() is invoked)
[out]exit_codepointer to variable that receives exit code when the process completes
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]executablepathPath to executable file to be started as new child process
[in]argsPointer to first argument string in an array of arguments
[in]argcountAmount of elements in args array
[in]workdirPath of current working directory
[in]envvarspointer to first string in an array of environment variables (format: key=value)
[in]envvarcountAmount of elements in envvars array
[in]flagsstart bit flags GATE_PROCESS_START_*
[out]result_handlepointer to variable that receives handle to control the new child process
[out]result_pidpointer to variable that receives the process ID of the new child process
[out]result_streampointer 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]executablepathPath to executable file to be started as new child process
[in]argsPointer to first argument string in an array of arguments
[in]argcountAmount of elements in args array
[in]workdirPath of current working directory
[in]envvarspointer to first string in an array of environment variables (format: key=value)
[in]envvarcountAmount of elements in envvars array
[in]flagsstart bit flags GATE_PROCESS_START_*
[in]sessionlocationstring that identifies the target session context of the new process
[in]usernamename of account the process shall run as
[in]passwordpassword of the account to login for the new process
[out]result_handlepointer to variable that receives handle to control the new child process
[out]result_pidpointer to variable that receives the process ID of the new child process
[out]result_streampointer to process_stream pointer that represents IO streams of the new child process
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]handleHandle 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]pidProcess ID of process to be accessed
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]handleHandle of process to be accessed
[in]system_requestIf "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]pidProcess Id of process to be accessed
[in]system_requestIf "true" the process is killed by a system call, otherwise a user-initiated termination is performed
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]handleHandle to process to be accessed
[in]timeoutmsTimeout 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]pidProcess ID of process to be accessed
[in]timeoutmsTimeout in milliseconds to wait for process termination
Returns
GATE_RESULT_* result codes