Intel® OpenMP* Runtime Library
 All Classes Functions Variables Typedefs Enumerations Enumerator Modules Pages
kmp_i18n.h
1 /*
2  * kmp_i18n.h
3  */
4 
5 /* <copyright>
6  Copyright (c) 2007-2015 Intel Corporation. All Rights Reserved.
7 
8  Redistribution and use in source and binary forms, with or without
9  modification, are permitted provided that the following conditions
10  are met:
11 
12  * Redistributions of source code must retain the above copyright
13  notice, this list of conditions and the following disclaimer.
14  * Redistributions in binary form must reproduce the above copyright
15  notice, this list of conditions and the following disclaimer in the
16  documentation and/or other materials provided with the distribution.
17  * Neither the name of Intel Corporation nor the names of its
18  contributors may be used to endorse or promote products derived
19  from this software without specific prior written permission.
20 
21  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
24  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
25  HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
26  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
27  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
28  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
29  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
30  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32 
33 </copyright> */
34 
35 #ifndef KMP_I18N_H
36 #define KMP_I18N_H
37 
38 #include "kmp_str.h"
39 
40 #ifdef __cplusplus
41  extern "C" {
42 #endif // __cplusplus
43 
44 /*
45  kmp_i18n_id.inc defines kmp_i18n_id_t type. It is an enumeration with identifiers of all the
46  messages in the catalog. There is one special identifier: kmp_i18n_null, which denotes absence
47  of message.
48 */
49 #include "kmp_i18n_id.inc" // Generated file. Do not edit it manually.
50 
51 /*
52  Low-level functions handling message catalog. __kmp_i18n_open() opens message catalog,
53  __kmp_i18n_closes() it. Explicit opening is not required: if message catalog is not yet open,
54  __kmp_i18n_catgets() will open it implicitly. However, catalog should be explicitly closed,
55  otherwise resources (mamory, handles) may leak.
56 
57  __kmp_i18n_catgets() returns read-only string. It should not be freed.
58 
59  KMP_I18N_STR macro simplifies acces to strings in message catalog a bit. Following two lines are
60  equivalent:
61 
62  __kmp_i18n_catgets( kmp_i18n_str_Warning )
63  KMP_I18N_STR( Warning )
64 */
65 
66 void __kmp_i18n_catopen();
67 void __kmp_i18n_catclose();
68 char const * __kmp_i18n_catgets( kmp_i18n_id_t id );
69 
70 #define KMP_I18N_STR( id ) __kmp_i18n_catgets( kmp_i18n_str_ ## id )
71 
72 
73 /*
74  ------------------------------------------------------------------------------------------------
75 
76  High-level interface for printing strings targeted to the user.
77 
78  All the strings are divided into 3 types:
79 
80  * messages,
81  * hints,
82  * system errors.
83 
84  There are 3 kind of message severities:
85 
86  * informational messages,
87  * warnings (non-fatal errors),
88  * fatal errors.
89 
90  For example:
91 
92  OMP: Warning #2: Cannot open message catalog "libguide.cat": (1)
93  OMP: System error #2: No such file or directory (2)
94  OMP: Hint: Please check NLSPATH environment variable. (3)
95  OMP: Info #3: Default messages will be used. (4)
96 
97  where
98 
99  (1) is a message of warning severity,
100  (2) is a system error caused the previous warning,
101  (3) is a hint for the user how to fix the problem,
102  (4) is a message of informational severity.
103 
104  Usage in complex cases (message is accompanied with hints and system errors):
105 
106  int error = errno; // We need save errno immediately, because it may be changed.
107  __kmp_msg(
108  kmp_ms_warning, // Severity
109  KMP_MSG( CantOpenMessageCatalog, name ), // Primary message
110  KMP_ERR( error ), // System error
111  KMP_HNT( CheckNLSPATH ), // Hint
112  __kmp_msg_null // Variadic argument list finisher
113  );
114 
115  Usage in simple cases (just a message, no system errors or hints):
116 
117  KMP_INFORM( WillUseDefaultMessages );
118  KMP_WARNING( CantOpenMessageCatalog, name );
119  KMP_FATAL( StackOverlap );
120  KMP_SYSFAIL( "pthread_create", status );
121  KMP_CHECK_SYSFAIL( "pthread_create", status );
122  KMP_CHECK_SYSFAIL_ERRNO( "gettimeofday", status );
123 
124  ------------------------------------------------------------------------------------------------
125 */
126 
127 enum kmp_msg_type {
128  kmp_mt_dummy = 0, // Special type for internal purposes.
129  kmp_mt_mesg = 4, // Primary OpenMP message, could be information, warning, or fatal.
130  kmp_mt_hint = 5, // Hint to the user.
131  kmp_mt_syserr = -1 // System error message.
132 }; // enum kmp_msg_type
133 typedef enum kmp_msg_type kmp_msg_type_t;
134 
135 struct kmp_msg {
136  kmp_msg_type_t type;
137  int num;
138  char const * str;
139  int len;
140 }; // struct kmp_message
141 typedef struct kmp_msg kmp_msg_t;
142 
143 // Two special messages.
144 extern kmp_msg_t __kmp_msg_empty; // Can be used in place where message is required syntactically.
145 extern kmp_msg_t __kmp_msg_null; // Denotes the end of variadic list of arguments.
146 
147 // Helper functions. Creates messages either from message catalog or from system. Note: these
148 // functions allocate memory. You should pass created messages to __kmp_msg() function, it will
149 // print messages and destroy them.
150 kmp_msg_t __kmp_msg_format( kmp_i18n_id_t id, ... );
151 kmp_msg_t __kmp_msg_error_code( int code );
152 kmp_msg_t __kmp_msg_error_mesg( char const * mesg );
153 
154 // Helper macros to make calls shorter.
155 #define KMP_MSG( ... ) __kmp_msg_format( kmp_i18n_msg_ ## __VA_ARGS__ )
156 #define KMP_HNT( ... ) __kmp_msg_format( kmp_i18n_hnt_ ## __VA_ARGS__ )
157 #define KMP_SYSERRCODE( code ) __kmp_msg_error_code( code )
158 #define KMP_SYSERRMESG( mesg ) __kmp_msg_error_mesg( mesg )
159 #define KMP_ERR KMP_SYSERRCODE
160 
161 // Message severity.
162 enum kmp_msg_severity {
163  kmp_ms_inform, // Just information for the user.
164  kmp_ms_warning, // Non-fatal error, execution continues.
165  kmp_ms_fatal // Fatal error, program aborts.
166 }; // enum kmp_msg_severity
167 typedef enum kmp_msg_severity kmp_msg_severity_t;
168 
169 // Primary function for printing messages for the user. The first message is mandatory. Any number
170 // of system errors and hints may be specified. Argument list must be finished with __kmp_msg_null.
171 void __kmp_msg( kmp_msg_severity_t severity, kmp_msg_t message, ... );
172 
173 // Helper macros to make calls shorter in simple cases.
174 #define KMP_INFORM( ... ) __kmp_msg( kmp_ms_inform, KMP_MSG( __VA_ARGS__ ), __kmp_msg_null )
175 #define KMP_WARNING( ... ) __kmp_msg( kmp_ms_warning, KMP_MSG( __VA_ARGS__ ), __kmp_msg_null )
176 #define KMP_FATAL( ... ) __kmp_msg( kmp_ms_fatal, KMP_MSG( __VA_ARGS__ ), __kmp_msg_null )
177 #define KMP_SYSFAIL( func, error ) \
178  __kmp_msg( \
179  kmp_ms_fatal, \
180  KMP_MSG( FunctionError, func ), \
181  KMP_SYSERRCODE( error ), \
182  __kmp_msg_null \
183  )
184 
185 // Check error, if not zero, generate fatal error message.
186 #define KMP_CHECK_SYSFAIL( func, error ) \
187  { \
188  if ( error ) { \
189  KMP_SYSFAIL( func, error ); \
190  }; \
191  }
192 
193 // Check status, if not zero, generate fatal error message using errno.
194 #define KMP_CHECK_SYSFAIL_ERRNO( func, status ) \
195  { \
196  if ( status != 0 ) { \
197  int error = errno; \
198  KMP_SYSFAIL( func, error ); \
199  }; \
200  }
201 
202 #ifdef KMP_DEBUG
203  void __kmp_i18n_dump_catalog( kmp_str_buf_t * buffer );
204 #endif // KMP_DEBUG
205 
206 #ifdef __cplusplus
207  }; // extern "C"
208 #endif // __cplusplus
209 
210 #endif // KMP_I18N_H
211 
212 // end of file //