1 /* 2 * kmp_i18n.h 3 */ 4 5 //===----------------------------------------------------------------------===// 6 // 7 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 8 // See https://llvm.org/LICENSE.txt for license information. 9 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 10 // 11 //===----------------------------------------------------------------------===// 12 13 #ifndef KMP_I18N_H 14 #define KMP_I18N_H 15 16 #include "kmp_str.h" 17 18 #ifdef __cplusplus 19 extern "C" { 20 #endif // __cplusplus 21 22 /* kmp_i18n_id.inc defines kmp_i18n_id_t type. It is an enumeration with 23 identifiers of all the messages in the catalog. There is one special 24 identifier: kmp_i18n_null, which denotes absence of message. */ 25 #include "kmp_i18n_id.inc" // Generated file. Do not edit it manually. 26 27 /* Low-level functions handling message catalog. __kmp_i18n_open() opens message 28 catalog, __kmp_i18n_closes() it. Explicit opening is not required: if message 29 catalog is not yet open, __kmp_i18n_catgets() will open it implicitly. 30 However, catalog should be explicitly closed, otherwise resources (mamory, 31 handles) may leak. 32 33 __kmp_i18n_catgets() returns read-only string. It should not be freed. 34 35 KMP_I18N_STR macro simplifies access to strings in message catalog a bit. 36 Following two lines are equivalent: 37 38 __kmp_i18n_catgets( kmp_i18n_str_Warning ) 39 KMP_I18N_STR( Warning ) 40 */ 41 42 void __kmp_i18n_catopen(); 43 void __kmp_i18n_catclose(); 44 char const *__kmp_i18n_catgets(kmp_i18n_id_t id); 45 46 #define KMP_I18N_STR(id) __kmp_i18n_catgets(kmp_i18n_str_##id) 47 48 /* High-level interface for printing strings targeted to the user. 49 50 All the strings are divided into 3 types: 51 * messages, 52 * hints, 53 * system errors. 54 55 There are 3 kind of message severities: 56 * informational messages, 57 * warnings (non-fatal errors), 58 * fatal errors. 59 60 For example: 61 OMP: Warning #2: Cannot open message catalog "libguide.cat": (1) 62 OMP: System error #2: No such file or directory (2) 63 OMP: Hint: Please check NLSPATH environment variable. (3) 64 OMP: Info #3: Default messages will be used. (4) 65 66 where 67 (1) is a message of warning severity, 68 (2) is a system error caused the previous warning, 69 (3) is a hint for the user how to fix the problem, 70 (4) is a message of informational severity. 71 72 Usage in complex cases (message is accompanied with hints and system errors): 73 74 int error = errno; // We need save errno immediately, because it may 75 // be changed. 76 __kmp_msg( 77 kmp_ms_warning, // Severity 78 KMP_MSG( CantOpenMessageCatalog, name ), // Primary message 79 KMP_ERR( error ), // System error 80 KMP_HNT( CheckNLSPATH ), // Hint 81 __kmp_msg_null // Variadic argument list finisher 82 ); 83 84 Usage in simple cases (just a message, no system errors or hints): 85 KMP_INFORM( WillUseDefaultMessages ); 86 KMP_WARNING( CantOpenMessageCatalog, name ); 87 KMP_FATAL( StackOverlap ); 88 KMP_SYSFAIL( "pthread_create", status ); 89 KMP_CHECK_SYSFAIL( "pthread_create", status ); 90 KMP_CHECK_SYSFAIL_ERRNO( "gettimeofday", status ); 91 */ 92 93 enum kmp_msg_type { 94 kmp_mt_dummy = 0, // Special type for internal purposes. 95 kmp_mt_mesg = 96 4, // Primary OpenMP message, could be information, warning, or fatal. 97 kmp_mt_hint = 5, // Hint to the user. 98 kmp_mt_syserr = -1 // System error message. 99 }; // enum kmp_msg_type 100 typedef enum kmp_msg_type kmp_msg_type_t; 101 102 struct kmp_msg { 103 kmp_msg_type_t type; 104 int num; 105 char *str; 106 size_t len; 107 }; // struct kmp_message 108 typedef struct kmp_msg kmp_msg_t; 109 110 // Special message to denote the end of variadic list of arguments. 111 extern kmp_msg_t __kmp_msg_null; 112 113 // Helper functions. Creates messages either from message catalog or from 114 // system. Note: these functions allocate memory. You should pass created 115 // messages to __kmp_msg() function, it will print messages and destroy them. 116 kmp_msg_t __kmp_msg_format(unsigned id_arg, ...); 117 kmp_msg_t __kmp_msg_error_code(int code); 118 kmp_msg_t __kmp_msg_error_mesg(char const *mesg); 119 120 // Helper macros to make calls shorter. 121 #define KMP_MSG(...) __kmp_msg_format(kmp_i18n_msg_##__VA_ARGS__) 122 #define KMP_HNT(...) __kmp_msg_format(kmp_i18n_hnt_##__VA_ARGS__) 123 #define KMP_SYSERRCODE(code) __kmp_msg_error_code(code) 124 #define KMP_SYSERRMESG(mesg) __kmp_msg_error_mesg(mesg) 125 #define KMP_ERR KMP_SYSERRCODE 126 127 // Message severity. 128 enum kmp_msg_severity { 129 kmp_ms_inform, // Just information for the user. 130 kmp_ms_warning, // Non-fatal error, execution continues. 131 kmp_ms_fatal // Fatal error, program aborts. 132 }; // enum kmp_msg_severity 133 typedef enum kmp_msg_severity kmp_msg_severity_t; 134 135 // Primary function for printing messages for the user. The first message is 136 // mandatory. Any number of system errors and hints may be specified. Argument 137 // list must be finished with __kmp_msg_null. 138 void __kmp_msg(kmp_msg_severity_t severity, kmp_msg_t message, ...); 139 KMP_NORETURN void __kmp_fatal(kmp_msg_t message, ...); 140 141 // Helper macros to make calls shorter in simple cases. 142 #define KMP_INFORM(...) \ 143 __kmp_msg(kmp_ms_inform, KMP_MSG(__VA_ARGS__), __kmp_msg_null) 144 #define KMP_WARNING(...) \ 145 __kmp_msg(kmp_ms_warning, KMP_MSG(__VA_ARGS__), __kmp_msg_null) 146 #define KMP_FATAL(...) __kmp_fatal(KMP_MSG(__VA_ARGS__), __kmp_msg_null) 147 #define KMP_SYSFAIL(func, error) \ 148 __kmp_fatal(KMP_MSG(FunctionError, func), KMP_SYSERRCODE(error), \ 149 __kmp_msg_null) 150 151 // Check error, if not zero, generate fatal error message. 152 #define KMP_CHECK_SYSFAIL(func, error) \ 153 { \ 154 if (error) { \ 155 KMP_SYSFAIL(func, error); \ 156 } \ 157 } 158 159 // Check status, if not zero, generate fatal error message using errno. 160 #define KMP_CHECK_SYSFAIL_ERRNO(func, status) \ 161 { \ 162 if (status != 0) { \ 163 int error = errno; \ 164 KMP_SYSFAIL(func, error); \ 165 } \ 166 } 167 168 #ifdef KMP_DEBUG 169 void __kmp_i18n_dump_catalog(kmp_str_buf_t *buffer); 170 #endif // KMP_DEBUG 171 172 #ifdef __cplusplus 173 } // extern "C" 174 #endif // __cplusplus 175 176 #endif // KMP_I18N_H 177 178 // end of file // 179