You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
217 lines
7.9 KiB
217 lines
7.9 KiB
/*
|
|
* Copyright 2002-2019 Intel Corporation.
|
|
*
|
|
* This software and the related documents are Intel copyrighted materials, and your
|
|
* use of them is governed by the express license under which they were provided to
|
|
* you ("License"). Unless the License provides otherwise, you may not use, modify,
|
|
* copy, publish, distribute, disclose or transmit this software or the related
|
|
* documents without Intel's prior written permission.
|
|
*
|
|
* This software and the related documents are provided as is, with no express or
|
|
* implied warranties, other than those that are expressly stated in the License.
|
|
*/
|
|
|
|
// <COMPONENT>: os-apis
|
|
// <FILE-TYPE>: component public header
|
|
|
|
/*!
|
|
* @defgroup OS_APIS_PROCESS Process
|
|
* @brief Contains process-related os apis
|
|
*/
|
|
|
|
#ifndef OS_APIS_PROCESS_H
|
|
#define OS_APIS_PROCESS_H
|
|
|
|
#include "process-core.h"
|
|
|
|
/*! @ingroup OS_APIS_FILE
|
|
* Opaque object that represents a process that we can wait for its termination
|
|
*/
|
|
typedef UINT64 OS_PROCESS_WAITABLE_PROCESS;
|
|
|
|
/*! @ingroup OS_APIS_PROCESS
|
|
* Retrieve the command line for a given process.
|
|
*
|
|
* @param[in] pid Process descriptor
|
|
* @param[out] argc Command line's argc
|
|
* @param[out] argv Command line's argv array, allocated by this function (with OS_AllocateMemory())
|
|
* @param[out] bufsize Size in bytes of the buffer pointer by argv
|
|
*
|
|
* @return Operation status code.
|
|
* @retval OS_RETURN_CODE_NO_ERROR If the operation succeeded
|
|
* @retval OS_RETURN_CODE_PROCESS_QUERY_FAILED If the operation Failed
|
|
*
|
|
* @par Availability:
|
|
* @b O/S: Windows, Linux & macOS*\n
|
|
* @b CPU: All\n
|
|
*/
|
|
OS_RETURN_CODE OS_GetCommandLine(NATIVE_PID pid, USIZE* argc, CHAR*** argv, USIZE* bufsize);
|
|
|
|
/*! @ingroup OS_APIS_PROCESS
|
|
* Retrieve pointer to process environment variables block encoded in UTF8.
|
|
*
|
|
* @param[in] pid Process descriptor.
|
|
* @param[out] block Return pointer to point to the environment block.
|
|
* @param[out] bufSize Number of bytes allocated for the envrionement block.
|
|
*
|
|
* @return Operation status code.
|
|
* @retval OS_RETURN_CODE_NO_ERROR If the operation succeeded
|
|
* @retval 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.
|
|
* @par Availability:
|
|
* @b O/S: Windows, Linux & macOS*\n
|
|
* @b CPU: All\n
|
|
*/
|
|
OS_RETURN_CODE OS_GetEnvironmentBlock(NATIVE_PID pid, CHAR*** block, USIZE* bufSize);
|
|
|
|
/*! @ingroup OS_APIS_PROCESS
|
|
* Exits the current process.
|
|
*
|
|
* @param[in] code Process descriptor
|
|
*
|
|
* @par Availability:
|
|
* @b O/S: Windows, Linux & macOS*\n
|
|
* @b CPU: All\n
|
|
*/
|
|
NORETURN void OS_ExitProcess(INT code);
|
|
|
|
/*! @ingroup OS_APIS_PROCESS
|
|
* Queries whether the current process is being debugged.
|
|
*
|
|
* @param[out] pid Process descriptor
|
|
* @param[out] isPresent True if the process 'pid' is being debugged.
|
|
*
|
|
* @return Operation status code.
|
|
* @retval OS_RETURN_CODE_NO_ERROR If the operation succeeded
|
|
* @retval OS_RETURN_CODE_PROCESS_QUERY_FAILED If the operation Failed
|
|
*
|
|
* @par Availability:
|
|
* @b O/S: Windows, Linux & macOS*\n
|
|
* @b CPU: All\n
|
|
*/
|
|
OS_RETURN_CODE OS_IsDebuggerPresent(NATIVE_PID pid, BOOL_T* isPresent);
|
|
|
|
/*! @ingroup OS_APIS_PROCESS
|
|
* Queries whether the current process is being debugged.
|
|
*
|
|
* @param[out] uid Process descriptor
|
|
*
|
|
* @return Operation status code.
|
|
* @retval OS_RETURN_CODE_NO_ERROR If the operation succeeded
|
|
* @retval OS_RETURN_CODE_PROCESS_QUERY_FAILED If the operation Failed
|
|
*
|
|
* @par Availability:
|
|
* @b O/S: Linux & macOS*\n
|
|
* @b CPU: All\n
|
|
*/
|
|
OS_RETURN_CODE OS_GetUid(NATIVE_UID* uid);
|
|
|
|
/*! @ingroup OS_APIS_PROCESS
|
|
* Queries whether the current process is being debugged.
|
|
*
|
|
* @param[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.
|
|
*
|
|
* @return Operation status code.
|
|
* @retval OS_RETURN_CODE_NO_ERROR If the operation succeeded
|
|
* @retval OS_RETURN_CODE_PROCESS_QUERY_FAILED If the operation Failed
|
|
*
|
|
* @par Availability:
|
|
* @b O/S: Windows\n
|
|
* @b CPU: All\n
|
|
*/
|
|
OS_RETURN_CODE OS_FindStdFiles(NATIVE_FD* files);
|
|
|
|
/*! @ingroup OS_APIS_PROCESS
|
|
* Create a process, possibly redirect its standard input/output/error.
|
|
* The process is created using the system command line interpreter or shell.
|
|
*
|
|
* @param[in] args Full command line for the process.
|
|
* @param[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.
|
|
* @param[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.
|
|
* @param[in] environ Pointer to the environment block to use in the new process.
|
|
* @param[out] process An opaque object representing the created process.
|
|
* One can wait for the process termination by calling
|
|
* @ref OS_WaitForProcessTermination
|
|
*
|
|
* @return Operation status code.
|
|
* @retval OS_RETURN_CODE_NO_ERROR If the operation succeeded
|
|
* @retval OS_RETURN_CODE_PROCESS_QUERY_FAILED If the operation Failed
|
|
*
|
|
* @par Availability:
|
|
* @b O/S: Windows, Linux & macOS*\n
|
|
* @b CPU: All\n
|
|
*/
|
|
OS_RETURN_CODE OS_CreateProcess(const CHAR* args, NATIVE_FD* stdFiles, NATIVE_FD* closeFiles,
|
|
char **environ, OS_PROCESS_WAITABLE_PROCESS* process);
|
|
|
|
/*! @ingroup OS_APIS_PROCESS
|
|
* Type definition of a pointer to an OS_CreateProcess function.
|
|
*/
|
|
typedef OS_RETURN_CODE (*OS_FnPtrCreateProcess)(const CHAR* args, NATIVE_FD* stdFiles, NATIVE_FD* closeFiles,
|
|
char **environ, OS_PROCESS_WAITABLE_PROCESS* process);
|
|
|
|
/*! @ingroup OS_APIS_PROCESS
|
|
* Wait for process termination.
|
|
*
|
|
* @param[in] process An opaque object representing the process to wait for.
|
|
* @param[out] exitStatus The exit status of the terminated process.
|
|
*
|
|
* @return Operation status code.
|
|
* @retval OS_RETURN_CODE_NO_ERROR If the operation succeeded
|
|
* @retval OS_RETURN_CODE_PROCESS_QUERY_FAILED If the operation Failed
|
|
*
|
|
* @par Availability:
|
|
* @b O/S: Windows, Linux & macOS*\n
|
|
* @b CPU: All\n
|
|
*/
|
|
OS_RETURN_CODE OS_WaitForProcessTermination(OS_PROCESS_WAITABLE_PROCESS process, UINT32* exitStatus);
|
|
|
|
/*! @ingroup OS_APIS_PROCESS
|
|
* 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.
|
|
*
|
|
* @par Availability:
|
|
* @b O/S: Windows, Linux & macOS*\n
|
|
* @b CPU: All\n
|
|
*/
|
|
VOID OS_TriggerSoftwareBreakpoint();
|
|
|
|
#ifndef TARGET_WINDOWS
|
|
/*! @ingroup OS_APIS_PROCESS
|
|
* 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.
|
|
*
|
|
* @par Availability:
|
|
* - @b O/S: Linux & macOS*
|
|
* - @b CPU: All
|
|
*/
|
|
void OS_NotifyFork();
|
|
|
|
/*! @ingroup OS_APIS_PROCESS
|
|
* Get the current generation of forked processes.
|
|
* This value is increased by one every time OS_NotifyFork() is called.
|
|
*
|
|
* @par Availability:
|
|
* - @b O/S: Linux & macOS*
|
|
* - @b CPU: All
|
|
*/
|
|
UINT32 OS_GetForksCount();
|
|
|
|
|
|
#endif // TARGET_WINDOWS
|
|
|
|
#endif // file guard
|