lib/util/tfork.h

   1 /*
   2    fork on steroids to avoid SIGCHLD and waitpid
   3
   4    Copyright (C) Stefan Metzmacher 2010
   5    Copyright (C) Ralph Boehme 2017
   6
   7    This program is free software; you can redistribute it and/or modify
   8    it under the terms of the GNU General Public License as published by
   9    the Free Software Foundation; either version 3 of the License, or
  10    (at your option) any later version.
  11
  12    This program is distributed in the hope that it will be useful,
  13    but WITHOUT ANY WARRANTY; without even the implied warranty of
  14    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15    GNU General Public License for more details.
  16
  17    You should have received a copy of the GNU General Public License
  18    along with this program.  If not, see <http://www.gnu.org/licenses/>.
  19 */
  20
  21 #ifndef LIB_UTIL_TFORK_H
  22 #define LIB_UTIL_TFORK_H
  23
  24 struct tfork;
  25
  26 /**
  27  * @brief a fork() that avoids SIGCHLD and waitpid
  28  *
  29  * This function is a solution to the problem of fork() requiring special
  30  * preperations in the caller to handle SIGCHLD signals and to reap the child by
  31  * wait()ing for it.
  32  *
  33  * The advantage over fork() is that the child process termination is signalled
  34  * to the caller by making a pipe fd readable returned by tfork_event_fd(), in
  35  * which case the exit status of the child can be fetched with tfork_status()
  36  * without blocking.
  37  *
  38  * The child process will start with SIGCHLD handler set to SIG_DFL.
  39  *
  40  * @return                On success, a struct tfork. NULL on failure.
  41  *                        Use tfork_worker_pid() to get the pid of the created
  42  *                        child and tfork_event_fd() to get the file descriptor
  43  *                        that can be used to poll for process termination and
  44  *                        reading the child process exit status.
  45  *
  46  * @note There's one thing this thing can't protect us against and that is if a
  47  * process installs a SIGCHLD handler from one thread while another thread is
  48  * running inside tfork_create() or tfork_status() and the signal handler
  49  * doesn't forward signals for exitted childs it didn't fork, ie our childs.
  50  **/
  51 struct tfork *tfork_create(void);
  52
  53 /**
  54  * @brief Return the child pid from tfork_create()
  55  *
  56  * @param[in]   t    Pointer to struct tfork returned by tfork_create()
  57  *
  58  * @return           In the caller this returns the pid of the child,
  59  *                   in the child this returns 0.
  60  **/
  61 pid_t tfork_child_pid(const struct tfork *t);
  62
  63 /**
  64  * @brief Return an event fd that signals child termination
  65  *
  66  * @param[in]   t    Pointer to struct tfork returned by tfork_create()
  67  *
  68  * @return           An fd that becomes readable when the child created with
  69  *                   tfork_create() terminates. It is guaranteed that a
  70  *                   subsequent call to tfork_status() will not block and return
  71  *                   the exit status of the child.
  72  **/
  73 int tfork_event_fd(const struct tfork *t);
  74
  75 /**
  76  * @brief Wait for the child to terminate and return its exit status
  77  *
  78  * @param[in]   t     Pointer-pointer to a struct tfork returned by
  79  *                    tfork_create(). Upon successful completion t is freed and
  80  *                    set to NULL.
  81  *
  82  * @param[in]   wait  Whether to wait for the child to change state. If wait is
  83  *                    false, and the child hasn't changed state, tfork_status()
  84  *                    will return -1 with errno set to EAGAIN. If wait is true,
  85  *                    tfork_status() will block waiting for the child to change
  86  *                    runstate.
  87  *
  88  * @return            The exit status of the child, -1 on error.
  89  *
  90  * @note We overload the return value a bit, but a process exit status is pretty
  91  * much guaranteed to be a 16-bit int and can't be -1.
  92  **/
  93 int tfork_status(struct tfork **_t, bool wait);
  94
  95 /**
  96  * @brief Terminate the child discarding the exit status
  97  *
  98  * @param[in]   t     Pointer-pointer to a struct tfork returned by
  99  *                    tfork_create(). Upon successful completion t is freed and
 100  *                    set to NULL.
 101  *
 102  * @return            0 on success, -1 on error.
 103  **/
 104 int tfork_destroy(struct tfork **_t);
 105
 106 #endif /* LIB_UTIL_TFORK_H */