original/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  2008-12-05 "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 .sp
  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 .TP
  54 .B LC_ALL
  55 for all of the locale.
  56 .TP
  57 .B LC_COLLATE
  58 for regular expression matching (it determines the meaning
  59 of range expressions and equivalence classes) and string collation.
  60 .TP
  61 .B LC_CTYPE
  62 for regular expression matching, character classification, conversion,
  63 case-sensitive comparison, and wide character functions.
  64 .TP
  65 .B LC_MESSAGES
  66 for localizable natural-language messages.
  67 .TP
  68 .B LC_MONETARY
  69 for monetary formatting.
  70 .TP
  71 .B LC_NUMERIC
  72 for number formatting (such as the decimal point and the thousands separator).
  73 .TP
  74 .B LC_TIME
  75 for time and date formatting.
  76 .PP
  77 The argument
  78 .I locale
  79 is a pointer to a character string containing the
  80 required setting of
  81 .IR category .
  82 Such a string is either a well-known constant like "C" or "da_DK"
  83 (see below), or an opaque string that was returned by another call of
  84 .BR setlocale ().
  85 .PP
  86 If
  87 .I locale
  88 is
  89 .BR """""" ,
  90 each part of the locale that should be modified is set according to the
  91 environment variables.
  92 The details are implementation-dependent.
  93 For glibc, first (regardless of
  94 .IR category ),
  95 the environment variable
  96 .B LC_ALL
  97 is inspected,
  98 next the environment variable with the same name as the category
  99 .RB ( LC_COLLATE ,
 100 .BR LC_CTYPE ,
 101 .BR LC_MESSAGES ,
 102 .BR LC_MONETARY ,
 103 .BR LC_NUMERIC ,
 104 .BR LC_TIME )
 105 and finally the environment variable
 106 .BR LANG .
 107 The first existing environment variable is used.
 108 If its value is not a valid locale specification, the locale
 109 is unchanged, and
 110 .BR setlocale ()
 111 returns NULL.
 112 .PP
 113 The locale
 114 .B """C"""
 115 or
 116 .B """POSIX"""
 117 is a portable locale; its
 118 .B LC_CTYPE
 119 part corresponds to the 7-bit ASCII
 120 character set.
 121 .PP
 122 A locale name is typically of the form
 123 .IR language "[_" territory "][." codeset "][@" modifier "],"
 124 where
 125 .I language
 126 is an ISO 639 language code,
 127 .I territory
 128 is an ISO 3166 country code, and
 129 .I codeset
 130 is a character set or encoding identifier like
 131 .B "ISO-8859-1"
 132 or
 133 .BR "UTF-8" .
 134 For a list of all supported locales, try "locale \-a", cf.\&
 135 .BR locale (1).
 136 .PP
 137 If
 138 .I locale
 139 is NULL, the current locale is only queried, not modified.
 140 .PP
 141 On startup of the main program, the portable
 142 .B """C"""
 143 locale is selected as default.
 144 A program may be made portable to all locales by calling:
 145 .nf
 146
 147     setlocale(LC_ALL, "");
 148
 149 .fi
 150 after program initialization, by using the values returned
 151 from a
 152 .BR localeconv (3)
 153 call
 154 for locale-dependent information, by using the multibyte and wide
 155 character functions for text processing if
 156 .BR "MB_CUR_MAX > 1" ,
 157 and by using
 158 .BR strcoll (3),
 159 .BR wcscoll (3)
 160 or
 161 .BR strxfrm (3),
 162 .BR wcsxfrm (3)
 163 to compare strings.
 164 .SH RETURN VALUE
 165 A successful call to
 166 .BR setlocale ()
 167 returns an opaque string that corresponds to the locale set.
 168 This string may be allocated in static storage.
 169 The string returned is such that a subsequent call with that string
 170 and its associated category will restore that part of the process's
 171 locale.
 172 The return value is NULL if the request cannot be honored.
 173 .SH CONFORMING TO
 174 C89, C99, POSIX.1-2001.
 175 .SH NOTES
 176 Linux (that is, glibc) supports the portable locales
 177 .BR """C""" " and " """POSIX""" .
 178 In the good old days there used to be support for
 179 the European Latin-1
 180 .B """ISO-8859-1"""
 181 locale (e.g., in libc-4.5.21 and libc-4.6.27), and the Russian
 182 .B """KOI-8"""
 183 (more precisely, "koi-8r") locale (e.g., in libc-4.6.27),
 184 so that having an environment variable \fILC_CTYPE=ISO-8859-1\fP
 185 sufficed to make
 186 .BR isprint (3)
 187 return the right answer.
 188 These days non-English speaking Europeans have to work a bit harder,
 189 and must install actual locale files.
 190 .SH SEE ALSO
 191 .BR locale (1),
 192 .BR localedef (1),
 193 .BR isalpha (3),
 194 .BR localeconv (3),
 195 .BR nl_langinfo (3),
 196 .BR rpmatch (3),
 197 .BR strcoll (3),
 198 .BR strftime (3),
 199 .BR charsets (7),
 200 .BR locale (7)
 201 .SH COLOPHON
 202 This page is part of release 3.67 of the Linux
 203 .I man-pages
 204 project.
 205 A description of the project,
 206 information about reporting bugs,
 207 and the latest version of this page,
 208 can be found at
 209 \%http://www.kernel.org/doc/man\-pages/.