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