root/include/crm/common/internal.h

/* */

INCLUDED FROM

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

/* */