src/core/unit.h

   1 /*-*- Mode: C; c-basic-offset: 8; indent-tabs-mode: nil -*-*/
   2
   3 #ifndef foounithfoo
   4 #define foounithfoo
   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 Lesser General Public License as published by
  13   the Free Software Foundation; either version 2.1 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   Lesser General Public License for more details.
  20
  21   You should have received a copy of the GNU Lesser General Public License
  22   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  23 ***/
  24
  25 #include <stdbool.h>
  26 #include <stdlib.h>
  27
  28 typedef struct Unit Unit;
  29 typedef struct UnitVTable UnitVTable;
  30 typedef enum UnitType UnitType;
  31 typedef enum UnitLoadState UnitLoadState;
  32 typedef enum UnitActiveState UnitActiveState;
  33 typedef enum UnitDependency UnitDependency;
  34 typedef struct UnitRef UnitRef;
  35
  36 #include "set.h"
  37 #include "util.h"
  38 #include "list.h"
  39 #include "socket-util.h"
  40 #include "execute.h"
  41 #include "condition.h"
  42 #include "install.h"
  43
  44 enum UnitType {
  45         UNIT_SERVICE = 0,
  46         UNIT_SOCKET,
  47         UNIT_TARGET,
  48         UNIT_DEVICE,
  49         UNIT_MOUNT,
  50         UNIT_AUTOMOUNT,
  51         UNIT_SNAPSHOT,
  52         UNIT_TIMER,
  53         UNIT_SWAP,
  54         UNIT_PATH,
  55         _UNIT_TYPE_MAX,
  56         _UNIT_TYPE_INVALID = -1
  57 };
  58
  59 enum UnitLoadState {
  60         UNIT_STUB,
  61         UNIT_LOADED,
  62         UNIT_ERROR,
  63         UNIT_MERGED,
  64         UNIT_MASKED,
  65         _UNIT_LOAD_STATE_MAX,
  66         _UNIT_LOAD_STATE_INVALID = -1
  67 };
  68
  69 enum UnitActiveState {
  70         UNIT_ACTIVE,
  71         UNIT_RELOADING,
  72         UNIT_INACTIVE,
  73         UNIT_FAILED,
  74         UNIT_ACTIVATING,
  75         UNIT_DEACTIVATING,
  76         _UNIT_ACTIVE_STATE_MAX,
  77         _UNIT_ACTIVE_STATE_INVALID = -1
  78 };
  79
  80 static inline bool UNIT_IS_ACTIVE_OR_RELOADING(UnitActiveState t) {
  81         return t == UNIT_ACTIVE || t == UNIT_RELOADING;
  82 }
  83
  84 static inline bool UNIT_IS_ACTIVE_OR_ACTIVATING(UnitActiveState t) {
  85         return t == UNIT_ACTIVE || t == UNIT_ACTIVATING || t == UNIT_RELOADING;
  86 }
  87
  88 static inline bool UNIT_IS_INACTIVE_OR_DEACTIVATING(UnitActiveState t) {
  89         return t == UNIT_INACTIVE || t == UNIT_FAILED || t == UNIT_DEACTIVATING;
  90 }
  91
  92 static inline bool UNIT_IS_INACTIVE_OR_FAILED(UnitActiveState t) {
  93         return t == UNIT_INACTIVE || t == UNIT_FAILED;
  94 }
  95
  96 enum UnitDependency {
  97         /* Positive dependencies */
  98         UNIT_REQUIRES,
  99         UNIT_REQUIRES_OVERRIDABLE,
 100         UNIT_REQUISITE,
 101         UNIT_REQUISITE_OVERRIDABLE,
 102         UNIT_WANTS,
 103         UNIT_BIND_TO,
 104
 105         /* Inverse of the above */
 106         UNIT_REQUIRED_BY,             /* inverse of 'requires' and 'requisite' is 'required_by' */
 107         UNIT_REQUIRED_BY_OVERRIDABLE, /* inverse of 'requires_overridable' and 'requisite_overridable' is 'soft_required_by' */
 108         UNIT_WANTED_BY,               /* inverse of 'wants' */
 109         UNIT_BOUND_BY,                /* inverse of 'bind_to' */
 110
 111         /* Negative dependencies */
 112         UNIT_CONFLICTS,               /* inverse of 'conflicts' is 'conflicted_by' */
 113         UNIT_CONFLICTED_BY,
 114
 115         /* Order */
 116         UNIT_BEFORE,                  /* inverse of 'before' is 'after' and vice versa */
 117         UNIT_AFTER,
 118
 119         /* On Failure */
 120         UNIT_ON_FAILURE,
 121
 122         /* Triggers (i.e. a socket triggers a service) */
 123         UNIT_TRIGGERS,
 124         UNIT_TRIGGERED_BY,
 125
 126         /* Propagate reloads */
 127         UNIT_PROPAGATE_RELOAD_TO,
 128         UNIT_PROPAGATE_RELOAD_FROM,
 129
 130         /* Reference information for GC logic */
 131         UNIT_REFERENCES,              /* Inverse of 'references' is 'referenced_by' */
 132         UNIT_REFERENCED_BY,
 133
 134         _UNIT_DEPENDENCY_MAX,
 135         _UNIT_DEPENDENCY_INVALID = -1
 136 };
 137
 138 #include "manager.h"
 139 #include "job.h"
 140 #include "cgroup.h"
 141 #include "cgroup-attr.h"
 142
 143 struct Unit {
 144         Manager *manager;
 145
 146         UnitType type;
 147         UnitLoadState load_state;
 148         Unit *merged_into;
 149
 150         char *id; /* One name is special because we use it for identification. Points to an entry in the names set */
 151         char *instance;
 152
 153         Set *names;
 154         Set *dependencies[_UNIT_DEPENDENCY_MAX];
 155
 156         char **requires_mounts_for;
 157
 158         char *description;
 159
 160         char *fragment_path; /* if loaded from a config file this is the primary path to it */
 161         usec_t fragment_mtime;
 162
 163         /* If there is something to do with this unit, then this is the installed job for it */
 164         Job *job;
 165
 166         /* JOB_NOP jobs are special and can be installed without disturbing the real job. */
 167         Job *nop_job;
 168
 169         usec_t job_timeout;
 170
 171         /* References to this */
 172         LIST_HEAD(UnitRef, refs);
 173
 174         /* Conditions to check */
 175         LIST_HEAD(Condition, conditions);
 176
 177         dual_timestamp condition_timestamp;
 178
 179         dual_timestamp inactive_exit_timestamp;
 180         dual_timestamp active_enter_timestamp;
 181         dual_timestamp active_exit_timestamp;
 182         dual_timestamp inactive_enter_timestamp;
 183
 184         /* Counterparts in the cgroup filesystem */
 185         CGroupBonding *cgroup_bondings;
 186         CGroupAttribute *cgroup_attributes;
 187
 188         /* Per type list */
 189         LIST_FIELDS(Unit, units_by_type);
 190
 191         /* All units which have requires_mounts_for set */
 192         LIST_FIELDS(Unit, has_requires_mounts_for);
 193
 194         /* Load queue */
 195         LIST_FIELDS(Unit, load_queue);
 196
 197         /* D-Bus queue */
 198         LIST_FIELDS(Unit, dbus_queue);
 199
 200         /* Cleanup queue */
 201         LIST_FIELDS(Unit, cleanup_queue);
 202
 203         /* GC queue */
 204         LIST_FIELDS(Unit, gc_queue);
 205
 206         /* Used during GC sweeps */
 207         unsigned gc_marker;
 208
 209         /* When deserializing, temporarily store the job type for this
 210          * unit here, if there was a job scheduled.
 211          * Only for deserializing from a legacy version. New style uses full
 212          * serialized jobs. */
 213         int deserialized_job; /* This is actually of type JobType */
 214
 215         /* Error code when we didn't manage to load the unit (negative) */
 216         int load_error;
 217
 218         /* Cached unit file state */
 219         UnitFileState unit_file_state;
 220
 221         /* Garbage collect us we nobody wants or requires us anymore */
 222         bool stop_when_unneeded;
 223
 224         /* Create default dependencies */
 225         bool default_dependencies;
 226
 227         /* Refuse manual starting, allow starting only indirectly via dependency. */
 228         bool refuse_manual_start;
 229
 230         /* Don't allow the user to stop this unit manually, allow stopping only indirectly via dependency. */
 231         bool refuse_manual_stop;
 232
 233         /* Allow isolation requests */
 234         bool allow_isolate;
 235
 236         /* Isolate OnFailure unit */
 237         bool on_failure_isolate;
 238
 239         /* Ignore this unit when isolating */
 240         bool ignore_on_isolate;
 241
 242         /* Ignore this unit when snapshotting */
 243         bool ignore_on_snapshot;
 244
 245         /* Did the last condition check suceed? */
 246         bool condition_result;
 247
 248         bool in_load_queue:1;
 249         bool in_dbus_queue:1;
 250         bool in_cleanup_queue:1;
 251         bool in_gc_queue:1;
 252
 253         bool sent_dbus_new_signal:1;
 254
 255         bool no_gc:1;
 256
 257         bool in_audit:1;
 258 };
 259
 260 struct UnitRef {
 261         /* Keeps tracks of references to a unit. This is useful so
 262          * that we can merge two units if necessary and correct all
 263          * references to them */
 264
 265         Unit* unit;
 266         LIST_FIELDS(UnitRef, refs);
 267 };
 268
 269 #include "service.h"
 270 #include "timer.h"
 271 #include "socket.h"
 272 #include "target.h"
 273 #include "device.h"
 274 #include "mount.h"
 275 #include "automount.h"
 276 #include "snapshot.h"
 277 #include "swap.h"
 278 #include "path.h"
 279
 280 struct UnitVTable {
 281         const char *suffix;
 282
 283         /* How much memory does an object of this unit type need */
 284         size_t object_size;
 285
 286         /* Config file sections this unit type understands, separated
 287          * by NUL chars */
 288         const char *sections;
 289
 290         /* This should reset all type-specific variables. This should
 291          * not allocate memory, and is called with zero-initialized
 292          * data. It should hence only initialize variables that need
 293          * to be set != 0. */
 294         void (*init)(Unit *u);
 295
 296         /* This should free all type-specific variables. It should be
 297          * idempotent. */
 298         void (*done)(Unit *u);
 299
 300         /* Actually load data from disk. This may fail, and should set
 301          * load_state to UNIT_LOADED, UNIT_MERGED or leave it at
 302          * UNIT_STUB if no configuration could be found. */
 303         int (*load)(Unit *u);
 304
 305         /* If a a lot of units got created via enumerate(), this is
 306          * where to actually set the state and call unit_notify(). */
 307         int (*coldplug)(Unit *u);
 308
 309         void (*dump)(Unit *u, FILE *f, const char *prefix);
 310
 311         int (*start)(Unit *u);
 312         int (*stop)(Unit *u);
 313         int (*reload)(Unit *u);
 314
 315         int (*kill)(Unit *u, KillWho w, KillMode m, int signo, DBusError *error);
 316
 317         bool (*can_reload)(Unit *u);
 318
 319         /* Write all data that cannot be restored from other sources
 320          * away using unit_serialize_item() */
 321         int (*serialize)(Unit *u, FILE *f, FDSet *fds);
 322
 323         /* Restore one item from the serialization */
 324         int (*deserialize_item)(Unit *u, const char *key, const char *data, FDSet *fds);
 325
 326         /* Boils down the more complex internal state of this unit to
 327          * a simpler one that the engine can understand */
 328         UnitActiveState (*active_state)(Unit *u);
 329
 330         /* Returns the substate specific to this unit type as
 331          * string. This is purely information so that we can give the
 332          * user a more fine grained explanation in which actual state a
 333          * unit is in. */
 334         const char* (*sub_state_to_string)(Unit *u);
 335
 336         /* Return true when there is reason to keep this entry around
 337          * even nothing references it and it isn't active in any
 338          * way */
 339         bool (*check_gc)(Unit *u);
 340
 341         /* Return true when this unit is suitable for snapshotting */
 342         bool (*check_snapshot)(Unit *u);
 343
 344         void (*fd_event)(Unit *u, int fd, uint32_t events, Watch *w);
 345         void (*sigchld_event)(Unit *u, pid_t pid, int code, int status);
 346         void (*timer_event)(Unit *u, uint64_t n_elapsed, Watch *w);
 347
 348         /* Check whether unit needs a daemon reload */
 349         bool (*need_daemon_reload)(Unit *u);
 350
 351         /* Reset failed state if we are in failed state */
 352         void (*reset_failed)(Unit *u);
 353
 354         /* Called whenever any of the cgroups this unit watches for
 355          * ran empty */
 356         void (*cgroup_notify_empty)(Unit *u);
 357
 358         /* Called whenever a process of this unit sends us a message */
 359         void (*notify_message)(Unit *u, pid_t pid, char **tags);
 360
 361         /* Called whenever a name thus Unit registered for comes or
 362          * goes away. */
 363         void (*bus_name_owner_change)(Unit *u, const char *name, const char *old_owner, const char *new_owner);
 364
 365         /* Called whenever a bus PID lookup finishes */
 366         void (*bus_query_pid_done)(Unit *u, const char *name, pid_t pid);
 367
 368         /* Called for each message received on the bus */
 369         DBusHandlerResult (*bus_message_handler)(Unit *u, DBusConnection *c, DBusMessage *message);
 370
 371         /* Return the unit this unit is following */
 372         Unit *(*following)(Unit *u);
 373
 374         /* Return the set of units that are following each other */
 375         int (*following_set)(Unit *u, Set **s);
 376
 377         /* This is called for each unit type and should be used to
 378          * enumerate existing devices and load them. However,
 379          * everything that is loaded here should still stay in
 380          * inactive state. It is the job of the coldplug() call above
 381          * to put the units into the initial state.  */
 382         int (*enumerate)(Manager *m);
 383
 384         /* Type specific cleanups. */
 385         void (*shutdown)(Manager *m);
 386
 387         /* When sending out PropertiesChanged signal, which properties
 388          * shall be invalidated? This is a NUL separated list of
 389          * strings, to minimize relocations a little. */
 390         const char *bus_invalidating_properties;
 391
 392         /* The interface name */
 393         const char *bus_interface;
 394
 395         /* Can units of this type have multiple names? */
 396         bool no_alias:1;
 397
 398         /* Instances make no sense for this type */
 399         bool no_instances:1;
 400
 401         /* Exclude from automatic gc */
 402         bool no_gc:1;
 403
 404         /* Show status updates on the console */
 405         bool show_status:1;
 406 };
 407
 408 extern const UnitVTable * const unit_vtable[_UNIT_TYPE_MAX];
 409
 410 #define UNIT_VTABLE(u) unit_vtable[(u)->type]
 411
 412 /* For casting a unit into the various unit types */
 413 #define DEFINE_CAST(UPPERCASE, MixedCase)                               \
 414         static inline MixedCase* UPPERCASE(Unit *u) {                   \
 415                 if (_unlikely_(!u || u->type != UNIT_##UPPERCASE))      \
 416                         return NULL;                                    \
 417                                                                         \
 418                 return (MixedCase*) u;                                  \
 419         }
 420
 421 /* For casting the various unit types into a unit */
 422 #define UNIT(u) (&(u)->meta)
 423
 424 DEFINE_CAST(SOCKET, Socket);
 425 DEFINE_CAST(TIMER, Timer);
 426 DEFINE_CAST(SERVICE, Service);
 427 DEFINE_CAST(TARGET, Target);
 428 DEFINE_CAST(DEVICE, Device);
 429 DEFINE_CAST(MOUNT, Mount);
 430 DEFINE_CAST(AUTOMOUNT, Automount);
 431 DEFINE_CAST(SNAPSHOT, Snapshot);
 432 DEFINE_CAST(SWAP, Swap);
 433 DEFINE_CAST(PATH, Path);
 434
 435 Unit *unit_new(Manager *m, size_t size);
 436 void unit_free(Unit *u);
 437
 438 int unit_add_name(Unit *u, const char *name);
 439
 440 int unit_add_dependency(Unit *u, UnitDependency d, Unit *other, bool add_reference);
 441 int unit_add_two_dependencies(Unit *u, UnitDependency d, UnitDependency e, Unit *other, bool add_reference);
 442
 443 int unit_add_dependency_by_name(Unit *u, UnitDependency d, const char *name, const char *filename, bool add_reference);
 444 int unit_add_two_dependencies_by_name(Unit *u, UnitDependency d, UnitDependency e, const char *name, const char *path, bool add_reference);
 445
 446 int unit_add_dependency_by_name_inverse(Unit *u, UnitDependency d, const char *name, const char *filename, bool add_reference);
 447 int unit_add_two_dependencies_by_name_inverse(Unit *u, UnitDependency d, UnitDependency e, const char *name, const char *path, bool add_reference);
 448
 449 int unit_add_exec_dependencies(Unit *u, ExecContext *c);
 450
 451 int unit_add_cgroup(Unit *u, CGroupBonding *b);
 452 int unit_add_cgroup_from_text(Unit *u, const char *name);
 453 int unit_add_default_cgroups(Unit *u);
 454 CGroupBonding* unit_get_default_cgroup(Unit *u);
 455 int unit_add_cgroup_attribute(Unit *u, const char *controller, const char *name, const char *value, CGroupAttributeMapCallback map_callback);
 456
 457 int unit_choose_id(Unit *u, const char *name);
 458 int unit_set_description(Unit *u, const char *description);
 459
 460 bool unit_check_gc(Unit *u);
 461
 462 void unit_add_to_load_queue(Unit *u);
 463 void unit_add_to_dbus_queue(Unit *u);
 464 void unit_add_to_cleanup_queue(Unit *u);
 465 void unit_add_to_gc_queue(Unit *u);
 466
 467 int unit_merge(Unit *u, Unit *other);
 468 int unit_merge_by_name(Unit *u, const char *other);
 469
 470 Unit *unit_follow_merge(Unit *u);
 471
 472 int unit_load_fragment_and_dropin(Unit *u);
 473 int unit_load_fragment_and_dropin_optional(Unit *u);
 474 int unit_load(Unit *unit);
 475
 476 const char *unit_description(Unit *u);
 477
 478 bool unit_has_name(Unit *u, const char *name);
 479
 480 UnitActiveState unit_active_state(Unit *u);
 481
 482 const char* unit_sub_state_to_string(Unit *u);
 483
 484 void unit_dump(Unit *u, FILE *f, const char *prefix);
 485
 486 bool unit_can_reload(Unit *u);
 487 bool unit_can_start(Unit *u);
 488 bool unit_can_isolate(Unit *u);
 489
 490 int unit_start(Unit *u);
 491 int unit_stop(Unit *u);
 492 int unit_reload(Unit *u);
 493
 494 int unit_kill(Unit *u, KillWho w, KillMode m, int signo, DBusError *error);
 495
 496 void unit_notify(Unit *u, UnitActiveState os, UnitActiveState ns, bool reload_success);
 497
 498 int unit_watch_fd(Unit *u, int fd, uint32_t events, Watch *w);
 499 void unit_unwatch_fd(Unit *u, Watch *w);
 500
 501 int unit_watch_pid(Unit *u, pid_t pid);
 502 void unit_unwatch_pid(Unit *u, pid_t pid);
 503
 504 int unit_watch_timer(Unit *u, usec_t delay, Watch *w);
 505 void unit_unwatch_timer(Unit *u, Watch *w);
 506
 507 int unit_watch_bus_name(Unit *u, const char *name);
 508 void unit_unwatch_bus_name(Unit *u, const char *name);
 509
 510 bool unit_job_is_applicable(Unit *u, JobType j);
 511
 512 int set_unit_path(const char *p);
 513
 514 char *unit_dbus_path(Unit *u);
 515
 516 int unit_load_related_unit(Unit *u, const char *type, Unit **_found);
 517 int unit_get_related_unit(Unit *u, const char *type, Unit **_found);
 518
 519 char *unit_name_printf(Unit *u, const char* text);
 520 char *unit_full_printf(Unit *u, const char *text);
 521 char **unit_full_printf_strv(Unit *u, char **l);
 522
 523 bool unit_can_serialize(Unit *u);
 524 int unit_serialize(Unit *u, FILE *f, FDSet *fds);
 525 void unit_serialize_item_format(Unit *u, FILE *f, const char *key, const char *value, ...) _printf_attr_(4,5);
 526 void unit_serialize_item(Unit *u, FILE *f, const char *key, const char *value);
 527 int unit_deserialize(Unit *u, FILE *f, FDSet *fds);
 528
 529 int unit_add_node_link(Unit *u, const char *what, bool wants);
 530
 531 int unit_coldplug(Unit *u);
 532
 533 void unit_status_printf(Unit *u, const char *status, const char *format, ...);
 534
 535 bool unit_need_daemon_reload(Unit *u);
 536
 537 void unit_reset_failed(Unit *u);
 538
 539 Unit *unit_following(Unit *u);
 540
 541 bool unit_pending_inactive(Unit *u);
 542 bool unit_pending_active(Unit *u);
 543
 544 int unit_add_default_target_dependency(Unit *u, Unit *target);
 545
 546 int unit_following_set(Unit *u, Set **s);
 547
 548 UnitType unit_name_to_type(const char *n);
 549 bool unit_name_is_valid(const char *n, bool template_ok);
 550
 551 void unit_trigger_on_failure(Unit *u);
 552
 553 bool unit_condition_test(Unit *u);
 554
 555 UnitFileState unit_get_unit_file_state(Unit *u);
 556
 557 Unit* unit_ref_set(UnitRef *ref, Unit *u);
 558 void unit_ref_unset(UnitRef *ref);
 559
 560 #define UNIT_DEREF(ref) ((ref).unit)
 561
 562 int unit_add_one_mount_link(Unit *u, Mount *m);
 563 int unit_add_mount_links(Unit *u);
 564
 565 const char *unit_load_state_to_string(UnitLoadState i);
 566 UnitLoadState unit_load_state_from_string(const char *s);
 567
 568 const char *unit_active_state_to_string(UnitActiveState i);
 569 UnitActiveState unit_active_state_from_string(const char *s);
 570
 571 const char *unit_dependency_to_string(UnitDependency i);
 572 UnitDependency unit_dependency_from_string(const char *s);
 573
 574 #endif