diff --git a/core/os/os2/process.odin b/core/os/os2/process.odin index ce65987b0..7b8f22a99 100644 --- a/core/os/os2/process.odin +++ b/core/os/os2/process.odin @@ -4,13 +4,13 @@ import "base:runtime" import "core:time" /* - In procedures that explicitly state this as one of the allowed values, - specifies an infinite timeout. +In procedures that explicitly state this as one of the allowed values, +specifies an infinite timeout. */ TIMEOUT_INFINITE :: time.MIN_DURATION // Note(flysand): Any negative duration will be treated as infinity /* - Arguments to the current process. +Arguments to the current process. */ args := get_args() @@ -24,17 +24,17 @@ get_args :: proc() -> []string { } /* - Exit the current process. +Exit the current process. */ exit :: proc "contextless" (code: int) -> ! { _exit(code) } /* - Obtain the UID of the current process. +Obtain the UID of the current process. - **Note(windows)**: Windows doesn't follow the posix permissions model, so - the function simply returns -1. +**Note(windows)**: Windows doesn't follow the posix permissions model, so +the function simply returns -1. */ @(require_results) get_uid :: proc() -> int { @@ -42,15 +42,15 @@ get_uid :: proc() -> int { } /* - Obtain the effective UID of the current process. +Obtain the effective UID of the current process. - The effective UID is typically the same as the UID of the process. In case - the process was run by a user with elevated permissions, the process may - lower the privilege to perform some tasks without privilege. In these cases - the real UID of the process and the effective UID are different. - - **Note(windows)**: Windows doesn't follow the posix permissions model, so - the function simply returns -1. +The effective UID is typically the same as the UID of the process. In case +the process was run by a user with elevated permissions, the process may +lower the privilege to perform some tasks without privilege. In these cases +the real UID of the process and the effective UID are different. + +**Note(windows)**: Windows doesn't follow the posix permissions model, so +the function simply returns -1. */ @(require_results) get_euid :: proc() -> int { @@ -58,10 +58,10 @@ get_euid :: proc() -> int { } /* - Obtain the GID of the current process. - - **Note(windows)**: Windows doesn't follow the posix permissions model, so - the function simply returns -1. +Obtain the GID of the current process. + +**Note(windows)**: Windows doesn't follow the posix permissions model, so +the function simply returns -1. */ @(require_results) get_gid :: proc() -> int { @@ -69,15 +69,15 @@ get_gid :: proc() -> int { } /* - Obtain the effective GID of the current process. - - The effective GID is typically the same as the GID of the process. In case - the process was run by a user with elevated permissions, the process may - lower the privilege to perform some tasks without privilege. In these cases - the real GID of the process and the effective GID are different. +Obtain the effective GID of the current process. - **Note(windows)**: Windows doesn't follow the posix permissions model, so - the function simply returns -1. +The effective GID is typically the same as the GID of the process. In case +the process was run by a user with elevated permissions, the process may +lower the privilege to perform some tasks without privilege. In these cases +the real GID of the process and the effective GID are different. + +**Note(windows)**: Windows doesn't follow the posix permissions model, so +the function simply returns -1. */ @(require_results) get_egid :: proc() -> int { @@ -85,7 +85,7 @@ get_egid :: proc() -> int { } /* - Obtain the ID of the current process. +Obtain the ID of the current process. */ @(require_results) get_pid :: proc() -> int { @@ -93,13 +93,13 @@ get_pid :: proc() -> int { } /* - Obtain the ID of the parent process. +Obtain the ID of the parent process. - **Note(windows)**: Windows does not mantain strong relationships between - parent and child processes. This function returns the ID of the process - that has created the current process. In case the parent has died, the ID - returned by this function can identify a non-existent or a different - process. +**Note(windows)**: Windows does not mantain strong relationships between +parent and child processes. This function returns the ID of the process +that has created the current process. In case the parent has died, the ID +returned by this function can identify a non-existent or a different +process. */ @(require_results) get_ppid :: proc() -> int { @@ -107,7 +107,7 @@ get_ppid :: proc() -> int { } /* - Obtain ID's of all processes running in the system. +Obtain ID's of all processes running in the system. */ @(require_results) process_list :: proc(allocator: runtime.Allocator) -> ([]int, Error) { @@ -115,9 +115,9 @@ process_list :: proc(allocator: runtime.Allocator) -> ([]int, Error) { } /* - Bit set specifying which fields of the `Process_Info` struct need to be - obtained by the `process_info()` procedure. Each bit corresponds to a - field in the `Process_Info` struct. +Bit set specifying which fields of the `Process_Info` struct need to be +obtained by the `process_info()` procedure. Each bit corresponds to a +field in the `Process_Info` struct. */ Process_Info_Fields :: bit_set[Process_Info_Field] Process_Info_Field :: enum { @@ -134,8 +134,8 @@ Process_Info_Field :: enum { ALL_INFO :: Process_Info_Fields{.Executable_Path, .PPid, .Priority, .Command_Line, .Command_Args, .Environment, .Username, .Working_Dir} /* - Contains information about the process as obtained by the `process_info()` - procedure. +Contains information about the process as obtained by the `process_info()` +procedure. */ Process_Info :: struct { // The information about a process the struct contains. `pid` is always @@ -162,19 +162,19 @@ Process_Info :: struct { } /* - Obtain information about a process. +Obtain information about a process. - This procedure obtains an information, specified by `selection` parameter of - a process given by `pid`. +This procedure obtains an information, specified by `selection` parameter of +a process given by `pid`. - Use `free_process_info` to free the memory allocated by this procedure. The - `free_process_info` procedure needs to be called, even if this procedure - returned an error, as some of the fields may have been allocated. +Use `free_process_info` to free the memory allocated by this procedure. The +`free_process_info` procedure needs to be called, even if this procedure +returned an error, as some of the fields may have been allocated. - **Note**: The resulting information may or may contain the fields specified - by the `selection` parameter. Always check whether the returned - `Process_Info` struct has the required fields before checking the error code - returned by this procedure. +**Note**: The resulting information may or may contain the fields specified +by the `selection` parameter. Always check whether the returned +`Process_Info` struct has the required fields before checking the error code +returned by this procedure. */ @(require_results) process_info_by_pid :: proc(pid: int, selection: Process_Info_Fields, allocator: runtime.Allocator) -> (Process_Info, Error) { @@ -182,20 +182,20 @@ process_info_by_pid :: proc(pid: int, selection: Process_Info_Fields, allocator: } /* - Obtain information about a process. +Obtain information about a process. - This procedure obtains information, specified by `selection` parameter - about a process that has been opened by the application, specified in - the `process` parameter. +This procedure obtains information, specified by `selection` parameter +about a process that has been opened by the application, specified in +the `process` parameter. - Use `free_process_info` to free the memory allocated by this procedure. The - `free_process_info` procedure needs to be called, even if this procedure - returned an error, as some of the fields may have been allocated. +Use `free_process_info` to free the memory allocated by this procedure. The +`free_process_info` procedure needs to be called, even if this procedure +returned an error, as some of the fields may have been allocated. - **Note**: The resulting information may or may contain the fields specified - by the `selection` parameter. Always check whether the returned - `Process_Info` struct has the required fields before checking the error code - returned by this procedure. +**Note**: The resulting information may or may contain the fields specified +by the `selection` parameter. Always check whether the returned +`Process_Info` struct has the required fields before checking the error code +returned by this procedure. */ @(require_results) process_info_by_handle :: proc(process: Process, selection: Process_Info_Fields, allocator: runtime.Allocator) -> (Process_Info, Error) { @@ -203,19 +203,19 @@ process_info_by_handle :: proc(process: Process, selection: Process_Info_Fields, } /* - Obtain information about the current process. +Obtain information about the current process. - This procedure obtains the information, specified by `selection` parameter - about the currently running process. +This procedure obtains the information, specified by `selection` parameter +about the currently running process. - Use `free_process_info` to free the memory allocated by this procedure. The - `free_process_info` procedure needs to be called, even if this procedure - returned an error, as some of the fields may have been allocated. +Use `free_process_info` to free the memory allocated by this procedure. The +`free_process_info` procedure needs to be called, even if this procedure +returned an error, as some of the fields may have been allocated. - **Note**: The resulting information may or may contain the fields specified - by the `selection` parameter. Always check whether the returned - `Process_Info` struct has the required fields before checking the error code - returned by this procedure. +**Note**: The resulting information may or may contain the fields specified +by the `selection` parameter. Always check whether the returned +`Process_Info` struct has the required fields before checking the error code +returned by this procedure. */ @(require_results) current_process_info :: proc(selection: Process_Info_Fields, allocator: runtime.Allocator) -> (Process_Info, Error) { @@ -223,7 +223,7 @@ current_process_info :: proc(selection: Process_Info_Fields, allocator: runtime. } /* - Obtain information about the specified process. +Obtain information about the specified process. */ process_info :: proc { process_info_by_pid, @@ -232,11 +232,11 @@ process_info :: proc { } /* - Free the information about the process. +Free the information about the process. - This procedure frees the memory occupied by process info using the provided - allocator. The allocator needs to be the same allocator that was supplied - to the `process_info` function. +This procedure frees the memory occupied by process info using the provided +allocator. The allocator needs to be the same allocator that was supplied +to the `process_info` function. */ free_process_info :: proc(pi: Process_Info, allocator: runtime.Allocator) { delete(pi.executable_path, allocator) @@ -254,13 +254,13 @@ free_process_info :: proc(pi: Process_Info, allocator: runtime.Allocator) { } /* - Represents a process handle. +Represents a process handle. - When a process dies, the OS is free to re-use the pid of that process. The - `Process` struct represents a handle to the process that will refer to a - specific process, even after it has died. +When a process dies, the OS is free to re-use the pid of that process. The +`Process` struct represents a handle to the process that will refer to a +specific process, even after it has died. - **Note(linux)**: The `handle` will be referring to pidfd. +**Note(linux)**: The `handle` will be referring to pidfd. */ Process :: struct { pid: int, @@ -276,13 +276,13 @@ Process_Open_Flag :: enum { } /* - Open a process handle using it's pid. +Open a process handle using it's pid. - This procedure obtains a process handle of a process specified by `pid`. - This procedure can be subject to race conditions. See the description of - `Process`. +This procedure obtains a process handle of a process specified by `pid`. +This procedure can be subject to race conditions. See the description of +`Process`. - Use `process_close()` function to close the process handle. +Use `process_close()` function to close the process handle. */ @(require_results) process_open :: proc(pid: int, flags := Process_Open_Flags {}) -> (Process, Error) { @@ -322,28 +322,28 @@ Process_Desc :: struct { } /* - Create a new process and obtain its handle. +Create a new process and obtain its handle. - This procedure creates a new process, with a given command and environment - strings as parameters. Use `environ()` to inherit the environment of the - current process. +This procedure creates a new process, with a given command and environment +strings as parameters. Use `environ()` to inherit the environment of the +current process. - The `desc` parameter specifies the description of how the process should - be created. It contains information such as the command line, the - environment of the process, the starting directory and many other options. - Most of the fields in the struct can be set to `nil` or an empty value. - - Use `process_close` to close the handle to the process. Note, that this - is not the same as terminating the process. One can terminate the process - and not close the handle, in which case the handle would be leaked. In case - the function returns an error, an invalid handle is returned. +The `desc` parameter specifies the description of how the process should +be created. It contains information such as the command line, the +environment of the process, the starting directory and many other options. +Most of the fields in the struct can be set to `nil` or an empty value. - This procedure is not thread-safe. It may alter the inheritance properties - of file handles in an unpredictable manner. In case multiple threads change - handle inheritance properties, make sure to serialize all those calls. +Use `process_close` to close the handle to the process. Note, that this +is not the same as terminating the process. One can terminate the process +and not close the handle, in which case the handle would be leaked. In case +the function returns an error, an invalid handle is returned. + +This procedure is not thread-safe. It may alter the inheritance properties +of file handles in an unpredictable manner. In case multiple threads change +handle inheritance properties, make sure to serialize all those calls. */ @(require_results) -process_start :: proc(desc := Process_Desc {}) -> (Process, Error) { +process_start :: proc(desc: Process_Desc) -> (Process, Error) { return _process_start(desc) } @@ -371,17 +371,17 @@ Process_State :: struct { } /* - Wait for a process event. +Wait for a process event. - This procedure blocks the execution until the process has exited or the - timeout (if specified) has reached zero. If the timeout is `TIMEOUT_INFINITE`, - no timeout restriction is imposed and the procedure can block indefinately. +This procedure blocks the execution until the process has exited or the +timeout (if specified) has reached zero. If the timeout is `TIMEOUT_INFINITE`, +no timeout restriction is imposed and the procedure can block indefinately. - If the timeout has expired, the `General_Error.Timeout` is returned as - the error. +If the timeout has expired, the `General_Error.Timeout` is returned as +the error. - If an error is returned for any other reason, other than timeout, the - process state is considered undetermined. +If an error is returned for any other reason, other than timeout, the +process state is considered undetermined. */ @(require_results) process_wait :: proc(process: Process, timeout := TIMEOUT_INFINITE) -> (Process_State, Error) { @@ -389,12 +389,12 @@ process_wait :: proc(process: Process, timeout := TIMEOUT_INFINITE) -> (Process_ } /* - Close the handle to a process. +Close the handle to a process. - This procedure closes the handle associated with a process. It **does not** - terminate a process, in case it was running. In case a termination is - desired, kill the process first, wait for the process to finish, - then close the handle. +This procedure closes the handle associated with a process. It **does not** +terminate a process, in case it was running. In case a termination is +desired, kill the process first, wait for the process to finish, +then close the handle. */ @(require_results) process_close :: proc(process: Process) -> (Error) { @@ -402,10 +402,9 @@ process_close :: proc(process: Process) -> (Error) { } /* - Terminate a process. - - This procedure terminates a process, specified by it's handle, `process`. +Terminate a process. +This procedure terminates a process, specified by it's handle, `process`. */ @(require_results) process_kill :: proc(process: Process) -> (Error) { diff --git a/misc/odin.res b/misc/odin.res new file mode 100644 index 000000000..f9cace9c5 Binary files /dev/null and b/misc/odin.res differ