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