Sun Microsystems, Inc.
spacerspacer
spacer   www.sun.com docs.sun.com | | |  
spacer
black dot
   
A   B   C   D   E   F   G   H   I   J   K   L   M   N   O   P   Q   R   S   T   U   V   W   X   Y   Z
    
 
Standard C Library Functionssetlocale(3C)


NAME

 setlocale - modify and query a program's locale

SYNOPSIS

 
#include <locale.h>
char *setlocale(int category, const char *locale);

DESCRIPTION

 

The setlocale() function selects the appropriate piece of the program's locale as specified by the category and locale arguments. The category argument may have the following values: LC_CTYPE, LC_NUMERIC, LC_TIME, LC_COLLATE, LC_MONETARY, LC_MESSAGES, and LC_ALL. These names are defined in the <locale.h> header. The LC_ALL variable names all of a program's locale categories.

The LC_CTYPE variable affects the behavior of character handling functions such as isdigit(3C) and tolower(3C), and multibyte character functions such as mbtowc(3C) and wctomb(3C).

The LC_NUMERIC variable affects the decimal point character and thousands separator character for the formatted input/output functions and string conversion functions.

The LC_TIME variable affects the date and time format as delivered by ascftime(3C) cftime(3C) getdate(3C) strftime(3C) and strptime(3C)

The LC_COLLATE variable affects the sort order produced by collating functions such as strcoll (3C) and strxfrm(3C)

The LC_MONETARY variable affects the monetary formatted information returned by localeconv(3C).

The LC_MESSAGES variable affects the behavior of messaging functions such as dgettext(3C), gettext(3C), and gettxt(3C).

A value of "C" for locale specifies the traditional UNIX system behavior. At program startup, the equivalent of

setlocale(LC_ALL, "C")

is executed. This has the effect of initializing each category to the locale described by the environment "C".

A value of "" for locale specifies that the locale should be taken from environment variables. The order in which the environment variables are checked for the various categories is given below:

Category1st Env Var2nd Env Var3rd Env Var
LC_CTYPE:LC_ALLLC_CTYPELANG
LC_COLLATE:LC_ALLLC_COLLATELANG
LC_CTIME:LC_ALLLC_CTIMELANG
LC_NUMERIC:LC_ALLLC_NUMERICLANG
LC_MONETARY:LC_ALLLC_MONETARYLANG
LC_MESSAGES:LC_ALLLC_MESSAGESLANG

If a pointer to a string is given for locale, setlocale() attempts to set the locale for the given category to locale. If setlocale() succeeds, locale is returned. If setlocale() fails, a null pointer is returned and the program's locale is not changed.

For category LC_ALL, the behavior is slightly different. If a pointer to a string is given for locale and LC_ALL is given for category, setlocale() attempts to set the locale for all the categories to locale. The locale may be a simple locale, consisting of a single locale, or a composite locale. If the locales for all the categories are the same after all the attempted locale changes, setlocale() will return a pointer to the common simple locale. If there is a mixture of locales among the categories, setlocale() will return a composite locale.

RETURN VALUES

 

Upon successful completion, setlocale() returns the string associated with the specified category for the new locale. Otherwise, setlocale() returns a null pointer and the program's locale is not changed.

A null pointer for locale causes setlocale() to return a pointer to the string associated with the category for the program's current locale. The program's locale is not changed.

The string returned by setlocale() is such that a subsequent call with that string and its associated category will restore that part of the program's locale. The string returned must not be modified by the program, but may be overwritten by a subsequent call to setlocale().

ERRORS

 

No errors are defined.

FILES

 
/usr/lib/locale/locale
locale database directory for locale

ATTRIBUTES

 

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPEATTRIBUTE VALUE
MT-LevelMT-Safe with exceptions
CSIEnabled

SEE ALSO

 

locale(1), ctype(3C), getdate(3C) gettext(3C), gettxt(3C), isdigit(3C), localeconv(3C), mbtowc(3C), strcoll(3C), strftime(3C), strptime(3C) strxfrm(3C) tolower(3C), wctomb(3C), libc(3LIB), attributes(5), environ(5), locale(5)

NOTES

 

To change locale in a multithreaded application, setlocale() should be called prior to using any locale-sensitive routine. Using setlocale() to query the current locale is safe and can be used anywhere in a multithreaded application.

It is the user's responsibility to ensure that mixed locale categories are compatible. For example, setting LC_CTYPE=C and LC_TIME=ja (where ja indicates Japanese) will not work, because Japanese time cannot be represented in the "C" locale's ASCII codeset.

Internationalization functions by setlocale() are supported only when the dynamic linking version of libc has been linked with the application. If the static linking version of libc has been linked with the application, setlocale() can handle only C and POSIX locales.


SunOS 5.9Go To TopLast Changed 20 Dec 1996

 
      
      
Copyright 2002 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.