chiark / gitweb /
a6dbe8ddbcd0ce7231d8fefd78476922ce1310a0
[elogind.git] / src / core / unit.h
1 /*-*- Mode: C; c-basic-offset: 8; indent-tabs-mode: nil -*-*/
2
3 #pragma once
4
5 /***
6   This file is part of systemd.
7
8   Copyright 2010 Lennart Poettering
9
10   systemd is free software; you can redistribute it and/or modify it
11   under the terms of the GNU Lesser General Public License as published by
12   the Free Software Foundation; either version 2.1 of the License, or
13   (at your option) any later version.
14
15   systemd is distributed in the hope that it will be useful, but
16   WITHOUT ANY WARRANTY; without even the implied warranty of
17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18   Lesser General Public License for more details.
19
20   You should have received a copy of the GNU Lesser General Public License
21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
22 ***/
23
24 #include <stdbool.h>
25 #include <stdlib.h>
26 #include <unistd.h>
27
28 typedef struct Unit Unit;
29 typedef struct UnitVTable UnitVTable;
30 typedef enum UnitActiveState UnitActiveState;
31 typedef enum UnitDependency UnitDependency;
32 typedef struct UnitRef UnitRef;
33 typedef struct UnitStatusMessageFormats UnitStatusMessageFormats;
34
35 #include "sd-event.h"
36 #include "set.h"
37 #include "util.h"
38 #include "list.h"
39 #include "socket-util.h"
40 #include "execute.h"
41 #include "cgroup.h"
42 #include "condition.h"
43 #include "install.h"
44 #include "unit-name.h"
45
46 enum UnitActiveState {
47         UNIT_ACTIVE,
48         UNIT_RELOADING,
49         UNIT_INACTIVE,
50         UNIT_FAILED,
51         UNIT_ACTIVATING,
52         UNIT_DEACTIVATING,
53         _UNIT_ACTIVE_STATE_MAX,
54         _UNIT_ACTIVE_STATE_INVALID = -1
55 };
56
57 static inline bool UNIT_IS_ACTIVE_OR_RELOADING(UnitActiveState t) {
58         return t == UNIT_ACTIVE || t == UNIT_RELOADING;
59 }
60
61 static inline bool UNIT_IS_ACTIVE_OR_ACTIVATING(UnitActiveState t) {
62         return t == UNIT_ACTIVE || t == UNIT_ACTIVATING || t == UNIT_RELOADING;
63 }
64
65 static inline bool UNIT_IS_INACTIVE_OR_DEACTIVATING(UnitActiveState t) {
66         return t == UNIT_INACTIVE || t == UNIT_FAILED || t == UNIT_DEACTIVATING;
67 }
68
69 static inline bool UNIT_IS_INACTIVE_OR_FAILED(UnitActiveState t) {
70         return t == UNIT_INACTIVE || t == UNIT_FAILED;
71 }
72
73 enum UnitDependency {
74         /* Positive dependencies */
75         UNIT_REQUIRES,
76         UNIT_REQUIRES_OVERRIDABLE,
77         UNIT_REQUISITE,
78         UNIT_REQUISITE_OVERRIDABLE,
79         UNIT_WANTS,
80         UNIT_BINDS_TO,
81         UNIT_PART_OF,
82
83         /* Inverse of the above */
84         UNIT_REQUIRED_BY,             /* inverse of 'requires' and 'requisite' is 'required_by' */
85         UNIT_REQUIRED_BY_OVERRIDABLE, /* inverse of 'requires_overridable' and 'requisite_overridable' is 'soft_required_by' */
86         UNIT_WANTED_BY,               /* inverse of 'wants' */
87         UNIT_BOUND_BY,                /* inverse of 'binds_to' */
88         UNIT_CONSISTS_OF,             /* inverse of 'part_of' */
89
90         /* Negative dependencies */
91         UNIT_CONFLICTS,               /* inverse of 'conflicts' is 'conflicted_by' */
92         UNIT_CONFLICTED_BY,
93
94         /* Order */
95         UNIT_BEFORE,                  /* inverse of 'before' is 'after' and vice versa */
96         UNIT_AFTER,
97
98         /* On Failure */
99         UNIT_ON_FAILURE,
100
101         /* Triggers (i.e. a socket triggers a service) */
102         UNIT_TRIGGERS,
103         UNIT_TRIGGERED_BY,
104
105         /* Propagate reloads */
106         UNIT_PROPAGATES_RELOAD_TO,
107         UNIT_RELOAD_PROPAGATED_FROM,
108
109         /* Reference information for GC logic */
110         UNIT_REFERENCES,              /* Inverse of 'references' is 'referenced_by' */
111         UNIT_REFERENCED_BY,
112
113         _UNIT_DEPENDENCY_MAX,
114         _UNIT_DEPENDENCY_INVALID = -1
115 };
116
117 #include "manager.h"
118 #include "job.h"
119
120 struct UnitRef {
121         /* Keeps tracks of references to a unit. This is useful so
122          * that we can merge two units if necessary and correct all
123          * references to them */
124
125         Unit* unit;
126         LIST_FIELDS(UnitRef, refs);
127 };
128
129 struct Unit {
130         Manager *manager;
131
132         UnitType type;
133         UnitLoadState load_state;
134         Unit *merged_into;
135
136         char *id; /* One name is special because we use it for identification. Points to an entry in the names set */
137         char *instance;
138
139         Set *names;
140         Set *dependencies[_UNIT_DEPENDENCY_MAX];
141
142         char **requires_mounts_for;
143
144         char *description;
145         char **documentation;
146
147         char *fragment_path; /* if loaded from a config file this is the primary path to it */
148         char *source_path; /* if converted, the source file */
149         char **dropin_paths;
150         usec_t fragment_mtime;
151         usec_t source_mtime;
152         usec_t dropin_mtime;
153
154         /* If there is something to do with this unit, then this is the installed job for it */
155         Job *job;
156
157         /* JOB_NOP jobs are special and can be installed without disturbing the real job. */
158         Job *nop_job;
159
160         usec_t job_timeout;
161
162         /* References to this */
163         LIST_HEAD(UnitRef, refs);
164
165         /* Conditions to check */
166         LIST_HEAD(Condition, conditions);
167
168         dual_timestamp condition_timestamp;
169
170         dual_timestamp inactive_exit_timestamp;
171         dual_timestamp active_enter_timestamp;
172         dual_timestamp active_exit_timestamp;
173         dual_timestamp inactive_enter_timestamp;
174
175         /* Counterparts in the cgroup filesystem */
176         char *cgroup_path;
177         CGroupControllerMask cgroup_mask;
178         CGroupControllerMask cgroup_members_mask;
179
180         UnitRef slice;
181
182         /* Per type list */
183         LIST_FIELDS(Unit, units_by_type);
184
185         /* All units which have requires_mounts_for set */
186         LIST_FIELDS(Unit, has_requires_mounts_for);
187
188         /* Load queue */
189         LIST_FIELDS(Unit, load_queue);
190
191         /* D-Bus queue */
192         LIST_FIELDS(Unit, dbus_queue);
193
194         /* Cleanup queue */
195         LIST_FIELDS(Unit, cleanup_queue);
196
197         /* GC queue */
198         LIST_FIELDS(Unit, gc_queue);
199
200         /* CGroup realize members queue */
201         LIST_FIELDS(Unit, cgroup_queue);
202
203         /* Used during GC sweeps */
204         unsigned gc_marker;
205
206         /* When deserializing, temporarily store the job type for this
207          * unit here, if there was a job scheduled.
208          * Only for deserializing from a legacy version. New style uses full
209          * serialized jobs. */
210         int deserialized_job; /* This is actually of type JobType */
211
212         /* Error code when we didn't manage to load the unit (negative) */
213         int load_error;
214
215         /* Cached unit file state */
216         UnitFileState unit_file_state;
217
218         /* Garbage collect us we nobody wants or requires us anymore */
219         bool stop_when_unneeded;
220
221         /* Create default dependencies */
222         bool default_dependencies;
223
224         /* Refuse manual starting, allow starting only indirectly via dependency. */
225         bool refuse_manual_start;
226
227         /* Don't allow the user to stop this unit manually, allow stopping only indirectly via dependency. */
228         bool refuse_manual_stop;
229
230         /* Allow isolation requests */
231         bool allow_isolate;
232
233         /* How to start OnFailure units */
234         JobMode on_failure_job_mode;
235
236         /* Ignore this unit when isolating */
237         bool ignore_on_isolate;
238
239         /* Ignore this unit when snapshotting */
240         bool ignore_on_snapshot;
241
242         /* Did the last condition check succeed? */
243         bool condition_result;
244
245         /* Is this a transient unit? */
246         bool transient;
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         bool in_cgroup_queue:1;
253
254         bool sent_dbus_new_signal:1;
255
256         bool no_gc:1;
257
258         bool in_audit:1;
259
260         bool cgroup_realized:1;
261 };
262
263 struct UnitStatusMessageFormats {
264         const char *starting_stopping[2];
265         const char *finished_start_job[_JOB_RESULT_MAX];
266         const char *finished_stop_job[_JOB_RESULT_MAX];
267 };
268
269 typedef enum UnitSetPropertiesMode {
270         UNIT_CHECK = 0,
271         UNIT_RUNTIME = 1,
272         UNIT_PERSISTENT = 2,
273 } UnitSetPropertiesMode;
274
275 #include "service.h"
276 #include "timer.h"
277 #include "socket.h"
278 #include "target.h"
279 #include "device.h"
280 #include "mount.h"
281 #include "automount.h"
282 #include "snapshot.h"
283 #include "swap.h"
284 #include "path.h"
285 #include "slice.h"
286 #include "scope.h"
287
288 struct UnitVTable {
289         /* How much memory does an object of this unit type need */
290         size_t object_size;
291
292         /* If greater than 0, the offset into the object where
293          * ExecContext is found, if the unit type has that */
294         size_t exec_context_offset;
295
296         /* If greater than 0, the offset into the object where
297          * CGroupContext is found, if the unit type has that */
298         size_t cgroup_context_offset;
299
300         /* If greater than 0, the offset into the object where
301          * KillContext is found, if the unit type has that */
302         size_t kill_context_offset;
303
304         /* The name of the configuration file section with the private settings of this unit*/
305         const char *private_section;
306
307         /* Config file sections this unit type understands, separated
308          * by NUL chars */
309         const char *sections;
310
311         /* This should reset all type-specific variables. This should
312          * not allocate memory, and is called with zero-initialized
313          * data. It should hence only initialize variables that need
314          * to be set != 0. */
315         void (*init)(Unit *u);
316
317         /* This should free all type-specific variables. It should be
318          * idempotent. */
319         void (*done)(Unit *u);
320
321         /* Actually load data from disk. This may fail, and should set
322          * load_state to UNIT_LOADED, UNIT_MERGED or leave it at
323          * UNIT_STUB if no configuration could be found. */
324         int (*load)(Unit *u);
325
326         /* If a lot of units got created via enumerate(), this is
327          * where to actually set the state and call unit_notify(). */
328         int (*coldplug)(Unit *u);
329
330         void (*dump)(Unit *u, FILE *f, const char *prefix);
331
332         int (*start)(Unit *u);
333         int (*stop)(Unit *u);
334         int (*reload)(Unit *u);
335
336         int (*kill)(Unit *u, KillWho w, int signo, sd_bus_error *error);
337
338         bool (*can_reload)(Unit *u);
339
340         /* Write all data that cannot be restored from other sources
341          * away using unit_serialize_item() */
342         int (*serialize)(Unit *u, FILE *f, FDSet *fds);
343
344         /* Restore one item from the serialization */
345         int (*deserialize_item)(Unit *u, const char *key, const char *data, FDSet *fds);
346
347         /* Try to match up fds with what we need for this unit */
348         int (*distribute_fds)(Unit *u, FDSet *fds);
349
350         /* Boils down the more complex internal state of this unit to
351          * a simpler one that the engine can understand */
352         UnitActiveState (*active_state)(Unit *u);
353
354         /* Returns the substate specific to this unit type as
355          * string. This is purely information so that we can give the
356          * user a more fine grained explanation in which actual state a
357          * unit is in. */
358         const char* (*sub_state_to_string)(Unit *u);
359
360         /* Return true when there is reason to keep this entry around
361          * even nothing references it and it isn't active in any
362          * way */
363         bool (*check_gc)(Unit *u);
364
365         /* Return true when this unit is suitable for snapshotting */
366         bool (*check_snapshot)(Unit *u);
367
368         /* Invoked on every child that died */
369         void (*sigchld_event)(Unit *u, pid_t pid, int code, int status);
370
371         /* Reset failed state if we are in failed state */
372         void (*reset_failed)(Unit *u);
373
374         /* Called whenever any of the cgroups this unit watches for
375          * ran empty */
376         void (*notify_cgroup_empty)(Unit *u);
377
378         /* Called whenever a process of this unit sends us a message */
379         void (*notify_message)(Unit *u, pid_t pid, char **tags);
380
381         /* Called whenever a name this Unit registered for comes or
382          * goes away. */
383         void (*bus_name_owner_change)(Unit *u, const char *name, const char *old_owner, const char *new_owner);
384
385         /* Called for each property that is being set */
386         int (*bus_set_property)(Unit *u, const char *name, sd_bus_message *message, UnitSetPropertiesMode mode, sd_bus_error *error);
387
388         /* Called after at least one property got changed to apply the necessary change */
389         int (*bus_commit_properties)(Unit *u);
390
391         /* Return the unit this unit is following */
392         Unit *(*following)(Unit *u);
393
394         /* Return the set of units that are following each other */
395         int (*following_set)(Unit *u, Set **s);
396
397         /* Invoked each time a unit this unit is triggering changes
398          * state or gains/loses a job */
399         void (*trigger_notify)(Unit *u, Unit *trigger);
400
401         /* Called whenever CLOCK_REALTIME made a jump */
402         void (*time_change)(Unit *u);
403
404         /* This is called for each unit type and should be used to
405          * enumerate existing devices and load them. However,
406          * everything that is loaded here should still stay in
407          * inactive state. It is the job of the coldplug() call above
408          * to put the units into the initial state.  */
409         int (*enumerate)(Manager *m);
410
411         /* Type specific cleanups. */
412         void (*shutdown)(Manager *m);
413
414         /* The interface name */
415         const char *bus_interface;
416
417         /* The bus vtable */
418         const sd_bus_vtable *bus_vtable;
419
420         /* strv list of changing properties */
421         const char * const * const bus_changing_properties;
422
423         /* The strings to print in status messages */
424         UnitStatusMessageFormats status_message_formats;
425
426         /* Can units of this type have multiple names? */
427         bool no_alias:1;
428
429         /* Instances make no sense for this type */
430         bool no_instances:1;
431
432         /* Exclude from automatic gc */
433         bool no_gc:1;
434
435         /* True if transient units of this type are OK */
436         bool can_transient:1;
437 };
438
439 extern const UnitVTable * const unit_vtable[_UNIT_TYPE_MAX];
440
441 #define UNIT_VTABLE(u) unit_vtable[(u)->type]
442
443 /* For casting a unit into the various unit types */
444 #define DEFINE_CAST(UPPERCASE, MixedCase)                               \
445         static inline MixedCase* UPPERCASE(Unit *u) {                   \
446                 if (_unlikely_(!u || u->type != UNIT_##UPPERCASE))      \
447                         return NULL;                                    \
448                                                                         \
449                 return (MixedCase*) u;                                  \
450         }
451
452 /* For casting the various unit types into a unit */
453 #define UNIT(u) (&(u)->meta)
454
455 #define UNIT_TRIGGER(u) ((Unit*) set_first((u)->dependencies[UNIT_TRIGGERS]))
456
457 DEFINE_CAST(SOCKET, Socket);
458 DEFINE_CAST(TIMER, Timer);
459 DEFINE_CAST(SERVICE, Service);
460 DEFINE_CAST(TARGET, Target);
461 DEFINE_CAST(DEVICE, Device);
462 DEFINE_CAST(MOUNT, Mount);
463 DEFINE_CAST(AUTOMOUNT, Automount);
464 DEFINE_CAST(SNAPSHOT, Snapshot);
465 DEFINE_CAST(SWAP, Swap);
466 DEFINE_CAST(PATH, Path);
467 DEFINE_CAST(SLICE, Slice);
468 DEFINE_CAST(SCOPE, Scope);
469
470 Unit *unit_new(Manager *m, size_t size);
471 void unit_free(Unit *u);
472
473 int unit_add_name(Unit *u, const char *name);
474
475 int unit_add_dependency(Unit *u, UnitDependency d, Unit *other, bool add_reference);
476 int unit_add_two_dependencies(Unit *u, UnitDependency d, UnitDependency e, Unit *other, bool add_reference);
477
478 int unit_add_dependency_by_name(Unit *u, UnitDependency d, const char *name, const char *filename, bool add_reference);
479 int unit_add_two_dependencies_by_name(Unit *u, UnitDependency d, UnitDependency e, const char *name, const char *path, bool add_reference);
480
481 int unit_add_dependency_by_name_inverse(Unit *u, UnitDependency d, const char *name, const char *filename, bool add_reference);
482 int unit_add_two_dependencies_by_name_inverse(Unit *u, UnitDependency d, UnitDependency e, const char *name, const char *path, bool add_reference);
483
484 int unit_add_exec_dependencies(Unit *u, ExecContext *c);
485
486 int unit_choose_id(Unit *u, const char *name);
487 int unit_set_description(Unit *u, const char *description);
488
489 bool unit_check_gc(Unit *u);
490
491 void unit_add_to_load_queue(Unit *u);
492 void unit_add_to_dbus_queue(Unit *u);
493 void unit_add_to_cleanup_queue(Unit *u);
494 void unit_add_to_gc_queue(Unit *u);
495
496 int unit_merge(Unit *u, Unit *other);
497 int unit_merge_by_name(Unit *u, const char *other);
498
499 Unit *unit_follow_merge(Unit *u) _pure_;
500
501 int unit_load_fragment_and_dropin(Unit *u);
502 int unit_load_fragment_and_dropin_optional(Unit *u);
503 int unit_load(Unit *unit);
504
505 int unit_add_default_slice(Unit *u);
506
507 const char *unit_description(Unit *u) _pure_;
508
509 bool unit_has_name(Unit *u, const char *name);
510
511 UnitActiveState unit_active_state(Unit *u);
512
513 const char* unit_sub_state_to_string(Unit *u);
514
515 void unit_dump(Unit *u, FILE *f, const char *prefix);
516
517 bool unit_can_reload(Unit *u) _pure_;
518 bool unit_can_start(Unit *u) _pure_;
519 bool unit_can_isolate(Unit *u) _pure_;
520
521 int unit_start(Unit *u);
522 int unit_stop(Unit *u);
523 int unit_reload(Unit *u);
524
525 int unit_kill(Unit *u, KillWho w, int signo, sd_bus_error *error);
526 int unit_kill_common(Unit *u, KillWho who, int signo, pid_t main_pid, pid_t control_pid, sd_bus_error *error);
527
528 void unit_notify(Unit *u, UnitActiveState os, UnitActiveState ns, bool reload_success);
529
530 int unit_watch_pid(Unit *u, pid_t pid);
531 void unit_unwatch_pid(Unit *u, pid_t pid);
532
533 int unit_watch_bus_name(Unit *u, const char *name);
534 void unit_unwatch_bus_name(Unit *u, const char *name);
535
536 bool unit_job_is_applicable(Unit *u, JobType j);
537
538 int set_unit_path(const char *p);
539
540 char *unit_dbus_path(Unit *u);
541
542 int unit_load_related_unit(Unit *u, const char *type, Unit **_found);
543
544 bool unit_can_serialize(Unit *u) _pure_;
545 int unit_serialize(Unit *u, FILE *f, FDSet *fds, bool serialize_jobs);
546 void unit_serialize_item_format(Unit *u, FILE *f, const char *key, const char *value, ...) _printf_(4,5);
547 void unit_serialize_item(Unit *u, FILE *f, const char *key, const char *value);
548 int unit_deserialize(Unit *u, FILE *f, FDSet *fds);
549
550 int unit_add_node_link(Unit *u, const char *what, bool wants);
551
552 int unit_coldplug(Unit *u);
553
554 void unit_status_printf(Unit *u, const char *status, const char *unit_status_msg_format) _printf_(3, 0);
555
556 bool unit_need_daemon_reload(Unit *u);
557
558 void unit_reset_failed(Unit *u);
559
560 Unit *unit_following(Unit *u);
561 int unit_following_set(Unit *u, Set **s);
562
563 const char *unit_slice_name(Unit *u);
564
565 bool unit_stop_pending(Unit *u) _pure_;
566 bool unit_inactive_or_pending(Unit *u) _pure_;
567 bool unit_active_or_pending(Unit *u);
568
569 int unit_add_default_target_dependency(Unit *u, Unit *target);
570
571 char *unit_default_cgroup_path(Unit *u);
572
573 void unit_start_on_failure(Unit *u);
574 void unit_trigger_notify(Unit *u);
575
576 UnitFileState unit_get_unit_file_state(Unit *u);
577
578 Unit* unit_ref_set(UnitRef *ref, Unit *u);
579 void unit_ref_unset(UnitRef *ref);
580
581 #define UNIT_DEREF(ref) ((ref).unit)
582 #define UNIT_ISSET(ref) (!!(ref).unit)
583
584 int unit_exec_context_defaults(Unit *u, ExecContext *c);
585
586 ExecContext *unit_get_exec_context(Unit *u) _pure_;
587 KillContext *unit_get_kill_context(Unit *u) _pure_;
588 CGroupContext *unit_get_cgroup_context(Unit *u) _pure_;
589
590 int unit_write_drop_in(Unit *u, UnitSetPropertiesMode mode, const char *name, const char *data);
591 int unit_write_drop_in_format(Unit *u, UnitSetPropertiesMode mode, const char *name, const char *format, ...) _printf_(4,5);
592
593 int unit_write_drop_in_private(Unit *u, UnitSetPropertiesMode mode, const char *name, const char *data);
594 int unit_write_drop_in_private_format(Unit *u, UnitSetPropertiesMode mode, const char *name, const char *format, ...) _printf_(4,5);
595
596 int unit_remove_drop_in(Unit *u, UnitSetPropertiesMode mode, const char *name);
597
598 int unit_kill_context(Unit *u, KillContext *c, bool sigkill, pid_t main_pid, pid_t control_pid, bool main_pid_alien);
599
600 int unit_make_transient(Unit *u);
601
602 int unit_require_mounts_for(Unit *u, const char *path);
603
604 const char *unit_active_state_to_string(UnitActiveState i) _const_;
605 UnitActiveState unit_active_state_from_string(const char *s) _pure_;
606
607 const char *unit_dependency_to_string(UnitDependency i) _const_;
608 UnitDependency unit_dependency_from_string(const char *s) _pure_;
609
610 /* Macros which append UNIT= or USER_UNIT= to the message */
611
612 #define log_full_unit(level, unit, ...) log_meta_object(level, __FILE__, __LINE__, __func__, getpid() == 1 ? "UNIT=" : "USER_UNIT=", unit, __VA_ARGS__)
613 #define log_debug_unit(unit, ...)       log_full_unit(LOG_DEBUG, unit, __VA_ARGS__)
614 #define log_info_unit(unit, ...)        log_full_unit(LOG_INFO, unit, __VA_ARGS__)
615 #define log_notice_unit(unit, ...)      log_full_unit(LOG_NOTICE, unit, __VA_ARGS__)
616 #define log_warning_unit(unit, ...)     log_full_unit(LOG_WARNING, unit, __VA_ARGS__)
617 #define log_error_unit(unit, ...)       log_full_unit(LOG_ERR, unit, __VA_ARGS__)
618
619 #define log_struct_unit(level, unit, ...) log_struct(level, getpid() == 1 ? "UNIT=%s" : "USER_UNIT=%s", unit, __VA_ARGS__)