diff options
Diffstat (limited to 'mbglib/common/mbgerror.c')
| -rwxr-xr-x | mbglib/common/mbgerror.c | 204 |
1 files changed, 105 insertions, 99 deletions
diff --git a/mbglib/common/mbgerror.c b/mbglib/common/mbgerror.c index f4bbafa..c3e19e3 100755 --- a/mbglib/common/mbgerror.c +++ b/mbglib/common/mbgerror.c @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgerror.c 1.9 2019/08/26 15:15:10 martin REL_M $ + * $Id: mbgerror.c 1.12 2021/03/16 12:20:57 martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,6 +10,12 @@ * * ----------------------------------------------------------------------- * $Log: mbgerror.c $ + * Revision 1.12 2021/03/16 12:20:57 martin + * Updated some comments. + * Revision 1.11 2021/03/12 12:32:15 martin + * Updated some comments. + * Revision 1.10 2019/11/11 09:43:41 martin + * Tiny doxygen change. * Revision 1.9 2019/08/26 15:15:10 martin * Translate POSIX ENODATA to MBG_ERR_NO_DATA. * Revision 1.8 2019/08/20 08:22:51 martin @@ -162,7 +168,7 @@ typedef struct #if defined( _MBG_TGT_HAS_POSIX_ERRNO ) /** - * @brief Mappings between Meinberg error codes and POSIX error codes + * @brief Mappings between Meinberg error codes and POSIX error codes. * * Always refer to the symbolic names only. The numeric codes listed * in the comments below are just for a quick reference, and may vary @@ -190,7 +196,7 @@ static ERRNO_CNV_ENTRY posix_errno_table[] = { ENOMEM, MBG_ERR_NO_MEM }, // 12, Out of memory (can't allocate memory). { EACCES, MBG_ERR_ACCESS }, // 13, Permission denied (e.g. when trying to access a device without sufficient permissions). { EFAULT, MBG_ERR_BAD_ADDRESS }, // 14, Bad address (e.g. invalid address in a function argument). - // { ENOTBLK, }, // 15, Block device required (eventually no POSIX error, but supported in Linux and *BSD). + // { ENOTBLK, }, // 15, Block device required (possibly not a POSIX error, but supported on Linux and *BSD). { EBUSY, MBG_ERR_BUSY }, // 16, Device or resource busy. { EEXIST, MBG_ERR_EXIST }, // 17, File exists. // { EXDEV, }, // 18, Cross-device link. @@ -223,10 +229,10 @@ static ERRNO_CNV_ENTRY posix_errno_table[] = { ENOTSOCK, MBG_ERR_NOT_A_SOCKET }, // 88, Socket operation on non-socket (file descriptor is not a socket). #endif #if defined( ECONNRESET ) - { ECONNRESET, MBG_ERR_CONN_RESET }, // 104, Connection reset by peer + { ECONNRESET, MBG_ERR_CONN_RESET }, // 104, Connection reset by peer. #endif #if defined( ETIMEDOUT ) - { ETIMEDOUT, MBG_ERR_TIMEOUT }, // 110, Connection timed out + { ETIMEDOUT, MBG_ERR_TIMEOUT }, // 110, Connection timed out. #endif { 0, 0 } // end-of-table identifier @@ -241,10 +247,10 @@ static ERRNO_CNV_ENTRY posix_errno_table[] = static ERRNO_CNV_ENTRY posix_h_errno_table[] = { // POSIX codes taken from Linux netdb.h - { HOST_NOT_FOUND, MBG_ERR_HOST_NOT_FOUND }, // The specified host is unknown - // { NO_ADDRESS, }, // Usually same numeric value as NO_DATA - // { NO_DATA, }, // The requested name is valid but does not have an IP address - // { NO_RECOVERY, }, // A nonrecoverable name server error occurred + { HOST_NOT_FOUND, MBG_ERR_HOST_NOT_FOUND }, // The specified host is unknown. + // { NO_ADDRESS, }, // Usually same numeric value as NO_DATA. + // { NO_DATA, }, // The requested name is valid but does not have an IP address. + // { NO_RECOVERY, }, // A nonrecoverable name server error occurred. // { TRY_AGAIN, }, // A temporary error occurred on an authoritative name server. Try again later. { 0, 0 } // end-of-table identifier @@ -320,7 +326,7 @@ static ERRNO_CNV_ENTRY cvi_rs232_error_table[] = #if defined( MBG_TGT_KERNEL ) /** - * @brief Mappings of some NTSTATUS codes to Meinberg error codes + * @brief Mappings of some NTSTATUS codes to Meinberg error codes. * * Kernel space Windows APIs use NTSTATUS codes as return values, * which consist of several bit fields which also provide some severity @@ -410,8 +416,8 @@ static ERRNO_CNV_ENTRY win32_kernel_status_table[] = * - The user space function uses ::win32_sys_err_table to convert this * to a Meinberg error code, which again yields ::MBG_ERR_INV_PARM. * - * @note Eventually it would be possible to defined custom NTSTATUS codes - * in kernel space, e.g. ((NTSTATUS) (0xC0000000 | 0x20000000 | 31)). + * @note It is possible to define custom NTSTATUS codes in kernel space, + * e.g. ((NTSTATUS) (0xC0000000 | 0x20000000 | 31)). * Apparently, such custom error status codes are passed up to user space, * and GetLastError() after the ioctl() call then returns a negative number, * i.e. -31 for the example here. @@ -444,7 +450,7 @@ static ERRNO_CNV_ENTRY mbg_ioctl_to_ntstatus_table[] = #else // Windows user space /** - * @brief Mappings of WIN32 error codes to Meinberg error codes + * @brief Mappings of WIN32 error codes to Meinberg error codes. * * If a WIN32 user space API function encounters an error, * the Windows GetLastError() function has to be called in @@ -500,7 +506,7 @@ static ERRNO_CNV_ENTRY win32_sys_err_table[] = /** - * @brief Mappings of Winsock error codes to Meinberg error codes + * @brief Mappings of Winsock error codes to Meinberg error codes. * * If a Windows socket (Winsock) function encounters an error, * the Windows WSAGetLastError() function has to be called in @@ -597,10 +603,10 @@ static ERRNO_CNV_ENTRY win32_wsa_err_table[] = static /*HDR*/ /** - * @brief Lookup some error code in a conversion table + * @brief Lookup some error code in a conversion table. * - * @param[in] srch_errno The error number to be looked up in the conversion table - * @param[in] tbl A conversion table + * @param[in] srch_errno The error number to be looked up in the conversion table. + * @param[in] tbl A conversion table. * @param[in] dflt_val The code to be returned if no table entry was found. * * @return @ref MBG_ERROR_CODES associated with the original error code, @@ -623,13 +629,13 @@ int lookup_tbl_errno( int srch_errno, const ERRNO_CNV_ENTRY tbl[], int dflt_val /*HDR*/ /** - * @brief Convert one of the @ref MBG_ERROR_CODES to an OS-specific format + * @brief Convert one of the @ref MBG_ERROR_CODES to an OS-specific format. * * @param[in] err_no One of the @ref MBG_ERROR_CODES. * * @see @ref MBG_ERROR_CODES * - * @return An OS-specific error code + * @return An OS-specific error code. */ int mbg_errno_to_os( int err_no ) { @@ -684,11 +690,12 @@ int mbg_errno_to_os( int err_no ) /*HDR*/ /** - * @brief Return an error string associated with the @ref MBG_ERROR_CODES + * @brief Return an error string associated with the @ref MBG_ERROR_CODES. * - * @param[in] mbg_errno One of the @ref MBG_ERROR_CODES + * @param[in] mbg_errno One of the @ref MBG_ERROR_CODES. * - * @return A constant string describing the error, or NULL for unknown error codes + * @return A constant string describing the error, or a generic string + * "Unknown error" for unknown error codes. */ const char *mbg_strerror( int mbg_errno ) { @@ -712,12 +719,12 @@ const char *mbg_strerror( int mbg_errno ) /*HDR*/ /** - * @brief Check if a value is an error code and print an associated error message + * @brief Check if a value is an error code and print an associated error message. * - * @param[in] rc A positive number including ::MBG_SUCCESS, or one of the @ref MBG_ERROR_CODES - * @param[in] what A string indicated what failed + * @param[in] rc A positive number including ::MBG_SUCCESS, or one of the @ref MBG_ERROR_CODES. + * @param[in] what A string indicated what failed. * - * @return true if rc represented an error code, and a message has been printed, else false + * @return @a true if @p rc represented an error code and a message has been printed, else @a false. */ bool mbg_cond_err_msg( int rc, const char *what ) { @@ -729,23 +736,22 @@ bool mbg_cond_err_msg( int rc, const char *what ) /*HDR*/ /** - * @brief Check if a value is an general or a "not supported" error code and print an associated message + * @brief Check if a value is a general or a "not supported" error code, and print an associated message. * - * If rc contains an error code then an error message is printed, and true is returned. + * If @p rc contains an error code, an error message is printed. * - * If the optional parameter string info2 is not NULL then it should contain - * the name of a feature which has been tested before. In this case, if the error - * code is the specific error ::MBG_ERR_NOT_SUPP_BY_DEV then a "not supported" message - * is printed using info2. + * If the error code is ::MBG_ERR_NOT_SUPP_BY_DEV and the optional parameter + * string @p info is not @a NULL, a specific error message is generated. * - * If info2 is NULL, or the error code is not ::MBG_ERR_NOT_SUPP_BY_DEV then the standard - * error message is printed anyway. + * If @p rc contains a different error code, or the optional parameter + * string @p info is @a NULL, a generic error message is generated that + * includes the string from parameter @p what. * - * @param[in] rc A positive number including ::MBG_SUCCESS, or one of the @ref MBG_ERROR_CODES - * @param[in] what A string indicated what failed - * @param[in] info An optional informational string telling what is not supported (may be NULL). + * @param[in] rc A positive number including ::MBG_SUCCESS, or one of the @ref MBG_ERROR_CODES. + * @param[in] what A string indicated what failed. + * @param[in] info An optional informational string telling what is not supported (may be @a NULL). * - * @return true if rc represented an error code, and a message has been printed, else false + * @return @a true if @p rc represented any error code, and a message has been printed, else @a false. */ bool mbg_cond_err_msg_info( int rc, const char *what, const char *info ) { @@ -771,12 +777,12 @@ bool mbg_cond_err_msg_info( int rc, const char *what, const char *info ) /*HDR*/ /** - * @brief Translate an error code from the Labwindows/CVI RS-232 library to one of the @ref MBG_ERROR_CODES + * @brief Translate an error code from the Labwindows/CVI RS-232 library to one of the @ref MBG_ERROR_CODES. * - * @param[in] cvi_rc An error code returned by a CVI RS-232 library function - * @param[in] info An optional informational text string, or NULL + * @param[in] cvi_rc An error code returned by a CVI RS-232 library function. + * @param[in] info An optional informational text string, or @a NULL. * - * @return One of the @ref MBG_ERROR_CODES + * @return One of the @ref MBG_ERROR_CODES. * * @see http://zone.ni.com/reference/en-XX/help/370051V-01/cvi/libref/cvirs232_error_conditions/ */ @@ -803,12 +809,12 @@ int mbg_cvi_rs232_error_to_mbg( int cvi_rc, const char *info ) /*HDR*/ /** - * @brief Translate a Windows NTSTATUS code to one of the @ref MBG_ERROR_CODES + * @brief Translate a Windows NTSTATUS code to one of the @ref MBG_ERROR_CODES. * - * @param[in] st One of the NTSTATUS codes defined in ntstatus.h - * @param[in] info An optional informational text string, or NULL + * @param[in] st One of the NTSTATUS codes defined in ntstatus.h. + * @param[in] info An optional informational text string, or @a NULL. * - * @return One of the @ref MBG_ERROR_CODES + * @return One of the @ref MBG_ERROR_CODES. */ int mbg_win32_ntstatus_to_mbg( NTSTATUS st, const char *info ) { @@ -828,12 +834,12 @@ int mbg_win32_ntstatus_to_mbg( NTSTATUS st, const char *info ) /*HDR*/ /** - * @brief Translate a Windows non-socket API return code to one of the @ref MBG_RETURN_CODES + * @brief Translate a Windows non-socket API return code to one of the @ref MBG_RETURN_CODES. * - * @param[in] win32_sys_rc A Windows non-socket API error code as returned by GetLastError(), or ERROR_SUCCESS. - * @param[in] info An optional informational text string, or NULL. + * @param[in] win32_sys_rc A Windows non-socket API error code as returned by @a GetLastError, or @a ERROR_SUCCESS. + * @param[in] info An optional informational text string, or @a NULL. * - * @return One of the @ref MBG_RETURN_CODES + * @return One of the @ref MBG_RETURN_CODES. */ int mbg_win32_sys_err_to_mbg( DWORD win32_sys_rc, const char *info ) { @@ -858,9 +864,9 @@ int mbg_win32_sys_err_to_mbg( DWORD win32_sys_rc, const char *info ) if ( rc < 0 ) { - // If the error code is negative then this is a user-defined - // error code e.g. returned by an IOCTL call. In this case we - // assume it's one of the + // If the error code is negative, this is a user-defined + // error code e.g. returned by an IOCTL call. In this case + // we assume it's one of the ... goto out; } #endif @@ -885,12 +891,12 @@ out: /*HDR*/ /** - * @brief Translate a Windows socket API error code to one of the @ref MBG_ERROR_CODES + * @brief Translate a Windows socket API error code to one of the @ref MBG_ERROR_CODES. * - * @param[in] wsa_err A Windows socket API error code as returned by WSAGetLastError() - * @param[in] info An optional informational text string, or NULL + * @param[in] wsa_err A Windows socket API error code as returned by @a WSAGetLastError. + * @param[in] info An optional informational text string, or @a NULL. * - * @return One of the @ref MBG_ERROR_CODES + * @return One of the @ref MBG_ERROR_CODES. */ int mbg_win32_wsa_err_to_mbg( int wsa_err, const char *info ) { @@ -918,12 +924,12 @@ int mbg_win32_wsa_err_to_mbg( int wsa_err, const char *info ) /*HDR*/ /** - * @brief Translate a POSIX errno error code to one of the @ref MBG_ERROR_CODES + * @brief Translate a POSIX errno error code to one of the @ref MBG_ERROR_CODES. * - * @param[in] posix_errno A POSIX error code as usually defined in errno.h - * @param[in] info An optional informational text string, or NULL + * @param[in] posix_errno A POSIX error code as usually defined in errno.h. + * @param[in] info An optional informational text string, or @a NULL. * - * @return One of the @ref MBG_ERROR_CODES + * @return One of the @ref MBG_ERROR_CODES. */ int mbg_posix_errno_to_mbg( int posix_errno, const char *info ) { @@ -947,19 +953,19 @@ int mbg_posix_errno_to_mbg( int posix_errno, const char *info ) /*HDR*/ /** - * @brief Translate a POSIX h_errno error code to one of the @ref MBG_ERROR_CODES + * @brief Translate a POSIX h_errno error code to one of the @ref MBG_ERROR_CODES. * * This function is specific to translate error codes returned by - * gethostbyname() and gethostbyaddr(). In case of error these functions - * don't set errno but h_errno to a specific value. + * @a gethostbyname and @a gethostbyaddr. In case of error these functions + * don't set @a errno but @a h_errno to a specific value. * - * The functions gethostbyname() and gethostbyaddr() are obsolete, - * and getaddressinfo() should be used preferably. + * The functions @a gethostbyname and @a gethostbyaddr are obsolete, + * and @a getaddressinfo should be used preferably. * - * @param[in] posix_h_errno An error code as usually defined in netdb.h - * @param[in] info An optional informational text string, or NULL + * @param[in] posix_h_errno An error code as usually defined in netdb.h. + * @param[in] info An optional informational text string, or @a NULL. * - * @return One of the @ref MBG_ERROR_CODES + * @return One of the @ref MBG_ERROR_CODES. */ int mbg_posix_h_errno_to_mbg( int posix_h_errno, const char *info ) { @@ -983,26 +989,26 @@ int mbg_posix_h_errno_to_mbg( int posix_h_errno, const char *info ) /*HDR*/ /** - * @brief Get and translate last error after non-socket function call + * @brief Get and translate last error after non-socket function call. * * Retrieve the "last error" code after a non-socket function has been called * and translate to one of the @ref MBG_ERROR_CODES. * - * On POSIX systems the "last error" code is always stored in errno, but - * e.g. under Windows the "last error" code after a socket function - * has to be retrieved by calling WSAGetLastError(), whereas the "last error" + * On POSIX systems the "last error" code is always stored in @a errno, but + * e.g. on Windows the "last error" code after a socket function + * has to be retrieved by calling @a WSAGetLastError, whereas the "last error" * code from non-socket POSIX-like functions has to be retrieved - * by calling GetLastError(). + * by calling @a GetLastError. * - * @param[in] info An optional informational text string, or NULL + * @param[in] info An optional informational text string, or @a NULL. * - * @return One of the @ref MBG_ERROR_CODES + * @return One of the @ref MBG_ERROR_CODES. */ int mbg_get_last_error( const char *info ) { #if defined( MBG_TGT_WIN32 ) - // Under Windows the "last error" code after a non-socket function + // On Windows the "last error" code after a non-socket function // ("Windows System Errors") has to be retrieved by calling GetLastError(), // whereas the "last error" code from POSIX-like socket functions // ("Windows Sockets Error Codes") has to be retrieved by calling @@ -1029,19 +1035,19 @@ int mbg_get_last_error( const char *info ) /*HDR*/ /** - * @brief Get and translate last error after socket function call + * @brief Get and translate last error after socket function call. * * Retrieve the "last error" code after a socket function has been called * and translate to one of the @ref MBG_ERROR_CODES. * - * On POSIX systems the "last error" code is always stored in errno, but - * e.g. under Windows the "last error" code after a socket function - * has to be retrieved by calling WSAGetLastError, whereas the "last error" - * code from non-socket POSIX-like functions is stored in errno as usual. + * On POSIX systems the "last error" code is always stored in @a errno, but + * e.g. on Windows the "last error" code after a socket function + * has to be retrieved by calling @a WSAGetLastError, whereas the "last error" + * code from non-socket POSIX-like functions is stored in @a errno as usual. * - * @param[in] info An optional informational text string, or NULL + * @param[in] info An optional informational text string, or @a NULL. * - * @return One of the @ref MBG_ERROR_CODES + * @return One of the @ref MBG_ERROR_CODES. */ int mbg_get_last_socket_error( const char *info ) { @@ -1053,7 +1059,7 @@ int mbg_get_last_socket_error( const char *info ) #elif defined( MBG_TGT_WIN32 ) #if !defined( MBG_TGT_KERNEL ) - // Under Windows the "last error" code after a POSIX-like socket + // On Windows the "last error" code after a POSIX-like socket // function ("Windows Sockets Error Code") has to be retrieved // by calling WSAGetLastError(), whereas the "last error" code // after a non-socket function ("Windows System Errors") has @@ -1080,20 +1086,20 @@ int mbg_get_last_socket_error( const char *info ) /*HDR*/ /** - * @brief Retrieve and convert last error after gethostbyname() + * @brief Retrieve and convert last error after gethostbyname(). * * This function is specific to retrieve and translate error codes - * returned by gethostbyname() and gethostbyaddr(). In case of error - * these functions don't set errno but h_errno on POSIX systems, but - * under Windows the error code can be retrieved by WSAGetLastError() + * returned by @a gethostbyname and @a gethostbyaddr. In case of error + * these functions don't set @a errno but @a h_errno on POSIX systems, + * but on Windows the error code can be retrieved by @a WSAGetLastError * as usual. * - * The functions gethostbyname() and gethostbyaddr() are obsolete, - * and getaddressinfo() should be used preferably. + * The functions @a gethostbyname and @a gethostbyaddr are obsolete, + * and @a getaddressinfo should be used preferably. * - * @param[in] info An optional informational text string, or NULL + * @param[in] info An optional informational text string, or @a NULL. * - * @return One of the @ref MBG_ERROR_CODES + * @return One of the @ref MBG_ERROR_CODES. */ int mbg_get_gethostbyname_error( const char *info ) { @@ -1165,14 +1171,14 @@ int mbg_gai_error( int rc, const char *info ) /*HDR*/ /** - * @brief Retrieve and convert last zlib internal error code + * @brief Retrieve and convert last zlib internal error code. * - * @param[in] zlib_error zlib internal error code - * @param[in] info An optional informational text string, or NULL - * @param[in] msg An optional zlib specific error msg, or NULL. - * Struct z_stream contains member msg. + * @param[in] zlib_error zlib internal error code. + * @param[in] info An optional informational text string, or @a NULL. + * @param[in] msg An optional zlib specific error msg, or @a NULL. + * Struct @a z_stream contains member msg. * - * @return One of the @ref MBG_ERROR_CODES + * @return One of the @ref MBG_ERROR_CODES. */ int mbg_zlib_error_to_mbg( int zlib_error, const char *info, const char *msg ) { |