EIC code displayed by LXR |
|
|
|
|||
File indexing completed on 2025-04-18 09:16:02
0001 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 0002 * Copyright by The HDF Group. * 0003 * All rights reserved. * 0004 * * 0005 * This file is part of HDF5. The full HDF5 copyright notice, including * 0006 * terms governing use, modification, and redistribution, is contained in * 0007 * the COPYING file, which can be found at the root of the source code * 0008 * distribution tree, or in https://www.hdfgroup.org/licenses. * 0009 * If you do not have access to either file, you may request a copy from * 0010 * help@hdfgroup.org. * 0011 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 0012 0013 /* 0014 * This file contains public declarations for the H5E module. 0015 */ 0016 #ifndef H5Epublic_H 0017 #define H5Epublic_H 0018 0019 #include <stdio.h> /* FILE arg of H5Eprint() */ 0020 0021 #include "H5public.h" /* Generic Functions */ 0022 #include "H5Ipublic.h" /* Identifiers */ 0023 0024 /* Value for the default error stack */ 0025 #define H5E_DEFAULT 0 /* (hid_t) */ 0026 0027 /** 0028 * Different kinds of error information 0029 */ 0030 typedef enum H5E_type_t { H5E_MAJOR, H5E_MINOR } H5E_type_t; 0031 0032 /** 0033 * Information about an error; element of error stack 0034 */ 0035 typedef struct H5E_error2_t { 0036 hid_t cls_id; 0037 /**< Class ID */ 0038 hid_t maj_num; 0039 /**< Major error ID */ 0040 hid_t min_num; 0041 /**< Minor error number */ 0042 unsigned line; 0043 /**< Line in file where error occurs */ 0044 const char *func_name; 0045 /**< Function in which error occurred */ 0046 const char *file_name; 0047 /**< File in which error occurred */ 0048 const char *desc; 0049 /**< Optional supplied description */ 0050 } H5E_error2_t; 0051 0052 /* When this header is included from a private header, don't make calls to H5open() */ 0053 #undef H5OPEN 0054 #ifndef H5private_H 0055 #define H5OPEN H5open(), 0056 #else /* H5private_H */ 0057 #define H5OPEN 0058 #endif /* H5private_H */ 0059 0060 /* HDF5 error class */ 0061 /* Extern "C" block needed to compile C++ filter plugins with some compilers */ 0062 #ifdef __cplusplus 0063 extern "C" { 0064 #endif 0065 #define H5E_ERR_CLS (H5OPEN H5E_ERR_CLS_g) 0066 H5_DLLVAR hid_t H5E_ERR_CLS_g; 0067 #ifdef __cplusplus 0068 } 0069 #endif 0070 0071 /* Include the automatically generated public header information */ 0072 /* (This includes the list of major and minor error codes for the library) */ 0073 #include "H5Epubgen.h" 0074 0075 /* 0076 * One often needs to temporarily disable automatic error reporting when 0077 * trying something that's likely or expected to fail. The code to try can 0078 * be nested between calls to H5Eget_auto() and H5Eset_auto(), but it's 0079 * easier just to use this macro like: 0080 * 0081 * H5E_BEGIN_TRY { 0082 * ...stuff here that's likely to fail... 0083 * } H5E_END_TRY 0084 * 0085 * Warning: don't break, return, or longjmp() from the block of code or 0086 * the error reporting won't be properly restored! 0087 * 0088 * These two macros still use the old API functions for backward compatibility 0089 * purpose. 0090 */ 0091 #ifndef H5_NO_DEPRECATED_SYMBOLS 0092 #define H5E_BEGIN_TRY \ 0093 { \ 0094 unsigned H5E_saved_is_v2; \ 0095 union { \ 0096 H5E_auto1_t efunc1; \ 0097 H5E_auto2_t efunc2; \ 0098 } H5E_saved; \ 0099 void *H5E_saved_edata; \ 0100 \ 0101 (void)H5Eauto_is_v2(H5E_DEFAULT, &H5E_saved_is_v2); \ 0102 if (H5E_saved_is_v2) { \ 0103 (void)H5Eget_auto2(H5E_DEFAULT, &H5E_saved.efunc2, &H5E_saved_edata); \ 0104 (void)H5Eset_auto2(H5E_DEFAULT, NULL, NULL); \ 0105 } \ 0106 else { \ 0107 (void)H5Eget_auto1(&H5E_saved.efunc1, &H5E_saved_edata); \ 0108 (void)H5Eset_auto1(NULL, NULL); \ 0109 } 0110 0111 #define H5E_END_TRY \ 0112 if (H5E_saved_is_v2) \ 0113 (void)H5Eset_auto2(H5E_DEFAULT, H5E_saved.efunc2, H5E_saved_edata); \ 0114 else \ 0115 (void)H5Eset_auto1(H5E_saved.efunc1, H5E_saved_edata); \ 0116 } 0117 #else /* H5_NO_DEPRECATED_SYMBOLS */ 0118 #define H5E_BEGIN_TRY \ 0119 { \ 0120 H5E_auto2_t saved_efunc; \ 0121 void *H5E_saved_edata; \ 0122 \ 0123 (void)H5Eget_auto2(H5E_DEFAULT, &saved_efunc, &H5E_saved_edata); \ 0124 (void)H5Eset_auto2(H5E_DEFAULT, NULL, NULL); 0125 0126 #define H5E_END_TRY \ 0127 (void)H5Eset_auto2(H5E_DEFAULT, saved_efunc, H5E_saved_edata); \ 0128 } 0129 #endif /* H5_NO_DEPRECATED_SYMBOLS */ 0130 0131 /* 0132 * Public API Convenience Macros for Error reporting - Documented 0133 */ 0134 /* Use the Standard C __FILE__ & __LINE__ macros instead of typing them in */ 0135 #define H5Epush_sim(func, cls, maj, min, str) \ 0136 H5Epush2(H5E_DEFAULT, __FILE__, func, __LINE__, cls, maj, min, str) 0137 0138 /* 0139 * Public API Convenience Macros for Error reporting - Undocumented 0140 */ 0141 /* Use the Standard C __FILE__ & __LINE__ macros instead of typing them in */ 0142 /* And return after pushing error onto stack */ 0143 #define H5Epush_ret(func, cls, maj, min, str, ret) \ 0144 do { \ 0145 H5Epush2(H5E_DEFAULT, __FILE__, func, __LINE__, cls, maj, min, str); \ 0146 return (ret); \ 0147 } while (0) 0148 0149 /* Use the Standard C __FILE__ & __LINE__ macros instead of typing them in 0150 * And goto a label after pushing error onto stack. 0151 */ 0152 #define H5Epush_goto(func, cls, maj, min, str, label) \ 0153 do { \ 0154 H5Epush2(H5E_DEFAULT, __FILE__, func, __LINE__, cls, maj, min, str); \ 0155 goto label; \ 0156 } while (0) 0157 0158 /** 0159 * Error stack traversal direction 0160 */ 0161 typedef enum H5E_direction_t { 0162 H5E_WALK_UPWARD = 0, /**< begin w/ most specific error, end at API function */ 0163 H5E_WALK_DOWNWARD = 1 /**< begin at API function, end w/ most specific error */ 0164 } H5E_direction_t; 0165 0166 #ifdef __cplusplus 0167 extern "C" { 0168 #endif 0169 0170 /* Error stack traversal callback function pointers */ 0171 //! <!-- [H5E_walk2_t_snip] --> 0172 /** 0173 * \brief Callback function for H5Ewalk2() 0174 * 0175 * \param[in] n Indexed error position in the stack 0176 * \param[in] err_desc Pointer to a data structure describing the error 0177 * \param[in] client_data Pointer to client data in the format expected by the 0178 * user-defined function 0179 * \return \herr_t 0180 * 0181 * \since 1.8.0 0182 * 0183 */ 0184 typedef herr_t (*H5E_walk2_t)(unsigned n, const H5E_error2_t *err_desc, void *client_data); 0185 //! <!-- [H5E_walk2_t_snip] --> 0186 0187 //! <!-- [H5E_auto2_t_snip] --> 0188 /** 0189 * \brief Callback function for H5Eset_auto2() 0190 * 0191 * \estack_id{estack} 0192 * \param[in] client_data Pointer to client data in the format expected by the 0193 * user-defined function 0194 * \return \herr_t 0195 * 0196 * \since 1.8.0 0197 * 0198 */ 0199 typedef herr_t (*H5E_auto2_t)(hid_t estack, void *client_data); 0200 //! <!-- [H5E_auto2_t_snip] --> 0201 0202 /* Public API functions */ 0203 /** 0204 * -------------------------------------------------------------------------- 0205 * \ingroup H5E 0206 * 0207 * \brief Registers a client library or application program to the HDF5 error API 0208 * 0209 * \param[in] cls_name Name of the error class 0210 * \param[in] lib_name Name of the client library or application to which the error class belongs 0211 * \param[in] version Version of the client library or application to which the 0212 error class belongs. It can be \c NULL. 0213 * \return Returns a class identifier on success; otherwise returns H5I_INVALID_ID. 0214 * 0215 * \details H5Eregister_class() registers a client library or application 0216 * program to the HDF5 error API so that the client library or 0217 * application program can report errors together with the HDF5 0218 * library. It receives an identifier for this error class for further 0219 * error operations. The library name and version number will be 0220 * printed out in the error message as a preamble. 0221 * 0222 * \since 1.8.0 0223 */ 0224 H5_DLL hid_t H5Eregister_class(const char *cls_name, const char *lib_name, const char *version); 0225 /** 0226 * -------------------------------------------------------------------------- 0227 * \ingroup H5E 0228 * 0229 * \brief Removes an error class 0230 * 0231 * \param[in] class_id Error class identifier. 0232 * \return \herr_t 0233 * 0234 * \details H5Eunregister_class() removes the error class specified by \p 0235 * class_id. All the major and minor errors in this class will also be 0236 * closed. 0237 * 0238 * \since 1.8.0 0239 */ 0240 H5_DLL herr_t H5Eunregister_class(hid_t class_id); 0241 /** 0242 * -------------------------------------------------------------------------- 0243 * \ingroup H5E 0244 * 0245 * \brief Closes an error message 0246 * 0247 * \param[in] err_id An error message identifier 0248 * \return \herr_t 0249 * 0250 * \details H5Eclose_msg() closes an error message identifier, which can be 0251 * either a major or minor message. 0252 * 0253 * \since 1.8.0 0254 */ 0255 H5_DLL herr_t H5Eclose_msg(hid_t err_id); 0256 /** 0257 * -------------------------------------------------------------------------- 0258 * \ingroup H5E 0259 * 0260 * \brief Adds a major or minor error message to an error class 0261 * 0262 * \param[in] cls An error class identifier 0263 * \param[in] msg_type The type of the error message 0264 * \param[in] msg Error message 0265 * \return An error ID (success), H5I_INVALID_HID (failure) 0266 * 0267 * \details H5Ecreate_msg() adds an error message to an error class defined by 0268 * client library or application program. The error message can be 0269 * either major or minor as indicated by the parameter \p msg_type. 0270 * 0271 * Use H5Eclose_msg() to close the message identifier returned by this 0272 * function. 0273 * 0274 * \since 1.8.0 0275 */ 0276 H5_DLL hid_t H5Ecreate_msg(hid_t cls, H5E_type_t msg_type, const char *msg); 0277 /** 0278 * -------------------------------------------------------------------------- 0279 * \ingroup H5E 0280 * 0281 * \brief Creates a new, empty error stack 0282 * 0283 * \return \hid_ti{error stack} 0284 * 0285 * \details H5Ecreate_stack() creates a new empty error stack and returns the 0286 * new stack's identifier. Use H5Eclose_stack() to close the error stack 0287 * identifier returned by this function. 0288 * 0289 * \since 1.8.0 0290 */ 0291 H5_DLL hid_t H5Ecreate_stack(void); 0292 /** 0293 * -------------------------------------------------------------------------- 0294 * \ingroup H5E 0295 * 0296 * \brief Returns a copy of the current error stack 0297 * 0298 * \return \hid_ti{error stack} 0299 * 0300 * \details H5Eget_current_stack() copies the current error stack and returns an 0301 * error stack identifier for the new copy. 0302 * 0303 * \since 1.8.0 0304 */ 0305 H5_DLL hid_t H5Eget_current_stack(void); 0306 /** 0307 * -------------------------------------------------------------------------- 0308 * \ingroup H5E 0309 * 0310 * \brief Appends one error stack to another, optionally closing the source 0311 * stack. 0312 * 0313 * \estack_id{dst_stack_id} 0314 * \estack_id{src_stack_id} 0315 * \param[in] close_source_stack Flag to indicate whether to close the source stack 0316 * \return \herr_t 0317 * 0318 * \details H5Eappend_stack() appends the messages from error stack 0319 * \p src_stack_id to the error stack \p dst_stack_id. 0320 * If \p close_source_stack is \c true, the source error stack 0321 * will be closed. 0322 * 0323 * \since 1.14.0 0324 */ 0325 H5_DLL herr_t H5Eappend_stack(hid_t dst_stack_id, hid_t src_stack_id, hbool_t close_source_stack); 0326 /** 0327 * -------------------------------------------------------------------------- 0328 * \ingroup H5E 0329 * 0330 * \brief * Check if pushing errors on an error stack is paused 0331 * 0332 * \estack_id{stack_id} 0333 * \param[out] is_paused Flag whether stack is paused 0334 * \return \herr_t 0335 * 0336 * \details H5Eis_paused() can be used within HDF5 VOL connectors and other 0337 * dynamically loaded components to check if the HDF5 library, or other 0338 * component has paused pushing error on the default error stack or 0339 * an application stack. 0340 * 0341 * The library may pause pushing errors on the default error stack 0342 * when performing "speculative" operations, such as testing for the 0343 * existence of something that could be located at one of many 0344 * locations. \p stack_id is the error stack to query, and the value 0345 * pointed to by \p is_paused is set to TRUE/FALSE. 0346 * 0347 * If an error occurs while attempting to query the status of \p stack_id, 0348 * the value pointed to by \p is_paused is unchanged. 0349 * 0350 * \since 1.14.5 0351 */ 0352 H5_DLL herr_t H5Eis_paused(hid_t stack_id, hbool_t *is_paused); 0353 /** 0354 * -------------------------------------------------------------------------- 0355 * \ingroup H5E 0356 * 0357 * \brief * Pause pushing errors on an error stack 0358 * 0359 * \estack_id{stack_id} 0360 * \return \herr_t 0361 * 0362 * \details H5Epause_stack() pauses pushing errors on an error stack. Pushing 0363 * an error on a paused error stack will be ignored (not fail). 0364 * 0365 * H5Eresume_stack() is used to allow errors to be pushed on a stack. 0366 * Calls to H5Epause_stack() and H5Eresume_stack() must be matched. 0367 * 0368 * Calls to H5Epause_stack()/H5Eresume_stack() may be nested. 0369 * 0370 * \since 1.14.5 0371 */ 0372 H5_DLL herr_t H5Epause_stack(hid_t stack_id); 0373 /** 0374 * -------------------------------------------------------------------------- 0375 * \ingroup H5E 0376 * 0377 * \brief * Resume pushing errors on an error stack 0378 * 0379 * \estack_id{stack_id} 0380 * \return \herr_t 0381 * 0382 * \details H5Eresume_stack() resumes pushing errors on an error stack. 0383 * 0384 * Calls to H5Epause_stack() and H5Eresume_stack() must be matched. 0385 * 0386 * Calls to H5Epause_stack()/H5Eresume_stack() may be nested. 0387 * 0388 * \since 1.14.5 0389 */ 0390 H5_DLL herr_t H5Eresume_stack(hid_t stack_id); 0391 /** 0392 * -------------------------------------------------------------------------- 0393 * \ingroup H5E 0394 * 0395 * \brief Closes an error stack handle 0396 * 0397 * \estack_id{stack_id} 0398 * 0399 * \return \herr_t 0400 * 0401 * \details H5Eclose_stack() closes the error stack handle \p stack_id 0402 * and releases its resources. #H5E_DEFAULT cannot be closed. 0403 * 0404 * \since 1.8.0 0405 */ 0406 H5_DLL herr_t H5Eclose_stack(hid_t stack_id); 0407 /** 0408 * -------------------------------------------------------------------------- 0409 * \ingroup H5E 0410 * 0411 * \brief Retrieves error class name 0412 * 0413 * \param[in] class_id Error class identifier 0414 * \param[out] name Buffer for the error class name 0415 * \param[in] size The maximum number of characters of the class name to be returned 0416 * by this function in \p name. 0417 * \return Returns non-negative value as on success; otherwise returns negative value. 0418 * 0419 * \details H5Eget_class_name() retrieves the name of the error class specified 0420 * by the class identifier. If a non-NULL pointer is passed in for \p 0421 * name and \p size is greater than zero, the class name of \p size 0422 * long is returned. The length of the error class name is also 0423 * returned. 0424 * 0425 * \details_namelen{error class,H5Eget_class_name} 0426 * 0427 * If zero is returned, it means the error class has no name. 0428 * 0429 * \since 1.8.0 0430 */ 0431 H5_DLL ssize_t H5Eget_class_name(hid_t class_id, char *name, size_t size); 0432 /** 0433 * -------------------------------------------------------------------------- 0434 * \ingroup H5E 0435 * 0436 * \brief Replaces the current error stack 0437 * 0438 * \estack_id{err_stack_id} 0439 * 0440 * \return \herr_t 0441 * 0442 * \details H5Eset_current_stack() replaces the content of the current error 0443 * stack with a copy of the content of the error stack specified by 0444 * \p err_stack_id, and it closes the error stack specified by 0445 * \p err_stack_id. 0446 * 0447 * \since 1.8.0 0448 */ 0449 H5_DLL herr_t H5Eset_current_stack(hid_t err_stack_id); 0450 /** 0451 * -------------------------------------------------------------------------- 0452 * \ingroup H5E 0453 * 0454 * \brief Pushes a new error record onto an error stack 0455 * 0456 * \estack_id{err_stack}. If the identifier is #H5E_DEFAULT, the error record 0457 * will be pushed to the current stack. 0458 * \param[in] file Name of the file in which the error was detected 0459 * \param[in] func Name of the function in which the error was detected 0460 * \param[in] line Line number in the file where the error was detected 0461 * \param[in] cls_id Error class identifier 0462 * \param[in] maj_id Major error identifier 0463 * \param[in] min_id Minor error identifier 0464 * \param[in] msg Error description string 0465 * \return \herr_t 0466 * 0467 * \details H5Epush2() pushes a new error record onto the error stack specified 0468 * by \p err_stack.\n 0469 * The error record contains the error class identifier \p cls_id, the 0470 * major and minor message identifiers \p maj_id and \p min_id, the 0471 * function name \p func where the error was detected, the file name \p 0472 * file and line number \p line in the file where the error was 0473 * detected, and an error description \p msg.\n 0474 * The major and minor errors must be in the same error class.\n 0475 * The function name, filename, and error description strings must be 0476 * statically allocated.\n 0477 * \p msg can be a format control string with additional 0478 * arguments. This design of appending additional arguments is similar 0479 * to the system and C functions printf() and fprintf(). 0480 * 0481 * \since 1.8.0 0482 */ 0483 H5_DLL herr_t H5Epush2(hid_t err_stack, const char *file, const char *func, unsigned line, hid_t cls_id, 0484 hid_t maj_id, hid_t min_id, const char *msg, ...); 0485 /** 0486 * -------------------------------------------------------------------------- 0487 * \ingroup H5E 0488 * 0489 * \brief Deletes specified number of error messages from the error stack 0490 * 0491 * \estack_id{err_stack} 0492 * \param[in] count The number of error messages to be deleted from the top 0493 * of error stack 0494 * \return \herr_t 0495 * 0496 * \details H5Epop() deletes the number of error records specified in \p count 0497 * from the top of the error stack specified by \p err_stack (including 0498 * major, minor messages and description). The number of error messages 0499 * to be deleted is specified by \p count. 0500 * 0501 * \since 1.8.0 0502 */ 0503 H5_DLL herr_t H5Epop(hid_t err_stack, size_t count); 0504 /** 0505 * -------------------------------------------------------------------------- 0506 * \ingroup H5E 0507 * 0508 * \brief Prints the specified error stack in a default manner 0509 * 0510 * \estack_id{err_stack} 0511 * \param[in] stream File pointer, or \c NULL for \c stderr 0512 * \return \herr_t 0513 * 0514 * \details H5Eprint2() prints the error stack specified by \p err_stack on the 0515 * specified stream, \p stream. Even if the error stack is empty, a 0516 * one-line message of the following form will be printed: 0517 * \code{.unparsed} 0518 * HDF5-DIAG: Error detected in HDF5 library version: 1.5.62 thread 0. 0519 * \endcode 0520 * 0521 * A similar line will appear before the error messages of each error 0522 * class stating the library name, library version number, and thread 0523 * identifier. 0524 * 0525 * If \p err_stack is #H5E_DEFAULT, the current error stack will be 0526 * printed. 0527 * 0528 * H5Eprint2() is a convenience function for H5Ewalk2() with a function 0529 * that prints error messages. Users are encouraged to write their own 0530 * more specific error handlers. 0531 * 0532 * \since 1.8.0 0533 */ 0534 H5_DLL herr_t H5Eprint2(hid_t err_stack, FILE *stream); 0535 /** 0536 * -------------------------------------------------------------------------- 0537 * \ingroup H5E 0538 * 0539 * \brief Walks the specified error stack, calling the specified function 0540 * 0541 * \estack_id{err_stack} 0542 * \param[in] direction Direction in which the error stack is to be walked 0543 * \param[in] func Function to be called for each error encountered 0544 * \param[in] client_data Data to be passed to \p func 0545 * \return \herr_t 0546 * 0547 * \details H5Ewalk2() walks the error stack specified by err_stack for the 0548 * current thread and calls the function specified in \p func for each 0549 * error along the way. 0550 * 0551 * If the value of \p err_stack is #H5E_DEFAULT, then H5Ewalk2() walks 0552 * the current error stack. 0553 * 0554 * \p direction specifies whether the stack is walked from the inside 0555 * out or the outside in. A value of #H5E_WALK_UPWARD means to begin 0556 * with the most specific error and end at the API; a value of 0557 * #H5E_WALK_DOWNWARD means to start at the API and end at the 0558 * innermost function where the error was first detected. 0559 * 0560 * \p func, a function conforming to the #H5E_walk2_t prototype, will 0561 * be called for each error in the error stack. Its arguments will 0562 * include an index number \c n (beginning at zero regardless of stack 0563 * traversal direction), an error stack entry \c err_desc, and the \c 0564 * client_data pointer passed to H5Eprint(). The #H5E_walk2_t prototype 0565 * is as follows: 0566 * \snippet this H5E_walk2_t_snip 0567 * 0568 * \since 1.8.0 0569 */ 0570 H5_DLL herr_t H5Ewalk2(hid_t err_stack, H5E_direction_t direction, H5E_walk2_t func, void *client_data); 0571 /** 0572 * -------------------------------------------------------------------------- 0573 * \ingroup H5E 0574 * 0575 * \brief Returns the settings for the automatic error stack traversal 0576 * function and its data 0577 * 0578 * \estack_id 0579 * \param[out] func The function currently set to be called upon an error condition 0580 * \param[out] client_data Data currently set to be passed to the error function 0581 * \return \herr_t 0582 * 0583 * \details H5Eget_auto2() returns the settings for the automatic error stack 0584 * traversal function, \p func, and its data, \p client_data, that are 0585 * associated with the error stack specified by \p estack_id. 0586 * 0587 * Either or both of the \p func and \p client_data arguments may be 0588 * \c NULL, in which case the value is not returned. 0589 * 0590 * The library initializes its default error stack traversal functions 0591 * to H5Eprint1() and H5Eprint2(). A call to H5Eget_auto2() returns 0592 * H5Eprint2() or the user-defined function passed in through 0593 * H5Eset_auto2(). A call to H5Eget_auto1() returns H5Eprint1() or the 0594 * user-defined function passed in through H5Eset_auto1(). However, if 0595 * the application passes in a user-defined function through 0596 * H5Eset_auto1(), it should call H5Eget_auto1() to query the traversal 0597 * function. If the application passes in a user-defined function 0598 * through H5Eset_auto2(), it should call H5Eget_auto2() to query the 0599 * traversal function. 0600 * 0601 * Mixing the new style and the old style functions will cause a 0602 * failure. For example, if the application sets a user-defined 0603 * old-style traversal function through H5Eset_auto1(), a call to 0604 * H5Eget_auto2() will fail and will indicate that the application has 0605 * mixed H5Eset_auto1() and H5Eget_auto2(). On the other hand, mixing 0606 * H5Eset_auto2() and H5Eget_auto1() will also cause a failure. But if 0607 * the traversal functions are the library's default H5Eprint1() or 0608 * H5Eprint2(), mixing H5Eset_auto1() and H5Eget_auto2() or mixing 0609 * H5Eset_auto2() and H5Eget_auto1() does not fail. 0610 * 0611 * \since 1.8.0 0612 */ 0613 H5_DLL herr_t H5Eget_auto2(hid_t estack_id, H5E_auto2_t *func, void **client_data); 0614 /** 0615 * -------------------------------------------------------------------------- 0616 * \ingroup H5E 0617 * 0618 * \brief Turns automatic error printing on or off 0619 * 0620 * \estack_id 0621 * \param[in] func Function to be called upon an error condition 0622 * \param[in] client_data Data passed to the error function 0623 * \return \herr_t 0624 * 0625 * \details H5Eset_auto2() turns on or off automatic printing of errors for the 0626 * error stack specified with \p estack_id. An \p estack_id value of 0627 * #H5E_DEFAULT indicates the current stack. 0628 * 0629 * When automatic printing is turned on, by the use of a non-null \p func 0630 * pointer, any API function which returns an error indication will 0631 * first call \p func, passing it \p client_data as an argument. 0632 * 0633 * \p func, a function compliant with the #H5E_auto2_t prototype, is 0634 * defined in the H5Epublic.h source code file as: 0635 * \snippet this H5E_auto2_t_snip 0636 * 0637 * When the library is first initialized, the auto printing function is 0638 * set to H5Eprint2() (cast appropriately) and \p client_data is the 0639 * standard error stream pointer, \c stderr. 0640 * 0641 * Automatic stack traversal is always in the #H5E_WALK_DOWNWARD 0642 * direction. 0643 * 0644 * Automatic error printing is turned off with a H5Eset_auto2() call 0645 * with a \c NULL \p func pointer. 0646 * 0647 * \since 1.8.0 0648 */ 0649 H5_DLL herr_t H5Eset_auto2(hid_t estack_id, H5E_auto2_t func, void *client_data); 0650 /** 0651 * -------------------------------------------------------------------------- 0652 * \ingroup H5E 0653 * 0654 * \brief Clears the specified error stack or the error stack for the current thread 0655 * 0656 * \estack_id{err_stack} 0657 * \return \herr_t 0658 * 0659 * \details H5Eclear2() clears the error stack specified by \p err_stack, or, if 0660 * \p err_stack is set to #H5E_DEFAULT, the error stack for the current 0661 * thread. 0662 * 0663 * \p err_stack is an error stack identifier, such as that returned by 0664 * H5Eget_current_stack(). 0665 * 0666 * The current error stack is also cleared whenever an API function is 0667 * called, with certain exceptions (for instance, H5Eprint1() or 0668 * H5Eprint2()). 0669 * 0670 * \since 1.8.0 0671 */ 0672 H5_DLL herr_t H5Eclear2(hid_t err_stack); 0673 /** 0674 * -------------------------------------------------------------------------- 0675 * \ingroup H5E 0676 * 0677 * \brief Determines the type of error stack 0678 * 0679 * \estack_id{err_stack} 0680 * \param[out] is_stack A flag indicating which error stack \c typedef the 0681 * specified error stack conforms to 0682 * 0683 * \return \herr_t 0684 * 0685 * \details H5Eauto_is_v2() determines whether the error auto reporting function 0686 * for an error stack conforms to the #H5E_auto2_t \c typedef or the 0687 * #H5E_auto1_t \c typedef. 0688 * 0689 * The \p is_stack parameter is set to 1 if the error stack conforms to 0690 * #H5E_auto2_t and 0 if it conforms to #H5E_auto1_t. 0691 * 0692 * \since 1.8.0 0693 */ 0694 H5_DLL herr_t H5Eauto_is_v2(hid_t err_stack, unsigned *is_stack); 0695 /** 0696 * -------------------------------------------------------------------------- 0697 * \ingroup H5E 0698 * 0699 * \brief Retrieves an error message 0700 * 0701 * \param[in] msg_id Error message identifier 0702 * \param[out] type The type of the error message. Valid values are #H5E_MAJOR 0703 * and #H5E_MINOR. 0704 * \param[out] msg Error message buffer 0705 * \param[in] size The length of error message to be returned by this function 0706 * \return Returns the size of the error message in bytes on success; otherwise 0707 * returns a negative value. 0708 * 0709 * \details H5Eget_msg() retrieves the error message including its length and 0710 * type. The error message is specified by \p msg_id. The user is 0711 * responsible for passing in sufficient buffer space for the 0712 * message. If \p msg is not NULL and \p size is greater than zero, the 0713 * error message of \p size long is returned. The length of the message 0714 * is also returned. If NULL is passed in as \p msg, only the length 0715 * and type of the message is returned. If the return value is zero, it 0716 * means there is no message. 0717 * 0718 * \since 1.8.0 0719 */ 0720 H5_DLL ssize_t H5Eget_msg(hid_t msg_id, H5E_type_t *type, char *msg, size_t size); 0721 /** 0722 * -------------------------------------------------------------------------- 0723 * \ingroup H5E 0724 * 0725 * \brief Retrieves the number of error messages in an error stack 0726 * 0727 * \estack_id{error_stack_id} 0728 * \return Returns number of error messages in an error stack on 0729 * success; otherwise returns a negative value. 0730 * 0731 * \details H5Eget_num() retrieves the number of error records in the error 0732 * stack specified by \p error_stack_id (including major, minor 0733 * messages and description). 0734 * 0735 * \since 1.8.0 0736 */ 0737 H5_DLL ssize_t H5Eget_num(hid_t error_stack_id); 0738 0739 /* Symbols defined for compatibility with previous versions of the HDF5 API. 0740 * 0741 * Use of these symbols is deprecated. 0742 */ 0743 #ifndef H5_NO_DEPRECATED_SYMBOLS 0744 0745 /* Typedefs */ 0746 0747 /* Alias major & minor error types to hid_t's, for compatibility with new 0748 * error API in v1.8 0749 */ 0750 typedef hid_t H5E_major_t; 0751 typedef hid_t H5E_minor_t; 0752 0753 /** 0754 * Information about an error element of error stack. 0755 */ 0756 typedef struct H5E_error1_t { 0757 H5E_major_t maj_num; /**< major error number */ 0758 H5E_minor_t min_num; /**< minor error number */ 0759 const char *func_name; /**< function in which error occurred */ 0760 const char *file_name; /**< file in which error occurred */ 0761 unsigned line; /**< line in file where error occurs */ 0762 const char *desc; /**< optional supplied description */ 0763 } H5E_error1_t; 0764 0765 /* Error stack traversal callback function pointers */ 0766 //! <!-- [H5E_walk1_t_snip] --> 0767 /** 0768 * \brief Callback function for H5Ewalk1() 0769 * 0770 * \param[in] n Indexed error position in the stack 0771 * \param[in] err_desc Pointer to a data structure describing the error 0772 * \param[in] client_data Pointer to client data in the format expected by the 0773 * user-defined function 0774 * \return \herr_t 0775 * 0776 * \since 1.0.0 0777 * 0778 */ 0779 typedef herr_t (*H5E_walk1_t)(int n, H5E_error1_t *err_desc, void *client_data); 0780 //! <!-- [H5E_walk1_t_snip] --> 0781 0782 //! <!-- [H5E_auto1_t_snip] --> 0783 /** 0784 * \brief Callback function for H5Eset_auto1() 0785 * 0786 * \param[in] client_data Pointer to client data in the format expected by the 0787 * user-defined function 0788 * \return \herr_t 0789 * 0790 * \since 1.0.0 0791 * 0792 */ 0793 typedef herr_t (*H5E_auto1_t)(void *client_data); 0794 //! <!-- [H5E_auto1_t_snip] --> 0795 0796 /* Function prototypes */ 0797 /** 0798 * -------------------------------------------------------------------------- 0799 * \ingroup H5E 0800 * 0801 * \brief Clears the error stack for the current thread 0802 * 0803 * \return \herr_t 0804 * 0805 * \deprecated 1.8.0 Function H5Eclear() renamed to H5Eclear1() and deprecated 0806 * in this release. 0807 * 0808 * \details H5Eclear1() clears the error stack for the current thread.\n 0809 * The stack is also cleared whenever an API function is called, with 0810 * certain exceptions (for instance, H5Eprint1()). 0811 * 0812 * \since 1.0.0 0813 * 0814 */ 0815 H5_DLL herr_t H5Eclear1(void); 0816 /** 0817 * -------------------------------------------------------------------------- 0818 * \ingroup H5E 0819 * 0820 * \brief Returns the current settings for the automatic error stack traversal 0821 * function and its data 0822 * 0823 * \param[out] func Current setting for the function to be called upon an error 0824 * condition 0825 * \param[out] client_data Current setting for the data passed to the error 0826 * function 0827 * \return \herr_t 0828 * 0829 * \deprecated 1.8.0 Function H5Eget_auto() renamed to H5Eget_auto1() and 0830 * deprecated in this release. 0831 * 0832 * \details H5Eget_auto1() returns the current settings for the automatic error 0833 * stack traversal function, \p func, and its data, 0834 * \p client_data. Either or both arguments may be \c NULL, in which case the 0835 * value is not returned. 0836 * 0837 * The library initializes its default error stack traversal functions 0838 * to H5Eprint1() and H5Eprint2(). A call to H5Eget_auto2() returns 0839 * H5Eprint2() or the user-defined function passed in through 0840 * H5Eset_auto2(). A call to H5Eget_auto1() returns H5Eprint1() or the 0841 * user-defined function passed in through H5Eset_auto1(). However, if 0842 * the application passes in a user-defined function through 0843 * H5Eset_auto1(), it should call H5Eget_auto1() to query the traversal 0844 * function. If the application passes in a user-defined function 0845 * through H5Eset_auto2(), it should call H5Eget_auto2() to query the 0846 * traversal function. 0847 * 0848 * Mixing the new style and the old style functions will cause a 0849 * failure. For example, if the application sets a user-defined 0850 * old-style traversal function through H5Eset_auto1(), a call to 0851 * H5Eget_auto2() will fail and will indicate that the application has 0852 * mixed H5Eset_auto1() and H5Eget_auto2(). On the other hand, mixing 0853 * H5Eset_auto2() and H5Eget_auto1() will also cause a failure. But if 0854 * the traversal functions are the library's default H5Eprint1() or 0855 * H5Eprint2(), mixing H5Eset_auto1() and H5Eget_auto2() or mixing 0856 * H5Eset_auto2() and H5Eget_auto1() does not fail. 0857 * 0858 * \since 1.0.0 0859 * 0860 */ 0861 H5_DLL herr_t H5Eget_auto1(H5E_auto1_t *func, void **client_data); 0862 /** 0863 * -------------------------------------------------------------------------- 0864 * \ingroup H5E 0865 * 0866 * \brief Pushes a new error record onto the error stack 0867 * 0868 * \param[in] file Name of the file in which the error was detected 0869 * \param[in] func Name of the function in which the error was detected 0870 * \param[in] line Line number in the file where the error was detected 0871 * \param[in] maj Major error identifier 0872 * \param[in] min Minor error identifier 0873 * \param[in] str Error description string 0874 * \return \herr_t 0875 * 0876 * \deprecated 1.8.0 Function H5Epush() renamed to H5Epush1() and 0877 * deprecated in this release. 0878 * 0879 * \details H5Epush1() pushes a new error record onto the error stack for the 0880 * current thread.\n 0881 * The error has major and minor numbers \p maj_num 0882 * and \p min_num, the function \p func where the error was detected, the 0883 * name of the file \p file where the error was detected, the line \p line 0884 * within that file, and an error description string \p str.\n 0885 * The function name, filename, and error description strings must be statically 0886 * allocated. 0887 * 0888 * \since 1.4.0 0889 */ 0890 H5_DLL herr_t H5Epush1(const char *file, const char *func, unsigned line, H5E_major_t maj, H5E_minor_t min, 0891 const char *str); 0892 /** 0893 * -------------------------------------------------------------------------- 0894 * \ingroup H5E 0895 * 0896 * \brief Prints the current error stack in a default manner 0897 * 0898 * \param[in] stream File pointer, or \c NULL for \c stderr 0899 * \return \herr_t 0900 * 0901 * \deprecated 1.8.0 Function H5Eprint() renamed to H5Eprint1() and 0902 * deprecated in this release. 0903 * 0904 * \details H5Eprint1() prints the error stack for the current thread 0905 * on the specified stream, \p stream. Even if the error stack is empty, a 0906 * one-line message of the following form will be printed: 0907 * \code{.unparsed} 0908 * HDF5-DIAG: Error detected in thread 0. 0909 * \endcode 0910 * H5Eprint1() is a convenience function for H5Ewalk1() with a function 0911 * that prints error messages. Users are encouraged to write their own 0912 * more specific error handlers. 0913 * 0914 * \since 1.0.0 0915 * 0916 */ 0917 H5_DLL herr_t H5Eprint1(FILE *stream); 0918 /** 0919 * -------------------------------------------------------------------------- 0920 * \ingroup H5E 0921 * 0922 * \brief Turns automatic error printing on or off 0923 * 0924 * \param[in] func Function to be called upon an error condition 0925 * \param[in] client_data Data passed to the error function 0926 * \return \herr_t 0927 * 0928 * \deprecated 1.8.0 Function H5Eset_auto() renamed to H5Eset_auto1() and 0929 * deprecated in this release. 0930 * 0931 * \details H5Eset_auto1() turns on or off automatic printing of errors. When 0932 * turned on (non-null \p func pointer), any API function which returns 0933 * an error indication will first call \p func, passing it \p 0934 * client_data as an argument. 0935 * 0936 * \p func, a function conforming to the #H5E_auto1_t prototype, is 0937 * defined in the H5Epublic.h source code file as: 0938 * \snippet this H5E_auto1_t_snip 0939 * 0940 * When the library is first initialized, the auto printing function is 0941 * set to H5Eprint1() (cast appropriately) and \p client_data is the 0942 * standard error stream pointer, \c stderr. 0943 * 0944 * Automatic stack traversal is always in the #H5E_WALK_DOWNWARD 0945 * direction. 0946 * 0947 * \since 1.0.0 0948 * 0949 */ 0950 H5_DLL herr_t H5Eset_auto1(H5E_auto1_t func, void *client_data); 0951 /** 0952 * -------------------------------------------------------------------------- 0953 * \ingroup H5E 0954 * 0955 * \brief Walks the current error stack, calling the specified function 0956 * 0957 * \param[in] direction Direction in which the error stack is to be walked 0958 * \param[in] func Function to be called for each error encountered 0959 * \param[in] client_data Data to be passed to \p func 0960 * \return \herr_t 0961 * 0962 * \deprecated 1.8.0 Function H5Ewalk() renamed to H5Ewalk1() and 0963 * deprecated in this release. 0964 * 0965 * \details H5Ewalk1() walks the error stack for the current thread and calls 0966 * the function specified in \p func for each error along the way. 0967 * 0968 * \p direction specifies whether the stack is walked from the inside 0969 * out or the outside in. A value of #H5E_WALK_UPWARD means to begin 0970 * with the most specific error and end at the API; a value of 0971 * #H5E_WALK_DOWNWARD means to start at the API and end at the 0972 * innermost function where the error was first detected. 0973 * 0974 * \p func, a function conforming to the #H5E_walk1_t prototype, will 0975 * be called for each error in the error stack. Its arguments will 0976 * include an index number \c n (beginning at zero regardless of stack 0977 * traversal direction), an error stack entry \c err_desc, and the \c 0978 * client_data pointer passed to H5Eprint(). The #H5E_walk1_t prototype 0979 * is as follows: 0980 * \snippet this H5E_walk1_t_snip 0981 * 0982 * \since 1.0.0 0983 * 0984 */ 0985 H5_DLL herr_t H5Ewalk1(H5E_direction_t direction, H5E_walk1_t func, void *client_data); 0986 /** 0987 * -------------------------------------------------------------------------- 0988 * \ingroup H5E 0989 * 0990 * \brief Returns a character string describing an error specified by a major 0991 * error number 0992 * 0993 * \param[in] maj Major error number 0994 * \return Pointer to the message (success), or NULL (failure) 0995 * 0996 * \deprecated 1.8.0 Function deprecated in this release. 0997 * 0998 * \details H5Eget_major() returns a constant 0999 * character string that describes the error, given a major error number. 1000 * 1001 * \attention This function returns a dynamically allocated string (\c char 1002 * array). An application calling this function must free the memory 1003 * associated with the return value to prevent a memory leak. 1004 * 1005 * \since 1.0.0 1006 * 1007 */ 1008 H5_DLL char *H5Eget_major(H5E_major_t maj); 1009 /** 1010 * -------------------------------------------------------------------------- 1011 * \ingroup H5E 1012 * 1013 * \brief Returns a character string describing an error specified by a minor 1014 * error number 1015 * 1016 * \param[in] min Minor error number 1017 * \return Pointer to the message (success), or NULL (failure) 1018 * 1019 * \deprecated 1.8.0 Function deprecated and return type changed in this release. 1020 * 1021 * \details H5Eget_minor() returns a constant 1022 * character string that describes the error, given a minor error number. 1023 * 1024 * \attention In the Release 1.8.x series, H5Eget_minor() returns a string of 1025 * dynamic allocated \c char array. An application calling this 1026 * function from an HDF5 library of Release 1.8.0 or later must free 1027 * the memory associated with the return value to prevent a memory 1028 * leak. This is a change from the 1.6.x release series. 1029 * 1030 * \since 1.0.0 1031 * 1032 */ 1033 H5_DLL char *H5Eget_minor(H5E_minor_t min); 1034 #endif /* H5_NO_DEPRECATED_SYMBOLS */ 1035 1036 #ifdef __cplusplus 1037 } 1038 #endif 1039 1040 #endif /* end H5Epublic_H */
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated by the 2.3.7 LXR engine. The LXR team |
|