Debian Codegraph @

src/basic/pidref.h

raw
1 /* SPDX-License-Identifier: LGPL-2.1-or-later */
2 #pragma once
3
4 #include <signal.h>
5
6 #include "basic-forward.h"
7
8 /* An embeddable structure carrying a reference to a process. Supposed to be used when tracking processes
9 * continuously. This combines a PID, a modern Linux pidfd and the 64bit inode number of the pidfd into one
10 * structure. Note that depending on kernel support the pidfd might not be initialized, and if it is
11 * initialized then fd_id might still not be initialized (because the concept was added to the kernel much
12 * later than pidfds themselves).
13 *
14 * There are three special states a PidRef can be in:
15 *
16 * 1. It can be *unset*. Use pidref_is_set() to detect this case. Most operations attempted on such a PidRef
17 * will fail with -ESRCH. Use PIDREF_NULL for initializing a PidRef in this state.
18 *
19 * 2. It can be marked as *automatic*. This is a special state indicating that a process reference is
20 * supposed to be derived automatically from the current context. This is used by the Varlink/JSON
21 * dispatcher as indication that a PidRef shall be derived from the connection peer, but might be
22 * otherwise used too. When marked *automatic* the PidRef will also be considered *unset*, hence most
23 * operations will fail with -ESRCH, as above.
24 *
25 * 3. It can be marked as *remote*. This is useful when deserializing a PidRef structure from an IPC message
26 * or similar, and it has been determined that the given PID definitely doesn't refer to a local
27 * process. In this case the PidRef logic will refrain from trying to acquire a pidfd for the
28 * process. Moreover, most operations will fail with -EREMOTE. Only PidRef structures that are not marked
29 * *unset* can be marked *remote*.
30 */
31 typedef struct PidRef {
32 pid_t pid; /* > 0 if the PidRef is set, otherwise set to INT_MIN (PID_AUTOMATIC) if automatic
33 * mode is desired, or 0 otherwise. */
34 int fd; /* only valid if pidfd are available in the kernel, and we manage to get an fd. If we
35 * know that the PID is not from the local machine we set this to -EREMOTE, otherwise
36 * we use -EBADF as indicator the fd is invalid. */
37 uint64_t fd_id; /* the inode number of pidfd. only useful in kernel 6.9+ where pidfds live in
38 their own pidfs and each process comes with a unique inode number */
39 } PidRef;
40
41 #define PIDREF_NULL (PidRef) { .fd = -EBADF }
42
43 /* A special pidref value that we are using when a PID shall be automatically acquired from some surrounding
44 * context, for example connection peer. Much like PIDREF_NULL it will be considered unset by
45 * pidref_is_set(). */
46 #define PIDREF_AUTOMATIC (const PidRef) { .pid = (pid_t) INT_MIN, .fd = -EBADF }
47
48 /* Turns a pid_t into a PidRef structure on-the-fly *without* acquiring a pidfd for it. (As opposed to
49 * pidref_set_pid() which does so *with* acquiring one, see below) */
50 #define PIDREF_MAKE_FROM_PID(x) (PidRef) { .pid = (x), .fd = -EBADF }
51
52 static inline bool pidref_is_set(const PidRef *pidref) {
53 return pidref && pidref->pid > 0;
54 }
55
56 bool pidref_is_automatic(const PidRef *pidref);
57
58 static inline bool pidref_is_set_or_automatic(const PidRef *pidref) {
59 return pidref_is_set(pidref) || pidref_is_automatic(pidref);
60 }
61
62 static inline bool pidref_is_remote(const PidRef *pidref) {
63 /* If the fd is set to -EREMOTE we assume PidRef does not refer to a local PID, but on another
64 * machine (and we just got the PidRef initialized due to deserialization of some RPC message) */
65 return pidref_is_set(pidref) && pidref->fd == -EREMOTE;
66 }
67
68 int pidref_acquire_pidfd_id(PidRef *pidref);
69 bool pidref_equal(PidRef *a, PidRef *b);
70
71 /* This turns a pid_t into a PidRef structure, and acquires a pidfd for it, if possible. (As opposed to
72 * PIDREF_MAKE_FROM_PID() above, which does not acquire a pidfd.) */
73 int pidref_set_pid(PidRef *pidref, pid_t pid);
74 int pidref_set_pidstr(PidRef *pidref, const char *pid);
75 int pidref_set_pid_and_pidfd_id(PidRef *pidref, pid_t pid, uint64_t pidfd_id);
76 int pidref_set_pidfd(PidRef *pidref, int fd);
77 int pidref_set_pidfd_take(PidRef *pidref, int fd); /* takes ownership of the passed pidfd on success */
78 int pidref_set_pidfd_consume(PidRef *pidref, int fd); /* takes ownership of the passed pidfd in both success and failure */
79 int pidref_set_parent(PidRef *ret);
80 static inline int pidref_set_self(PidRef *pidref) {
81 return pidref_set_pid(pidref, 0);
82 }
83
84 bool pidref_is_self(PidRef *pidref);
85
86 void pidref_done(PidRef *pidref);
87 PidRef* pidref_free(PidRef *pidref);
88 DEFINE_TRIVIAL_CLEANUP_FUNC(PidRef*, pidref_free);
89
90 int pidref_copy(const PidRef *pidref, PidRef *ret);
91 int pidref_dup(const PidRef *pidref, PidRef **ret);
92
93 int pidref_new_from_pid(pid_t pid, PidRef **ret);
94
95 int pidref_kill(const PidRef *pidref, int sig);
96 int pidref_kill_and_sigcont(const PidRef *pidref, int sig);
97 int pidref_sigqueue(const PidRef *pidref, int sig, int value);
98
99 int pidref_wait_for_terminate_full(PidRef *pidref, usec_t timeout, siginfo_t *ret_si);
100 static inline int pidref_wait_for_terminate(PidRef *pidref, siginfo_t *ret_si) {
101 return pidref_wait_for_terminate_full(pidref, USEC_INFINITY, ret_si);
102 }
103
104 static inline void pidref_done_sigterm_wait(PidRef *pidref) {
105 if (!pidref_is_set(pidref))
106 return;
107
108 (void) pidref_kill(pidref, SIGTERM);
109 (void) pidref_wait_for_terminate(pidref, NULL);
110 pidref_done(pidref);
111 }
112
113 static inline void pidref_done_sigkill_wait(PidRef *pidref) {
114 if (!pidref_is_set(pidref))
115 return;
116
117 (void) pidref_kill(pidref, SIGKILL);
118 (void) pidref_wait_for_terminate(pidref, NULL);
119 pidref_done(pidref);
120 }
121
122 static inline void pidref_done_sigkill_nowait(PidRef *pidref) {
123 if (!pidref_is_set(pidref))
124 return;
125
126 (void) pidref_kill(pidref, SIGKILL);
127 pidref_done(pidref);
128 }
129
130 int pidref_verify(const PidRef *pidref);
131
132 #define TAKE_PIDREF(p) TAKE_GENERIC((p), PidRef, PIDREF_NULL)
133
134 struct siphash;
135 void pidref_hash_func(const PidRef *pidref, struct siphash *state);
136 int pidref_compare_func(const PidRef *a, const PidRef *b);
137
138 extern const struct hash_ops pidref_hash_ops;
139 extern const struct hash_ops pidref_hash_ops_free; /* Has destructor call for pidref_free(), i.e. expects heap allocated PidRef as keys */