man3/setlocale.3

   1 .\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
   2 .\" and Copyright 1999 by Bruno Haible (haible@clisp.cons.org)
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .\" Modified Sat Jul 24 18:20:12 1993 by Rik Faith (faith@cs.unc.edu)
  27 .\" Modified Tue Jul 15 16:49:10 1997 by Andries Brouwer (aeb@cwi.nl)
  28 .\" Modified Sun Jul  4 14:52:16 1999 by Bruno Haible (haible@clisp.cons.org)
  29 .\" Modified Tue Aug 24 17:11:01 1999 by Andries Brouwer (aeb@cwi.nl)
  30 .\" Modified Tue Feb  6 03:31:55 2001 by Andries Brouwer (aeb@cwi.nl)
  31 .\"
  32 .TH SETLOCALE 3  2021-03-22 "GNU" "Linux Programmer's Manual"
  33 .SH NAME
  34 setlocale \- set the current locale
  35 .SH SYNOPSIS
  36 .nf
  37 .B #include <locale.h>
  38 .PP
  39 .BI "char *setlocale(int " category ", const char *" locale );
  40 .fi
  41 .SH DESCRIPTION
  42 The
  43 .BR setlocale ()
  44 function is used to set or query the program's current locale.
  45 .PP
  46 If
  47 .I locale
  48 is not NULL,
  49 the program's current locale is modified according to the arguments.
  50 The argument
  51 .I category
  52 determines which parts of the program's current locale should be modified.
  53 .ad l
  54 .nh
  55 .TS
  56 lB lB
  57 lB lx.
  58 Category        Governs
  59 LC_ALL  All of the locale
  60 LC_ADDRESS      T{
  61 Formatting of addresses and
  62 geography-related items (*)
  63 T}
  64 LC_COLLATE      String collation
  65 LC_CTYPE        Character classification
  66 LC_IDENTIFICATION       T{
  67 Metadata describing the locale (*)
  68 T}
  69 LC_MEASUREMENT  T{
  70 Settings related to measurements
  71 (metric versus US customary) (*)
  72 T}
  73 LC_MESSAGES     T{
  74 Localizable natural-language messages
  75 T}
  76 LC_MONETARY     T{
  77 Formatting of monetary values
  78 T}
  79 LC_NAME T{
  80 Formatting of salutations for persons (*)
  81 T}
  82 LC_NUMERIC      T{
  83 Formatting of nonmonetary numeric values
  84 T}
  85 LC_PAPER        T{
  86 Settings related to the standard paper size (*)
  87 T}
  88 LC_TELEPHONE    T{
  89 Formats to be used with telephone services (*)
  90 T}
  91 LC_TIME T{
  92 Formatting of date and time values
  93 T}
  94 .TE
  95 .hy
  96 .ad
  97 .PP
  98 The categories marked with an asterisk in the above table
  99 are GNU extensions.
 100 For further information on these locale categories, see
 101 .BR locale (7).
 102 .PP
 103 The argument
 104 .I locale
 105 is a pointer to a character string containing the
 106 required setting of
 107 .IR category .
 108 Such a string is either a well-known constant like "C" or "da_DK"
 109 (see below), or an opaque string that was returned by another call of
 110 .BR setlocale ().
 111 .PP
 112 If
 113 .I locale
 114 is an empty string,
 115 .BR """""" ,
 116 each part of the locale that should be modified is set according to the
 117 environment variables.
 118 The details are implementation-dependent.
 119 For glibc, first (regardless of
 120 .IR category ),
 121 the environment variable
 122 .B LC_ALL
 123 is inspected,
 124 next the environment variable with the same name as the category
 125 (see the table above),
 126 and finally the environment variable
 127 .BR LANG .
 128 The first existing environment variable is used.
 129 If its value is not a valid locale specification, the locale
 130 is unchanged, and
 131 .BR setlocale ()
 132 returns NULL.
 133 .PP
 134 The locale
 135 .B """C"""
 136 or
 137 .B """POSIX"""
 138 is a portable locale;
 139 it exists on all conforming systems.
 140 .PP
 141 A locale name is typically of the form
 142 .IR language "[_" territory "][." codeset "][@" modifier "],"
 143 where
 144 .I language
 145 is an ISO 639 language code,
 146 .I territory
 147 is an ISO 3166 country code, and
 148 .I codeset
 149 is a character set or encoding identifier like
 150 .B "ISO\-8859\-1"
 151 or
 152 .BR "UTF\-8" .
 153 For a list of all supported locales, try "locale \-a" (see
 154 .BR locale (1)).
 155 .PP
 156 If
 157 .I locale
 158 is NULL, the current locale is only queried, not modified.
 159 .PP
 160 On startup of the main program, the portable
 161 .B """C"""
 162 locale is selected as default.
 163 A program may be made portable to all locales by calling:
 164 .PP
 165 .in +4n
 166 .EX
 167 setlocale(LC_ALL, "");
 168 .EE
 169 .in
 170 .PP
 171 after program initialization, and then:
 172 .IP \(bu 2
 173 using the values returned from a
 174 .BR localeconv (3)
 175 call for locale-dependent information;
 176 .IP \(bu
 177 using the multibyte and wide character functions for text processing if
 178 .BR "MB_CUR_MAX > 1" ;
 179 .IP \(bu
 180 using
 181 .BR strcoll (3)
 182 and
 183 .BR strxfrm (3)
 184 to compare strings; and
 185 .IP \(bu
 186 using
 187 .BR wcscoll (3)
 188 and
 189 .BR wcsxfrm (3)
 190 to compare wide-character strings.
 191 .SH RETURN VALUE
 192 A successful call to
 193 .BR setlocale ()
 194 returns an opaque string that corresponds to the locale set.
 195 This string may be allocated in static storage.
 196 The string returned is such that a subsequent call with that string
 197 and its associated category will restore that part of the process's
 198 locale.
 199 The return value is NULL if the request cannot be honored.
 200 .SH ATTRIBUTES
 201 For an explanation of the terms used in this section, see
 202 .BR attributes (7).
 203 .ad l
 204 .nh
 205 .TS
 206 allbox;
 207 lbx lb lb
 208 l l l.
 209 Interface       Attribute       Value
 210 T{
 211 .BR setlocale ()
 212 T}      Thread safety   MT-Unsafe const:locale env
 213 .TE
 214 .hy
 215 .ad
 216 .sp 1
 217 .SH CONFORMING TO
 218 POSIX.1-2001, POSIX.1-2008, C89, C99.
 219 .PP
 220 The C standards specify only the categories
 221 .BR LC_ALL ,
 222 .BR LC_COLLATE ,
 223 .BR LC_CTYPE ,
 224 .BR LC_MONETARY ,
 225 .BR LC_NUMERIC ,
 226 and
 227 .BR LC_TIME .
 228 POSIX.1 adds
 229 .BR LC_MESSAGES .
 230 The remaining categories are GNU extensions.
 231 .SH SEE ALSO
 232 .BR locale (1),
 233 .BR localedef (1),
 234 .BR isalpha (3),
 235 .BR localeconv (3),
 236 .BR nl_langinfo (3),
 237 .BR rpmatch (3),
 238 .BR strcoll (3),
 239 .BR strftime (3),
 240 .BR charsets (7),
 241 .BR locale (7)