setlocale()

select a portion of a program's locale

Synopsis:

#include <locale.h>

char *setlocale( int category, 
                 const char *locale );

Description:

The setlocale() function selects a portion of a program's locale, according to the category given by category and the locale specified by locale. A locale affects the following:

• 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
• the format and names used in the time string produced by the strftime() function

See the function localeconv() for more information about the locale.

Potentially, there may be many such environments. Watcom C/C++ supports only the 'C' locale, and so invoking this function will have no effect on the behavior of a program at present.

The possible values for the argument category are as follows:

LC_ALL

select entire environment

LC_COLLATE

select collating sequence

LC_CTYPE

select the character-handling

LC_MESSAGES

LC_MONETARY

select monetary formatting information

LC_NUMERIC

select the numeric-format environment

LC_TIME

select the time-related environment

At the start of a program, the equivalent of the following statement is executed:

    setlocale( LC_ALL, "C" );

Returns:

If the selection is successful, a string is returned to indicate the locale that was in effect before the function was invoked; otherwise, a NULL pointer is returned.

Examples:

#include <stdio.h>
#include <string.h>
#include <locale.h>

char src[] = { "A sample STRING" };
char dst[20];

void main()
  {
    char *prev_locale;
    size_t len;

    /* set native locale */
    prev_locale = setlocale( LC_ALL, "" );
    printf( "%s\n", prev_locale );
    len = strxfrm( dst, src, 20 );
    printf( "%s (%u)\n", dst, len );
  }

produces the output:

C
A sample STRING (15)

Classification:

ANSI, POSIX 1003.1

See also:

localeconv(), strcoll(), strftime(), strxfrm()