1 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 2 * Copyright by The HDF Group. * 3 * Copyright by the Board of Trustees of the University of Illinois. * 4 * All rights reserved. * 5 * * 6 * This file is part of HDF5. The full HDF5 copyright notice, including * 7 * terms governing use, modification, and redistribution, is contained in * 8 * the files COPYING and Copyright.html. COPYING can be found at the root * 9 * of the source code distribution tree; Copyright.html can be found at the * 10 * root level of an installed copy of the electronic HDF5 document set and * 11 * is linked from the top-level documents page. It can also be found at * 12 * http://hdfgroup.org/HDF5/doc/Copyright.html. If you do not have * 13 * access to either file, you may request a copy from help@hdfgroup.org. * 14 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 15 16 /* 17 * This file contains public declarations for the H5E module. 18 */ 19 #ifndef _H5Epublic_H 20 #define _H5Epublic_H 21 22 #include <stdio.h> /*FILE arg of H5Eprint() */ 23 24 /* Public headers needed by this file */ 25 #include "H5public.h" 26 #include "H5Ipublic.h" 27 28 /* Value for the default error stack */ 29 #define H5E_DEFAULT 0 30 31 /* Different kinds of error information */ 32 typedef enum H5E_type_t { 33 H5E_MAJOR, 34 H5E_MINOR 35 } H5E_type_t; 36 37 /* Information about an error; element of error stack */ 38 typedef struct H5E_error2_t { 39 hid_t cls_id; /*class ID */ 40 hid_t maj_num; /*major error ID */ 41 hid_t min_num; /*minor error number */ 42 unsigned line; /*line in file where error occurs */ 43 const char *func_name; /*function in which error occurred */ 44 const char *file_name; /*file in which error occurred */ 45 const char *desc; /*optional supplied description */ 46 } H5E_error2_t; 47 48 /* When this header is included from a private header, don't make calls to H5open() */ 49 #undef H5OPEN 50 #ifndef _H5private_H 51 #define H5OPEN H5open(), 52 #else /* _H5private_H */ 53 #define H5OPEN 54 #endif /* _H5private_H */ 55 56 /* HDF5 error class */ 57 #define H5E_ERR_CLS (H5OPEN H5E_ERR_CLS_g) 58 H5_DLLVAR hid_t H5E_ERR_CLS_g; 59 60 /* Include the automatically generated public header information */ 61 /* (This includes the list of major and minor error codes for the library) */ 62 #include "H5Epubgen.h" 63 64 /* 65 * One often needs to temporarily disable automatic error reporting when 66 * trying something that's likely or expected to fail. The code to try can 67 * be nested between calls to H5Eget_auto() and H5Eset_auto(), but it's 68 * easier just to use this macro like: 69 * H5E_BEGIN_TRY { 70 * ...stuff here that's likely to fail... 71 * } H5E_END_TRY; 72 * 73 * Warning: don't break, return, or longjmp() from the body of the loop or 74 * the error reporting won't be properly restored! 75 * 76 * These two macros still use the old API functions for backward compatibility 77 * purpose. 78 */ 79 #ifndef H5_NO_DEPRECATED_SYMBOLS 80 #define H5E_BEGIN_TRY { \ 81 unsigned H5E_saved_is_v2; \ 82 union { \ 83 H5E_auto1_t efunc1; \ 84 H5E_auto2_t efunc2; \ 85 } H5E_saved; \ 86 void *H5E_saved_edata; \ 87 \ 88 (void)H5Eauto_is_v2(H5E_DEFAULT, &H5E_saved_is_v2); \ 89 if(H5E_saved_is_v2) { \ 90 (void)H5Eget_auto2(H5E_DEFAULT, &H5E_saved.efunc2, &H5E_saved_edata); \ 91 (void)H5Eset_auto2(H5E_DEFAULT, NULL, NULL); \ 92 } else { \ 93 (void)H5Eget_auto1(&H5E_saved.efunc1, &H5E_saved_edata); \ 94 (void)H5Eset_auto1(NULL, NULL); \ 95 } 96 97 #define H5E_END_TRY \ 98 if(H5E_saved_is_v2) \ 99 (void)H5Eset_auto2(H5E_DEFAULT, H5E_saved.efunc2, H5E_saved_edata); \ 100 else \ 101 (void)H5Eset_auto1(H5E_saved.efunc1, H5E_saved_edata); \ 102 } 103 #else /* H5_NO_DEPRECATED_SYMBOLS */ 104 #define H5E_BEGIN_TRY { \ 105 H5E_auto_t saved_efunc; \ 106 void *H5E_saved_edata; \ 107 \ 108 (void)H5Eget_auto(H5E_DEFAULT, &saved_efunc, &H5E_saved_edata); \ 109 (void)H5Eset_auto(H5E_DEFAULT, NULL, NULL); 110 111 #define H5E_END_TRY \ 112 (void)H5Eset_auto(H5E_DEFAULT, saved_efunc, H5E_saved_edata); \ 113 } 114 #endif /* H5_NO_DEPRECATED_SYMBOLS */ 115 116 /* 117 * Public API Convenience Macros for Error reporting - Documented 118 */ 119 /* Use the Standard C __FILE__ & __LINE__ macros instead of typing them in */ 120 #define H5Epush_sim(func, cls, maj, min, str) H5Epush2(H5E_DEFAULT, __FILE__, func, __LINE__, cls, maj, min, str) 121 122 /* 123 * Public API Convenience Macros for Error reporting - Undocumented 124 */ 125 /* Use the Standard C __FILE__ & __LINE__ macros instead of typing them in */ 126 /* And return after pushing error onto stack */ 127 #define H5Epush_ret(func, cls, maj, min, str, ret) { \ 128 H5Epush2(H5E_DEFAULT, __FILE__, func, __LINE__, cls, maj, min, str); \ 129 return(ret); \ 130 } 131 132 /* Use the Standard C __FILE__ & __LINE__ macros instead of typing them in 133 * And goto a label after pushing error onto stack. 134 */ 135 #define H5Epush_goto(func, cls, maj, min, str, label) { \ 136 H5Epush2(H5E_DEFAULT, __FILE__, func, __LINE__, cls, maj, min, str); \ 137 goto label; \ 138 } 139 140 /* Error stack traversal direction */ 141 typedef enum H5E_direction_t { 142 H5E_WALK_UPWARD = 0, /*begin deep, end at API function */ 143 H5E_WALK_DOWNWARD = 1 /*begin at API function, end deep */ 144 } H5E_direction_t; 145 146 147 #ifdef __cplusplus 148 extern "C" { 149 #endif 150 151 /* Error stack traversal callback function pointers */ 152 typedef herr_t (*H5E_walk2_t)(unsigned n, const H5E_error2_t *err_desc, 153 void *client_data); 154 typedef herr_t (*H5E_auto2_t)(hid_t estack, void *client_data); 155 156 /* Public API functions */ 157 H5_DLL hid_t H5Eregister_class(const char *cls_name, const char *lib_name, 158 const char *version); 159 H5_DLL herr_t H5Eunregister_class(hid_t class_id); 160 H5_DLL herr_t H5Eclose_msg(hid_t err_id); 161 H5_DLL hid_t H5Ecreate_msg(hid_t cls, H5E_type_t msg_type, const char *msg); 162 H5_DLL hid_t H5Ecreate_stack(void); 163 H5_DLL hid_t H5Eget_current_stack(void); 164 H5_DLL herr_t H5Eclose_stack(hid_t stack_id); 165 H5_DLL ssize_t H5Eget_class_name(hid_t class_id, char *name, size_t size); 166 H5_DLL herr_t H5Eset_current_stack(hid_t err_stack_id); 167 H5_DLL herr_t H5Epush2(hid_t err_stack, const char *file, const char *func, unsigned line, 168 hid_t cls_id, hid_t maj_id, hid_t min_id, const char *msg, ...); 169 H5_DLL herr_t H5Epop(hid_t err_stack, size_t count); 170 H5_DLL herr_t H5Eprint2(hid_t err_stack, FILE *stream); 171 H5_DLL herr_t H5Ewalk2(hid_t err_stack, H5E_direction_t direction, H5E_walk2_t func, 172 void *client_data); 173 H5_DLL herr_t H5Eget_auto2(hid_t estack_id, H5E_auto2_t *func, void **client_data); 174 H5_DLL herr_t H5Eset_auto2(hid_t estack_id, H5E_auto2_t func, void *client_data); 175 H5_DLL herr_t H5Eclear2(hid_t err_stack); 176 H5_DLL herr_t H5Eauto_is_v2(hid_t err_stack, unsigned *is_stack); 177 H5_DLL ssize_t H5Eget_msg(hid_t msg_id, H5E_type_t *type, char *msg, 178 size_t size); 179 H5_DLL ssize_t H5Eget_num(hid_t error_stack_id); 180 181 182 /* Symbols defined for compatibility with previous versions of the HDF5 API. 183 * 184 * Use of these symbols is deprecated. 185 */ 186 #ifndef H5_NO_DEPRECATED_SYMBOLS 187 188 /* Typedefs */ 189 190 /* Alias major & minor error types to hid_t's, for compatibility with new 191 * error API in v1.8 192 */ 193 typedef hid_t H5E_major_t; 194 typedef hid_t H5E_minor_t; 195 196 /* Information about an error element of error stack. */ 197 typedef struct H5E_error1_t { 198 H5E_major_t maj_num; /*major error number */ 199 H5E_minor_t min_num; /*minor error number */ 200 const char *func_name; /*function in which error occurred */ 201 const char *file_name; /*file in which error occurred */ 202 unsigned line; /*line in file where error occurs */ 203 const char *desc; /*optional supplied description */ 204 } H5E_error1_t; 205 206 /* Error stack traversal callback function pointers */ 207 typedef herr_t (*H5E_walk1_t)(int n, H5E_error1_t *err_desc, void *client_data); 208 typedef herr_t (*H5E_auto1_t)(void *client_data); 209 210 /* Function prototypes */ 211 H5_DLL herr_t H5Eclear1(void); 212 H5_DLL herr_t H5Eget_auto1(H5E_auto1_t *func, void **client_data); 213 H5_DLL herr_t H5Epush1(const char *file, const char *func, unsigned line, 214 H5E_major_t maj, H5E_minor_t min, const char *str); 215 H5_DLL herr_t H5Eprint1(FILE *stream); 216 H5_DLL herr_t H5Eset_auto1(H5E_auto1_t func, void *client_data); 217 H5_DLL herr_t H5Ewalk1(H5E_direction_t direction, H5E_walk1_t func, 218 void *client_data); 219 H5_DLL char *H5Eget_major(H5E_major_t maj); 220 H5_DLL char *H5Eget_minor(H5E_minor_t min); 221 #endif /* H5_NO_DEPRECATED_SYMBOLS */ 222 223 #ifdef __cplusplus 224 } 225 #endif 226 227 #endif /* end _H5Epublic_H */ 228 229