modules/portlib/src/main/native/port/shared/hyerror.c File Reference

---

Detailed Description

Error Handling.

If an OS system call fails the error code reported by the OS needs to be saved for future reference. The OS error code as well as the corresponding portable error code are stored in the per thread buffers hyportptb.h via a call the hyerror_set_last_error or hyerror_set_last_error_with_message. These functions are meant for private use by the port library, to set the error related to a system call failure. They are in the port library table as people overriding port library functions may need to set the error message accordingly.

The majority of applications are not interested in the human readable error message corresponding to the error. As a result the error message is not stored at time of the reported error, but can be looked up at a later time.

#include <stdlib.h>
#include <string.h>
#include "portpriv.h"
#include "portnls.h"
#include "hyportptb.h"

Functions
I_32 VMCALL	hyerror_startup (struct HyPortLibrary *portLibrary)
	PortLibrary startup.
void VMCALL	hyerror_shutdown (struct HyPortLibrary *portLibrary)
	PortLibrary shutdown.
const char *VMCALL	hyerror_last_error_message (struct HyPortLibrary *portLibrary)
	Error Handling.
I_32 VMCALL	hyerror_last_error_number (struct HyPortLibrary *portLibrary)
	Error Handling.
I_32 VMCALL	hyerror_set_last_error (struct HyPortLibrary *portLibrary, I_32 platformCode, I_32 portableCode)
	Error Handling.
I_32 VMCALL	hyerror_set_last_error_with_message (struct HyPortLibrary *portLibrary, I_32 portableCode, const char *errorMessage)
	Error Handling.

---

Function Documentation

const char* VMCALL hyerror_last_error_message

(

struct HyPortLibrary *

portLibrary

)

Error Handling.

Return the error message as reported by the OS for the last saved error. If no error has been saved then an empty message is returned.

Parameters:

[in]

portLibrary

The port library

Returns:

The error message for the last OS failure, empty message on failure.

I_32 VMCALL hyerror_last_error_number

(

struct HyPortLibrary *

portLibrary

)

Error Handling.

Look up the reason for the last stored failure. If no error code has been stored then failure is returned.

Parameters:

[in]

portLibrary

The port library

Returns:

The negative portable error code on success, 0 on failure.

Note:

Does not clear the reason for the last failure.

I_32 VMCALL hyerror_set_last_error	(	struct HyPortLibrary *	portLibrary,
		I_32	platformCode,
		I_32	portableCode
	)

Error Handling.

Save the platform specific error code and the portable error code for future reference. Once stored an application may obtain the error message describing the last stored error by calling hyerror_last_error_message. Likewise the last portable error code can be obtained by calling hyerror_last_error_number.

Parameters:

[in]	portLibrary	The port library
[in]	platformCode	The error code reported by the OS
[in]	portableCode	The corresponding portable error code as determined by the caller

Returns:

portable error code

Note:

There is no way to access the last platform specific error code.

If per thread buffers

See also:

hyportptb.h are not available the error code is not stored. This event would only occur if the per thread buffers could not be allocated, which is highly unlikely. In this case an application will receive a generic message/errorCode when querying for the last stored values.

I_32 VMCALL hyerror_set_last_error_with_message	(	struct HyPortLibrary *	portLibrary,
		I_32	portableCode,
		const char *	errorMessage
	)

Error Handling.

Save the platform specific error code and the portable error code for future reference. Once stored an application may obtain the error message describing the last stored error by calling hyerror_last_error_message. Likewise the last portable error code can be obtained by calling hyerror_last_error_number.

Parameters:

[in]	portLibrary	The port library
[in]	portableCode	The corresponding portable error code as determined by the caller
[in]	errorMessage	The customized error message to be stored

Returns:

portable error code

Note:

There is no way to access the last platform specific error code.

If per thread buffers

See also:

hyportptb.h are not available the error code is not stored. This event would only occur if the per thread buffers could not be allocated, which is highly unlikely. In this case an application will receive a generic message/errorCode when querying for the last stored values.

void VMCALL hyerror_shutdown

(

struct HyPortLibrary *

portLibrary

)

PortLibrary shutdown.

This function is called during shutdown of the portLibrary. Any resources that were created by hyerror_startup should be destroyed here.

Parameters:

[in]

portLibrary

The port library

Note:

Most implementations will be empty.

I_32 VMCALL hyerror_startup

(

struct HyPortLibrary *

portLibrary

)

PortLibrary startup.

This function is called during startup of the portLibrary. Any resources that are required for the error handling operations may be created here. All resources created here should be destroyed in hyerror_shutdown.

Parameters:

[in]

portLibrary

The port library

Returns:

0 on success, negative error code on failure. Error code values returned are

• HYPORT_ERROR_STARTUP_ERROR

Note:

Most implementations will simply return success.

---