source: trunk/man/arm_get_error_message.3 @ 704

.\" Copyright (c) 2005-2008 David Carter <dcarter@arm4.org> and others.
.\" All rights reserved.   This program and the accompanying materials
.\" are made available under the terms of the Eclipse Public License v1.0
.\" which accompanies this distribution, and is available at
.\" http://www.eclipse.org/legal/epl-v10.html
.TH "arm_get_error_message" 3 "August 2008" "arm4.org" "ARM 4 Programmer's Manual"
.SH NAME
arm_get_error_message \- get error message
.SH SYNOPSIS
.B #include <arm4.h>
.sp
\fBarm_error_t
.br
arm_get_error_message( 
.br
    const arm_charset_t \fIcharset\fB,
.br
    const arm_error_t \fIcode\fB, 
.br
    arm_message_buffer_t \fImsg\fB);\fR
.SH DESCRIPTION
\fBarm_get_error_message()\fR stores a string containing an error message for the specified error 
code. 

ARM implementations return values that are specific to the implementation. The only enforced 
convention is that a return code of zero indicates that no errors are reported (though an error 
could have occurred), and a negative return code indicates that some error occurred. Some 
implementations may report an error at times when another implementation would not. 

To help an application developer or administrator understand what a negative error code means, 
\fBarm_get_error_message()\fR can be used to store a string containing an error message for the 
specified error code. The ARM library is not obliged to return a message, even if it returned a 
non-zero return code. 

\fIcharset\fR is an IANA (Internet Assigned Numbers Authority \- see www.iana.org) MIBenum 
value [see \fBarm_is_charset_supported()\fR]. If a non-null message is returned, it will 
be in this encoding. It is strongly recommended that no value be used for \fIcharset\fR 
that has not been tested for support by the library using 
\fBarm_is_charset_supported()\fR.
 
\fIcode\fR is an error code returned as \fBarm_error_t\fR from an API call.
 
\fImsg\fR is a pointer to a buffer that can contain 256 characters (including the termination 
character) into which the null-terminated error message will be copied. The 
message will be in the encoding specified by the \fIcharset\fR parameter. If the 
implementation cannot honor the request, the implementation must store at least the 
null termination character (e.g., which it would do if it does not return a message or 
does not recognize the error code or cannot return the message in the application's 
encoding). The function is ignored if the pointer is null and an error status may be 
returned. 
.SH "RETURN VALUE"
On success, the function returns \fBARM_SUCCESS\fR. A non-zero value indicates
an error.
.SH ERRORS
If the return code is negative, an error occurred. If the return code is not negative, an error may
or may not have occurred - the determination of what is an error and whether an error code is
returned is at the discretion of the ARM implementation. The application can test the return code
if it wants to provide its own error logging.

The following errors are recognized by this implementation, but may not be portable to other implementations:

.TP
.B ARM_FAILURE_NULL_ARGUMENT
The \fImsg\fR must not be null.
.TP
.B ARM_FAILURE_UNSUPPORTED_CHARSET
The \fIcharset\fR requested isn't supported.
.SH "CONFORMING TO"
ARM Issue 4.0 C Language Bindings, Version 2
.SH EXAMPLE
None.
.SH "SEE ALSO"
.BR arm_is_charset_supported (3)