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