diff options
Diffstat (limited to 'src/H5Emodule.h')
| -rw-r--r-- | src/H5Emodule.h | 478 |
1 files changed, 211 insertions, 267 deletions
diff --git a/src/H5Emodule.h b/src/H5Emodule.h index f2e6d44..5abdb6a 100644 --- a/src/H5Emodule.h +++ b/src/H5Emodule.h @@ -84,24 +84,24 @@ * an error stack ID is needed as a parameter, \ref H5E_DEFAULT can be used to indicate the library’s default * stack. The first error record of the error stack, number #000, is produced by the API function itself and * is usually sufficient to indicate to the application what went wrong. - * <table> - * <caption align=top>Example: An Error Message</caption> - * <tr> - * <td> - * <p>If an application calls \ref H5Tclose on a + * <table> + * <caption align=top>Example: An Error Message</caption> + * <tr> + * <td> + * <p>If an application calls \ref H5Tclose on a * predefined datatype then the following message is * printed on the standard error stream. This is a * simple error that has only one component, the API * function; other errors may have many components. - * <p><code><pre> + * <p><code><pre> * HDF5-DIAG: Error detected in HDF5 (1.10.9) thread 0. * #000: H5T.c line ### in H5Tclose(): predefined datatype * major: Function argument * minor: Bad value - * </pre></code> - * </td> - * </tr> - * </table> + * </pre></code> + * </td> + * </tr> + * </table> * In the example above, we can see that an error record has a major message and a minor message. A major * message generally indicates where the error happens. The location can be a dataset or a dataspace, for * example. A minor message explains further details of the error. An example is “unable to open file”. @@ -152,51 +152,40 @@ * * <em>To see the current settings:</em> * \code - * herr_t H5Eget_auto(hid_t error_stack, H5E_auto_t * func, void **client_data) + * herr_t H5Eget_auto(hid_t error_stack, H5E_auto_t * func, void **client_data) * \endcode * The function above returns the current settings for the automatic error stack traversal function, func, and * its data, client_data. If either or both of the arguments are null, then the value is not returned. * - * <table> - * <caption align=top>Example: Turn off error messages while probing a function</caption> - * <tr> - * <td> - * <p>An application can temporarily turn off error messages while “probing” a function. See the + * An application can temporarily turn off error messages while “probing” a function. See the * example below. - * <p><code><pre> - * *** Save old error handler *** - * H5E_auto2_t oldfunc; - * void *old_client_data; - * H5Eget_auto2(error_stack, &old_func, &old_client_data); - * *** Turn off error handling *** - * H5Eset_auto2(error_stack, NULL, NULL); - * *** Probe. Likely to fail, but that’s okay *** - * status = H5Fopen (......); - * *** Restore previous error handler *** - * H5Eset_auto2(error_stack, old_func, old_client_data); - * </pre></code> - * </td> - * </tr> - * </table> - * - * <table> - * <caption align=top>Example: Disable automatic printing and explicitly print error messages</caption> - * <tr> - * <td> - * <p>Or automatic printing can be disabled altogether and error messages can be explicitly printed. - * <p><code><pre> - * *** Turn off error handling permanently *** - * H5Eset_auto2(error_stack, NULL, NULL); - * *** If failure, print error message *** - * if (H5Fopen (....)<0) { - * H5Eprint2(H5E_DEFAULT, stderr); - * exit (1); - * } - * </pre></code> - * </td> - * </tr> - * </table> * + * <em>Example: Turn off error messages while probing a function</em> + * \code + * *** Save old error handler *** + * H5E_auto2_t oldfunc; + * void *old_client_data; + * H5Eget_auto2(error_stack, &old_func, &old_client_data); + * *** Turn off error handling *** + * H5Eset_auto2(error_stack, NULL, NULL); + * *** Probe. Likely to fail, but that’s okay *** + * status = H5Fopen (......); + * *** Restore previous error handler *** + * H5Eset_auto2(error_stack, old_func, old_client_data); + * \endcode + * + * Or automatic printing can be disabled altogether and error messages can be explicitly printed. + * + * <em>Example: Disable automatic printing and explicitly print error messages</em> + * \code + * *** Turn off error handling permanently *** + * H5Eset_auto2(error_stack, NULL, NULL); + * *** If failure, print error message *** + * if (H5Fopen (....)<0) { + * H5Eprint2(H5E_DEFAULT, stderr); + * exit (1); + * } + * \endcode * * \subsubsection subsubsec_error_ops_custom_print Customized Printing of an Error Stack * Applications are allowed to define an automatic error traversal function other than the default @@ -204,41 +193,28 @@ * the standard error stream and then exits. The first example below defines a such a function. The second * example below installs the function as the error handler. * - * <table> - * <caption align=top>Example: Defining a function to print a simple error message</caption> - * <tr> - * <td> - * <p><code><pre> - * herr_t - * my_hdf5_error_handler(void *unused) - * { - * fprintf (stderr, “An HDF5 error was detected. Bye.\\n”); - * exit (1); - * } - * - * </pre></code> - * </td> - * </tr> - * </table> - * - * <table> - * <caption align=top>Example: The user‐defined error handler</caption> - * <tr> - * <td> - * <p><code><pre> - * H5Eset_auto2(H5E_DEFAULT, my_hdf5_error_handler, NULL); - * </pre></code> - * </td> - * </tr> - * </table> + * <em>Example: Defining a function to print a simple error message</em> + * \code + * herr_t + * my_hdf5_error_handler(void *unused) + * { + * fprintf (stderr, “An HDF5 error was detected. Bye.\\n”); + * exit (1); + * } + * \endcode + * + * <em>Example: The user‐defined error handler</em> + * \code + * H5Eset_auto2(H5E_DEFAULT, my_hdf5_error_handler, NULL); + * \endcode * * \subsubsection subsubsec_error_ops_walk Walk through the Error Stack * The \ref H5Eprint2 function is actually just a wrapper around the more complex \ref H5Ewalk function * which traverses an error stack and calls a user‐defined function for each member of the stack. The example * below shows how \ref H5Ewalk is used. * \code - * herr_t H5Ewalk(hid_t err_stack, H5E_direction_t direction, - * H5E_walk_t func, void *client_data) + * herr_t H5Ewalk(hid_t err_stack, H5E_direction_t direction, + * H5E_walk_t func, void *client_data) * \endcode * The error stack err_stack is traversed and func is called for each member of the stack. Its arguments * are an integer sequence number beginning at zero (regardless of direction) and the client_data @@ -251,62 +227,57 @@ * zero for each traversal, eptr is a pointer to an error stack member, and client_data is the same pointer * used in the example above passed to \ref H5Ewalk. See the example below. * \code - * typedef herr_t (*H5E_walk_t)(unsigned n, H5E_error2_t *eptr, void *client_data) + * typedef herr_t (*H5E_walk_t)(unsigned n, H5E_error2_t *eptr, void *client_data) * \endcode * The H5E_error2_t structure is shown below. * \code - * typedef struct { - * hid_t cls_id; - * hid_t maj_num; - * hid_t min_num; - * unsigned line; - * const char *func_name; - * const char *file_name; - * const char *desc; - * } H5E_error2_t; + * typedef struct { + * hid_t cls_id; + * hid_t maj_num; + * hid_t min_num; + * unsigned line; + * const char *func_name; + * const char *file_name; + * const char *desc; + * } H5E_error2_t; * \endcode * The maj_num and min_num are major and minor error IDs, func_name is the name of the function where * the error was detected, file_name and line locate the error within the HDF5 Library source code, and * desc points to a description of the error. * - * <table> - * <caption align=top>Example: A user‐defined callback function</caption> - * <tr> - * <td> - * <p>The following example shows a user‐defined callback function. - * <p><code><pre> - * \#define MSG_SIZE 64 - * herr_t - * custom_print_cb(unsigned n, const H5E_error2_t *err_desc, void *client_data) - * { - * FILE *stream = (FILE *)client_data; - * char maj[MSG_SIZE]; - * char min[MSG_SIZE]; - * char cls[MSG_SIZE]; - * const int indent = 4; - * - * *** Get descriptions for the major and minor error numbers *** - * if(H5Eget_class_name(err_desc->cls_id, cls, MSG_SIZE) < 0) - * TEST_ERROR; - * if(H5Eget_msg(err_desc->maj_num, NULL, maj, MSG_SIZE) < 0) - * TEST_ERROR; - * if(H5Eget_msg(err_desc->min_num, NULL, min, MSG_SIZE) < 0) - * TEST_ERROR; - * fprintf (stream, “%*serror #%03d: %s in %s(): - * line %u\\n”, - * indent, “”, n, err_desc->file_name, - * err_desc->func_name, err_desc->line); - * fprintf (stream, “%*sclass: %s\\n”, indent*2, “”, cls); - * fprintf (stream, “%*smajor: %s\\n”, indent*2, “”, maj); - * fprintf (stream, “%*sminor: %s\\n”, indent*2, “”, min); - * return 0; - * error: - * return -1; - * } - * </pre></code> - * </td> - * </tr> - * </table> + * The following example shows a user‐defined callback function. + * + * <em>Example: A user‐defined callback function</em> + * \code + * \#define MSG_SIZE 64 + * herr_t + * custom_print_cb(unsigned n, const H5E_error2_t *err_desc, void *client_data) + * { + * FILE *stream = (FILE *)client_data; + * char maj[MSG_SIZE]; + * char min[MSG_SIZE]; + * char cls[MSG_SIZE]; + * const int indent = 4; + * + * *** Get descriptions for the major and minor error numbers *** + * if(H5Eget_class_name(err_desc->cls_id, cls, MSG_SIZE) < 0) + * TEST_ERROR; + * if(H5Eget_msg(err_desc->maj_num, NULL, maj, MSG_SIZE) < 0) + * TEST_ERROR; + * if(H5Eget_msg(err_desc->min_num, NULL, min, MSG_SIZE) < 0) + * TEST_ERROR; + * fprintf (stream, “%*serror #%03d: %s in %s(): + * line %u\\n”, + * indent, “”, n, err_desc->file_name, + * err_desc->func_name, err_desc->line); + * fprintf (stream, “%*sclass: %s\\n”, indent*2, “”, cls); + * fprintf (stream, “%*smajor: %s\\n”, indent*2, “”, maj); + * fprintf (stream, “%*sminor: %s\\n”, indent*2, “”, min); + * return 0; + * error: + * return -1; + * } + * \endcode * * <h4>Programming Note for C++ Developers Using C Functions</h4> * If a C routine that takes a function pointer as an argument is called from within C++ code, the C routine @@ -329,13 +300,13 @@ * to push its own error records onto the error stack once it declares an error class of its own through the * HDF5 Error API. * - * <table> - * <caption align=top>Example: An Error Report</caption> - * <tr> - * <td> - * <p>An error report shows both the library’s error record and the application’s error records. + * <table> + * <caption align=top>Example: An Error Report</caption> + * <tr> + * <td> + * <p>An error report shows both the library’s error record and the application’s error records. * See the example below. - * <p><code><pre> + * <p><code><pre> * Error Test-DIAG: Error detected in Error Program (1.0) * thread 8192: * #000: ../../hdf5/test/error_test.c line ### in main(): @@ -351,10 +322,10 @@ * not a dataset * major: Invalid arguments to routine * minor: Inappropriate type - * </pre></code> - * </td> - * </tr> - * </table> + * </pre></code> + * </td> + * </tr> + * </table> * In the line above error record #002 in the example above, the starting phrase is HDF5. This is the error * class name of the HDF5 Library. All of the library’s error messages (major and minor) are in this default * error class. The Error Test in the beginning of the line above error record #000 is the name of the @@ -365,44 +336,38 @@ * in an error class. An application will have object handles for the error class and for major and minor * messages for further operation. See the example below. * - * <table> - * <caption align=top>Example: The user‐defined error handler</caption> - * <tr> - * <td> - * <p><code><pre> - * \#define MSG_SIZE 64 - * herr_t - * custom_print_cb(unsigned n, const H5E_error2_t *err_desc, - * void* client_data) - * { - * FILE *stream = (FILE *)client_data; - * char maj[MSG_SIZE]; - * char min[MSG_SIZE]; - * char cls[MSG_SIZE]; - * const int indent = 4; - * - * *** Get descriptions for the major and minor error numbers *** - * if(H5Eget_class_name(err_desc->cls_id, cls, MSG_SIZE) < 0) - * TEST_ERROR; - * if(H5Eget_msg(err_desc->maj_num, NULL, maj, MSG_SIZE) < 0) - * TEST_ERROR; - * if(H5Eget_msg(err_desc->min_num, NULL, min, MSG_SIZE) < 0) - * TEST_ERROR; - * fprintf (stream, “%*serror #%03d: %s in %s(): - * line %u\\n”, - * indent, “”, n, err_desc->file_name, - * err_desc->func_name, err_desc->line); - * fprintf (stream, “%*sclass: %s\\n”, indent*2, “”, cls); - * fprintf (stream, “%*smajor: %s\\n”, indent*2, “”, maj); - * fprintf (stream, “%*sminor: %s\\n”, indent*2, “”, min); - * return 0; - * error: - * return -1; - * } - * </pre></code> - * </td> - * </tr> - * </table> + * <em>Example: The user‐defined error handler</em> + * \code + * \#define MSG_SIZE 64 + * herr_t + * custom_print_cb(unsigned n, const H5E_error2_t *err_desc, + * void* client_data) + * { + * FILE *stream = (FILE *)client_data; + * char maj[MSG_SIZE]; + * char min[MSG_SIZE]; + * char cls[MSG_SIZE]; + * const int indent = 4; + * + * *** Get descriptions for the major and minor error numbers *** + * if(H5Eget_class_name(err_desc->cls_id, cls, MSG_SIZE) < 0) + * TEST_ERROR; + * if(H5Eget_msg(err_desc->maj_num, NULL, maj, MSG_SIZE) < 0) + * TEST_ERROR; + * if(H5Eget_msg(err_desc->min_num, NULL, min, MSG_SIZE) < 0) + * TEST_ERROR; + * fprintf (stream, “%*serror #%03d: %s in %s(): + * line %u\\n”, + * indent, “”, n, err_desc->file_name, + * err_desc->func_name, err_desc->line); + * fprintf (stream, “%*sclass: %s\\n”, indent*2, “”, cls); + * fprintf (stream, “%*smajor: %s\\n”, indent*2, “”, maj); + * fprintf (stream, “%*sminor: %s\\n”, indent*2, “”, min); + * return 0; + * error: + * return -1; + * } + * \endcode * * \subsubsection subsubsec_error_adv_more More Error API Functions * The Error API has functions that can be used to register or unregister an error class, to create or close @@ -410,75 +375,64 @@ * * <em>To register an error class:</em> * \code - * hid_t H5Eregister_class(const char* cls_name, const char* lib_name, const char* version) + * hid_t H5Eregister_class(const char* cls_name, const char* lib_name, const char* version) * \endcode * This function registers an error class with the HDF5 Library so that the application library or program * can report errors together with the HDF5 Library. * * <em>To add an error message to an error class:</em> * \code - * hid_t H5Ecreate_msg(hid_t class, H5E_type_t msg_type, const char* mesg) + * hid_t H5Ecreate_msg(hid_t class, H5E_type_t msg_type, const char* mesg) * \endcode * This function adds an error message to an error class defined by an application library or program. The * error message can be either major or minor which is indicated by parameter msg_type. * * <em>To get the name of an error class:</em> * \code - * ssize_t H5Eget_class_name(hid_t class_id, char* name, size_t size) + * ssize_t H5Eget_class_name(hid_t class_id, char* name, size_t size) * \endcode * This function retrieves the name of the error class specified by the class ID. * * <em>To retrieve an error message:</em> * \code - * ssize_t H5Eget_msg(hid_t mesg_id, H5E_type_t* mesg_type, char* mesg, size_t size) + * ssize_t H5Eget_msg(hid_t mesg_id, H5E_type_t* mesg_type, char* mesg, size_t size) * \endcode * This function retrieves the error message including its length and type. * * <em>To close an error message:</em> * \code - * herr_t H5Eclose_msg(hid_t mesg_id) + * herr_t H5Eclose_msg(hid_t mesg_id) * \endcode * This function closes an error message. * * <em>To remove an error class:</em> * \code - * herr_t H5Eunregister_class(hid_t class_id) + * herr_t H5Eunregister_class(hid_t class_id) * \endcode * This function removes an error class from the Error API. * - * <table> - * <caption align=top>Example: Create an error class and error messages</caption> - * <tr> - * <td> - * <p>The example below shows how an application creates an error class and error messages. - * <p><code><pre> - * *** Create an error class *** - * class_id = H5Eregister_class(ERR_CLS_NAME, PROG_NAME, PROG_VERS); - * *** Retrieve class name *** - * H5Eget_class_name(class_id, cls_name, cls_size); - * *** Create a major error message in the class *** - * maj_id = H5Ecreate_msg(class_id, H5E_MAJOR, “... ...”); - * *** Create a minor error message in the class *** - * min_id = H5Ecreate_msg(class_id, H5E_MINOR, “... ...”); - * </pre></code> - * </td> - * </tr> - * </table> - * - * <table> - * <caption align=top>Example: Closing error messages and unregistering the error class</caption> - * <tr> - * <td> - * <p>The example below shows how an application closes error messages and unregisters the error - * class. - * <p><code><pre> - * H5Eclose_msg(maj_id); - * H5Eclose_msg(min_id); - * H5Eunregister_class(class_id); - * </pre></code> - * </td> - * </tr> - * </table> + * The example below shows how an application creates an error class and error messages. + * + * <em>Example: Create an error class and error messages</em> + * \code + * *** Create an error class *** + * class_id = H5Eregister_class(ERR_CLS_NAME, PROG_NAME, PROG_VERS); + * *** Retrieve class name *** + * H5Eget_class_name(class_id, cls_name, cls_size); + * *** Create a major error message in the class *** + * maj_id = H5Ecreate_msg(class_id, H5E_MAJOR, “... ...”); + * *** Create a minor error message in the class *** + * min_id = H5Ecreate_msg(class_id, H5E_MINOR, “... ...”); + * \endcode + * + * The example below shows how an application closes error messages and unregisters the error class. + * + * <em>Example: Closing error messages and unregistering the error class</em> + * \code + * H5Eclose_msg(maj_id); + * H5Eclose_msg(min_id); + * H5Eunregister_class(class_id); + * \endcode * * \subsubsection subsubsec_error_adv_app Pushing an Application Error Message onto Error Stack * An application can push error records onto or pop error records off of the error stack just as the library @@ -487,7 +441,7 @@ * * <em>To register the current stack:</em> * \code - * hid_t H5Eget_current_stack(void) + * hid_t H5Eget_current_stack(void) * \endcode * This function registers the current error stack, returns an object handle, and clears the current error * stack. @@ -495,88 +449,78 @@ * * <em>To replace the current error stack with another:</em> * \code - * herr_t H5Eset_current_stack(hid_t error_stack) + * herr_t H5Eset_current_stack(hid_t error_stack) * \endcode * This function replaces the current error stack with another error stack specified by error_stack and * clears the current error stack. The object handle error_stack is closed after this function call. * * <em>To push a new error record to the error stack:</em> * \code - * herr_t H5Epush(hid_t error_stack, const char* file, const char* func, - * unsigned line, hid_t cls_id, hid_t major_id, hid_t minor_id, - * const char* desc, ... ) + * herr_t H5Epush(hid_t error_stack, const char* file, const char* func, + * unsigned line, hid_t cls_id, hid_t major_id, hid_t minor_id, + * const char* desc, ... ) * \endcode * This function pushes a new error record onto the error stack for the current thread. * * <em>To delete some error messages:</em> * \code - * herr_t H5Epop(hid_t error_stack, size_t count) + * herr_t H5Epop(hid_t error_stack, size_t count) * \endcode * This function deletes some error messages from the error stack. * * <em>To retrieve the number of error records:</em> * \code - * int H5Eget_num(hid_t error_stack) + * int H5Eget_num(hid_t error_stack) * \endcode * This function retrieves the number of error records from an error stack. * * <em>To clear the error stack:</em> * \code - * herr_t H5Eclear_stack(hid_t error_stack) + * herr_t H5Eclear_stack(hid_t error_stack) * \endcode * This function clears the error stack. * * <em>To close the object handle for an error stack:</em> * \code - * herr_t H5Eclose_stack(hid_t error_stack) + * herr_t H5Eclose_stack(hid_t error_stack) * \endcode * This function closes the object handle for an error stack and releases its resources. * - * <table> - * <caption align=top>Example: Pushing an error message to an error stack</caption> - * <tr> - * <td> - * <p>The example below shows how an application pushes an error record onto the default error stack. - * <p><code><pre> - * *** Make call to HDF5 I/O routine *** - * if((dset_id=H5Dopen(file_id, dset_name, access_plist)) < 0) - * { - * *** Push client error onto error stack *** - * H5Epush(H5E_DEFAULT,__FILE__,FUNC,__LINE__,cls_id, - * CLIENT_ERR_MAJ_IO,CLIENT_ERR_MINOR_OPEN, “H5Dopen failed”); - * } - * *** Indicate error occurred in function *** - * return 0; - * </pre></code> - * </td> - * </tr> - * </table> - * - * <table> - * <caption align=top>Example: Registering the error stack</caption> - * <tr> - * <td> - * <p>The example below shows how an application registers the current error stack and - * creates an object handle to avoid another HDF5 function from clearing the error stack. - * <p><code><pre> - * if (H5Dwrite(dset_id, mem_type_id, mem_space_id, file_space_id, dset_xfer_plist_id, buf) < 0) - * { - * *** Push client error onto error stack *** - * H5Epush2(H5E_DEFAULT,__FILE__,FUNC,__LINE__,cls_id, - * CLIENT_ERR_MAJ_IO,CLIENT_ERR_MINOR_HDF5, - * “H5Dwrite failed”); - * *** Preserve the error stack by assigning an object handle to it *** - * error_stack = H5Eget_current_stack(); - * *** Close dataset *** - * H5Dclose(dset_id); - * *** Replace the current error stack with the preserved one *** - * H5Eset_current_stack(error_stack); - * } - * return 0; - * </pre></code> - * </td> - * </tr> - * </table> + * The example below shows how an application pushes an error record onto the default error stack. + * + * <em>Example: Pushing an error message to an error stack</em> + * \code + * *** Make call to HDF5 I/O routine *** + * if((dset_id=H5Dopen(file_id, dset_name, access_plist)) < 0) + * { + * *** Push client error onto error stack *** + * H5Epush(H5E_DEFAULT,__FILE__,FUNC,__LINE__,cls_id, + * CLIENT_ERR_MAJ_IO,CLIENT_ERR_MINOR_OPEN, “H5Dopen failed”); + * } + * *** Indicate error occurred in function *** + * return 0; + * \endcode + * + * The example below shows how an application registers the current error stack and + * creates an object handle to avoid another HDF5 function from clearing the error stack. + * + * <em>Example: Registering the error stack</em> + * \code + * if (H5Dwrite(dset_id, mem_type_id, mem_space_id, file_space_id, dset_xfer_plist_id, buf) < 0) + * { + * *** Push client error onto error stack *** + * H5Epush2(H5E_DEFAULT,__FILE__,FUNC,__LINE__,cls_id, + * CLIENT_ERR_MAJ_IO,CLIENT_ERR_MINOR_HDF5, + * “H5Dwrite failed”); + * *** Preserve the error stack by assigning an object handle to it *** + * error_stack = H5Eget_current_stack(); + * *** Close dataset *** + * H5Dclose(dset_id); + * *** Replace the current error stack with the preserved one *** + * H5Eset_current_stack(error_stack); + * } + * return 0; + * \endcode * * Previous Chapter \ref sec_attribute - Next Chapter \ref sec_plist * |