process_util.h

// SPDX-License-Identifier: Apache-2.0

#ifndef XSECURELOCK_PROCESS_UTIL_H
#define XSECURELOCK_PROCESS_UTIL_H

#include <stdbool.h>
#include <unistd.h>  // for pid_t

typedef void (*ChildSetupFn)(void *arg);

struct ChildStdioSetup {
  int stdin_fd;
  int stdout_fd;
  int stderr_fd;  // -1 leaves stderr inherited.
};

/*! \brief Fork a subprocess, but do not inherit our signal handlers.
 *
 * Otherwise behaves exactly like fork().
 */
pid_t ForkWithoutSigHandlers(void);

/*! \brief Starts a new process group.
 *
 * Must be called from a child process, which will become the process group
 * leader. The process group will never die, unless killed using KillPgrp.
 */
void StartPgrp(void);

/*! \brief Forks and execs a helper subprocess.
 *
 * The child resets inherited signal handlers, optionally runs setup, then
 * execs the helper. The parent receives the child PID as fork() would.
 */
pid_t ForkHelperChild(const char *label, ChildSetupFn setup, void *setup_arg,
                      const char *path, const char *const argv[]);

/*! \brief Forks and execs a helper subprocess in a new process group.
 *
 * Like ForkHelperChild(), but the child calls StartPgrp() before setup.
 */
pid_t ForkHelperPgrpChild(const char *label, ChildSetupFn setup,
                          void *setup_arg, const char *path,
                          const char *const argv[]);

/*! \brief Executes an arbitrary PATH-resolved program and exits on failure.
 */
void ExecvpOrExit(const char *path, char *const argv[]);

/*! \brief Moves configured descriptors onto child stdin/stdout/stderr.
 *
 * Any field set to -1 is left inherited. This function exits the current child
 * process on failure.
 */
void ChildWireStdioOrExit(const struct ChildStdioSetup *setup);

/*! \brief Waits for exactly pid, retrying EINTR.
 *
 * \return true when the child was waited successfully, false on waitpid
 *   failure.
 */
bool WaitPidNoEintr(pid_t pid, int *status_out);

/*! \brief Logs a wait status and returns whether it represents success. */
bool LogWaitStatus(const char *label, int status);

void KillProcIfRunning(pid_t pid, int signo);

#endif  // XSECURELOCK_PROCESS_UTIL_H