NGS_PROCID proc_id_from_self(); returns the process identifier for the current process, (or current running instance of the application). On Windows, this identifier is an unsigned long. On Unix-likes, this number is a signed int. Despite being signed on Unix-likes, process identifiers should never be a negative number unless to indicate an error of some kind. For portability reasons, across Windows and Unix-likes, none of the functions in the xproc library will return a negative number to represent an error. Instead, it should return zero, with errno being set to non-zero. Getting the process identifier of the current process never fails, and so it will never return zero, nor will it ever set errno to a non-zero value.
std::vector<NGS_PROCID> proc_id_enum(); returns a C++ std::vector of process identifiers for every running process in the current user session. On some platforms the process identifier of zero is included by default, while on other platforms it is omitted, despite it always pointing to a valid and existing process id, one which represents the process swapper. For the sake of consistency, the vector returned by this function will prepend a process identifier of zero to the vector depending on whether the underlying platform-specific API happened to omit that process identifier. On Unix-likes, a process identifier of one represents the system initialization process, which is responsible for starting up and shutting down your machine. This function only includes thread group identifiers in the vector, which are the process identifiers of a process's main thread. Kernel thread identifiers are omitted. On failure, std::vector::empty() will be true.
bool proc_id_exists(NGS_PROCID proc_id); returns true if the process identifier in proc_id represents a process which is running in the current user session. This function will iterate over all processes running in the current user session until one is found which is represented by the process identifier passed to the proc_id argument, and if one is found, true is returned; otherwise, false is returned because the specified process identifier did not match an existing process in the current user session. This function only checks for equality of existing thread group identifiers, which are the process identifiers of a process's main thread. Kernel thread identifiers are omitted from the check. To check for the existence of kernel threads, consider using a different API. On failure, the return value will be false, and errno will be set to a non-zero value.
bool proc_id_suspend(NGS_PROCID proc_id); suspends the process represented by the process identifier in the proc_id argument. Returns true on success; returns false on failure. Useful for preventing race conditions when reading foreign process information. Also good for debugging applications.
bool proc_id_resume(NGS_PROCID proc_id); resumes a previously suspended process represented by the process identifier in the proc_id argument. Returns true on success; returns false on failure. Useful for preventing race conditions when reading foreign process information. Also good for debugging applications.
bool proc_id_kill(NGS_PROCID proc_id); kills the process represented by the process identifier in the proc_id argument. When a process is killed, it is forced to be closed by the calling process. It can be dangerous to accidentally kill the wrong process. Returns true on success; returns false on failure.
std::vector<NGS_PROCID> parent_proc_id_from_proc_id(NGS_PROCID proc_id); on success, the function returns a C++ std::vector holding a single process identifier which represents the parent process of the process identifier provided in the proc_id argument. std::vector::empty() returns true if the function fails, and errno will be set to a non-zero value. Every process is guaranteed to have a parent, even if the function fails to find one. A process identifier of zero has a parent; its parent is itself.
std::vector<NGS_PROCID> proc_id_from_parent_proc_id(NGS_PROCID parent_proc_id); on success, the function returns a C++ std::vector holding all process identifiers which represent the children of the given parent process identifier in the parent_proc_id argument. std::vector::empty() returns true if there are no children, or if the function has failed. To determine whether an error occurred, check against the value of errno after a call to the function. errno will be non-zero if an error occurred.
std::vector<NGS_PROCID> proc_id_from_exe(std::string exe); on success, the function returns a C++ std::vector holding all process identifiers which represent matches in a search of the given criteria in the std::string exe argument. The criteria in the search may be one of three things; the executable basename associated with the process, the executable absolute pathname, or the directory the executable spawned from, (without a trailing slash at the end). Note the criteria in the search will be case-sensitive on Unix-likes, and an absolute, normalized pathname. There should be no double slashes, no dot, and no dot-dot, provided in the search. If no matches were found, the function fails and std::vector::empty() returns true.
std::vector<NGS_PROCID> proc_id_from_cwd(std::string cwd); on success, the function returns a C++ std::vector holding all process identifiers which represent matches in a search of the given criteria in the std::string cwd argument. The criteria in the search may be one thing; the current working directory associated with the process, (without a trailing slash at the end). Note the criteria in the search will be a case-sensitive on Unix-likes, and an absolute, normalized pathname. There should be no double slashes, no dot, and no dot-dot, provided in the search. If no matches were found, the function fails and std::vector::empty() returns true.
std::string exe_from_proc_id(NGS_PROCID proc_id); returns the executable pathname associated with the given process identifier in the proc_id argument. std::string::empty() is true if the function has failed. The return value will be an absolute pathname with all symbollic links resolved. The pathname will be normalized, meaning there will be no double slashes, no dot, and no dot-dot in the returned pathname. The returned pathname is limited to MAX_PATH characters on Windows, and on Unix-likes, the returned pathname is limited to PATH_MAX characters. PATH_MAX is implementation-defined by the platform.
std::string cwd_from_proc_id(NGS_PROCID proc_id); returns the current working directory associated with the given process identifier in the proc_id argument. std::string::empty() is true if the function has failed. The return value will be an absolute pathname with all symbollic links resolved. The pathname will be normalized, meaning there will be no double slashes, no dot, and no dot-dot in the returned pathname. The returned pathname is limited to MAX_PATH characters on Windows, and on Unix-likes, the returned pathname is limited to PATH_MAX characters. PATH_MAX is implementation-defined by the platform. The pathname returned will not contain a trailing slash on all platforms. On Windows, the underlying API has a trailing slash, which this function removes. On Windows, the calling process must be spawned from an executable whose architecture is the same as the executable which spawned the target process identifier, if the calling process was spawned from a 32-bit executable, otherwise, the function will fail.
std::string comm_from_proc_id(NGS_PROCID proc_id); returns the executable filename, (or command name), associated with the given process identifier in the proc_id argument, not including the executable filename's path component. std::string::empty() is true if the function has failed. Some platforms have an official API to get this information, (most Unix-likes do), however it is truncated to MAXCOMMLEN or something similar, which is often a very short amount of characters, not fit for longer filenames. Instead of using the official API for this purpose, this function retrieves the absolute pathname of the executable using an internal call to exe_from_proc_id(), and then removes the path component from the resulting filename, (thus giving the command name).
std::vector<std::string> cmdline_from_proc_id(NGS_PROCID proc_id); returns a C++ std::vector of the full list of command line arguments associated with the given process represented by the process identifier in the proc_id argument. On most platforms this value can be modified by the process associated with it, as well as its initial value by the parent process which spawned it. The exception to this would be on macOS, the C++ std::vector returned will be the initial command line argument values, and will not return any modifications that were made to the command line arguments by the process represented by the process intentifier passed to the proc_id argument of this function. std::vector::empty() returns true if the function failed, and errno will be set to a non-zero value. On Windows, the calling process must be spawned from an executable whose architecture is the same as the executable which spawned the target process identifier, if the calling process was spawned from a 32-bit executable, otherwise, the function will fail.
std::vector<std::string> environ_from_proc_id(NGS_PROCID proc_id); returns a C++ std::vector of the full list of environment variables associated with the given process represented by the process identifier in the proc_id argument. On most platforms this value can be modified by the process associated with it, as well as its initial value by the parent process which spawned it. The exception to this would be on macOS, the C++ std::vector returned will be the initial environment variables passed to the executable, and will not return any modifications that were made to the environment variables by the process represented by the process intentifier passed to the proc_id argument of this function. std::vector::empty() returns true if the function failed, and errno will be set to a non-zero value. On Windows, the calling process must be spawned from an executable whose architecture is the same as the executable which spawned the target process identifier, if the calling process was spawned from a 32-bit executable, otherwise, the function will fail.
std::string envvar_value_from_proc_id(NGS_PROCID proc_id, std::string name); returns the string value of an environment variable of the given name in the name argument belonging to the process whose process identifier is represented by the proc_id argument. std::string::empty() returns true if the variable does not exist or if the value it has is empty. To find out if a environment variable exists within the scope of a foreign process environment block, call envvar_exists_from_proc_id() instead, as there are times where a variable does exist within the environment block but has no value associated with it. On Windows, the calling process must be spawned from an executable whose architecture is the same as the executable which spawned the target process identifier, if the calling process was spawned from a 32-bit executable, otherwise, the function will fail. On failure, std::string::empty() will be true, and errno will be set to a non-zero value.
bool envvar_exists_from_proc_id(NGS_PROCID proc_id, std::string name); returns whether an environment variable of the given name in the name argument belongs to the process whose process identifier is represented by the proc_id argument. Returns true if the variable was found, and returns false otherwise. On Windows, the calling process must be spawned from an executable whose architecture is the same as the executable which spawned the target process identifier, if the calling process was spawned from a 32-bit executable, otherwise, the function will fail. On failure, the return value will be false, and errno will be set to a non-zero value.
NGS_PROCID spawn_child_proc_id(std::string command, bool wait); spawns a new child process, while returning the process identifier used to represent the new child. The child is spawned based on the given command line in the command argument, and wait indicates whether to spawn the child in the calling thread when true, or to spawn within a new thread when false. On most Unix-likes, the command line is run from the shell interpreter provided by "/bin/sh", except on Android, where that shell is located at "/system/bin/sh" instead. Regardless of system configuration, operating system, or operating system distribution, the function attempts to return the process identifier spawned directly in the command argument, and not the process identifier of the parent shell process. This means if you try to run "/bin/gedit" on Linux, for example, if successful, it will always return the exact process identifier for "/bin/gedit", and not the process identifier of the shell instance which spawned it, (for example, "/bin/sh"). On Windows, by contrast, no default shell is used to spawn the command line. If you want to spawn a child process on Windows with Command Prompt as your shell, for example, you would still need to specifiy "cmd.exe" in your command argument string directly, along with "/c" passed to it to prevent infinite hanging when the command completes. On Windows, unlike Unix-likes, it will indeed return the shell interpreter's process identifier, if one is used, because the shell would need to be specified in the command argument directly. Known issue: the wait argument, (when set to true), is known to sometimes allow the calling thread to resume sooner than it was intended to, when compiling with MSVC on Windows in Release Mode. Thus, it is recommended on Windows to either build in Debug Mode with MSVC or to use MinGW as your compiler instead.
void stdout_set_buffer_limit(long long limit); sets the buffer limit, (in bytes), for the string held in the standard output file descriptor, for all children processes spawned from the spawn_child_proc_id() function. To reiterate, this limit will be applied to all child processes spawned from the spawn_child_proc_id() function. There is no limit by default, which is both dangerous and can result in buffer overflow with very large strings. Setting a buffer limit is recommended in most cases. If a buffer limit is to be temporarily set, and turned back off again, set the limit to zero, to have no more limit, on the number of bytes the buffer can hold again. To read from the standard output buffer string of a process spawned from the spawn_child_proc_id() function, call the read_from_stdout_for_child_proc_id() function, while passing the child process identifier to it, and get the string from the returned value.
std::string read_from_stdout_for_child_proc_id(NGS_PROCID proc_id); returns the string held in the standard output file descriptor, for a child process spawned from the spawn_child_proc_id() function, based on the given child process identifier. This string can have its number of bytes truncated to a specified limit as provided by the stdout_set_buffer_limit() function. Always free the standard output string when the child process has completed execution by passing its process identifier to the free_stdout_for_child_proc_id() function. To check whether a child process has completed running, call the child_proc_id_is_complete() function on its process identifier.
long long write_to_stdin_for_child_proc_id(NGS_PROCID proc_id, std::string input); writes a string to the standard input file descriptor for the specified child process identifier, using the given input argument as the string to write. Returns the number of bytes written, or -1 if the function failed to write anything. Always free the standard input string when the child process has completed execution by passing its process identifier to the free_stdin_for_child_proc_id() function. To check whether a child process has completed running, call the child_proc_id_is_complete() function on its process identifier.
bool child_proc_id_is_complete(NGS_PROCID proc_id); returns true whenever the child process indentifier specificed in the proc_id argument corresponds to a process that either previously spawned from a call to the spawn_child_proc_id() function and completed its execution, or points to a non-existent child process identifier. Returns false if the child process both exists and is still running. Known issue: when compiling with MSVC on Windows in Release Mode, this function is known to return true incorrectly. Thus, it is recommended on Windows to either build in Debug Mode with MSVC or to use MinGW as your compiler instead.
std::string read_from_stdin_for_self() returns the string held in the standard input file descriptor, for the current process. std::string::empty() is true if the function has failed, or also when the file descriptor has no string which has been written to it yet. Known issue: on Windows, you must build your app using the Windows subsystem to make it be treated like a GUI program, and not a console, otherwise the fucnition will fail. The Windows subsystem can be used with the /subsystem:windows linker flag in MSVC or the -mwindows linker flag in MinGW.
bool free_stdout_for_child_proc_id(NGS_PROCID proc_id); frees the string held in the standard output file descriptor of the given child process identifier, as indicated by the proc_id argument, which was a process previously spawned from the spawn_child_proc_id() function, and the child completed its execution. Do not attempt to use this function on a child process which is still running. To check whether a child process has completed running, call the child_proc_id_is_complete() function on its process identifier.
bool free_stdin_for_child_proc_id(NGS_PROCID proc_id); frees the string held in the standard input file descriptor of the given child process identifier, as indicated by the proc_id argument, which was a process previously spawned from the spawn_child_proc_id() function, and the child completed its execution. Do not attempt to use this function on a child process which is still running. To check whether a child process has completed running, call the child_proc_id_is_complete() function on its process identifier.