lib/libc/locale/setlocale.3

   1 .\" Copyright (c) 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" Donn Seeley at BSDI.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 3. Neither the name of the University nor the names of its contributors
  16 .\"    may be used to endorse or promote products derived from this software
  17 .\"    without specific prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  22 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29 .\" SUCH DAMAGE.
  30 .\"
  31 .\"     @(#)setlocale.3 8.1 (Berkeley) 6/9/93
  32 .\"
  33 .Dd August 7, 2020
  34 .Dt SETLOCALE 3
  35 .Os
  36 .Sh NAME
  37 .Nm setlocale
  38 .Nd natural language formatting for C
  39 .Sh LIBRARY
  40 .Lb libc
  41 .Sh SYNOPSIS
  42 .In locale.h
  43 .Ft char *
  44 .Fn setlocale "int category" "const char *locale"
  45 .Sh DESCRIPTION
  46 The
  47 .Fn setlocale
  48 function sets the C library's notion
  49 of natural language formatting style
  50 for particular sets of routines.
  51 Each such style is called a
  52 .Sq locale
  53 and is invoked using an appropriate name passed as a C string.
  54 .Pp
  55 The
  56 .Fn setlocale
  57 function recognizes several categories of routines.
  58 These are the categories and the sets of routines they select:
  59 .Bl -tag -width LC_MONETARY
  60 .It Dv LC_ALL
  61 Set the entire locale generically.
  62 .It Dv LC_COLLATE
  63 Set a locale for string collation routines.
  64 This controls alphabetic ordering in
  65 .Fn strcoll
  66 and
  67 .Fn strxfrm .
  68 .It Dv LC_CTYPE
  69 Set a locale for the
  70 .Xr ctype 3
  71 and
  72 .Xr multibyte 3
  73 functions.
  74 This controls recognition of upper and lower case,
  75 alphabetic or non-alphabetic characters,
  76 and so on.
  77 .It Dv LC_MESSAGES
  78 Set a locale for message catalogs, see
  79 .Xr catopen 3
  80 function.
  81 .It Dv LC_MONETARY
  82 Set a locale for formatting monetary values;
  83 this affects the
  84 .Fn localeconv
  85 function.
  86 .It Dv LC_NUMERIC
  87 Set a locale for formatting numbers.
  88 This controls the formatting of decimal points
  89 in input and output of floating point numbers
  90 in functions such as
  91 .Fn printf
  92 and
  93 .Fn scanf ,
  94 as well as values returned by
  95 .Fn localeconv .
  96 .It Dv LC_TIME
  97 Set a locale for formatting dates and times using the
  98 .Fn strftime
  99 function.
 100 .It Dv LANG
 101 Sets the generic locale category for native language, local customs
 102 and coded character set in the absence of more specific locale
 103 variables.
 104 .El
 105 .Pp
 106 Only three locales are defined by default,
 107 the empty string
 108 .Li \&"\|"
 109 which denotes the native environment, and the
 110 .Li \&"C"
 111 and
 112 .Li \&"POSIX"
 113 locales, which denote the C language environment.
 114 A
 115 .Fa locale
 116 argument of
 117 .Dv NULL
 118 causes
 119 .Fn setlocale
 120 to return the current locale.
 121 .Pp
 122 The option
 123 .Fl a
 124 to the
 125 .Xr locale 1
 126 command can be used to display all further possible names for the
 127 .Fa locale
 128 argument that are recognized.
 129 Specifying any unrecognized value for
 130 .Fa locale
 131 makes
 132 .Fn setlocale
 133 fail.
 134 .Pp
 135 By default, C programs start in the
 136 .Li \&"C"
 137 locale.
 138 .Pp
 139 The only function in the library that sets the locale is
 140 .Fn setlocale ;
 141 the locale is never changed as a side effect of some other routine.
 142 .Sh RETURN VALUES
 143 Upon successful completion,
 144 .Fn setlocale
 145 returns the string associated with the specified
 146 .Fa category
 147 for the requested
 148 .Fa locale .
 149 The
 150 .Fn setlocale
 151 function returns
 152 .Dv NULL
 153 and fails to change the locale
 154 if the given combination of
 155 .Fa category
 156 and
 157 .Fa locale
 158 makes no sense.
 159 .Sh FILES
 160 .Bl -tag -width /usr/share/locale/locale/category -compact
 161 .It Pa $PATH_LOCALE/ Ns Em locale/category
 162 .It Pa /usr/share/locale/ Ns Em locale/category
 163 locale file for the locale
 164 .Em locale
 165 and the category
 166 .Em category .
 167 .El
 168 .Sh EXAMPLES
 169 The following code illustrates how a program can initialize the
 170 international environment for one language, while selectively
 171 modifying the program's locale such that regular expressions and
 172 string operations can be applied to text recorded in a different
 173 language:
 174 .Bd -literal
 175     setlocale(LC_ALL, "de");
 176     setlocale(LC_COLLATE, "fr");
 177 .Ed
 178 .Pp
 179 When a process is started, its current locale is set to the C or POSIX
 180 locale.
 181 An internationalized program that depends on locale data not defined in
 182 the C or POSIX locale must invoke the setlocale subroutine in the
 183 following manner before using any of the locale-specific information:
 184 .Bd -literal
 185     setlocale(LC_ALL, "");
 186 .Ed
 187 .Sh ERRORS
 188 No errors are defined.
 189 .Sh SEE ALSO
 190 .Xr locale 1 ,
 191 .Xr localedef 1 ,
 192 .Xr catopen 3 ,
 193 .Xr ctype 3 ,
 194 .Xr localeconv 3 ,
 195 .Xr multibyte 3 ,
 196 .Xr strcoll 3 ,
 197 .Xr strxfrm 3 ,
 198 .Xr euc 5 ,
 199 .Xr utf8 5 ,
 200 .Xr environ 7
 201 .Sh STANDARDS
 202 The
 203 .Fn setlocale
 204 function conforms to
 205 .St -isoC-99 .
 206 .Sh HISTORY
 207 The
 208 .Fn setlocale
 209 function first appeared in
 210 .Bx 4.4 .