Process

Typedefs
typedef OS_RETURN_CODE(*	OS_FnPtrCreateProcess) (const CHAR *args, NATIVE_FD *stdFiles, NATIVE_FD *closeFiles, char **environ, OS_PROCESS_WAITABLE_PROCESS *process)

Functions
OS_RETURN_CODE	OS_GetPid (NATIVE_PID *pid)
OS_RETURN_CODE	OS_GetCommandLine (NATIVE_PID pid, USIZE *argc, CHAR ***argv, USIZE *bufsize)
OS_RETURN_CODE	OS_GetEnvironmentBlock (NATIVE_PID pid, CHAR ***block, USIZE *bufSize)
NORETURN void	OS_ExitProcess (INT code)
OS_RETURN_CODE	OS_IsDebuggerPresent (NATIVE_PID pid, BOOL_T *isPresent)
OS_RETURN_CODE	OS_GetUid (NATIVE_UID *uid)
OS_RETURN_CODE	OS_FindStdFiles (NATIVE_FD *files)
OS_RETURN_CODE	OS_CreateProcess (const CHAR *args, NATIVE_FD *stdFiles, NATIVE_FD *closeFiles, char **environ, OS_PROCESS_WAITABLE_PROCESS *process)
OS_RETURN_CODE	OS_WaitForProcessTermination (OS_PROCESS_WAITABLE_PROCESS process, UINT32 *exitStatus)
VOID	OS_TriggerSoftwareBreakpoint ()
void	OS_NotifyFork ()
UINT32	OS_GetForksCount ()

Detailed Description

Typedef Documentation

OS_FnPtrCreateProcess

typedef OS_RETURN_CODE(* OS_FnPtrCreateProcess) (const CHAR *args, NATIVE_FD *stdFiles, NATIVE_FD *closeFiles, char **environ, OS_PROCESS_WAITABLE_PROCESS *process)

Type definition of a pointer to an OS_CreateProcess function.

Function Documentation

OS_CreateProcess()

OS_RETURN_CODE OS_CreateProcess	(	const CHAR *	args,
		NATIVE_FD *	stdFiles,
		NATIVE_FD *	closeFiles,
		char **	environ,
		OS_PROCESS_WAITABLE_PROCESS *	process
	)

Create a process, possibly redirect its standard input/output/error. The process is created using the system command line interpreter or shell.

Parameters

[in]	args	Full command line for the process.
[in]	stdFiles	Points to an array of NATIVE_FD objects with at least 3 elements. These elements will be used to determine the file descriptors: STDIN, STDOUT, STDERR respectively of the newly created process.
[in]	closeFiles	(Optional) Points to an array of NATIVE_FD objects that needs to be closed in the context of the created proces. The last entry of this array should be INVALID_NATIVE_FD.
[in]	environ	Pointer to the environment block to use in the new process.
[out]	process	An opaque object representing the created process. One can wait for the process termination by calling OS_WaitForProcessTermination

Returns

Operation status code.

Return values

OS_RETURN_CODE_NO_ERROR	If the operation succeeded
OS_RETURN_CODE_PROCESS_QUERY_FAILED	If the operation Failed

Availability:

O/S: Windows, Linux & macOS*
CPU: All

OS_ExitProcess()

NORETURN void OS_ExitProcess

(

INT

code

)

Exits the current process.

Parameters

[in]

code

Process descriptor

Availability:

O/S: Windows, Linux & macOS*
CPU: All

OS_FindStdFiles()

OS_RETURN_CODE OS_FindStdFiles

(

NATIVE_FD *

files

)

Queries whether the current process is being debugged.

Parameters

[out]

files

Points to an array of NATIVE_FD objects with at least 3 elements. These elements will be filled with the file descriptors of STDIN, STDOUT, STDERR respectively.

Returns

Operation status code.

Return values

OS_RETURN_CODE_NO_ERROR	If the operation succeeded
OS_RETURN_CODE_PROCESS_QUERY_FAILED	If the operation Failed

Availability:

O/S: Windows
CPU: All

OS_GetCommandLine()

OS_RETURN_CODE OS_GetCommandLine	(	NATIVE_PID	pid,
		USIZE *	argc,
		CHAR ***	argv,
		USIZE *	bufsize
	)

Retrieve the command line for a given process.

Parameters

[in]	pid	Process descriptor
[out]	argc	Command line's argc
[out]	argv	Command line's argv array, allocated by this function (with OS_AllocateMemory())
[out]	bufsize	Size in bytes of the buffer pointer by argv

Returns

Operation status code.

Return values

OS_RETURN_CODE_NO_ERROR	If the operation succeeded
OS_RETURN_CODE_PROCESS_QUERY_FAILED	If the operation Failed

Availability:

O/S: Windows, Linux & macOS*
CPU: All

OS_GetEnvironmentBlock()

OS_RETURN_CODE OS_GetEnvironmentBlock	(	NATIVE_PID	pid,
		CHAR ***	block,
		USIZE *	bufSize
	)

Retrieve pointer to process environment variables block encoded in UTF8.

Parameters

[in]	pid	Process descriptor.
[out]	block	Return pointer to point to the environment block.
[out]	bufSize	Number of bytes allocated for the envrionement block.

Returns

Operation status code.

Return values

OS_RETURN_CODE_NO_ERROR	If the operation succeeded
OS_RETURN_CODE_PROCESS_UPDATE_FAILED	If the operation Failed

Note

On Linux and macOS* this function will retrieve the initial environment block that was valid when the process started. This function doesn't catch up with changes done to the environment variables while the process is running.

Availability:

O/S: Windows, Linux & macOS*
CPU: All

OS_GetForksCount()

UINT32 OS_GetForksCount

(

)

Get the current generation of forked processes. This value is increased by one every time OS_NotifyFork() is called.

Availability:

• O/S: Linux & macOS*
• CPU: All

OS_GetPid()

OS_RETURN_CODE OS_GetPid

(

NATIVE_PID *

pid

)

Retrieves the process ID of the current process.

Parameters

[out]

pid

Process descriptor

Returns

Operation status code.

Return values

OS_RETURN_CODE_NO_ERROR	If the operation succeeded
OS_RETURN_CODE_PROCESS_QUERY_FAILED	If the operation Failed

Availability:

O/S: Windows, Linux & macOS*
CPU: All

OS_GetUid()

OS_RETURN_CODE OS_GetUid

(

NATIVE_UID *

uid

)

Queries whether the current process is being debugged.

Parameters

[out]

uid

Process descriptor

Returns

Operation status code.

Return values

OS_RETURN_CODE_NO_ERROR	If the operation succeeded
OS_RETURN_CODE_PROCESS_QUERY_FAILED	If the operation Failed

Availability:

O/S: Linux & macOS*
CPU: All

OS_IsDebuggerPresent()

OS_RETURN_CODE OS_IsDebuggerPresent	(	NATIVE_PID	pid,
		BOOL_T *	isPresent
	)

Queries whether the current process is being debugged.

Parameters

[out]	pid	Process descriptor
[out]	isPresent	True if the process 'pid' is being debugged.

Returns

Operation status code.

Return values

OS_RETURN_CODE_NO_ERROR	If the operation succeeded
OS_RETURN_CODE_PROCESS_QUERY_FAILED	If the operation Failed

Availability:

O/S: Windows, Linux & macOS*
CPU: All

OS_NotifyFork()

void OS_NotifyFork

(

)

Notify the locking mechanism about a forked child.

Note

Must be called earliest as possible by the child process after it was created for functional correctness.

Availability:

• O/S: Linux & macOS*
• CPU: All

OS_TriggerSoftwareBreakpoint()

VOID OS_TriggerSoftwareBreakpoint

(

)

Trigger a software breakpoint. When the current process is attached to a debugger, this function will stop the process and notify the debugger about a breakpoint that was triggered.

Availability:

O/S: Windows, Linux & macOS*
CPU: All

OS_WaitForProcessTermination()

OS_RETURN_CODE OS_WaitForProcessTermination	(	OS_PROCESS_WAITABLE_PROCESS	process,
		UINT32 *	exitStatus
	)

Wait for process termination.

Parameters

[in]	process	An opaque object representing the process to wait for.
[out]	exitStatus	The exit status of the terminated process.

Returns

Operation status code.

Return values

OS_RETURN_CODE_NO_ERROR	If the operation succeeded
OS_RETURN_CODE_PROCESS_QUERY_FAILED	If the operation Failed

Availability:

O/S: Windows, Linux & macOS*
CPU: All