root/include/crm/common/internal.h

/* [previous][next][first][last][top][bottom][index][help] */

INCLUDED FROM


DEFINITIONS

This source file includes following definitions.
  1. pcmk__is_privileged
  2. pcmk__open_devnull
  3. pcmk__set_flags_as
  4. pcmk__clear_flags_as
  5. pcmk__realloc
  6. pcmk__getpid_s
  7. pcmk__list_of_1
  8. pcmk__list_of_multiple
  9. pcmk__fail_attr_name
  10. pcmk__failcount_name
  11. pcmk__lastfailure_name

   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)
     /* [previous][next][first][last][top][bottom][index][help] */
  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][next][first][last][top][bottom][index][help] */
 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,
     /* [previous][next][first][last][top][bottom][index][help] */
 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,
     /* [previous][next][first][last][top][bottom][index][help] */
 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)
     /* [previous][next][first][last][top][bottom][index][help] */
 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)
     /* [previous][next][first][last][top][bottom][index][help] */
 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)
     /* [previous][next][first][last][top][bottom][index][help] */
 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)
     /* [previous][next][first][last][top][bottom][index][help] */
 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,
     /* [previous][next][first][last][top][bottom][index][help] */
 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)
     /* [previous][next][first][last][top][bottom][index][help] */
 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)
     /* [previous][next][first][last][top][bottom][index][help] */
 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 */

/* [previous][next][first][last][top][bottom][index][help] */