src/shared/eventfd-util.c

   1 /*-*- Mode: C; c-basic-offset: 8; indent-tabs-mode: nil -*-*/
   2
   3 /***
   4   This file is part of systemd.
   5
   6   Copyright 2014 Djalal Harouni
   7
   8   systemd is free software; you can redistribute it and/or modify it
   9   under the terms of the GNU Lesser General Public License as published by
  10   the Free Software Foundation; either version 2.1 of the License, or
  11   (at your option) any later version.
  12
  13   systemd is distributed in the hope that it will be useful, but
  14   WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  16   Lesser General Public License for more details.
  17
  18   You should have received a copy of the GNU Lesser General Public License
  19   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  20 ***/
  21
  22 #include <assert.h>
  23 #include <errno.h>
  24 #include <unistd.h>
  25 #include <sys/eventfd.h>
  26 #include <sys/syscall.h>
  27
  28 #include "eventfd-util.h"
  29 #include "util.h"
  30
  31
  32 /*
  33  * Use this to create processes that need to setup a full context
  34  * and sync it with their parents using cheap mechanisms.
  35  *
  36  * This will create two blocking eventfd(s). A pair for the parent and
  37  * the other for the child so they can be used as a notify mechanism.
  38  * Each process will gets its copy of the parent and child eventfds.
  39  *
  40  * This is useful in case:
  41  * 1) If the parent fails or dies, the child must die.
  42  * 2) Child will install PR_SET_PDEATHSIG as soon as possible.
  43  * 3) Parent and child need to sync using less resources.
  44  * 4) If parent is not able to install a SIGCHLD handler:
  45  *    parent will wait using a blocking eventfd_read() or
  46  *    eventfd_child_succeeded() call on the child eventfd.
  47  *
  48  *    * If the child setup succeeded, child should notify with an
  49  *      EVENTFD_CHILD_SUCCEEDED, parent will continue.
  50  *    * If the child setup failed, child should notify with an
  51  *      EVENTFD_CHILD_FAILED before any _exit(). This avoids blocking
  52  *      the parent.
  53  *
  54  * 5) If parent is able to install a SIGCHLD handler:
  55  *    An empty signal handler without SA_RESTART will do it, since the
  56  *    blocking eventfd_read() or eventfd_parent_succeeded() of the
  57  *    parent will be interrupted by SIGCHLD and the call will fail with
  58  *    EINTR. This is useful in case the child dies abnormaly and did
  59  *    not have a chance to notify its parent using EVENTFD_CHILD_FAILED.
  60  *
  61  * 6) Call wait*() in the main instead of the signal handler in order
  62  *    to: 1) reduce side effects and 2) have a better handling for
  63  *    child termination in order to reduce various race conditions.
  64  *
  65  *
  66  * The return value of clone_with_eventfd() is the same of clone().
  67  * On success the eventfds[] will contain the two eventfd(s). These
  68  * file descriptors can be closed later with safe_close(). On failure,
  69  * a negative value is returned in the caller's context, and errno will
  70  * be set appropriately.
  71  *
  72  * Extra preliminary work:
  73  * 1) Child can wait before starting its setup by using the
  74  *    eventfd_recv_start() call on the parent eventfd, in that case the
  75  *    parent must notify with EVENTFD_START, after doing any preliminary
  76  *    work.
  77  *
  78  * Note: this function depends on systemd internal functions
  79  * safe_close() and it should be used only by direct binaries, no
  80  * libraries.
  81  */
  82 pid_t clone_with_eventfd(int flags, int eventfds[2]) {
  83         pid_t pid;
  84
  85         assert(eventfds);
  86
  87         eventfds[0] = eventfd(EVENTFD_INIT, EFD_CLOEXEC);
  88         if (eventfds[0] < 0)
  89                 return -1;
  90
  91         eventfds[1] = eventfd(EVENTFD_INIT, EFD_CLOEXEC);
  92         if (eventfds[1] < 0)
  93                 goto err_eventfd0;
  94
  95         pid = syscall(__NR_clone, flags, NULL);
  96         if (pid < 0)
  97                 goto err_eventfd1;
  98
  99         return pid;
 100
 101 err_eventfd1:
 102         eventfds[1] = safe_close(eventfds[1]);
 103 err_eventfd0:
 104         eventfds[0] = safe_close(eventfds[0]);
 105         return -1;
 106 }
 107
 108 int eventfd_send_state(int efd, eventfd_t s) {
 109         return eventfd_write(efd, s);
 110 }
 111
 112 /*
 113  * Receive an eventfd state on the eventfd file descriptor.
 114  *
 115  * If the third argument is set to a value other than zero, then this
 116  * function will compare the received value with this argument and set
 117  * the return value.
 118  *
 119  * On success return 0. On error, -1 will be returned, and errno will
 120  * be set appropriately.
 121  */
 122 int eventfd_recv_state(int efd, eventfd_t *e, eventfd_t s) {
 123         int ret;
 124
 125         ret = eventfd_read(efd, e);
 126         if (ret < 0)
 127                 return ret;
 128         else if (s != 0 && *e != s) {
 129                 errno = EINVAL;
 130                 return -1;
 131         }
 132
 133         return 0;
 134 }
 135
 136 /*
 137  * Receive the EVENTFD_START state on the eventfd file descriptor.
 138  *
 139  * On Success return 0. On error, -1 will be returned, and errno will
 140  * be set appropriately.
 141  */
 142 int eventfd_recv_start(int efd) {
 143         eventfd_t e = EVENTFD_INIT;
 144         return eventfd_recv_state(efd, &e, EVENTFD_START);
 145 }
 146
 147 /*
 148  * Receive the EVENTFD_PARENT_SUCCEEDED state on the eventfd file
 149  * descriptor.
 150  *
 151  * On Success return 0. On error, -1 will be returned, and errno will
 152  * be set appropriately.
 153  */
 154 int eventfd_parent_succeeded(int efd) {
 155         eventfd_t e = EVENTFD_INIT;
 156         return eventfd_recv_state(efd, &e, EVENTFD_PARENT_SUCCEEDED);
 157 }
 158
 159 /*
 160  * Receive the EVENTFD_CHILD_SUCCEEDED state on the eventfd file
 161  * descriptor.
 162  *
 163  * On Success return 0. On error, -1 will be returned, and errno will
 164  * be set appropriately.
 165  */
 166 int eventfd_child_succeeded(int efd) {
 167         eventfd_t e = EVENTFD_INIT;
 168         return eventfd_recv_state(efd, &e, EVENTFD_CHILD_SUCCEEDED);
 169 }