plibsys
Typedefs | Functions
perror.h File Reference

Error report system. More...

#include <pmacros.h>
#include <ptypes.h>
#include <perrortypes.h>
Include dependency graph for perror.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs

typedef typedefP_BEGIN_DECLS struct PError_ PError
 Opaque data structure for an error object. More...
 

Functions

P_LIB_API PErrorp_error_new (void)
 Initializes a new empty PError. More...
 
P_LIB_API PErrorp_error_new_literal (pint code, pint native_code, const pchar *message)
 Initializes a new PError with data. More...
 
P_LIB_API const pcharp_error_get_message (PError *error)
 Gets an error message. More...
 
P_LIB_API pint p_error_get_code (PError *error)
 Gets an error code. More...
 
P_LIB_API pint p_error_get_native_code (PError *error)
 Gets a platform native error code, if any. More...
 
P_LIB_API PErrorDomain p_error_get_domain (PError *error)
 Gets an error domain. More...
 
P_LIB_API PErrorp_error_copy (PError *error)
 Creates a copy of a PError object. More...
 
P_LIB_API void p_error_set_error (PError *error, pint code, pint native_code, const pchar *message)
 Sets error data. More...
 
P_LIB_API void p_error_set_error_p (PError **error, pint code, pint native_code, const pchar *message)
 Sets error data through a double pointer. More...
 
P_LIB_API void p_error_set_code (PError *error, pint code)
 Sets an error code. More...
 
P_LIB_API void p_error_set_native_code (PError *error, pint native_code)
 Sets a platform native error code. More...
 
P_LIB_API void p_error_set_message (PError *error, const pchar *message)
 Sets an error message. More...
 
P_LIB_API void p_error_clear (PError *error)
 Clears error data. More...
 
P_LIB_API void p_error_free (PError *error)
 Frees a previously initialized error object. More...
 
P_LIB_API pint p_error_get_last_system (void)
 Gets the last system native error code. More...
 
P_LIB_API pint p_error_get_last_net (void)
 Gets the last network native error code. More...
 
P_LIB_API void p_error_set_last_system (pint code)
 Sets the last system native error code. More...
 
P_LIB_API void p_error_set_last_net (pint code)
 Sets the last network native error code. More...
 

Detailed Description

Error report system.

Author
Alexander Saprykin

An error report system is used to notify a caller about fatal situations during the library API invocation. Usually the sequence is as following:

PError *error = NULL;
...
if (error != NULL) {
...
p_error_free (error);
}

Note that you should not initialize a new PError object before passing the pointer into an API call. Simply initialize it with zero and check the result after. Therefore you need to free memory if an error occurred.

Most operating systems store the last error code of the most system calls in a thread-specific variable. Moreover, Windows stores the error code of the last socket related call in a separate variable. Use p_error_get_last_system() and p_error_set_last_system() to access the last system error code, p_error_get_last_net() and p_error_set_last_net() to access the last network error code.

Typedef Documentation

◆ PError

typedef typedefP_BEGIN_DECLS struct PError_ PError

Opaque data structure for an error object.

Function Documentation

◆ p_error_clear()

P_LIB_API void p_error_clear ( PError error)

Clears error data.

Parameters
errorPError object to clear the data for.
Since
0.0.1
Note
Error code is reseted to 0.

◆ p_error_copy()

P_LIB_API PError* p_error_copy ( PError error)

Creates a copy of a PError object.

Parameters
errorPError object to copy.
Returns
Newly created PError object in case of success, NULL otherwise.
Since
0.0.1
Note
The caller is responsible to free memory of the created object after usage.

◆ p_error_free()

P_LIB_API void p_error_free ( PError error)

Frees a previously initialized error object.

Parameters
errorPError object to free.
Since
0.0.1

◆ p_error_get_code()

P_LIB_API pint p_error_get_code ( PError error)

Gets an error code.

Parameters
errorPError object to get the code from.
Returns
Error code in case of success, 0 otherwise.
Since
0.0.1

◆ p_error_get_domain()

P_LIB_API PErrorDomain p_error_get_domain ( PError error)

Gets an error domain.

Parameters
errorPError object to get the domain from.
Returns
Error domain in case of success, P_ERROR_DOMAIN_NONE otherwise.
Since
0.0.1

◆ p_error_get_last_net()

P_LIB_API pint p_error_get_last_net ( void  )

Gets the last network native error code.

Returns
Last network native error code.
Since
0.0.2
See also
p_error_get_last_system(), p_error_set_last_net(), p_error_set_last_system()

◆ p_error_get_last_system()

P_LIB_API pint p_error_get_last_system ( void  )

Gets the last system native error code.

Returns
Last system native error code.
Since
0.0.2
See also
p_error_get_last_net(), p_error_set_last_system(), p_error_set_last_net()
Note
If you want get an error code for socket-related calls, use p_error_get_last_net() instead.

◆ p_error_get_message()

P_LIB_API const pchar* p_error_get_message ( PError error)

Gets an error message.

Parameters
errorPError object to get the message from.
Returns
Error message in case of success, NULL otherwise.
Since
0.0.1

◆ p_error_get_native_code()

P_LIB_API pint p_error_get_native_code ( PError error)

Gets a platform native error code, if any.

Parameters
errorPError object to get the native code from.
Returns
Error code in case of success, 0 otherwise.
Since
0.0.1
Note
In some situations there can be no native code error, i.e. when an internal library call failed. Do not rely on this code.

◆ p_error_new()

P_LIB_API PError* p_error_new ( void  )

Initializes a new empty PError.

Returns
Newly initialized PError object in case of success, NULL otherwise.
Since
0.0.1

◆ p_error_new_literal()

P_LIB_API PError* p_error_new_literal ( pint  code,
pint  native_code,
const pchar message 
)

Initializes a new PError with data.

Parameters
codeError code.
native_codeNative error code, leave 0 to ignore.
messageError message.
Returns
Newly initialized PError object in case of success, NULL otherwise.
Since
0.0.1

◆ p_error_set_code()

P_LIB_API void p_error_set_code ( PError error,
pint  code 
)

Sets an error code.

Parameters
errorPError object to set the code for.
codeError code.
Since
0.0.1

◆ p_error_set_error()

P_LIB_API void p_error_set_error ( PError error,
pint  code,
pint  native_code,
const pchar message 
)

Sets error data.

Parameters
errorPError object to set the data for.
codeError code.
native_codeNative error code, leave 0 to ignore.
messageError message.
Since
0.0.1

◆ p_error_set_error_p()

P_LIB_API void p_error_set_error_p ( PError **  error,
pint  code,
pint  native_code,
const pchar message 
)

Sets error data through a double pointer.

Parameters
errorPError object to set the data for.
codeError code.
native_codeNative error code, leave 0 to ignore.
messageError message.
Since
0.0.1

If error is NULL it does nothing. If error is not NULL then *error should be NULL, otherwise it does nothing. It creates a PError object, sets error data and assigns it to *error. The caller is responsible to free memory of the created object after usage.

◆ p_error_set_last_net()

P_LIB_API void p_error_set_last_net ( pint  code)

Sets the last network native error code.

Parameters
codeError code to set.
Since
0.0.2
See also
p_error_set_last_system(), p_error_get_last_net(), p_error_get_last_system()

◆ p_error_set_last_system()

P_LIB_API void p_error_set_last_system ( pint  code)

Sets the last system native error code.

Parameters
codeError code to set.
Since
0.0.2
See also
p_error_set_last_net(), p_error_get_last_system(), p_error_get_last_net()
Note
If you want set an error code for socket-related calls, use p_error_set_last_net() instead.

◆ p_error_set_message()

P_LIB_API void p_error_set_message ( PError error,
const pchar message 
)

Sets an error message.

Parameters
errorPError object to set the message for.
messageError message.
Since
0.0.1

◆ p_error_set_native_code()

P_LIB_API void p_error_set_native_code ( PError error,
pint  native_code 
)

Sets a platform native error code.

Parameters
errorPError object to set the native error code for.
native_codePlatform native error code.
Since
0.0.1