Merge branch 'feature/upstream' into develop

1 files changed, 233 insertions, 0 deletions

diff --git a/doc/process_management.rst b/doc/process_management.rst
new file mode 100644
index 0000000..8fe282b
--- /dev/null
+++ b/doc/process_management.rst
@@ -0,0 +1,233 @@
+==================
+Process management
+==================
+
+Historic note: The process code comes from a time before posix_spawn. It also
+relies on the POSIX functions ``fork``, ``execv``, ``execvp`` and ``pipe``, so
+it may not be available everywhere. Where this is the case, the functions will
+return ``-ENOSYS``.
+
+Process metadata structure
+==========================
+
+.. code-block:: c
+
+	#include <libHX/proc.h>
+
+	struct HXproc {
+		const struct HXproc_ops *p_ops;
+		void *p_data;
+		unsigned int p_flags;
+
+		/* Following members should only be read */
+		int p_stdin, p_stdout, p_stderr;
+		int p_pid;
+		char p_status;
+		bool p_exited, p_terminated;
+	};
+
+When creating a new process with the intent of running it asynchronously (using
+``HXproc_run_async``), the first three fields must be filled in by the user.
+
+``p_ops``
+	A table of callbacks, generally used for setting and/or
+	restoring signals before/after execution. This member may be
+	``NULL``.
+
+``p_data``
+	The user may provide a pointer of his choosing. It will be
+	passed the callback functions when invoked.
+
+``p_flags``
+	Process creation flags, see below.
+
+After the subprocess has been started, ``HXproc_run_async`` will have filled in
+some fields:
+
+``p_stdin``
+	If ``HXPROC_STDIN`` was specified in ``p_flags``, ``p_stdin`` will be
+	assigned the write side file descriptor of the subprocess's to-be
+	stdin. The subprocess will get the read side file descriptor in this
+	member. This is so that the correct fd is used in when
+	``p_ops->p_postfork`` is called.
+
+``p_stdout``
+	If ``HXPROC_STDOUT`` is specified in ``p_flags``, ``p_stdout`` will be
+	assigned the read side file descriptor of the subprocess's to-be
+	stdout. The subprocess will get the write side file descriptor value
+	from this member.
+
+``p_stderr``
+	If ``HXPROC_STDERR`` is specified in ``p_flags``, ``p_stderr`` will be
+	assigned the read side file descriptor of the subprocess's to-be stderr, and
+	the subprocess will get the write side fd.
+
+``p_pid``
+	The process ID of the spawned process.
+
+Upon calling ``HXproc_wait``, further fields will have been filled when the
+function returns:
+
+``p_exited``
+	Whether the process exited normally (cf. signalled/terminated).
+
+``p_terminated``
+	Whether the process was terminated (signalled).
+
+``p_status``
+	The exit status of the process or the termination signal.
+
+Flags
+-----
+
+Possible values for the ``p_flags`` member are:
+
+``HXPROC_STDIN``
+	The subprocess's stdin file descriptor shall be connected to the master
+	program, that is, not inherit the stdin of the master. Cannot be used
+	with ``HXproc_run_sync`` (because there would be no one to provide data
+	in a sync operation).
+
+``HXPROC_STDOUT``
+	Connect the stdout file descriptor of the subprocess with the master.
+	Cannot be used with ``HXproc_run_sync``.
+
+``HXPROC_STDERR``
+	Connect the stderr file descriptor of the subprocess with the master.
+	Cannot be used with ``HXproc_run_sync``.
+
+``HXPROC_NULL_STDIN``
+	The subprocess's stdin file descriptor shall be connected to
+	``/dev/null``. ``HXPROC_STDIN`` and ``HXPROC_NULL_STDIN`` are mutually
+	exclusive.
+
+``HXPROC_NULL_STDOUT``
+	Connect the stdout file descriptor of the subprocess to ``/dev/null``,
+	thereby essentially discarding its output. ``HXPROC_STDOUT`` and
+	``HXPROC_NULL_STDOUT`` are mutually exclusive.
+
+``HXPROC_NULL_STDERR``
+	Connect the stderr file descriptor of the subprocess to ``/dev/null``,
+	thereby essentially discarding its output. ``HXPROC_STDERR`` and
+	``HXPROC_NULL_STDERR`` are mutually exclusive.
+
+``HXPROC_VERBOSE``
+	Have the subprocess print an error message to stderr if exec'ing
+	returned an error.
+
+``HXPROC_A0``
+	``argv[0]`` refers to program file, while ``argv[1]`` to the program
+	invocation name, with ``argv[2]`` being the first argument, etc.
+	Without this flag, ``argv[0]`` will be both the program file and
+	program invocation name, and arguments begin at ``argv[1]``.
+
+``HXPROC_EXECV``
+	Normally, ``execvp`` will be used which scans ``$PATH for the program.
+	Use this flag to use ``execv`` instead, which will not do such thing.
+
+Callbacks
+=========
+
+.. code-block:: c
+
+	#include <libHX/proc.h>
+
+	struct HXproc_ops {
+		void (*p_prefork)(void *);
+		void (*p_postfork)(void *);
+		void (*p_complete)(void *);
+	};
+
+``struct HXproc_ops`` provides a way to run user-specified functions just
+before the fork, after, and when the process has been waited for. They can be
+used to set and/or restore signals as needed, for example. The function
+pointers can be ``NULL``. The ``p_data`` member is passed as an argument.
+
+``p_prefork``
+	Run immediately before calling ``fork``. This is useful for taking any
+	action regarding signals, like setting ``SIGCHLD`` to ``SIG_DFL``, or
+	``SIGPIPE`` to ``SIG_IGN``, for example.
+
+``p_postfork``
+	Run in the subprocess (and only there) after forking. Useful
+	to do a ``setuid`` or other change in privilege level.
+
+``p_complete``
+	Run in ``HXproc_wait`` when the process has been waited for.
+	Useful to restore the signal handler(s).
+
+Process control
+===============
+
+.. code-block:: c
+
+	#include <libHX/proc.h>
+
+	int HXproc_run_async(const char *const *argv, struct HXproc *proc);
+	int HXproc_run_sync(const char *const *argv, unsigned int flags);
+	int HXproc_wait(struct HXproc *proc);
+
+``HXproc_run_async``
+	Start a subprocess according to the parameters in proc. Returns a
+	negative errno code if something went wrong, or positive non-zero on
+	success.
+
+``HXproc_run_sync``
+	Start a subprocess synchronously, similar to calling ``system``, but
+	with the luxury of being able to specify arguments as separate strings
+	(via argv) rather than one big command line that is run through the
+	shell. ``flags`` is a value composed of the HXproc flags mentioned
+	above. ``HXPROC_STDIN``, ``HXPROC_STDOUT`` and ``HXPROC_STDERR`` are ignored
+	because there would be no one in a synchronous execution that
+	could supply data to these file descriptors or read from them.[#f1]_
+
+.. [#f1] Even for threads, please just use the async model.
+
+``HXproc_wait``
+	Wait for a subprocess to terminate, if it has not already. It will also
+	retrieve the exit status of the process and store it in the ``struct
+	HXproc``.
+
+The return value will be positive non-zero on success, or negative on
+error. Underlying system function's errors are returned, plus:
+
+``EINVAL``
+	Flags were not accepted.
+
+
+User identity control
+=====================
+
+.. code-block: c
+
+	#include <libHX/proc.h>
+
+	int HXproc_switch_user(const char *user, const char *group);
+
+``HXproc_switch_user`` is a wrapper for changing process identity to an
+unprivileged user. This utilizes ``setuid``, and possibly ``setgid`` plus
+``initgroups``.
+
+``user`` can either be a username or a numeric UID in string form, the latter
+of which will be parsed with strtoul in automatic base. If ``user`` is ``NULL``
+or the empty string, no change of process user identity occurs.
+
+``group`` can likewise be a name or GID. When ``group`` is ``NULL``, the
+process group(s) will change to the the user's group(s) — both primary and
+secondary — provided a user was specified (see above). When ``gruop`` is the
+empty string, no change of process group identity occurs.
+
+
+Process information
+===================
+
+.. code-block:: c
+
+	#include <libHX/proc.h>
+
+	int HXproc_top_fd(void);
+
+``HXproc_top_fd``
+	This function gives a heuristic for the highest fd in the process.
+	The returned number may be higher than the highest live fd actually.
+	On error, negative errno is returned.