D-Bus 1.4.0
sd-daemon.h
00001 /*-*- Mode: C; c-basic-offset: 8; indent-tabs-mode: nil -*-*/
00002 
00003 #ifndef foosddaemonhfoo
00004 #define foosddaemonhfoo
00005 
00006 /***
00007   Copyright 2010 Lennart Poettering
00008 
00009   Permission is hereby granted, free of charge, to any person
00010   obtaining a copy of this software and associated documentation files
00011   (the "Software"), to deal in the Software without restriction,
00012   including without limitation the rights to use, copy, modify, merge,
00013   publish, distribute, sublicense, and/or sell copies of the Software,
00014   and to permit persons to whom the Software is furnished to do so,
00015   subject to the following conditions:
00016 
00017   The above copyright notice and this permission notice shall be
00018   included in all copies or substantial portions of the Software.
00019 
00020   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
00021   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
00022   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
00023   NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
00024   BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
00025   ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
00026   CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
00027   SOFTWARE.
00028 ***/
00029 
00030 #include <sys/types.h>
00031 #include <inttypes.h>
00032 
00033 #ifdef __cplusplus
00034 extern "C" {
00035 #endif
00036 
00037 /*
00038   Reference implementation of a few systemd related interfaces for
00039   writing daemons. These interfaces are trivial to implement. To
00040   simplify porting we provide this reference implementation.
00041   Applications are welcome to reimplement the algorithms described
00042   here if they do not want to include these two source files.
00043 
00044   The following functionality is provided:
00045 
00046   - Support for logging with log levels on stderr
00047   - File descriptor passing for socket-based activation
00048   - Daemon startup and status notification
00049   - Detection of systemd boots
00050 
00051   You may compile this with -DDISABLE_SYSTEMD to disable systemd
00052   support. This makes all those calls NOPs that are directly related to
00053   systemd (i.e. only sd_is_xxx() will stay useful).
00054 
00055   Since this is drop-in code we don't want any of our symbols to be
00056   exported in any case. Hence we declare hidden visibility for all of
00057   them.
00058 
00059   You may find an up-to-date version of these source files online:
00060 
00061   http://cgit.freedesktop.org/systemd/plain/src/sd-daemon.h
00062   http://cgit.freedesktop.org/systemd/plain/src/sd-daemon.c
00063 
00064   This should compile on non-Linux systems, too, but with the
00065   exception of the sd_is_xxx() calls all functions will become NOPs.
00066 
00067   See sd-daemon(7) for more information.
00068 */
00069 
00070 #if __GNUC__ >= 4
00071 #define _sd_printf_attr_(a,b) __attribute__ ((format (printf, a, b)))
00072 #define _sd_hidden_ __attribute__ ((visibility("hidden")))
00073 #else
00074 #define _sd_printf_attr_(a,b)
00075 #define _sd_hidden_
00076 #endif
00077 
00078 /*
00079   Log levels for usage on stderr:
00080 
00081           fprintf(stderr, SD_NOTICE "Hello World!\n");
00082 
00083   This is similar to printk() usage in the kernel.
00084 */
00085 #define SD_EMERG   "<0>"  /* system is unusable */
00086 #define SD_ALERT   "<1>"  /* action must be taken immediately */
00087 #define SD_CRIT    "<2>"  /* critical conditions */
00088 #define SD_ERR     "<3>"  /* error conditions */
00089 #define SD_WARNING "<4>"  /* warning conditions */
00090 #define SD_NOTICE  "<5>"  /* normal but significant condition */
00091 #define SD_INFO    "<6>"  /* informational */
00092 #define SD_DEBUG   "<7>"  /* debug-level messages */
00093 
00094 /* The first passed file descriptor is fd 3 */
00095 #define SD_LISTEN_FDS_START 3
00096 
00097 /*
00098   Returns how many file descriptors have been passed, or a negative
00099   errno code on failure. Optionally, removes the $LISTEN_FDS and
00100   $LISTEN_PID file descriptors from the environment (recommended, but
00101   problematic in threaded environments). If r is the return value of
00102   this function you'll find the file descriptors passed as fds
00103   SD_LISTEN_FDS_START to SD_LISTEN_FDS_START+r-1. Returns a negative
00104   errno style error code on failure. This function call ensures that
00105   the FD_CLOEXEC flag is set for the passed file descriptors, to make
00106   sure they are not passed on to child processes. If FD_CLOEXEC shall
00107   not be set, the caller needs to unset it after this call for all file
00108   descriptors that are used.
00109 
00110   See sd_listen_fds(3) for more information.
00111 */
00112 int sd_listen_fds(int unset_environment) _sd_hidden_;
00113 
00114 /*
00115   Helper call for identifying a passed file descriptor. Returns 1 if
00116   the file descriptor is a FIFO in the file system stored under the
00117   specified path, 0 otherwise. If path is NULL a path name check will
00118   not be done and the call only verifies if the file descriptor
00119   refers to a FIFO. Returns a negative errno style error code on
00120   failure.
00121 
00122   See sd_is_fifo(3) for more information.
00123 */
00124 int sd_is_fifo(int fd, const char *path) _sd_hidden_;
00125 
00126 /*
00127   Helper call for identifying a passed file descriptor. Returns 1 if
00128   the file descriptor is a socket of the specified family (AF_INET,
00129   ...) and type (SOCK_DGRAM, SOCK_STREAM, ...), 0 otherwise. If
00130   family is 0 a socket family check will not be done. If type is 0 a
00131   socket type check will not be done and the call only verifies if
00132   the file descriptor refers to a socket. If listening is > 0 it is
00133   verified that the socket is in listening mode. (i.e. listen() has
00134   been called) If listening is == 0 it is verified that the socket is
00135   not in listening mode. If listening is < 0 no listening mode check
00136   is done. Returns a negative errno style error code on failure.
00137 
00138   See sd_is_socket(3) for more information.
00139 */
00140 int sd_is_socket(int fd, int family, int type, int listening) _sd_hidden_;
00141 
00142 /*
00143   Helper call for identifying a passed file descriptor. Returns 1 if
00144   the file descriptor is an Internet socket, of the specified family
00145   (either AF_INET or AF_INET6) and the specified type (SOCK_DGRAM,
00146   SOCK_STREAM, ...), 0 otherwise. If version is 0 a protocol version
00147   check is not done. If type is 0 a socket type check will not be
00148   done. If port is 0 a socket port check will not be done. The
00149   listening flag is used the same way as in sd_is_socket(). Returns a
00150   negative errno style error code on failure.
00151 
00152   See sd_is_socket_inet(3) for more information.
00153 */
00154 int sd_is_socket_inet(int fd, int family, int type, int listening, uint16_t port) _sd_hidden_;
00155 
00156 /*
00157   Helper call for identifying a passed file descriptor. Returns 1 if
00158   the file descriptor is an AF_UNIX socket of the specified type
00159   (SOCK_DGRAM, SOCK_STREAM, ...) and path, 0 otherwise. If type is 0
00160   a socket type check will not be done. If path is NULL a socket path
00161   check will not be done. For normal AF_UNIX sockets set length to
00162   0. For abstract namespace sockets set length to the length of the
00163   socket name (including the initial 0 byte), and pass the full
00164   socket path in path (including the initial 0 byte). The listening
00165   flag is used the same way as in sd_is_socket(). Returns a negative
00166   errno style error code on failure.
00167 
00168   See sd_is_socket_unix(3) for more information.
00169 */
00170 int sd_is_socket_unix(int fd, int type, int listening, const char *path, size_t length) _sd_hidden_;
00171 
00172 /*
00173   Informs systemd about changed daemon state. This takes a number of
00174   newline seperated environment-style variable assignments in a
00175   string. The following variables are known:
00176 
00177      READY=1      Tells systemd that daemon startup is finished (only
00178                   relevant for services of Type=notify). The passed
00179                   argument is a boolean "1" or "0". Since there is
00180                   little value in signalling non-readiness the only
00181                   value daemons should send is "READY=1".
00182 
00183      STATUS=...   Passes a single-line status string back to systemd
00184                   that describes the daemon state. This is free-from
00185                   and can be used for various purposes: general state
00186                   feedback, fsck-like programs could pass completion
00187                   percentages and failing programs could pass a human
00188                   readable error message. Example: "STATUS=Completed
00189                   66% of file system check..."
00190 
00191      ERRNO=...    If a daemon fails, the errno-style error code,
00192                   formatted as string. Example: "ERRNO=2" for ENOENT.
00193 
00194      BUSERROR=... If a daemon fails, the D-Bus error-style error
00195                   code. Example: "BUSERROR=org.freedesktop.DBus.Error.TimedOut"
00196 
00197      MAINPID=...  The main pid of a daemon, in case systemd did not
00198                   fork off the process itself. Example: "MAINPID=4711"
00199 
00200   Daemons can choose to send additional variables. However, it is
00201   recommened to prefix variable names not listed above with X_.
00202 
00203   Returns a negative errno-style error code on failure. Returns > 0
00204   if systemd could be notified, 0 if it couldn't possibly because
00205   systemd is not running.
00206 
00207   Example: When a daemon finished starting up, it could issue this
00208   call to notify systemd about it:
00209 
00210      sd_notify(0, "READY=1");
00211 
00212   See sd_notifyf() for more complete examples.
00213 
00214   See sd_notify(3) for more information.
00215 */
00216 int sd_notify(int unset_environment, const char *state) _sd_hidden_;
00217 
00218 /*
00219   Similar to sd_notify() but takes a format string.
00220 
00221   Example 1: A daemon could send the following after initialization:
00222 
00223      sd_notifyf(0, "READY=1\n"
00224                    "STATUS=Processing requests...\n"
00225                    "MAINPID=%lu",
00226                    (unsigned long) getpid());
00227 
00228   Example 2: A daemon could send the following shortly before
00229   exiting, on failure:
00230 
00231      sd_notifyf(0, "STATUS=Failed to start up: %s\n"
00232                    "ERRNO=%i",
00233                    strerror(errno),
00234                    errno);
00235 
00236   See sd_notifyf(3) for more information.
00237 */
00238 int sd_notifyf(int unset_environment, const char *format, ...) _sd_printf_attr_(2,3) _sd_hidden_;
00239 
00240 /*
00241   Returns > 0 if the system was booted with systemd. Returns < 0 on
00242   error. Returns 0 if the system was not booted with systemd. Note
00243   that all of the functions above handle non-systemd boots just
00244   fine. You should NOT protect them with a call to this function. Also
00245   note that this function checks whether the system, not the user
00246   session is controlled by systemd. However the functions above work
00247   for both session and system services.
00248 
00249   See sd_booted(3) for more information.
00250 */
00251 int sd_booted(void) _sd_hidden_;
00252 
00253 #ifdef __cplusplus
00254 }
00255 #endif
00256 
00257 #endif