locale/FreeBSD/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 .\" 4. 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 November 21, 2003
  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 .Fo setlocale
  46 .Fa "int category"
  47 .Fa "const char *locale"
  48 .Fc
  49 .Sh DESCRIPTION
  50 The
  51 .Fn setlocale
  52 function sets the C library's notion
  53 of natural language formatting style
  54 for particular sets of routines.
  55 Each such style is called a
  56 .Sq locale
  57 and is invoked using an appropriate name passed as a C string.
  58 .Pp
  59 The
  60 .Fn setlocale
  61 function recognizes several categories of routines.
  62 These are the categories and the sets of routines they select:
  63 .Bl -tag -width LC_MONETARY
  64 .It Dv LC_ALL
  65 Set the entire locale generically.
  66 .It Dv LC_COLLATE
  67 Set a locale for string collation routines.
  68 This controls alphabetic ordering in
  69 .Fn strcoll
  70 and
  71 .Fn strxfrm .
  72 .It Dv LC_CTYPE
  73 Set a locale for the
  74 .Xr ctype 3
  75 and
  76 .Xr multibyte 3
  77 functions.
  78 This controls recognition of upper and lower case,
  79 alphabetic or non-alphabetic characters,
  80 and so on.
  81 .It Dv LC_MESSAGES
  82 Set a locale for message catalogs, see
  83 .Xr catopen 3
  84 function.
  85 .It Dv LC_MONETARY
  86 Set a locale for formatting monetary values;
  87 this affects the
  88 .Fn localeconv
  89 function.
  90 .It Dv LC_NUMERIC
  91 Set a locale for formatting numbers.
  92 This controls the formatting of decimal points
  93 in input and output of floating point numbers
  94 in functions such as
  95 .Fn printf
  96 and
  97 .Fn scanf ,
  98 as well as values returned by
  99 .Fn localeconv .
 100 .It Dv LC_TIME
 101 Set a locale for formatting dates and times using the
 102 .Fn strftime
 103 function.
 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.  An argument of
 121 .Li \&"\|"
 122 will determine the name of the new locale taking into account the environment
 123 variables LANG and LC_*.  If these environment variables yield a locale that is
 124 invalid, NULL will be returned and the current locale will remain unchanged.
 125 By default, C programs start in the
 126 .Li \&"C"
 127 locale.
 128 The only function in the library that sets the locale is
 129 .Fn setlocale ;
 130 the locale is never changed as a side effect of some other routine.
 131 .Sh RETURN VALUES
 132 Upon successful completion,
 133 .Fn setlocale
 134 returns the string associated with the specified
 135 .Fa category
 136 for the requested
 137 .Fa locale .
 138 The
 139 .Fn setlocale
 140 function returns
 141 .Dv NULL
 142 and fails to change the locale
 143 if the given combination of
 144 .Fa category
 145 and
 146 .Fa locale
 147 makes no sense.
 148 .Sh FILES
 149 .Bl -tag -width /usr/share/locale/locale/category -compact
 150 .It Pa $PATH_LOCALE/ Ns Em locale/category
 151 .It Pa /usr/share/locale/ Ns Em locale/category
 152 locale file for the locale
 153 .Em locale
 154 and the category
 155 .Em category .
 156 .It Pa /usr/local/share/locale/ Ns Em locale/category
 157 locale file for the locale
 158 .Em locale
 159 and the category
 160 .Em category .
 161 .El
 162 .Sh ERRORS
 163 No errors are defined.
 164 .Sh SEE ALSO
 165 .Xr colldef 1 ,
 166 .Xr mklocale 1 ,
 167 .Xr catopen 3 ,
 168 .Xr ctype 3 ,
 169 .Xr localeconv 3 ,
 170 .Xr multibyte 3 ,
 171 .Xr strcoll 3 ,
 172 .Xr strxfrm 3 ,
 173 .Xr euc 5 ,
 174 .Xr utf8 5 ,
 175 .Xr environ 7
 176 .Sh STANDARDS
 177 The
 178 .Fn setlocale
 179 function conforms to
 180 .St -isoC-99 .
 181 .Sh HISTORY
 182 The
 183 .Fn setlocale
 184 function first appeared in
 185 .Bx 4.4 .