DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

setlocale(S)


setlocale -- set or read international environment

Syntax

cc . . . -lc

#include  <locale.h>

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

Description

The function setlocale sets all or part of the current program's locale (definitions of language and conventions). Once invoked, setlocale() immediately updates the information used by the routines that support locale-specific capabilities (for example character and string handling routines, collation, and so on).

The setlocale() function accepts two arguments. The category argument describes the category of international information to set. The following categories (defined in <locale.h>) are recognised:


LC_ALL
Set all categories in the international environment.

LC_COLLATE
Set only the category that contains collating information.

LC_CTYPE
Set only the category that contains character classification and case conversion information.

LC_NUMERIC
Set only the category that contains numeric formatting information.

LC_MESSAGES
Set only the category that contains message language information.

LC_MONETARY
Set only the category that contains currency formatting information.

LC_TIME
Set only the category that contains date and time formatting information.

The locale argument should be a character string that corresponds to the name of a particular international environment. There are three special locale strings, as follows:

"C" Defines the minimal environment needed for the C programming language.
"" (Null string) Specifies that the locale is set to be the implementation-defined native environment which may be affected by the /etc/defaults/lang file, the LANG environment variable, or any of the LC_ environment variables. (See environ(M)).
(char *) 0 (Null pointer) Used to query the current locale for a specific category.

 "C"          Defines the minimal environment needed
              for the C programming language.
 ""           (Null string) Specifies that the locale
              is set to be the implementation-defined
              native environment which may be affected
              by the /etc/defaults/lang file, the LANG
              environment variable, or any of the LC_
              environment variables.  (See environ(M)
 (char *) 0   (Null pointer) Used to query the current
              locale for a specific category.

Other strings use the same format as the user environment variables (see environ(M)).

setlocale() may be used to query the current locale. This is done by calling setlocale() with a null pointer (that is, (char *)0) as the locale argument. setlocale() returns the current locale associated with this category and the program's locale is not changed.

If setlocale() is unable to successfully set the locale for any category, the active locale is unchanged. If the failing call was for the category LC_ALL, all subcategories which could be set are changed; only those which could not be set remain as before.

Return value

If successful, setlocale() returns the locale name string associated with the locale just set. On error, setlocale() returns a null pointer.

When a null pointer is given as the locale, setlocale() returns the locale name string of the current locale. If the individual categories differ at all, and the specified category is LC_ALL, then an expanded locale name string is returned containing the information for each category.

The name string returned by setlocale() is such that a subsequent call to setlocale() with that locale name string and its associated category restores that part of the program's locale.

When a locale is partially defined and does not have a corresponding entry in the file /etc/default/lang, the following error message is displayed:

   libc: setlocale: xxxx: no LANG= line in /etc/default/lang
where xxxx is one of the environment variables found in environ(M). For example, LC_CTYPE.

When a locale is inaccurately defined, the following error message is displayed:

   libc: setlocale: xxxx: cannot open locale file
where xxxx is one of the environment variables found in environ(M). For example, LC_CTYPE.

Notes

The return values from setlocale() are pointers to static data, the content of which is overwritten with each call.

See also

strcoll(S), ctime(S), ctype(S), environ(M), locale(M)

Standards conformance

setlocale() is conformant with:

ANSI X3.159-1989 Programming Language -- C ;
IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C Language] (ISO/IEC 9945-1) ;
and NIST FIPS 151-1 .


© 2003 Caldera International, Inc. All rights reserved.
SCO OpenServer Release 5.0.7 -- 11 February 2003