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

/* */