usr/src/man/man3c/setlocale.3c

   1 '\" te
   2 .\" Copyright (c) 2007, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" Copyright 1989 AT&T
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH SETLOCALE 3C "Sep 19, 2005"
   8 .SH NAME
   9 setlocale \- modify and query a program's locale
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <locale.h>
  14
  15 \fBchar *\fR\fBsetlocale\fR(\fBint\fR \fIcategory\fR, \fBconst char *\fR\fIlocale\fR);
  16 .fi
  17
  18 .SH DESCRIPTION
  19 .sp
  20 .LP
  21 The \fBsetlocale()\fR function selects the appropriate piece of the program's
  22 locale as specified by the \fIcategory\fR and \fIlocale\fR arguments. The
  23 \fIcategory\fR argument may have the following values: \fBLC_CTYPE\fR,
  24 \fBLC_NUMERIC\fR, \fBLC_TIME\fR, \fBLC_COLLATE\fR, \fBLC_MONETARY\fR,
  25 \fBLC_MESSAGES\fR, and \fBLC_ALL\fR. These names are defined in the
  26 <\fBlocale.h\fR> header.  The \fBLC_ALL\fR variable names all of a program's
  27 locale categories.
  28 .sp
  29 .LP
  30 The \fBLC_CTYPE\fR variable affects the behavior of character handling
  31 functions such as \fBisdigit\fR(3C) and \fBtolower\fR(3C), and multibyte
  32 character functions such as  \fBmbtowc\fR(3C) and \fBwctomb\fR(3C).
  33 .sp
  34 .LP
  35 The \fBLC_NUMERIC\fR variable affects the decimal point character and thousands
  36 separator character for the formatted input/output functions and string
  37 conversion functions.
  38 .sp
  39 .LP
  40 The \fBLC_TIME\fR variable affects the date and time format as delivered by
  41 \fBascftime\fR(3C), \fBcftime\fR(3C), \fBgetdate\fR(3C), \fBstrftime\fR(3C),
  42 and \fBstrptime\fR(3C).
  43 .sp
  44 .LP
  45 The \fBLC_COLLATE\fR variable affects the sort order produced by collating
  46 functions such as \fBstrcoll\fR(3C) and \fBstrxfrm\fR(3C).
  47 .sp
  48 .LP
  49 The \fBLC_MONETARY\fR variable affects the monetary formatted information
  50 returned by \fBlocaleconv\fR(3C).
  51 .sp
  52 .LP
  53 The \fBLC_MESSAGES\fR variable affects the behavior of messaging functions such
  54 as \fBdgettext\fR(3C), \fBgettext\fR(3C), and \fBgettxt\fR(3C).
  55 .sp
  56 .LP
  57 A value of "C" for \fIlocale\fR specifies the traditional \fBUNIX\fR system
  58 behavior. At program startup, the equivalent of
  59 .sp
  60 .LP
  61 \fBsetlocale(LC_ALL, "C")\fR
  62 .sp
  63 .LP
  64 is executed. This has the effect of initializing each category to the locale
  65 described by the environment "C".
  66 .sp
  67 .LP
  68 A value of "" for \fIlocale\fR specifies that the locale should be taken from
  69 environment variables. The order in which the environment variables are checked
  70 for the various categories is given below:
  71 .sp
  72
  73 .sp
  74 .TS
  75 box;
  76 c | c | c | c
  77 l | l | l | l .
  78 Category        1st Env Var     2nd Env Var     3rd Env Var
  79 _
  80 LC_CTYPE:       LC_ALL  LC_CTYPE        LANG
  81 _
  82 LC_COLLATE:     LC_ALL  LC_COLLATE      LANG
  83 _
  84 LC_TIME:        LC_ALL  LC_TIME LANG
  85 _
  86 LC_NUMERIC:     LC_ALL  LC_NUMERIC      LANG
  87 _
  88 LC_MONETARY:    LC_ALL  LC_MONETARY     LANG
  89 _
  90 LC_MESSAGES:    LC_ALL  LC_MESSAGES     LANG
  91 .TE
  92
  93 .sp
  94 .LP
  95 If a pointer to a string is given for \fIlocale\fR, \fBsetlocale()\fR attempts
  96 to set the locale for the given category to \fIlocale\fR. If \fBsetlocale()\fR
  97 succeeds, \fIlocale\fR is returned. If \fBsetlocale()\fR fails, a null pointer
  98 is returned and the program's locale is not changed.
  99 .sp
 100 .LP
 101 For category \fBLC_ALL\fR, the behavior is slightly different. If a pointer to
 102 a string is given for \fIlocale\fR and \fBLC_ALL\fR is given for
 103 \fIcategory\fR, \fBsetlocale()\fR attempts to set the locale for all the
 104 categories to \fIlocale\fR. The \fIlocale\fR may be a simple locale, consisting
 105 of a single locale, or a composite locale. If the locales for all the
 106 categories are the same after all the attempted locale changes,
 107 \fBsetlocale()\fR will return a pointer to the common simple locale. If there
 108 is a mixture of locales among the categories, \fBsetlocale()\fR will return a
 109 composite locale.
 110 .SH RETURN VALUES
 111 .sp
 112 .LP
 113 Upon successful completion, \fBsetlocale()\fR returns the string associated
 114 with the specified category for the new locale. Otherwise, \fBsetlocale()\fR
 115 returns a null pointer and the program's locale is not changed.
 116 .sp
 117 .LP
 118 A null pointer for \fIlocale\fR causes \fBsetlocale()\fR to return a pointer to
 119 the string associated with the \fIcategory\fR for the program's current locale.
 120 The program's locale is not changed.
 121 .sp
 122 .LP
 123 The string returned by \fBsetlocale()\fR is such that a subsequent call with
 124 that string and its associated \fIcategory\fR will restore that part of the
 125 program's locale. The string returned must not be modified by the program, but
 126 may be overwritten by a subsequent call to \fBsetlocale()\fR.
 127 .SH ERRORS
 128 .sp
 129 .LP
 130 No errors are defined.
 131 .SH FILES
 132 .sp
 133 .ne 2
 134 .na
 135 \fB\fB/usr/lib/locale/\fIlocale\fR\fR\fR
 136 .ad
 137 .RS 26n
 138 locale database directory for \fIlocale\fR
 139 .RE
 140
 141 .SH ATTRIBUTES
 142 .sp
 143 .LP
 144 See \fBattributes\fR(5) for descriptions of the following attributes:
 145 .sp
 146
 147 .sp
 148 .TS
 149 box;
 150 c | c
 151 l | l .
 152 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 153 _
 154 CSI     Enabled
 155 _
 156 Interface Stability     Standard
 157 _
 158 MT-Level        MT-Safe with exceptions
 159 .TE
 160
 161 .SH SEE ALSO
 162 .sp
 163 .LP
 164 \fBlocale\fR(1), \fBctype\fR(3C), \fBgetdate\fR(3C) \fBgettext\fR(3C),
 165 \fBgettxt\fR(3C), \fBisdigit\fR(3C), \fBlibc\fR(3LIB), \fBlocaleconv\fR(3C),
 166 \fBmbtowc\fR(3C), \fBstrcoll\fR(3C), \fBstrftime\fR(3C), \fBstrptime\fR(3C)
 167 \fBstrxfrm\fR(3C) \fBtolower\fR(3C), \fBwctomb\fR(3C), \fBattributes\fR(5),
 168 \fBenviron\fR(5), \fBlocale\fR(5), \fBstandards\fR(5)
 169 .SH NOTES
 170 .sp
 171 .LP
 172 It is unsafe for any thread to change locale (by calling \fBsetlocale()\fR with
 173 a non-null locale argument) in a multithreaded application while any other
 174 thread in the application is using any locale-sensitive routine. To change
 175 locale in a multithreaded application, \fBsetlocale()\fR should be called prior
 176 to using any locale-sensitive routine. Using \fBsetlocale()\fR to query the
 177 current locale is safe and can be used anywhere in a multithreaded application
 178 except when some other thread is changing locale.
 179 .sp
 180 .LP
 181 It is the user's responsibility to ensure that mixed locale categories are
 182 compatible. For example, setting \fBLC_CTYPE=C\fR and \fBLC_TIME=ja\fR (where
 183 \fBja\fR indicates Japanese) will not work, because Japanese time cannot be
 184 represented in the "C" locale's ASCII codeset.