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