From 73011529cd4557d3c04698189bcc430edf04f5f4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20M=C3=BCller?= Date: Mon, 12 Feb 2024 22:44:15 +0100 Subject: [PATCH] Document all shell, OS, secure random and related functions Add/update doxygen comments for all `shell_*`, `os_*`, `secure_*`, `cmdline_*`, `windows_*` and related functions. Move `open_link` and `open_file` declarations to shell group, to the same relative position as their function definitions. --- src/base/system.h | 372 ++++++++++++++++++++++++++++------------------ 1 file changed, 226 insertions(+), 146 deletions(-) diff --git a/src/base/system.h b/src/base/system.h index f9bddbced..6979637bf 100644 --- a/src/base/system.h +++ b/src/base/system.h @@ -2068,36 +2068,6 @@ int net_would_block(); int net_socket_read_wait(NETSOCKET sock, int time); -/* - Function: open_link - Opens a link in the browser. - - Parameters: - link - The link to open in a browser. - - Returns: - Returns 1 on success, 0 on failure. - - Remarks: - This may not be called with untrusted input or it'll result in arbitrary code execution, especially on Windows. -*/ -int open_link(const char *link); - -/* - Function: open_file - Opens a file or directory with default program. - - Parameters: - path - The path to open. - - Returns: - Returns 1 on success, 0 on failure. - - Remarks: - This may not be called with untrusted input or it'll result in arbitrary code execution, especially on Windows. -*/ -int open_file(const char *path); - /** * Swaps the endianness of data. Each element is swapped individually by reversing its bytes. * @@ -2474,165 +2444,246 @@ unsigned bytes_be_to_uint(const unsigned char *bytes); */ void uint_to_bytes_be(unsigned char *bytes, unsigned value); -/* - Function: pid - Returns the pid of the current process. +/** + * @defgroup Shell + * Shell, process management, OS specific functionality. + */ - Returns: - pid of the current process -*/ +/** + * Returns the ID of the current process. + * + * @ingroup Shell + * + * @return PID of the current process. + */ int pid(); -/* - Function: cmdline_fix - Fixes the command line arguments to be encoded in UTF-8 on all - systems. - - Parameters: - argc - A pointer to the argc parameter that was passed to the main function. - argv - A pointer to the argv parameter that was passed to the main function. - - Remarks: - - You need to call cmdline_free once you're no longer using the - results. -*/ +/** + * Fixes the command line arguments to be encoded in UTF-8 on all systems. + * + * @ingroup Shell + * + * @param argc A pointer to the argc parameter that was passed to the main function. + * @param argv A pointer to the argv parameter that was passed to the main function. + * + * @remark You need to call @link cmdline_free @endlink once you're no longer using the results. + */ void cmdline_fix(int *argc, const char ***argv); -/* - Function: cmdline_free - Frees memory that was allocated by cmdline_fix. - - Parameters: - argc - The argc obtained from cmdline_fix. - argv - The argv obtained from cmdline_fix. - -*/ +/** + * Frees memory that was allocated by @link cmdline_fix @endlink. + * + * @ingroup Shell + * + * @param argc The argc obtained from `cmdline_fix`. + * @param argv The argv obtained from `cmdline_fix`. + */ void cmdline_free(int argc, const char **argv); #if defined(CONF_FAMILY_WINDOWS) +/** + * A handle for a process. + * + * @ingroup Shell + */ typedef void *PROCESS; +/** + * A handle that denotes an invalid process. + * + * @ingroup Shell + */ constexpr PROCESS INVALID_PROCESS = nullptr; #else +/** + * A handle for a process. + * + * @ingroup Shell + */ typedef pid_t PROCESS; +/** + * A handle that denotes an invalid process. + * + * @ingroup Shell + */ constexpr PROCESS INVALID_PROCESS = 0; #endif +/** + * Determines the initial window state when using @link shell_execute @endlink + * to execute a process. + * + * @ingroup Shell + * + * @remark Currently only supported on Windows. + */ enum class EShellExecuteWindowState { + /** + * The process window is opened in the foreground and activated. + */ FOREGROUND, + + /** + * The process window is opened in the background without focus. + */ BACKGROUND, }; /** * Executes a given file. * + * @ingroup Shell + * * @param file The file to execute. * @param window_state The window state how the process window should be shown. * - * @return Handle of the new process, or `INVALID_PROCESS` on error. + * @return Handle of the new process, or @link INVALID_PROCESS @endlink on error. */ PROCESS shell_execute(const char *file, EShellExecuteWindowState window_state); /** * Sends kill signal to a process. * + * @ingroup Shell + * * @param process Handle of the process to kill. * - * @return 1 on success, 0 on error. + * @return `1` on success, `0` on error. */ int kill_process(PROCESS process); /** * Checks if a process is alive. * + * @ingroup Shell + * * @param process Handle/PID of the process. * - * @return bool Returns true if the process is currently running, false if the process is not running (dead). + * @return `true` if the process is currently running, + * `false` if the process is not running (dead). */ bool is_process_alive(PROCESS process); -/* - Function: generate_password - Generates a null-terminated password of length `2 * - random_length`. +/** + * Opens a link in the browser. + * + * @ingroup Shell + * + * @param link The link to open in a browser. + * + * @return `1` on success, `0` on failure. + * + * @remark The strings are treated as zero-terminated strings. + * @remark This may not be called with untrusted input or it'll result in arbitrary code execution, especially on Windows. + */ +int open_link(const char *link); - Parameters: - buffer - Pointer to the start of the output buffer. - length - Length of the buffer. - random - Pointer to a randomly-initialized array of shorts. - random_length - Length of the short array. -*/ +/** + * Opens a file or directory with default program. + * + * @ingroup Shell + * + * @param path The path to open. + * + * @return `1` on success, `0` on failure. + * + * @remark The strings are treated as zero-terminated strings. + * @remark This may not be called with untrusted input or it'll result in arbitrary code execution, especially on Windows. + */ +int open_file(const char *path); + +/** + * @defgroup Secure-Random + * Secure random number generation. + */ + +/** + * Generates a null-terminated password of length `2 * random_length`. + * + * @ingroup Secure-Random + * + * @param buffer Pointer to the start of the output buffer. + * @param length Length of the buffer. + * @param random Pointer to a randomly-initialized array of shorts. + * @param random_length Length of the short array. + */ void generate_password(char *buffer, unsigned length, const unsigned short *random, unsigned random_length); -/* - Function: secure_random_init - Initializes the secure random module. - You *MUST* check the return value of this function. - - Returns: - 0 - Initialization succeeded. - 1 - Initialization failed. -*/ +/** + * Initializes the secure random module. + * You *MUST* check the return value of this function. + * + * @ingroup Secure-Random + * + * @return `0` on success. + */ int secure_random_init(); -/* - Function: secure_random_uninit - Uninitializes the secure random module. - - Returns: - 0 - Uninitialization succeeded. - 1 - Uninitialization failed. -*/ +/** + * Uninitializes the secure random module. + * + * @ingroup Secure-Random + * + * @return `0` on success. + */ int secure_random_uninit(); -/* - Function: secure_random_password - Fills the buffer with the specified amount of random password - characters. - - The desired password length must be greater or equal to 6, even - and smaller or equal to 128. - - Parameters: - buffer - Pointer to the start of the buffer. - length - Length of the buffer. - pw_length - Length of the desired password. -*/ +/** + * Fills the buffer with the specified amount of random password characters. + * + * @ingroup Secure-Random + * + * @param buffer Pointer to the start of the buffer. + * @param length Length of the buffer. + * @param pw_length Length of the desired password. + * + * @remark The desired password length must be greater or equal to 6, + * even and smaller or equal to 128. + */ void secure_random_password(char *buffer, unsigned length, unsigned pw_length); -/* - Function: secure_random_fill - Fills the buffer with the specified amount of random bytes. - - Parameters: - buffer - Pointer to the start of the buffer. - length - Length of the buffer. -*/ +/** + * Fills the buffer with the specified amount of random bytes. + * + * @ingroup Secure-Random + * + * @param buffer Pointer to the start of the buffer. + * @param length Length of the buffer. + */ void secure_random_fill(void *bytes, unsigned length); -/* - Function: secure_rand - Returns random int (replacement for rand()). -*/ +/** + * Returns random `int`. + * + * @ingroup Secure-Random + * + * @return Random int. + * + * @remark Can be used as a replacement for the `rand` function. + */ int secure_rand(); -/* - Function: secure_rand_below - Returns a random nonnegative integer below the given number, - with a uniform distribution. - - Parameters: - below - Upper limit (exclusive) of integers to return. -*/ +/** + * Returns a random nonnegative integer below the given number, + * with a uniform distribution. + * + * @ingroup Secure-Random + * + * @param below Upper limit (exclusive) of integers to return. + * + * @return Random nonnegative below the given number. + */ int secure_rand_below(int below); /** * Returns a human-readable version string of the operating system. * + * @ingroup Shell + * * @param version Buffer to use for the output. * @param length Length of the output buffer. * - * @return true on success, false on failure. + * @return `true` on success, `false` on failure. */ bool os_version_str(char *version, size_t length); @@ -2643,6 +2694,8 @@ bool os_version_str(char *version, size_t length); * If the preferred locale could not be determined this function * falls back to the locale `"en-US"`. * + * @ingroup Shell + * * @param locale Buffer to use for the output. * @param length Length of the output buffer. * @@ -2651,7 +2704,25 @@ bool os_version_str(char *version, size_t length); void os_locale_str(char *locale, size_t length); #if defined(CONF_EXCEPTION_HANDLING) +/** + * @defgroup Exception-Handling + * Exception handling (crash logging). + */ + +/** + * Initializes the exception handling module. + * + * @ingroup Exception-Handling + */ void init_exception_handler(); + +/** + * Sets the filename for writing the crash log. + * + * @ingroup Exception-Handling + * + * @param log_file_path Absolute path to which crash log file should be written. + */ void set_exception_handler_log_file(const char *log_file_path); #endif @@ -2668,7 +2739,9 @@ int net_socket_read_wait(NETSOCKET sock, std::chrono::nanoseconds nanoseconds); /** * Fixes the command line arguments to be encoded in UTF-8 on all systems. - * This is a RAII wrapper for cmdline_fix and cmdline_free. + * This is a RAII wrapper for @link cmdline_fix @endlink and @link cmdline_free @endlink. + * + * @ingroup Shell */ class CCmdlineFix { @@ -2690,25 +2763,29 @@ public: #if defined(CONF_FAMILY_WINDOWS) /** - * Converts a utf8 encoded string to a wide character string + * Converts a UTF-8 encoded string to a wide character string * for use with the Windows API. * - * @param str The utf8 encoded string to convert. + * @ingroup Shell + * + * @param str The UTF-8 encoded string to convert. * * @return The argument as a wide character string. * * @remark The argument string must be zero-terminated. - * @remark Fails with assertion error if passed utf8 is invalid. + * @remark Fails with assertion error if passed UTF-8 is invalid. */ std::wstring windows_utf8_to_wide(const char *str); /** * Converts a wide character string obtained from the Windows API - * to a utf8 encoded string. + * to a UTF-8 encoded string. + * + * @ingroup Shell * * @param wide_str The wide character string to convert. * - * @return The argument as a utf8 encoded string, wrapped in an optional. + * @return The argument as a UTF-8 encoded string, wrapped in an optional. * The optional is empty, if the wide string contains invalid codepoints. * * @remark The argument string must be zero-terminated. @@ -2717,10 +2794,13 @@ std::optional windows_wide_to_utf8(const wchar_t *wide_str); /** * This is a RAII wrapper to initialize/uninitialize the Windows COM library, - * which may be necessary for using the open_file and open_link functions. + * which may be necessary for using the @link open_file @endlink and + * @link open_link @endlink functions. * Must be used on every thread. It's automatically used on threads created - * with thread_init. Pass true to the constructor on threads that own a - * window (i.e. pump a message queue). + * with @link thread_init @endlink. Pass `true` to the constructor on threads + * that own a window (i.e. pump a message queue). + * + * @ingroup Shell */ class CWindowsComLifecycle { @@ -2736,11 +2816,11 @@ public: * * @param protocol_name The name of the protocol. * @param executable The absolute path of the executable that will be associated with the protocol. - * @param updated Pointer to a variable that will be set to true, iff the shell needs to be updated. + * @param updated Pointer to a variable that will be set to `true`, iff the shell needs to be updated. * - * @return true on success, false on failure. + * @return `true` on success, `false` on failure. * - * @remark The caller must later call shell_update, iff the shell needs to be updated. + * @remark The caller must later call @link shell_update @endlink, iff the shell needs to be updated. */ bool shell_register_protocol(const char *protocol_name, const char *executable, bool *updated); @@ -2753,11 +2833,11 @@ bool shell_register_protocol(const char *protocol_name, const char *executable, * @param description A readable description for the file extension. * @param executable_name A unique name that will used to describe the application. * @param executable The absolute path of the executable that will be associated with the file extension. - * @param updated Pointer to a variable that will be set to true, iff the shell needs to be updated. + * @param updated Pointer to a variable that will be set to `true`, iff the shell needs to be updated. * - * @return true on success, false on failure. + * @return `true` on success, `false` on failure. * - * @remark The caller must later call shell_update, iff the shell needs to be updated. + * @remark The caller must later call @link shell_update @endlink, iff the shell needs to be updated. */ bool shell_register_extension(const char *extension, const char *description, const char *executable_name, const char *executable, bool *updated); @@ -2768,11 +2848,11 @@ bool shell_register_extension(const char *extension, const char *description, co * * @param name Readable name of the application. * @param executable The absolute path of the executable being registered. - * @param updated Pointer to a variable that will be set to true, iff the shell needs to be updated. + * @param updated Pointer to a variable that will be set to `true`, iff the shell needs to be updated. * - * @return true on success, false on failure. + * @return `true` on success, `false` on failure. * - * @remark The caller must later call shell_update, iff the shell needs to be updated. + * @remark The caller must later call @link shell_update @endlink, iff the shell needs to be updated. */ bool shell_register_application(const char *name, const char *executable, bool *updated); @@ -2784,11 +2864,11 @@ bool shell_register_application(const char *name, const char *executable, bool * * @param shell_class The shell class to delete. * For protocols this is the name of the protocol. * For file extensions this is the program ID associated with the file extension. - * @param updated Pointer to a variable that will be set to true, iff the shell needs to be updated. + * @param updated Pointer to a variable that will be set to `true`, iff the shell needs to be updated. * - * @return true on success, false on failure. + * @return `true` on success, `false` on failure. * - * @remark The caller must later call shell_update, iff the shell needs to be updated. + * @remark The caller must later call @link shell_update @endlink, iff the shell needs to be updated. */ bool shell_unregister_class(const char *shell_class, bool *updated); @@ -2798,11 +2878,11 @@ bool shell_unregister_class(const char *shell_class, bool *updated); * @ingroup Shell * * @param executable The absolute path of the executable being unregistered. - * @param updated Pointer to a variable that will be set to true, iff the shell needs to be updated. + * @param updated Pointer to a variable that will be set to `true`, iff the shell needs to be updated. * - * @return true on success, false on failure. + * @return `true` on success, `false` on failure. * - * @remark The caller must later call shell_update, iff the shell needs to be updated. + * @remark The caller must later call @link shell_update @endlink, iff the shell needs to be updated. */ bool shell_unregister_application(const char *executable, bool *updated);