'\" te .\" Copyright (c) 2007, 2011, Oracle and/or its affiliates. All rights reserved. .\" Copyright 1989 AT&T .TH setlocale 3C "5 May 2011" "SunOS 5.11" "Standard C Library Functions" .SH NAME setlocale \- modify and query a program's locale .SH SYNOPSIS .LP .nf #include \fBchar *\fR\fBsetlocale\fR(\fBint\fR \fIcategory\fR, \fBconst char *\fR\fIlocale\fR); .fi .SH DESCRIPTION .sp .LP The \fBsetlocale()\fR function selects the appropriate piece of the program's locale as specified by the \fIcategory\fR and \fIlocale\fR arguments. The \fIcategory\fR argument may have the following values: \fBLC_CTYPE\fR, \fBLC_NUMERIC\fR, \fBLC_TIME\fR, \fBLC_COLLATE\fR, \fBLC_MONETARY\fR, \fBLC_MESSAGES\fR, and \fBLC_ALL\fR. These names are defined in the <\fBlocale.h\fR> header. The \fBLC_ALL\fR variable names all of a program's locale categories. .sp .LP The \fBLC_CTYPE\fR variable affects the behavior of character handling functions such as \fBisdigit\fR(3C) and \fBtolower\fR(3C), and multibyte character functions such as \fBmbtowc\fR(3C) and \fBwctomb\fR(3C). .sp .LP The \fBLC_NUMERIC\fR variable affects the decimal point character and thousands separator character for the formatted input/output functions and string conversion functions. .sp .LP The \fBLC_TIME\fR variable affects the date and time format as delivered by \fBascftime\fR(3C), \fBcftime\fR(3C), \fBgetdate\fR(3C), \fBstrftime\fR(3C), and \fBstrptime\fR(3C). .sp .LP The \fBLC_COLLATE\fR variable affects the sort order produced by collating functions such as \fBstrcoll\fR(3C) and \fBstrxfrm\fR(3C). .sp .LP The \fBLC_MONETARY\fR variable affects the monetary formatted information returned by \fBlocaleconv\fR(3C). .sp .LP The \fBLC_MESSAGES\fR variable affects the behavior of messaging functions such as \fBdgettext\fR(3C), \fBgettext\fR(3C), and \fBgettxt\fR(3C). .sp .LP A value of "C" for \fIlocale\fR specifies the traditional \fBUNIX\fR system behavior. At program startup, the equivalent of .sp .LP \fBsetlocale(LC_ALL, "C")\fR .sp .LP is executed. This has the effect of initializing each category to the locale described by the environment "C". .sp .LP A value of "" for \fIlocale\fR 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: .sp .sp .TS tab() box; cw(1.38i) |cw(1.38i) |cw(1.38i) |cw(1.38i) lw(1.38i) |lw(1.38i) |lw(1.38i) |lw(1.38i) . Category1st Env Var2nd Env Var3rd Env Var _ LC_CTYPE:LC_ALLLC_CTYPELANG _ LC_COLLATE:LC_ALLLC_COLLATELANG _ LC_TIME:LC_ALLLC_TIMELANG _ LC_NUMERIC:LC_ALLLC_NUMERICLANG _ LC_MONETARY:LC_ALLLC_MONETARYLANG _ LC_MESSAGES:LC_ALLLC_MESSAGESLANG .TE .sp .LP If a pointer to a string is given for \fIlocale\fR, \fBsetlocale()\fR attempts to set the locale for the given category to \fIlocale\fR. If \fBsetlocale()\fR succeeds, \fIlocale\fR is returned. If \fBsetlocale()\fR fails, a null pointer is returned and the program's locale is not changed. .sp .LP For category \fBLC_ALL\fR, the behavior is slightly different. If a pointer to a string is given for \fIlocale\fR and \fBLC_ALL\fR is given for \fIcategory\fR, \fBsetlocale()\fR attempts to set the locale for all the categories to \fIlocale\fR. The \fIlocale\fR 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, \fBsetlocale()\fR will return a pointer to the common simple locale. If there is a mixture of locales among the categories, \fBsetlocale()\fR will return a composite locale. .SH RETURN VALUES .sp .LP Upon successful completion, \fBsetlocale()\fR returns the string associated with the specified category for the new locale. Otherwise, \fBsetlocale()\fR returns a null pointer and the program's locale is not changed. .sp .LP A null pointer for \fIlocale\fR causes \fBsetlocale()\fR to return a pointer to the string associated with the \fIcategory\fR for the program's current locale. The program's locale is not changed. .sp .LP The string returned by \fBsetlocale()\fR is such that a subsequent call with that string and its associated \fIcategory\fR 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 \fBsetlocale()\fR. .SH ERRORS .sp .LP No errors are defined. .SH FILES .sp .ne 2 .mk .na \fB\fB/usr/lib/locale/\fIlocale\fR\fR\fR .ad .RS 26n .rt locale database directory for \fIlocale\fR .RE .SH ATTRIBUTES .sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp .sp .TS tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) . ATTRIBUTE TYPEATTRIBUTE VALUE _ CSIEnabled _ Interface StabilityCommitted _ MT-LevelMT-Safe with exceptions _ StandardSee \fBstandards\fR(5). .TE .SH SEE ALSO .sp .LP \fBlocale\fR(1), \fBctype\fR(3C), \fBgetdate\fR(3C) \fBgettext\fR(3C), \fBgettxt\fR(3C), \fBisdigit\fR(3C), \fBlibc\fR(3LIB), \fBlocalelist\fR(3C), \fBlocalelistfree\fR(3C), \fBlocaleconv\fR(3C), \fBmbtowc\fR(3C), \fBstrcoll\fR(3C), \fBstrftime\fR(3C), \fBstrptime\fR(3C) \fBstrxfrm\fR(3C) \fBtolower\fR(3C), \fBwctomb\fR(3C), \fBattributes\fR(5), \fBenviron\fR(5), \fBlocale\fR(5), \fBlocale_alias\fR(5), \fBstandards\fR(5) .SH NOTES .sp .LP It is unsafe for any thread to change locale (by calling \fBsetlocale()\fR with a non-null locale argument) in a multithreaded application while any other thread in the application is using any locale-sensitive routine. To change locale in a multithreaded application, \fBsetlocale()\fR should be called prior to using any locale-sensitive routine. Using \fBsetlocale()\fR to query the current locale is safe and can be used anywhere in a multithreaded application except when some other thread is changing locale. .sp .LP It is the user's responsibility to ensure that mixed locale categories are compatible. For example, setting \fBLC_CTYPE=C\fR and \fBLC_TIME=ja\fR (where \fBja\fR indicates Japanese) will not work, because Japanese time cannot be represented in the "C" locale's ASCII codeset. .sp .LP To get the list of installed locales, instead of calling \fBsetlocale()\fR over a list of potentially installed locales and checking on the return values, using \fBlocalelist\fR(3C) is recommended. The \fBlocalelist()\fR function does not switch locales and it is more efficient, faster, and fully MT-safe. .sp .LP If a string pointed by locale argument has a locale name that does not yield a usable locale in the current system but it is a locale name alias that is accepted and supported, such name is internally mapped to a corresponding canonical locale name which is then used to locate, load, and return the actual locale defined in the current system. If successful, the return value of the function is the locale name alias. If there is no actual locale for the canonical locale name, obviously, the \fBsetlocale()\fR will fail. The accepted and supported locale name aliases are shown in \fBlocale_alias\fR(5).