![[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-2022 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 CRM_COMMON_INTERNAL__H
11 #define CRM_COMMON_INTERNAL__H
12
13 #include <unistd.h> // getpid()
14 #include <stdbool.h> // bool
15 #include <stdint.h> // uint8_t, uint64_t
16 #include <string.h> // strcmp()
17 #include <fcntl.h> // open()
18 #include <sys/types.h> // uid_t, gid_t, pid_t
19
20 #include <glib.h> // guint, GList, GHashTable
21 #include <libxml/tree.h> // xmlNode
22
23 #include <crm/common/util.h> // crm_strdup_printf()
24 #include <crm/common/logging.h> // do_crm_log_unlikely(), etc.
25 #include <crm/common/mainloop.h> // mainloop_io_t, struct ipc_client_callbacks
26 #include <crm/common/health_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/strings_internal.h>
31
32 /* This says whether the current application is a Pacemaker daemon or not,
33 * and is used to change default logging settings such as whether to log to
34 * stderr, etc., as well as a few other details such as whether blackbox signal
35 * handling is enabled.
36 *
37 * It is set when logging is initialized, and does not need to be set directly.
38 */
39 extern bool pcmk__is_daemon;
40
41 // Number of elements in a statically defined array
42 #define PCMK__NELEM(a) ((int) (sizeof(a)/sizeof(a[0])) )
43
44 /* internal ACL-related utilities */
45
46 char *pcmk__uid2username(uid_t uid);
47 const char *pcmk__update_acl_user(xmlNode *request, const char *field,
48 const char *peer_user);
49
50 static inline bool
51 pcmk__is_privileged(const char *user)
/* ![[next]](../icons/right.png)
![[first]](../icons/n_first.png)
![[top]](../icons/top.png)
*/
52 {
53 return user && (!strcmp(user, CRM_DAEMON_USER) || !strcmp(user, "root"));
54 }
55
56 void pcmk__enable_acl(xmlNode *acl_source, xmlNode *target, const char *user);
57
58 bool pcmk__check_acl(xmlNode *xml, const char *name,
59 enum xml_private_flags mode);
60
61 #if SUPPORT_CIBSECRETS
62 /* internal CIB utilities (from cib_secrets.c) */
63
64 int pcmk__substitute_secrets(const char *rsc_id, GHashTable *params);
65 #endif
66
67
68 /* internal digest-related utilities (from digest.c) */
69
70 bool pcmk__verify_digest(xmlNode *input, const char *expected);
71
72
73 /* internal I/O utilities (from io.c) */
74
75 int pcmk__real_path(const char *path, char **resolved_path);
76
77 char *pcmk__series_filename(const char *directory, const char *series,
78 int sequence, bool bzip);
79 int pcmk__read_series_sequence(const char *directory, const char *series,
80 unsigned int *seq);
81 void pcmk__write_series_sequence(const char *directory, const char *series,
82 unsigned int sequence, int max);
83 int pcmk__chown_series_sequence(const char *directory, const char *series,
84 uid_t uid, gid_t gid);
85
86 int pcmk__build_path(const char *path_c, mode_t mode);
87 char *pcmk__full_path(const char *filename, const char *dirname);
88 bool pcmk__daemon_can_write(const char *dir, const char *file);
89 void pcmk__sync_directory(const char *name);
90
91 int pcmk__file_contents(const char *filename, char **contents);
92 int pcmk__write_sync(int fd, const char *contents);
93 int pcmk__set_nonblocking(int fd);
94 const char *pcmk__get_tmpdir(void);
95
96 void pcmk__close_fds_in_child(bool);
97
98 /*!
99 * \internal
100 * \brief Open /dev/null to consume next available file descriptor
101 *
102 * Open /dev/null, disregarding the result. This is intended when daemonizing to
103 * be able to null stdin, stdout, and stderr.
104 *
105 * \param[in] flags O_RDONLY (stdin) or O_WRONLY (stdout and stderr)
106 */
107 static inline void
108 pcmk__open_devnull(int flags)
/* ![[previous]](../icons/left.png)
*/
109 {
110 // Static analysis clutter
111 // cppcheck-suppress leakReturnValNotUsed
112 (void) open("/dev/null", flags);
113 }
114
115
116 /* internal main loop utilities (from mainloop.c) */
117
118 int pcmk__add_mainloop_ipc(crm_ipc_t *ipc, int priority, void *userdata,
119 struct ipc_client_callbacks *callbacks,
120 mainloop_io_t **source);
121 guint pcmk__mainloop_timer_get_period(mainloop_timer_t *timer);
122
123
124 /* internal name/value utilities (from nvpair.c) */
125
126 int pcmk__scan_nvpair(const char *input, char **name, char **value);
127 char *pcmk__format_nvpair(const char *name, const char *value,
128 const char *units);
129 char *pcmk__format_named_time(const char *name, time_t epoch_time);
130
131 /*!
132 * \internal
133 * \brief Add a boolean attribute to an XML node.
134 *
135 * \param[in,out] node XML node to add attributes to
136 * \param[in] name XML attribute to create
137 * \param[in] value Value to give to the attribute
138 */
139 void
140 pcmk__xe_set_bool_attr(xmlNodePtr node, const char *name, bool value);
141
142 /*!
143 * \internal
144 * \brief Extract a boolean attribute's value from an XML element
145 *
146 * \param[in] node XML node to get attribute from
147 * \param[in] name XML attribute to get
148 *
149 * \return True if the given \p name is an attribute on \p node and has
150 * the value "true", False in all other cases
151 */
152 bool
153 pcmk__xe_attr_is_true(xmlNodePtr node, const char *name);
154
155 /*!
156 * \internal
157 * \brief Extract a boolean attribute's value from an XML element, with
158 * error checking
159 *
160 * \param[in] node XML node to get attribute from
161 * \param[in] name XML attribute to get
162 * \param[out] value Destination for the value of the attribute
163 *
164 * \return EINVAL if \p name or \p value are NULL, ENODATA if \p node is
165 * NULL or the attribute does not exist, pcmk_rc_unknown_format
166 * if the attribute is not a boolean, and pcmk_rc_ok otherwise.
167 *
168 * \note \p value only has any meaning if the return value is pcmk_rc_ok.
169 */
170 int
171 pcmk__xe_get_bool_attr(xmlNodePtr node, const char *name, bool *value);
172
173
174 /* internal procfs utilities (from procfs.c) */
175
176 pid_t pcmk__procfs_pid_of(const char *name);
177 unsigned int pcmk__procfs_num_cores(void);
178
179
180 /* internal XML schema functions (from xml.c) */
181
182 void crm_schema_init(void);
183 void crm_schema_cleanup(void);
184
185
186 /* internal functions related to process IDs (from pid.c) */
187
188 /*!
189 * \internal
190 * \brief Check whether process exists (by PID and optionally executable path)
191 *
192 * \param[in] pid PID of process to check
193 * \param[in] daemon If not NULL, path component to match with procfs entry
194 *
195 * \return Standard Pacemaker return code
196 * \note Particular return codes of interest include pcmk_rc_ok for alive,
197 * ESRCH for process is not alive (verified by kill and/or executable path
198 * match), EACCES for caller unable or not allowed to check. A result of
199 * "alive" is less reliable when \p daemon is not provided or procfs is
200 * not available, since there is no guarantee that the PID has not been
201 * recycled for another process.
202 * \note This function cannot be used to verify \e authenticity of the process.
203 */
204 int pcmk__pid_active(pid_t pid, const char *daemon);
205
206 int pcmk__read_pidfile(const char *filename, pid_t *pid);
207 int pcmk__pidfile_matches(const char *filename, pid_t expected_pid,
208 const char *expected_name, pid_t *pid);
209 int pcmk__lock_pidfile(const char *filename, const char *name);
210
211
212 /* internal functions related to resource operations (from operations.c) */
213
214 // printf-style format to create operation ID from resource, action, interval
215 #define PCMK__OP_FMT "%s_%s_%u"
216
217 char *pcmk__op_key(const char *rsc_id, const char *op_type, guint interval_ms);
218 char *pcmk__notify_key(const char *rsc_id, const char *notify_type,
219 const char *op_type);
220 char *pcmk__transition_key(int transition_id, int action_id, int target_rc,
221 const char *node);
222 void pcmk__filter_op_for_digest(xmlNode *param_set);
223 bool pcmk__is_fencing_action(const char *action);
224
225
226 // bitwise arithmetic utilities
227
228 /*!
229 * \internal
230 * \brief Set specified flags in a flag group
231 *
232 * \param[in] function Function name of caller
233 * \param[in] line Line number of caller
234 * \param[in] log_level Log a message at this level
235 * \param[in] flag_type Label describing this flag group (for logging)
236 * \param[in] target Name of object whose flags these are (for logging)
237 * \param[in] flag_group Flag group being manipulated
238 * \param[in] flags Which flags in the group should be set
239 * \param[in] flags_str Readable equivalent of \p flags (for logging)
240 *
241 * \return Possibly modified flag group
242 */
243 static inline uint64_t
244 pcmk__set_flags_as(const char *function, int line, uint8_t log_level,
/* */
245 const char *flag_type, const char *target,
246 uint64_t flag_group, uint64_t flags, const char *flags_str)
247 {
248 uint64_t result = flag_group | flags;
249
250 if (result != flag_group) {
251 do_crm_log_unlikely(log_level,
252 "%s flags %#.8llx (%s) for %s set by %s:%d",
253 ((flag_type == NULL)? "Group of" : flag_type),
254 (unsigned long long) flags,
255 ((flags_str == NULL)? "flags" : flags_str),
256 ((target == NULL)? "target" : target),
257 function, line);
258 }
259 return result;
260 }
261
262 /*!
263 * \internal
264 * \brief Clear specified flags in a flag group
265 *
266 * \param[in] function Function name of caller
267 * \param[in] line Line number of caller
268 * \param[in] log_level Log a message at this level
269 * \param[in] flag_type Label describing this flag group (for logging)
270 * \param[in] target Name of object whose flags these are (for logging)
271 * \param[in] flag_group Flag group being manipulated
272 * \param[in] flags Which flags in the group should be cleared
273 * \param[in] flags_str Readable equivalent of \p flags (for logging)
274 *
275 * \return Possibly modified flag group
276 */
277 static inline uint64_t
278 pcmk__clear_flags_as(const char *function, int line, uint8_t log_level,
/* */
279 const char *flag_type, const char *target,
280 uint64_t flag_group, uint64_t flags, const char *flags_str)
281 {
282 uint64_t result = flag_group & ~flags;
283
284 if (result != flag_group) {
285 do_crm_log_unlikely(log_level,
286 "%s flags %#.8llx (%s) for %s cleared by %s:%d",
287 ((flag_type == NULL)? "Group of" : flag_type),
288 (unsigned long long) flags,
289 ((flags_str == NULL)? "flags" : flags_str),
290 ((target == NULL)? "target" : target),
291 function, line);
292 }
293 return result;
294 }
295
296 // miscellaneous utilities (from utils.c)
297
298 void pcmk__daemonize(const char *name, const char *pidfile);
299 void pcmk__panic(const char *origin);
300 pid_t pcmk__locate_sbd(void);
301 void pcmk__sleep_ms(unsigned int ms);
302
303 extern int pcmk__score_red;
304 extern int pcmk__score_green;
305 extern int pcmk__score_yellow;
306
307 /*!
308 * \internal
309 * \brief Resize a dynamically allocated memory block
310 *
311 * \param[in] ptr Memory block to resize (or NULL to allocate new memory)
312 * \param[in] size New size of memory block in bytes (must be > 0)
313 *
314 * \return Pointer to resized memory block
315 *
316 * \note This asserts on error, so the result is guaranteed to be non-NULL
317 * (which is the main advantage of this over directly using realloc()).
318 */
319 static inline void *
320 pcmk__realloc(void *ptr, size_t size)
/* */
321 {
322 void *new_ptr;
323
324 // realloc(p, 0) can replace free(p) but this wrapper can't
325 CRM_ASSERT(size > 0);
326
327 new_ptr = realloc(ptr, size);
328 if (new_ptr == NULL) {
329 free(ptr);
330 abort();
331 }
332 return new_ptr;
333 }
334
335
336 static inline char *
337 pcmk__getpid_s(void)
/* */
338 {
339 return crm_strdup_printf("%lu", (unsigned long) getpid());
340 }
341
342 // More efficient than g_list_length(list) == 1
343 static inline bool
344 pcmk__list_of_1(GList *list)
/* */
345 {
346 return list && (list->next == NULL);
347 }
348
349 // More efficient than g_list_length(list) > 1
350 static inline bool
351 pcmk__list_of_multiple(GList *list)
/* */
352 {
353 return list && (list->next != NULL);
354 }
355
356 /* convenience functions for failure-related node attributes */
357
358 #define PCMK__FAIL_COUNT_PREFIX "fail-count"
359 #define PCMK__LAST_FAILURE_PREFIX "last-failure"
360
361 /*!
362 * \internal
363 * \brief Generate a failure-related node attribute name for a resource
364 *
365 * \param[in] prefix Start of attribute name
366 * \param[in] rsc_id Resource name
367 * \param[in] op Operation name
368 * \param[in] interval_ms Operation interval
369 *
370 * \return Newly allocated string with attribute name
371 *
372 * \note Failure attributes are named like PREFIX-RSC#OP_INTERVAL (for example,
373 * "fail-count-myrsc#monitor_30000"). The '#' is used because it is not
374 * a valid character in a resource ID, to reliably distinguish where the
375 * operation name begins. The '_' is used simply to be more comparable to
376 * action labels like "myrsc_monitor_30000".
377 */
378 static inline char *
379 pcmk__fail_attr_name(const char *prefix, const char *rsc_id, const char *op,
/* */
380 guint interval_ms)
381 {
382 CRM_CHECK(prefix && rsc_id && op, return NULL);
383 return crm_strdup_printf("%s-%s#%s_%u", prefix, rsc_id, op, interval_ms);
384 }
385
386 static inline char *
387 pcmk__failcount_name(const char *rsc_id, const char *op, guint interval_ms)
/* */
388 {
389 return pcmk__fail_attr_name(PCMK__FAIL_COUNT_PREFIX, rsc_id, op,
390 interval_ms);
391 }
392
393 static inline char *
394 pcmk__lastfailure_name(const char *rsc_id, const char *op, guint interval_ms)
/* ![[last]](../icons/n_last.png)
*/
395 {
396 return pcmk__fail_attr_name(PCMK__LAST_FAILURE_PREFIX, rsc_id, op,
397 interval_ms);
398 }
399
400 // internal resource agent functions (from agents.c)
401 int pcmk__effective_rc(int rc);
402
403 #endif /* CRM_COMMON_INTERNAL__H */
![[bottom]](../icons/n_bottom.png){kind=icon}
*/