ifx_gl_lc_errno - error value

SYNOPSIS

#include <gls.h>
int ifx_gl_lc_errno(void)

DESCRIPTION

This value, of type int, is used by GLS library functions to indicate more information about an error that has occurred. This value is only set if an error has occurred, unless documented otherwise.

Since any GLS library function can set ifx_gl_lc_errno(), it must be inspected immediately after calling the function in which the error has occurred.

The values stored in ifx_gl_lc_errno() by a particular function are documented in the ERRORS section of that function's description. Certain code set conversion functions are not dependent on a locale, and do not set an errno that is retrievable with ifx_gl_lc_errno. Instead, these functions return a negative error code.

APPLICATION USAGE

To check for errors, an application usually inspects the return value of the function. If the return value is a unique value documented by the function to indicate that an error has occurred, only then does the application check ifx_gl_lc_errno(),
  if ( ifx_gl_mbslen(mbs, n) == -1 )
    switch ( ifx_gl_lc_errno() )
      ...
However, an application can also ignore the function's return value and just check ifx_gl_lc_errno() as long as the application sets ifx_gl_lc_errno() to zero before calling the function,
  ifx_gl_lc_errno() = 0;
  (void) ifx_gl_mbslen(mbs, n);
  if ( ifx_gl_lc_errno() != 0 )
    switch ( ifx_gl_lc_errno() )
      ...
Sometimes this is the only way to determine whether an error has occurred, because some GLS library functions do not return a unique value if an error has occurred. For example, the only way to test whether ifx_gl_ismupper() has detected an illegal multi-byte character is by,
  ifx_gl_lc_errno() = 0;
  value = gl_ismupper(mb, IFX_GL_NO_LIMIT);
  if ( ifx_gl_lc_errno() != 0 )
    switch ( ifx_gl_lc_errno() )
      ...
Setting ifx_gl_lc_errno() to zero and checking it after a function call only works if the processing locale has been initialized correctly with ifx_gl_init(). For example, the following will result in memory fault since the current locale is uninitialized,
  gl_lc_t lc;
  ifx_gl_lc_errno() = 0;    /* A memory fault will happen here */
  (void) ifx_gl_init();
  if ( ifx_gl_lc_errno() != 0 )
    switch ( ifx_gl_lc_errno() )
      ...
In this example, ifx_gl_lc_errno() can only be read or written after ifx_gl_init() has correctly initialized the internal processing locale.

THREAD SAFETY

For multi-threaded applications, this value is stored as a field in the thread control block. For all other applications, it is stored as a field in the locale object.

ACKNOWLEDGEMENT

Portions of this description were derived from the X/Open CAE Specification: "System Interfaces and Headers, Issue 4"; X/Open Document Number: C202; ISBN: 1-872630-47-2; Published by X/Open Company Ltd., U.K.