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 PCMK__CRM_COMMON_RESULTS__H 10 # define PCMK__CRM_COMMON_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) /* */ 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 "Internal communication failure"; 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