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 .\" $FreeBSD$
  33 .\"
  34 .Dd August 7, 2020
  35 .Dt SETLOCALE 3
  36 .Os
  37 .Sh NAME
  38 .Nm setlocale
  39 .Nd natural language formatting for C
  40 .Sh LIBRARY
  41 .Lb libc
  42 .Sh SYNOPSIS
  43 .In locale.h
  44 .Ft char *
  45 .Fn setlocale "int category" "const char *locale"
  46 .Sh DESCRIPTION
  47 The
  48 .Fn setlocale
  49 function sets the C library's notion
  50 of natural language formatting style
  51 for particular sets of routines.
  52 Each such style is called a
  53 .Sq locale
  54 and is invoked using an appropriate name passed as a C string.
  55 .Pp
  56 The
  57 .Fn setlocale
  58 function recognizes several categories of routines.
  59 These are the categories and the sets of routines they select:
  60 .Bl -tag -width LC_MONETARY
  61 .It Dv LC_ALL
  62 Set the entire locale generically.
  63 .It Dv LC_COLLATE
  64 Set a locale for string collation routines.
  65 This controls alphabetic ordering in
  66 .Fn strcoll
  67 and
  68 .Fn strxfrm .
  69 .It Dv LC_CTYPE
  70 Set a locale for the
  71 .Xr ctype 3
  72 and
  73 .Xr multibyte 3
  74 functions.
  75 This controls recognition of upper and lower case,
  76 alphabetic or non-alphabetic characters,
  77 and so on.
  78 .It Dv LC_MESSAGES
  79 Set a locale for message catalogs, see
  80 .Xr catopen 3
  81 function.
  82 .It Dv LC_MONETARY
  83 Set a locale for formatting monetary values;
  84 this affects the
  85 .Fn localeconv
  86 function.
  87 .It Dv LC_NUMERIC
  88 Set a locale for formatting numbers.
  89 This controls the formatting of decimal points
  90 in input and output of floating point numbers
  91 in functions such as
  92 .Fn printf
  93 and
  94 .Fn scanf ,
  95 as well as values returned by
  96 .Fn localeconv .
  97 .It Dv LC_TIME
  98 Set a locale for formatting dates and times using the
  99 .Fn strftime
 100 function.
 101 .It Dv LANG
 102 Sets the generic locale category for native language, local customs
 103 and coded character set in the absence of more specific locale
 104 variables.
 105 .El
 106 .Pp
 107 Only three locales are defined by default,
 108 the empty string
 109 .Li \&"\|"
 110 which denotes the native environment, and the
 111 .Li \&"C"
 112 and
 113 .Li \&"POSIX"
 114 locales, which denote the C language environment.
 115 A
 116 .Fa locale
 117 argument of
 118 .Dv NULL
 119 causes
 120 .Fn setlocale
 121 to return the current locale.
 122 .Pp
 123 The option
 124 .Fl a
 125 to the
 126 .Xr locale 1
 127 command can be used to display all further possible names for the
 128 .Fa locale
 129 argument that are recognized.
 130 Specifying any unrecognized value for
 131 .Fa locale
 132 makes
 133 .Fn setlocale
 134 fail.
 135 .Pp
 136 By default, C programs start in the
 137 .Li \&"C"
 138 locale.
 139 .Pp
 140 The only function in the library that sets the locale is
 141 .Fn setlocale ;
 142 the locale is never changed as a side effect of some other routine.
 143 .Sh RETURN VALUES
 144 Upon successful completion,
 145 .Fn setlocale
 146 returns the string associated with the specified
 147 .Fa category
 148 for the requested
 149 .Fa locale .
 150 The
 151 .Fn setlocale
 152 function returns
 153 .Dv NULL
 154 and fails to change the locale
 155 if the given combination of
 156 .Fa category
 157 and
 158 .Fa locale
 159 makes no sense.
 160 .Sh FILES
 161 .Bl -tag -width /usr/share/locale/locale/category -compact
 162 .It Pa $PATH_LOCALE/ Ns Em locale/category
 163 .It Pa /usr/share/locale/ Ns Em locale/category
 164 locale file for the locale
 165 .Em locale
 166 and the category
 167 .Em category .
 168 .El
 169 .Sh EXAMPLES
 170 The following code illustrates how a program can initialize the
 171 international environment for one language, while selectively
 172 modifying the program's locale such that regular expressions and
 173 string operations can be applied to text recorded in a different
 174 language:
 175 .Bd -literal
 176     setlocale(LC_ALL, "de");
 177     setlocale(LC_COLLATE, "fr");
 178 .Ed
 179 .Pp
 180 When a process is started, its current locale is set to the C or POSIX
 181 locale.
 182 An internationalized program that depends on locale data not defined in
 183 the C or POSIX locale must invoke the setlocale subroutine in the
 184 following manner before using any of the locale-specific information:
 185 .Bd -literal
 186     setlocale(LC_ALL, "");
 187 .Ed
 188 .Sh ERRORS
 189 No errors are defined.
 190 .Sh SEE ALSO
 191 .Xr locale 1 ,
 192 .Xr localedef 1 ,
 193 .Xr catopen 3 ,
 194 .Xr ctype 3 ,
 195 .Xr localeconv 3 ,
 196 .Xr multibyte 3 ,
 197 .Xr strcoll 3 ,
 198 .Xr strxfrm 3 ,
 199 .Xr euc 5 ,
 200 .Xr utf8 5 ,
 201 .Xr environ 7
 202 .Sh STANDARDS
 203 The
 204 .Fn setlocale
 205 function conforms to
 206 .St -isoC-99 .
 207 .Sh HISTORY
 208 The
 209 .Fn setlocale
 210 function first appeared in
 211 .Bx 4.4 .