pcsc-lite  1.7.4
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 #ifndef _sd_printf_attr_
00071 #if __GNUC__ >= 4
00072 #define _sd_printf_attr_(a,b) __attribute__ ((format (printf, a, b)))
00073 #else
00074 #define _sd_printf_attr_(a,b)
00075 #endif
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);
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);
00125 
00126 /*
00127   Helper call for identifying a passed file descriptor. Returns 1 if
00128   the file descriptor is a special character device on the file
00129   system stored under the specified path, 0 otherwise.
00130   If path is NULL a path name check will not be done and the call
00131   only verifies if the file descriptor refers to a special character.
00132   Returns a negative errno style error code on failure.
00133 
00134   See sd_is_special(3) for more information.
00135 */
00136 int sd_is_special(int fd, const char *path);
00137 
00138 /*
00139   Helper call for identifying a passed file descriptor. Returns 1 if
00140   the file descriptor is a socket of the specified family (AF_INET,
00141   ...) and type (SOCK_DGRAM, SOCK_STREAM, ...), 0 otherwise. If
00142   family is 0 a socket family check will not be done. If type is 0 a
00143   socket type check will not be done and the call only verifies if
00144   the file descriptor refers to a socket. If listening is > 0 it is
00145   verified that the socket is in listening mode. (i.e. listen() has
00146   been called) If listening is == 0 it is verified that the socket is
00147   not in listening mode. If listening is < 0 no listening mode check
00148   is done. Returns a negative errno style error code on failure.
00149 
00150   See sd_is_socket(3) for more information.
00151 */
00152 int sd_is_socket(int fd, int family, int type, int listening);
00153 
00154 /*
00155   Helper call for identifying a passed file descriptor. Returns 1 if
00156   the file descriptor is an Internet socket, of the specified family
00157   (either AF_INET or AF_INET6) and the specified type (SOCK_DGRAM,
00158   SOCK_STREAM, ...), 0 otherwise. If version is 0 a protocol version
00159   check is not done. If type is 0 a socket type check will not be
00160   done. If port is 0 a socket port check will not be done. The
00161   listening flag is used the same way as in sd_is_socket(). Returns a
00162   negative errno style error code on failure.
00163 
00164   See sd_is_socket_inet(3) for more information.
00165 */
00166 int sd_is_socket_inet(int fd, int family, int type, int listening, uint16_t port);
00167 
00168 /*
00169   Helper call for identifying a passed file descriptor. Returns 1 if
00170   the file descriptor is an AF_UNIX socket of the specified type
00171   (SOCK_DGRAM, SOCK_STREAM, ...) and path, 0 otherwise. If type is 0
00172   a socket type check will not be done. If path is NULL a socket path
00173   check will not be done. For normal AF_UNIX sockets set length to
00174   0. For abstract namespace sockets set length to the length of the
00175   socket name (including the initial 0 byte), and pass the full
00176   socket path in path (including the initial 0 byte). The listening
00177   flag is used the same way as in sd_is_socket(). Returns a negative
00178   errno style error code on failure.
00179 
00180   See sd_is_socket_unix(3) for more information.
00181 */
00182 int sd_is_socket_unix(int fd, int type, int listening, const char *path, size_t length);
00183 
00184 /*
00185   Helper call for identifying a passed file descriptor. Returns 1 if
00186   the file descriptor is a POSIX Message Queue of the specified name,
00187   0 otherwise. If path is NULL a message queue name check is not
00188   done. Returns a negative errno style error code on failure.
00189 */
00190 int sd_is_mq(int fd, const char *path);
00191 
00192 /*
00193   Informs systemd about changed daemon state. This takes a number of
00194   newline separated environment-style variable assignments in a
00195   string. The following variables are known:
00196 
00197      READY=1      Tells systemd that daemon startup is finished (only
00198                   relevant for services of Type=notify). The passed
00199                   argument is a boolean "1" or "0". Since there is
00200                   little value in signaling non-readiness the only
00201                   value daemons should send is "READY=1".
00202 
00203      STATUS=...   Passes a single-line status string back to systemd
00204                   that describes the daemon state. This is free-from
00205                   and can be used for various purposes: general state
00206                   feedback, fsck-like programs could pass completion
00207                   percentages and failing programs could pass a human
00208                   readable error message. Example: "STATUS=Completed
00209                   66% of file system check..."
00210 
00211      ERRNO=...    If a daemon fails, the errno-style error code,
00212                   formatted as string. Example: "ERRNO=2" for ENOENT.
00213 
00214      BUSERROR=... If a daemon fails, the D-Bus error-style error
00215                   code. Example: "BUSERROR=org.freedesktop.DBus.Error.TimedOut"
00216 
00217      MAINPID=...  The main pid of a daemon, in case systemd did not
00218                   fork off the process itself. Example: "MAINPID=4711"
00219 
00220   Daemons can choose to send additional variables. However, it is
00221   recommended to prefix variable names not listed above with X_.
00222 
00223   Returns a negative errno-style error code on failure. Returns > 0
00224   if systemd could be notified, 0 if it couldn't possibly because
00225   systemd is not running.
00226 
00227   Example: When a daemon finished starting up, it could issue this
00228   call to notify systemd about it:
00229 
00230      sd_notify(0, "READY=1");
00231 
00232   See sd_notifyf() for more complete examples.
00233 
00234   See sd_notify(3) for more information.
00235 */
00236 int sd_notify(int unset_environment, const char *state);
00237 
00238 /*
00239   Similar to sd_notify() but takes a format string.
00240 
00241   Example 1: A daemon could send the following after initialization:
00242 
00243      sd_notifyf(0, "READY=1\n"
00244                    "STATUS=Processing requests...\n"
00245                    "MAINPID=%lu",
00246                    (unsigned long) getpid());
00247 
00248   Example 2: A daemon could send the following shortly before
00249   exiting, on failure:
00250 
00251      sd_notifyf(0, "STATUS=Failed to start up: %s\n"
00252                    "ERRNO=%i",
00253                    strerror(errno),
00254                    errno);
00255 
00256   See sd_notifyf(3) for more information.
00257 */
00258 int sd_notifyf(int unset_environment, const char *format, ...) _sd_printf_attr_(2,3);
00259 
00260 /*
00261   Returns > 0 if the system was booted with systemd. Returns < 0 on
00262   error. Returns 0 if the system was not booted with systemd. Note
00263   that all of the functions above handle non-systemd boots just
00264   fine. You should NOT protect them with a call to this function. Also
00265   note that this function checks whether the system, not the user
00266   session is controlled by systemd. However the functions above work
00267   for both user and system services.
00268 
00269   See sd_booted(3) for more information.
00270 */
00271 int sd_booted(void);
00272 
00273 #ifdef __cplusplus
00274 }
00275 #endif
00276 
00277 #endif