src/systemd/sd-shutdown.h

   1 /*-*- Mode: C; c-basic-offset: 8; indent-tabs-mode: nil -*-*/
   2
   3 #ifndef foosdshutdownhfoo
   4 #define foosdshutdownhfoo
   5
   6 /***
   7   This file is part of systemd.
   8
   9   Copyright 2010 Lennart Poettering
  10
  11   systemd is free software; you can redistribute it and/or modify it
  12   under the terms of the GNU General Public License as published by
  13   the Free Software Foundation; either version 2 of the License, or
  14   (at your option) any later version.
  15
  16   systemd is distributed in the hope that it will be useful, but
  17   WITHOUT ANY WARRANTY; without even the implied warranty of
  18   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  19   General Public License for more details.
  20
  21   You should have received a copy of the GNU General Public License
  22   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  23 ***/
  24
  25 /* Interface for scheduling and cancelling timed shutdowns. */
  26
  27 #include <inttypes.h>
  28
  29 typedef enum sd_shutdown_mode {
  30         SD_SHUTDOWN_NONE = 0,
  31         SD_SHUTDOWN_REBOOT = 'r',
  32         SD_SHUTDOWN_POWEROFF = 'P',
  33         SD_SHUTDOWN_HALT = 'H',
  34         SD_SHUTDOWN_KEXEC = 'K'
  35 } sd_shutdown_mode_t;
  36
  37 /* Calculate the size of the message as "offsetof(struct
  38  * sd_shutdown_command, wall_message) +
  39  * strlen(command.wall_message)" */
  40 __attribute__((packed)) struct sd_shutdown_command {
  41         /* Microseconds after the epoch 1970 UTC */
  42         uint64_t usec;
  43
  44         /* H, P, r, i.e. the switches usually passed to
  45          * /usr/bin/shutdown to select whether to halt, power-off or
  46          * reboot the machine */
  47         sd_shutdown_mode_t mode:8;
  48
  49         /* If non-zero, don't actually shut down, just pretend */
  50         unsigned dry_run:1;
  51
  52         /* If non-zero, send our wall message */
  53         unsigned warn_wall:1;
  54
  55         /* The wall message to send around. Leave empty for the
  56          * default wall message */
  57         char wall_message[];
  58 };
  59
  60 /* The scheme is very simple:
  61  *
  62  * To schedule a shutdown, simply fill in and send a single
  63  * AF_UNIX/SOCK_DGRAM datagram with the structure above suffixed with
  64  * the wall message to the socket /run/systemd/shutdownd (leave an
  65  * empty wall message for the default shutdown message). To calculate
  66  * the size of the message use "offsetof(struct sd_shutdown_command,
  67  * wall_message) + strlen(command.wall_message)".
  68  *
  69  * To cancel a shutdown, do the same, but send an fully zeroed out
  70  * structure.
  71  *
  72  * To be notified about scheduled shutdowns, create an inotify watch
  73  * on /run/shutdown/. Whenever a file called "scheduled" appears a
  74  * shutdown is scheduled. If it is removed it is canceled. It is
  75  * replaced the scheduled shutdown has been changed. The file contains
  76  * a simple environment-like block, that contains information about
  77  * the scheduled shutdown:
  78  *
  79  * USEC=
  80  * encodes the time for the shutdown in usecs since the epoch UTC,
  81  * formatted as numeric string.
  82  *
  83  * WARN_WALL=
  84  * is 1 if a wall message shall be sent
  85  *
  86  * DRY_RUN=
  87  * is 1 if a dry run shutdown is scheduled
  88  *
  89  * MODE=
  90  * is the shutdown mode, one of "poweroff", "reboot", "halt", "kexec"
  91  *
  92  * WALL_MESSAGE=
  93  * is the wall message to use, with all special characters escape in C style.
  94  *
  95  * Note that some fields might be missing if they do not apply.
  96  *
  97  * Note that the file is first written to a temporary file and then
  98  * renamed, in order to provide atomic properties for readers: if the
  99  * file exists under the name "scheduled" it is guaranteed to be fully
 100  * written. A reader should ignore all files in that directory by any
 101  * other name.
 102  *
 103  * Scheduled shutdowns are only accepted from privileged processes,
 104  * but the directory may be watched and the file in it read by
 105  * anybody.
 106  */
 107
 108 #endif