![[first]](../icons/first.png){kind=icon}
![[previous]](../icons/n_left.png){kind=icon}
![[next]](../icons/n_right.png){kind=icon}
![[last]](../icons/last.png){kind=icon}
![[top]](../icons/n_top.png){kind=icon}
![[bottom]](../icons/bottom.png){kind=icon}
![[index]](../icons/index.png){kind=icon}
![[help]](../icons/help.png){kind=icon}
*/
1 /*
2 * Copyright 2015-2024 the Pacemaker project contributors
3 *
4 * The version control history for this file may have further details.
5 *
6 * This source code is licensed under the GNU Lesser General Public License
7 * version 2.1 or later (LGPLv2.1+) WITHOUT ANY WARRANTY.
8 */
9
10 #ifndef PCMK__CRM_COMMON_INTERNAL__H
11 #define PCMK__CRM_COMMON_INTERNAL__H
12
13 #include <unistd.h> // pid_t, getpid()
14 #include <stdbool.h> // bool
15 #include <stdint.h> // uint8_t, uint64_t
16
17 #include <glib.h> // guint, GList, GHashTable
18 #include <libxml/tree.h> // xmlNode
19
20 #include <crm/common/logging.h> // do_crm_log_unlikely(), etc.
21 #include <crm/common/mainloop.h> // mainloop_io_t, struct ipc_client_callbacks
22 #include <crm/common/strings.h> // crm_strdup_printf()
23 #include <crm/common/actions_internal.h>
24 #include <crm/common/digest_internal.h>
25 #include <crm/common/health_internal.h>
26 #include <crm/common/io_internal.h>
27 #include <crm/common/iso8601_internal.h>
28 #include <crm/common/results_internal.h>
29 #include <crm/common/messages_internal.h>
30 #include <crm/common/nvpair_internal.h>
31 #include <crm/common/scores_internal.h>
32 #include <crm/common/strings_internal.h>
33 #include <crm/common/acl_internal.h>
34
35 #ifdef __cplusplus
36 extern "C" {
37 #endif
38
39 /* This says whether the current application is a Pacemaker daemon or not,
40 * and is used to change default logging settings such as whether to log to
41 * stderr, etc., as well as a few other details such as whether blackbox signal
42 * handling is enabled.
43 *
44 * It is set when logging is initialized, and does not need to be set directly.
45 */
46 extern bool pcmk__is_daemon;
47
48 // Number of elements in a statically defined array
49 #define PCMK__NELEM(a) ((int) (sizeof(a)/sizeof(a[0])) )
50
51 #if PCMK__ENABLE_CIBSECRETS
52 /* internal CIB utilities (from cib_secrets.c) */
53
54 int pcmk__substitute_secrets(const char *rsc_id, GHashTable *params);
55 #endif
56
57
58 /* internal main loop utilities (from mainloop.c) */
59
60 int pcmk__add_mainloop_ipc(crm_ipc_t *ipc, int priority, void *userdata,
61 const struct ipc_client_callbacks *callbacks,
62 mainloop_io_t **source);
63 guint pcmk__mainloop_timer_get_period(const mainloop_timer_t *timer);
64
65
66 /* internal node-related XML utilities (from nodes.c) */
67
68 /*!
69 * \internal
70 * \brief Add local node name and ID to an XML node
71 *
72 * \param[in,out] request XML node to modify
73 * \param[in] node The local node's name
74 * \param[in] nodeid The local node's ID (can be 0)
75 */
76 void pcmk__xe_add_node(xmlNode *xml, const char *node, int nodeid);
77
78
79 /* internal name/value utilities (from nvpair.c) */
80
81 int pcmk__scan_nvpair(const char *input, char **name, char **value);
82 char *pcmk__format_nvpair(const char *name, const char *value,
83 const char *units);
84
85 /* internal procfs utilities (from procfs.c) */
86
87 pid_t pcmk__procfs_pid_of(const char *name);
88 unsigned int pcmk__procfs_num_cores(void);
89 int pcmk__procfs_pid2path(pid_t pid, char path[], size_t path_size);
90 bool pcmk__procfs_has_pids(void);
91
92 /* internal functions related to process IDs (from pid.c) */
93
94 /*!
95 * \internal
96 * \brief Check whether process exists (by PID and optionally executable path)
97 *
98 * \param[in] pid PID of process to check
99 * \param[in] daemon If not NULL, path component to match with procfs entry
100 *
101 * \return Standard Pacemaker return code
102 * \note Particular return codes of interest include pcmk_rc_ok for alive,
103 * ESRCH for process is not alive (verified by kill and/or executable path
104 * match), EACCES for caller unable or not allowed to check. A result of
105 * "alive" is less reliable when \p daemon is not provided or procfs is
106 * not available, since there is no guarantee that the PID has not been
107 * recycled for another process.
108 * \note This function cannot be used to verify \e authenticity of the process.
109 */
110 int pcmk__pid_active(pid_t pid, const char *daemon);
111
112 int pcmk__read_pidfile(const char *filename, pid_t *pid);
113 int pcmk__pidfile_matches(const char *filename, pid_t expected_pid,
114 const char *expected_name, pid_t *pid);
115 int pcmk__lock_pidfile(const char *filename, const char *name);
116
117
118 // bitwise arithmetic utilities
119
120 /*!
121 * \internal
122 * \brief Set specified flags in a flag group
123 *
124 * \param[in] function Function name of caller
125 * \param[in] line Line number of caller
126 * \param[in] log_level Log a message at this level
127 * \param[in] flag_type Label describing this flag group (for logging)
128 * \param[in] target Name of object whose flags these are (for logging)
129 * \param[in] flag_group Flag group being manipulated
130 * \param[in] flags Which flags in the group should be set
131 * \param[in] flags_str Readable equivalent of \p flags (for logging)
132 *
133 * \return Possibly modified flag group
134 */
135 static inline uint64_t
136 pcmk__set_flags_as(const char *function, int line, uint8_t log_level,
/* ![[next]](../icons/right.png)
![[first]](../icons/n_first.png)
![[top]](../icons/top.png)
*/
137 const char *flag_type, const char *target,
138 uint64_t flag_group, uint64_t flags, const char *flags_str)
139 {
140 uint64_t result = flag_group | flags;
141
142 if (result != flag_group) {
143 do_crm_log_unlikely(log_level,
144 "%s flags %#.8llx (%s) for %s set by %s:%d",
145 ((flag_type == NULL)? "Group of" : flag_type),
146 (unsigned long long) flags,
147 ((flags_str == NULL)? "flags" : flags_str),
148 ((target == NULL)? "target" : target),
149 function, line);
150 }
151 return result;
152 }
153
154 /*!
155 * \internal
156 * \brief Clear specified flags in a flag group
157 *
158 * \param[in] function Function name of caller
159 * \param[in] line Line number of caller
160 * \param[in] log_level Log a message at this level
161 * \param[in] flag_type Label describing this flag group (for logging)
162 * \param[in] target Name of object whose flags these are (for logging)
163 * \param[in] flag_group Flag group being manipulated
164 * \param[in] flags Which flags in the group should be cleared
165 * \param[in] flags_str Readable equivalent of \p flags (for logging)
166 *
167 * \return Possibly modified flag group
168 */
169 static inline uint64_t
170 pcmk__clear_flags_as(const char *function, int line, uint8_t log_level,
/* ![[previous]](../icons/left.png)
*/
171 const char *flag_type, const char *target,
172 uint64_t flag_group, uint64_t flags, const char *flags_str)
173 {
174 uint64_t result = flag_group & ~flags;
175
176 if (result != flag_group) {
177 do_crm_log_unlikely(log_level,
178 "%s flags %#.8llx (%s) for %s cleared by %s:%d",
179 ((flag_type == NULL)? "Group of" : flag_type),
180 (unsigned long long) flags,
181 ((flags_str == NULL)? "flags" : flags_str),
182 ((target == NULL)? "target" : target),
183 function, line);
184 }
185 return result;
186 }
187
188 /*!
189 * \internal
190 * \brief Get readable string for whether specified flags are set
191 *
192 * \param[in] flag_group Group of flags to check
193 * \param[in] flags Which flags in \p flag_group should be checked
194 *
195 * \return "true" if all \p flags are set in \p flag_group, otherwise "false"
196 */
197 static inline const char *
198 pcmk__flag_text(uint64_t flag_group, uint64_t flags)
/* */
199 {
200 return pcmk__btoa(pcmk_all_flags_set(flag_group, flags));
201 }
202
203
204 // miscellaneous utilities (from utils.c)
205
206 void pcmk__daemonize(const char *name, const char *pidfile);
207 void pcmk__panic(const char *reason);
208 pid_t pcmk__locate_sbd(void);
209 void pcmk__sleep_ms(unsigned int ms);
210 guint pcmk__create_timer(guint interval_ms, GSourceFunc fn, gpointer data);
211 guint pcmk__timeout_ms2s(guint timeout_ms);
212
213 extern int pcmk__score_red;
214 extern int pcmk__score_green;
215 extern int pcmk__score_yellow;
216
217 /*!
218 * \internal
219 * \brief Allocate new zero-initialized memory, asserting on failure
220 *
221 * \param[in] file File where \p function is located
222 * \param[in] function Calling function
223 * \param[in] line Line within \p file
224 * \param[in] nmemb Number of elements to allocate memory for
225 * \param[in] size Size of each element
226 *
227 * \return Newly allocated memory of of size <tt>nmemb * size</tt> (guaranteed
228 * not to be \c NULL)
229 *
230 * \note The caller is responsible for freeing the return value using \c free().
231 */
232 static inline void *
233 pcmk__assert_alloc_as(const char *file, const char *function, uint32_t line,
/* */
234 size_t nmemb, size_t size)
235 {
236 void *ptr = calloc(nmemb, size);
237
238 if (ptr == NULL) {
239 crm_abort(file, function, line, "Out of memory", FALSE, TRUE);
240 crm_exit(CRM_EX_OSERR);
241 }
242 return ptr;
243 }
244
245 /*!
246 * \internal
247 * \brief Allocate new zero-initialized memory, asserting on failure
248 *
249 * \param[in] nmemb Number of elements to allocate memory for
250 * \param[in] size Size of each element
251 *
252 * \return Newly allocated memory of of size <tt>nmemb * size</tt> (guaranteed
253 * not to be \c NULL)
254 *
255 * \note The caller is responsible for freeing the return value using \c free().
256 */
257 #define pcmk__assert_alloc(nmemb, size) \
258 pcmk__assert_alloc_as(__FILE__, __func__, __LINE__, nmemb, size)
259
260 /*!
261 * \internal
262 * \brief Resize a dynamically allocated memory block
263 *
264 * \param[in] ptr Memory block to resize (or NULL to allocate new memory)
265 * \param[in] size New size of memory block in bytes (must be > 0)
266 *
267 * \return Pointer to resized memory block
268 *
269 * \note This asserts on error, so the result is guaranteed to be non-NULL
270 * (which is the main advantage of this over directly using realloc()).
271 */
272 static inline void *
273 pcmk__realloc(void *ptr, size_t size)
/* */
274 {
275 void *new_ptr;
276
277 // realloc(p, 0) can replace free(p) but this wrapper can't
278 pcmk__assert(size > 0);
279
280 new_ptr = realloc(ptr, size);
281 if (new_ptr == NULL) {
282 free(ptr);
283 abort();
284 }
285 return new_ptr;
286 }
287
288 static inline char *
289 pcmk__getpid_s(void)
/* */
290 {
291 return crm_strdup_printf("%lu", (unsigned long) getpid());
292 }
293
294 // More efficient than g_list_length(list) == 1
295 static inline bool
296 pcmk__list_of_1(GList *list)
/* */
297 {
298 return list && (list->next == NULL);
299 }
300
301 // More efficient than g_list_length(list) > 1
302 static inline bool
303 pcmk__list_of_multiple(GList *list)
/* */
304 {
305 return list && (list->next != NULL);
306 }
307
308 /* convenience functions for failure-related node attributes */
309
310 #define PCMK__FAIL_COUNT_PREFIX "fail-count"
311 #define PCMK__LAST_FAILURE_PREFIX "last-failure"
312
313 /*!
314 * \internal
315 * \brief Generate a failure-related node attribute name for a resource
316 *
317 * \param[in] prefix Start of attribute name
318 * \param[in] rsc_id Resource name
319 * \param[in] op Operation name
320 * \param[in] interval_ms Operation interval
321 *
322 * \return Newly allocated string with attribute name
323 *
324 * \note Failure attributes are named like PREFIX-RSC#OP_INTERVAL (for example,
325 * "fail-count-myrsc#monitor_30000"). The '#' is used because it is not
326 * a valid character in a resource ID, to reliably distinguish where the
327 * operation name begins. The '_' is used simply to be more comparable to
328 * action labels like "myrsc_monitor_30000".
329 */
330 static inline char *
331 pcmk__fail_attr_name(const char *prefix, const char *rsc_id, const char *op,
/* */
332 guint interval_ms)
333 {
334 CRM_CHECK(prefix && rsc_id && op, return NULL);
335 return crm_strdup_printf("%s-%s#%s_%u", prefix, rsc_id, op, interval_ms);
336 }
337
338 static inline char *
339 pcmk__failcount_name(const char *rsc_id, const char *op, guint interval_ms)
/* */
340 {
341 return pcmk__fail_attr_name(PCMK__FAIL_COUNT_PREFIX, rsc_id, op,
342 interval_ms);
343 }
344
345 static inline char *
346 pcmk__lastfailure_name(const char *rsc_id, const char *op, guint interval_ms)
/* ![[last]](../icons/n_last.png)
*/
347 {
348 return pcmk__fail_attr_name(PCMK__LAST_FAILURE_PREFIX, rsc_id, op,
349 interval_ms);
350 }
351
352 // internal resource agent functions (from agents.c)
353 int pcmk__effective_rc(int rc);
354
355 #ifdef __cplusplus
356 }
357 #endif
358
359 #endif // PCMK__CRM_COMMON_INTERNAL__H
![[bottom]](../icons/n_bottom.png){kind=icon}
*/