openmp/runtime/src/kmp_i18n.h

   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 //