Novell Doc: NDK: Libraries for C (LibC), Volume 2

Syntax

  #include <locale.h> 
   
  char *setlocale_r (
     int             category,
     const char     *locale,
     struct lconv   *lconv,
     char           *buffer);

Parameters

category

(IN) Specifies the environment category for the specified locale.

Flag	Value	Description
LC_CTYPE	0	Select the character handling (unsupported)
LC_COLLATE	1	Select collating sequence (unsupported)
LC_NUMERIC	2	Select the numeric-format environment
LC_MONETARY	3	Select the monetary-format environment
LC_TIME	4	Select the time-related environment
LC_MESSAGES	5	Select the message-related environment (unsupported)
LC_ALL	6	Select the entire environment

locale

(IN) Points to the locale for the program. Pass a NULL pointer to query the current locale for the information specified by the category parameter.

lconv

(IN/OUT) Points to the address of a locale convention structure supplied by the caller. When this call returns, this structure contains the description of the locale currently in force.

buffer

(OUT) Points to a buffer to hold result of this call. This is the same information as a pointer to which is returned by setlocale except that, as a reentrant function, this buffer is supplied by the caller instead of being one that subsequent calls by this or other threads could contaminate.

Return Values

If successful, returns the string associated with the specified category for the new locale. Otherwise, returns a NULL pointer.

Remarks

The setlocale_r function selects a portion of a locale for a program according to the category given by the category parameter and the locale specified by the locale parameter.

A locale might affect the collating sequence (the order in which characters compare with one another), the way in which certain character-handling functions operate, the decimal-point character that is used in formatted input/output and string conversion, and the format and names used in the time string produced by the strftime function.

The semantics of the setlocale_r function, just as for its non-reentrant companion setlocale, can be confusing because this function is able both to query and to set aspects of the invoking process’ locale.

Querying the Locale

To query the locale setting, pass NULL for the locale parameter. When category is LC_ALL, the return is the name of the locale definition currently in force ("C", "en-us", "fr-fr", "cn-cn", etc.).

However, if category is one of the other possible values, this function returns a pointer to a string containing the currently associated definitions for the category. The expression of these definitions is not portable (nor do ISO/IEC or ANSI require that it be). The string returned in the buffer parameter can be modified for use in changing the behavior of a locale.

Setting the Locale

If the locale argument is a pointer to a character string containing correct definitions for items of category, those items will be modified in the current locale. This operation changes the locale for all threads of a process (or virtual machine), but not for any other process running on the NetWare server.

In the case where category is LC_ALL, only the following strings are valid for the locale parameter:

"POSIX". Specifies the minimal environment for C-language translation called the POSIX locale. Each NLM starting up is set to the POSIX locale when main() is invoked.
"C". Is the ANSI/ISO name of the default locale (also known as "POSIX".) "C", "en-us", and "POSIX" are one and the same. "C" is what is returned from setlocale for category LC_ALL and a NULL second argument unless and until setlocale is called with a different locale name.
A valid locale name. Specifies a locale, such as "fr-fr" or "en-us". The list of valid locale names is in flux. In the nls directory on the NetWare boot partition (c:\nwserver\nls), a set of table files with the .xml extension establish what is valid. The format of the string is a two letter language code, followed by a dash, followed by a two letter country code. These .xml files are also included in the LibC SDK download and, in a default installation, are placed in the c:\novell\ndk\libc\tables directory.
NULL. Directs setlocale to query the current internationalized environment and returns the name of the locale in force.

setlocale_r