Chapter Contents
Previous
Next
setlocale

setlocale


Select Current Locale

Portability: ISO/ANSI C conforming, POSIX.1 conforming

SYNOPSIS
DESCRIPTION
RETURN VALUE
CAUTIONS
IMPLEMENTATION
EXAMPLE

SYNOPSIS

#include <locale.h>

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

DESCRIPTION

setlocale selects the current locale or a portion thereof, as specified by the category and locale arguments. Here are the valid categories:
LC_ALL names the overall locale.
LC_COLLATE affects the behavior of strcoll and strxfrm .
LC_CTYPE affects the behavior of the character type macros and the multibyte functions.
LC_MONETARY affects the monetary-value formatting information returned by localeconv .
LC_NUMERIC affects the decimal point character used by the I/O and string conversion functions, and the nonmonetary formatting information returned by localeconv .
LC_TIME affects the behavior of strftime .

locale points to a locale_string that has one of the following formats:

In the locale_string formats, xxxx, yyyy, and zzzz have the following meanings:

Any number of category overrides can be specified; however, only the first one per category is honored. Category overrides are honored only when the LC_ALL category is requested or the specific category and the override match. For example, this statement sets only the LC_MONETARY category; the LC_TIME override is ignored. 

setlocale(LC_MONETARY,"C;LC_TIME=SAMP");

When NULL is specified, setlocale returns the current locale string in the same format as described earlier.

If the locale string is specified as "" , the library consults a number of environment variables to determine the appropriate settings. If none of the environment variables are defined, the "C" locale is used.

The locale "" is resolved in the following steps:

  1. If the environment variable LC_ALL is defined and not NULL, the value of LC_ALL is used as the locale.

  2. If a category other than LC_ALL was specified, and there is an environment variable with the same name as the category, the value of that variable is used (if not NULL). For instance, if the category was LC_COLLATE , and the environment variable LC_COLLATE is "DBEX" , then the LC_COLLATE component of the "DBEX" locale is used. Note that if the category is LC_ALL , the effect is the same as if each other category were set independently.

  3. If the environment variable LANG is defined and not NULL, the value of LANG is used as the locale.

  4. If the environment variable _LOCALE is defined and not NULL, the value of _LOCALE is used as the locale.

The first three steps are defined by the POSIX 1003.1 standard; the fourth step is for compatability with previous releases of SAS/C.

RETURN VALUE

setlocale returns the string associated with the specified category value. If the value for locale is not valid or an error occurs when loading the requested locale, setlocale returns NULL and the locale is not affected.

If locale is specified as NULL , setlocale returns the string associated with the category for the current locale and the locale is not affected.

When issuing setlocale for a mixed locale , if a category override fails (for example, if the locale load module cannot be found), then for that category the LC_ALL category is used if it is being set at the same time. Otherwise, a NULL return is issued and the category for which the locale override was requested remains unchanged. The returned string indicates the actual mixed locale in effect.

CAUTIONS

A second call to setlocale overwrites the previous value, so you must save the current value before calling setlocale again, if you need the value later. This involves determining the string length for the locale name, allocating storage space for it, and copying it. The following code does all three: 

char *name;
name = setlocale(LC_ALL, NULL);
name = strsave(name);

When you want to revert to the locale saved in name , use the following code: 

setlocale(LC_ALL, name);

IMPLEMENTATION

Except for the "S370" locale, which is built-in, locale information is kept in a load module created by compiling and linking "S370" source code for the locale's localization data and routines. The load module name is created by appending up to the first four uppercased characters of the locale's name to the "L$CL" prefix. For example, if the locale name is MYLOCALE , the load module name is L$CLMYLO .

The locale load module is loaded when needed (with loadm ) during setlocale processing. For the exact details and requirements on specifying localization data and routines, see User-Added Locales. Also loadm for load module library search and location requirements.

Mixed locale strings can be specified. In this case, all requested locales are loaded by a single call to setlocale .

EXAMPLE

#include <locale.h>

main()
{
char *name;

   /* Set all portions of the current locale to      */
   /* the values defined by the built-in "C" locale. */
setlocale(LC_ALL, "C");

   /* Set the LC_COLLATE category to the value       */
   /* defined by the "DBCS" locale.                  */
setlocale(LC_COLLATE, "DBCS");
   /* Set the LC_CTYPE category to the value         */
   /* defined by the "DBCS" locale.                  */
setlocale(LC_CTYPE, "DBCS");

   /* Set the LC_NUMERIC category to the value       */
   /* defined by the "SAMP" locale.                  */
setlocale(LC_NUMERIC, "SAMP");

   /* Return mixed locale string.                    */
name = setlocale(LC_ALL, NULL);
}

The following string is pointed to by name : 

"C;LC_COLLATE=DBCS;LC_CTYPE=DBCS;LC_NUMERIC=SAMP"

This string is interpreted as if the " C " locale ( LC_ALL ) is in effect except for LC_COLLATE and LC_CTYPE , which have the " DBCS " locale in effect, and LC_NUMERIC , which is using " SAMP ".

The same results can be accomplished with a single call to setlocale : 

#include <locale.h>

void main()
{
char *name;

name = setlocale(LC_ALL,
       "C;LC_COLLATE=DBCS;LC_CTYPE=DBCS;LC_NUMERIC=SAMP");
}


Chapter Contents
Previous
Next
Top of Page

Copyright © 2001 by SAS Institute Inc., Cary, NC, USA. All rights reserved.