root/include/crm/common/results.h

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

INCLUDED FROM


DEFINITIONS

This source file includes following definitions.
  1. pcmk_exec_status_str

   1 /*
   2  * Copyright 2012-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 #ifndef CRM_RESULTS__H
  10 #  define CRM_RESULTS__H
  11 
  12 #ifdef __cplusplus
  13 extern "C" {
  14 #endif
  15 
  16 /*!
  17  * \file
  18  * \brief Function and executable result codes
  19  * \ingroup core
  20  */
  21 
  22 // Lifted from config.h
  23 /* The _Noreturn keyword of C11.  */
  24 #ifndef _Noreturn
  25 # if (defined __cplusplus \
  26       && ((201103 <= __cplusplus && !(__GNUC__ == 4 && __GNUC_MINOR__ == 7)) \
  27           || (defined _MSC_VER && 1900 <= _MSC_VER)))
  28 #  define _Noreturn [[noreturn]]
  29 # elif ((!defined __cplusplus || defined __clang__) \
  30         && (201112 <= (defined __STDC_VERSION__ ? __STDC_VERSION__ : 0)  \
  31             || 4 < __GNUC__ + (7 <= __GNUC_MINOR__)))
  32    /* _Noreturn works as-is.  */
  33 # elif 2 < __GNUC__ + (8 <= __GNUC_MINOR__) || 0x5110 <= __SUNPRO_C
  34 #  define _Noreturn __attribute__ ((__noreturn__))
  35 # elif 1200 <= (defined _MSC_VER ? _MSC_VER : 0)
  36 #  define _Noreturn __declspec (noreturn)
  37 # else
  38 #  define _Noreturn
  39 # endif
  40 #endif
  41 
  42 #  define CRM_ASSERT(expr) do {                                              \
  43         if (!(expr)) {                                                       \
  44             crm_abort(__FILE__, __func__, __LINE__, #expr, TRUE, FALSE);     \
  45             abort(); /* crm_abort() doesn't always abort! */                 \
  46         }                                                                    \
  47     } while(0)
  48 
  49 /*
  50  * Function return codes
  51  *
  52  * Most Pacemaker API functions return an integer return code. There are two
  53  * alternative interpretations. The legacy interpration is that the absolute
  54  * value of the return code is either a system error number or a custom
  55  * pcmk_err_* number. This is less than ideal because system error numbers are
  56  * constrained only to the positive int range, so there's the possibility that
  57  * system errors and custom errors could collide (which did in fact happen
  58  * already on one architecture). The new intepretation is that negative values
  59  * are from the pcmk_rc_e enum, and positive values are system error numbers.
  60  * Both use 0 for success.
  61  *
  62  * For system error codes, see:
  63  * - /usr/include/asm-generic/errno.h
  64  * - /usr/include/asm-generic/errno-base.h
  65  */
  66 
  67 // Legacy custom return codes for Pacemaker API functions (deprecated)
  68 #  define pcmk_ok                       0
  69 #  define PCMK_ERROR_OFFSET             190    /* Replacements on non-linux systems, see include/portability.h */
  70 #  define PCMK_CUSTOM_OFFSET            200    /* Purely custom codes */
  71 #  define pcmk_err_generic              201
  72 #  define pcmk_err_no_quorum            202
  73 #  define pcmk_err_schema_validation    203
  74 #  define pcmk_err_transform_failed     204
  75 #  define pcmk_err_old_data             205
  76 #  define pcmk_err_diff_failed          206
  77 #  define pcmk_err_diff_resync          207
  78 #  define pcmk_err_cib_modified         208
  79 #  define pcmk_err_cib_backup           209
  80 #  define pcmk_err_cib_save             210
  81 #  define pcmk_err_schema_unchanged     211
  82 #  define pcmk_err_cib_corrupt          212
  83 #  define pcmk_err_multiple             213
  84 #  define pcmk_err_node_unknown         214
  85 #  define pcmk_err_already              215
  86 /* On HPPA 215 is ENOSYM (Unknown error 215), which hopefully never happens. */
  87 #ifdef __hppa__
  88 #  define pcmk_err_bad_nvpair           250 /* 216 is ENOTSOCK */
  89 #  define pcmk_err_unknown_format       252 /* 217 is EDESTADDRREQ */
  90 #else
  91 #  define pcmk_err_bad_nvpair           216
  92 #  define pcmk_err_unknown_format       217
  93 #endif
  94 
  95 /*!
  96  * \enum pcmk_rc_e
  97  * \brief Return codes for Pacemaker API functions
  98  *
  99  * Any Pacemaker API function documented as returning a "standard Pacemaker
 100  * return code" will return pcmk_rc_ok (0) on success, and one of this
 101  * enumeration's other (negative) values or a (positive) system error number
 102  * otherwise. The custom codes are at -1001 and lower, so that the caller may
 103  * use -1 through -1000 for their own custom values if desired. While generally
 104  * referred to as "errors", nonzero values simply indicate a result, which might
 105  * or might not be an error depending on the calling context.
 106  */
 107 enum pcmk_rc_e {
 108     /* When adding new values, use consecutively lower numbers, update the array
 109      * in lib/common/results.c, and test with crm_error.
 110      */
 111     pcmk_rc_invalid_transition  = -1031,
 112     pcmk_rc_graph_error         = -1030,
 113     pcmk_rc_dot_error           = -1029,
 114     pcmk_rc_underflow           = -1028,
 115     pcmk_rc_no_input            = -1027,
 116     pcmk_rc_no_output           = -1026,
 117     pcmk_rc_after_range         = -1025,
 118     pcmk_rc_within_range        = -1024,
 119     pcmk_rc_before_range        = -1023,
 120     pcmk_rc_undetermined        = -1022,
 121     pcmk_rc_op_unsatisfied      = -1021,
 122     pcmk_rc_ipc_pid_only        = -1020,
 123     pcmk_rc_ipc_unresponsive    = -1019,
 124     pcmk_rc_ipc_unauthorized    = -1018,
 125     pcmk_rc_no_quorum           = -1017,
 126     pcmk_rc_schema_validation   = -1016,
 127     pcmk_rc_schema_unchanged    = -1015,
 128     pcmk_rc_transform_failed    = -1014,
 129     pcmk_rc_old_data            = -1013,
 130     pcmk_rc_diff_failed         = -1012,
 131     pcmk_rc_diff_resync         = -1011,
 132     pcmk_rc_cib_modified        = -1010,
 133     pcmk_rc_cib_backup          = -1009,
 134     pcmk_rc_cib_save            = -1008,
 135     pcmk_rc_cib_corrupt         = -1007,
 136     pcmk_rc_multiple            = -1006,
 137     pcmk_rc_node_unknown        = -1005,
 138     pcmk_rc_already             = -1004,
 139     pcmk_rc_bad_nvpair          = -1003,
 140     pcmk_rc_unknown_format      = -1002,
 141     // Developers: Use a more specific code than pcmk_rc_error whenever possible
 142     pcmk_rc_error               = -1001,
 143 
 144     // Values -1 through -1000 reserved for caller use
 145 
 146     pcmk_rc_ok                  =     0
 147 
 148     // Positive values reserved for system error numbers
 149 };
 150 
 151 
 152 /*!
 153  * \enum ocf_exitcode
 154  * \brief Exit status codes for resource agents
 155  *
 156  * The OCF Resource Agent API standard enumerates the possible exit status codes
 157  * that agents should return. Besides being used with OCF agents, these values
 158  * are also used by the executor as a universal status for all agent standards;
 159  * actual results are mapped to these before returning them to clients.
 160  */
 161 enum ocf_exitcode {
 162     PCMK_OCF_OK                   = 0,   //!< Success
 163     PCMK_OCF_UNKNOWN_ERROR        = 1,   //!< Unspecified error
 164     PCMK_OCF_INVALID_PARAM        = 2,   //!< Parameter invalid (in local context)
 165     PCMK_OCF_UNIMPLEMENT_FEATURE  = 3,   //!< Requested action not implemented
 166     PCMK_OCF_INSUFFICIENT_PRIV    = 4,   //!< Insufficient privileges
 167     PCMK_OCF_NOT_INSTALLED        = 5,   //!< Dependencies not available locally
 168     PCMK_OCF_NOT_CONFIGURED       = 6,   //!< Parameter invalid (inherently)
 169     PCMK_OCF_NOT_RUNNING          = 7,   //!< Service safely stopped
 170     PCMK_OCF_RUNNING_PROMOTED     = 8,   //!< Service active and promoted
 171     PCMK_OCF_FAILED_PROMOTED      = 9,   //!< Service failed and possibly in promoted role
 172     PCMK_OCF_DEGRADED             = 190, //!< Service active but more likely to fail soon
 173     PCMK_OCF_DEGRADED_PROMOTED    = 191, //!< Service promoted but more likely to fail soon
 174 
 175     /* These two are Pacemaker extensions, not in the OCF standard. The
 176      * controller records PCMK_OCF_UNKNOWN for pending actions.
 177      * PCMK_OCF_CONNECTION_DIED is used only with older DCs that don't support
 178      * PCMK_EXEC_NOT_CONNECTED.
 179      *
 180      * @TODO PCMK_OCF_UNKNOWN should be deprecated, and an execution status of
 181      * PCMK_EXEC_PENDING relied on instead (though it might be worthwhile to
 182      * keep PCMK_OCF_UNKNOWN as an invalid value for initializing new action
 183      * objects). However, backward compatibility must be considered (processing
 184      * old saved CIB files, rolling upgrades with older DCs, older
 185      * Pacemaker Remote nodes or connection hosts, and older bundles).
 186      */
 187     PCMK_OCF_CONNECTION_DIED      = 189, //!< \deprecated See PCMK_EXEC_NOT_CONNECTED
 188     PCMK_OCF_UNKNOWN              = 193, //!< Action is pending
 189 
 190 #if !defined(PCMK_ALLOW_DEPRECATED) || (PCMK_ALLOW_DEPRECATED == 1)
 191     // Former Pacemaker extensions
 192     PCMK_OCF_EXEC_ERROR           = 192, //!< \deprecated (Unused)
 193     PCMK_OCF_SIGNAL               = 194, //!< \deprecated (Unused)
 194     PCMK_OCF_NOT_SUPPORTED        = 195, //!< \deprecated (Unused)
 195     PCMK_OCF_PENDING              = 196, //!< \deprecated (Unused)
 196     PCMK_OCF_CANCELLED            = 197, //!< \deprecated (Unused)
 197     PCMK_OCF_TIMEOUT              = 198, //!< \deprecated (Unused)
 198     PCMK_OCF_OTHER_ERROR          = 199, //!< \deprecated (Unused)
 199 
 200     //! \deprecated Use PCMK_OCF_RUNNING_PROMOTED instead
 201     PCMK_OCF_RUNNING_MASTER     = PCMK_OCF_RUNNING_PROMOTED,
 202 
 203     //! \deprecated Use PCMK_OCF_FAILED_PROMOTED instead
 204     PCMK_OCF_FAILED_MASTER      = PCMK_OCF_FAILED_PROMOTED,
 205 
 206     //! \deprecated Use PCMK_OCF_DEGRADED_PROMOTED instead
 207     PCMK_OCF_DEGRADED_MASTER    = PCMK_OCF_DEGRADED_PROMOTED,
 208 #endif
 209 };
 210 
 211 /*!
 212  * \enum crm_exit_e
 213  * \brief Exit status codes for tools and daemons
 214  *
 215  * We want well-specified (i.e. OS-invariant) exit status codes for our daemons
 216  * and applications so they can be relied on by callers. (Function return codes
 217  * and errno's do not make good exit statuses.)
 218  *
 219  * The only hard rule is that exit statuses must be between 0 and 255; all else
 220  * is convention. Universally, 0 is success, and 1 is generic error (excluding
 221  * OSes we don't support -- for example, OpenVMS considers 1 success!).
 222  *
 223  * For init scripts, the LSB gives meaning to 0-7, and sets aside 150-199 for
 224  * application use. OCF adds 8-9 and 190-191.
 225  *
 226  * sysexits.h was an attempt to give additional meanings, but never really
 227  * caught on. It uses 0 and 64-78.
 228  *
 229  * Bash reserves 2 ("incorrect builtin usage") and 126-255 (126 is "command
 230  * found but not executable", 127 is "command not found", 128 + n is
 231  * "interrupted by signal n").
 232  *
 233  * tldp.org recommends 64-113 for application use.
 234  *
 235  * We try to overlap with the above conventions when practical.
 236  */
 237 typedef enum crm_exit_e {
 238     // Common convention
 239     CRM_EX_OK                   =   0, //!< Success
 240     CRM_EX_ERROR                =   1, //!< Unspecified error
 241 
 242     // LSB + OCF
 243     CRM_EX_INVALID_PARAM        =   2, //!< Parameter invalid (in local context)
 244     CRM_EX_UNIMPLEMENT_FEATURE  =   3, //!< Requested action not implemented
 245     CRM_EX_INSUFFICIENT_PRIV    =   4, //!< Insufficient privileges
 246     CRM_EX_NOT_INSTALLED        =   5, //!< Dependencies not available locally
 247     CRM_EX_NOT_CONFIGURED       =   6, //!< Parameter invalid (inherently)
 248     CRM_EX_NOT_RUNNING          =   7, //!< Service safely stopped
 249 
 250     // sysexits.h
 251     CRM_EX_USAGE                =  64, //!< Command line usage error
 252     CRM_EX_DATAERR              =  65, //!< User-supplied data incorrect
 253     CRM_EX_NOINPUT              =  66, //!< Input file not available
 254     CRM_EX_NOUSER               =  67, //!< User does not exist
 255     CRM_EX_NOHOST               =  68, //!< Host unknown
 256     CRM_EX_UNAVAILABLE          =  69, //!< Needed service unavailable
 257     CRM_EX_SOFTWARE             =  70, //!< Internal software bug
 258     CRM_EX_OSERR                =  71, //!< External (OS/environmental) problem
 259     CRM_EX_OSFILE               =  72, //!< System file not usable
 260     CRM_EX_CANTCREAT            =  73, //!< File couldn't be created
 261     CRM_EX_IOERR                =  74, //!< File I/O error
 262     CRM_EX_TEMPFAIL             =  75, //!< Try again
 263     CRM_EX_PROTOCOL             =  76, //!< Protocol violated
 264     CRM_EX_NOPERM               =  77, //!< Non-file permission issue
 265     CRM_EX_CONFIG               =  78, //!< Misconfiguration
 266 
 267     // Custom
 268     CRM_EX_FATAL                = 100, //!< Do not respawn
 269     CRM_EX_PANIC                = 101, //!< Panic the local host
 270     CRM_EX_DISCONNECT           = 102, //!< Lost connection to something
 271     CRM_EX_OLD                  = 103, //!< Update older than existing config
 272     CRM_EX_DIGEST               = 104, //!< Digest comparison failed
 273     CRM_EX_NOSUCH               = 105, //!< Requested item does not exist
 274     CRM_EX_QUORUM               = 106, //!< Local partition does not have quorum
 275     CRM_EX_UNSAFE               = 107, //!< Requires --force or new conditions
 276     CRM_EX_EXISTS               = 108, //!< Requested item already exists
 277     CRM_EX_MULTIPLE             = 109, //!< Requested item has multiple matches
 278     CRM_EX_EXPIRED              = 110, //!< Requested item has expired
 279     CRM_EX_NOT_YET_IN_EFFECT    = 111, //!< Requested item is not in effect
 280     CRM_EX_INDETERMINATE        = 112, //!< Could not determine status
 281     CRM_EX_UNSATISFIED          = 113, //!< Requested item does not satisfy constraints
 282 
 283     // Other
 284     CRM_EX_TIMEOUT              = 124, //!< Convention from timeout(1)
 285 
 286     /* Anything above 128 overlaps with some shells' use of these values for
 287      * "interrupted by signal N", and so may be unreliable when detected by
 288      * shell scripts.
 289      */
 290 
 291     // OCF Resource Agent API 1.1
 292     CRM_EX_DEGRADED             = 190, //!< Service active but more likely to fail soon
 293     CRM_EX_DEGRADED_PROMOTED    = 191, //!< Service promoted but more likely to fail soon
 294 
 295     CRM_EX_MAX                  = 255, //!< Ensure crm_exit_t can hold this
 296 } crm_exit_t;
 297 
 298 /*!
 299  * \enum pcmk_exec_status
 300  * \brief Execution status
 301  *
 302  * These codes are used to specify the result of the attempt to execute an
 303  * agent, rather than the agent's result itself.
 304  */
 305 enum pcmk_exec_status {
 306     PCMK_EXEC_UNKNOWN = -2,     //!< Used only to initialize variables
 307     PCMK_EXEC_PENDING = -1,     //!< Action is in progress
 308     PCMK_EXEC_DONE,             //!< Action completed, result is known
 309     PCMK_EXEC_CANCELLED,        //!< Action was cancelled
 310     PCMK_EXEC_TIMEOUT,          //!< Action did not complete in time
 311     PCMK_EXEC_NOT_SUPPORTED,    //!< Agent does not implement requested action
 312     PCMK_EXEC_ERROR,            //!< Execution failed, may be retried
 313     PCMK_EXEC_ERROR_HARD,       //!< Execution failed, do not retry on node
 314     PCMK_EXEC_ERROR_FATAL,      //!< Execution failed, do not retry anywhere
 315     PCMK_EXEC_NOT_INSTALLED,    //!< Agent or dependency not available locally
 316     PCMK_EXEC_NOT_CONNECTED,    //!< No connection to executor
 317     PCMK_EXEC_INVALID,          //!< Action cannot be attempted (e.g. shutdown)
 318     PCMK_EXEC_NO_FENCE_DEVICE,  //!< No fence device is configured for target
 319     PCMK_EXEC_NO_SECRETS,       //!< Necessary CIB secrets are unavailable
 320 
 321     // Add new values above here then update this one below
 322     PCMK_EXEC_MAX = PCMK_EXEC_NO_SECRETS, //!< Maximum value for this enum
 323 };
 324 
 325 const char *pcmk_rc_name(int rc);
 326 const char *pcmk_rc_str(int rc);
 327 crm_exit_t pcmk_rc2exitc(int rc);
 328 enum ocf_exitcode pcmk_rc2ocf(int rc);
 329 int pcmk_rc2legacy(int rc);
 330 int pcmk_legacy2rc(int legacy_rc);
 331 const char *pcmk_strerror(int rc);
 332 const char *pcmk_errorname(int rc);
 333 const char *bz2_strerror(int rc);
 334 crm_exit_t crm_errno2exit(int rc);
 335 const char *crm_exit_name(crm_exit_t exit_code);
 336 const char *crm_exit_str(crm_exit_t exit_code);
 337 _Noreturn crm_exit_t crm_exit(crm_exit_t rc);
 338 
 339 static inline const char *
 340 pcmk_exec_status_str(enum pcmk_exec_status status)
     /* [previous][next][first][last][top][bottom][index][help] */
 341 {
 342     switch (status) {
 343         case PCMK_EXEC_PENDING:         return "pending";
 344         case PCMK_EXEC_DONE:            return "complete";
 345         case PCMK_EXEC_CANCELLED:       return "Cancelled";
 346         case PCMK_EXEC_TIMEOUT:         return "Timed Out";
 347         case PCMK_EXEC_NOT_SUPPORTED:   return "NOT SUPPORTED";
 348         case PCMK_EXEC_ERROR:           return "Error";
 349         case PCMK_EXEC_ERROR_HARD:      return "Hard error";
 350         case PCMK_EXEC_ERROR_FATAL:     return "Fatal error";
 351         case PCMK_EXEC_NOT_INSTALLED:   return "Not installed";
 352         case PCMK_EXEC_NOT_CONNECTED:   return "No executor connection";
 353         case PCMK_EXEC_INVALID:         return "Cannot execute now";
 354         case PCMK_EXEC_NO_FENCE_DEVICE: return "No fence device";
 355         case PCMK_EXEC_NO_SECRETS:      return "CIB secrets unavailable";
 356         default:                        return "UNKNOWN!";
 357     }
 358 }
 359 
 360 #ifdef __cplusplus
 361 }
 362 #endif
 363 
 364 #endif

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