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 .\" 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 .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 .Pp
  61 .Bl -tag -width LC_MONETARY
  62 .It Dv LC_ALL
  63 Set the entire locale generically.
  64 .It Dv LC_COLLATE
  65 Set a locale for string collation routines.
  66 This controls alphabetic ordering in
  67 .Fn strcoll
  68 and
  69 .Fn strxfrm .
  70 .It Dv LC_CTYPE
  71 Set a locale for the
  72 .Xr ctype 3
  73 and
  74 .Xr multibyte 3
  75 functions.
  76 This controls recognition of upper and lower case,
  77 alphabetic or non-alphabetic characters,
  78 and so on.
  79 .It Dv LC_MESSAGES
  80 Set a locale for message catalogs, see
  81 .Xr catopen 3
  82 function.
  83 .It Dv LC_MONETARY
  84 Set a locale for formatting monetary values;
  85 this affects the
  86 .Fn localeconv
  87 function.
  88 .It Dv LC_NUMERIC
  89 Set a locale for formatting numbers.
  90 This controls the formatting of decimal points
  91 in input and output of floating point numbers
  92 in functions such as
  93 .Fn printf
  94 and
  95 .Fn scanf ,
  96 as well as values returned by
  97 .Fn localeconv .
  98 .It Dv LC_TIME
  99 Set a locale for formatting dates and times using the
 100 .Fn strftime
 101 function.
 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 By default, C programs start in the
 120 .Li "\&""C""
 121 locale.
 122 The only function in the library that sets the locale is
 123 .Fn setlocale ;
 124 the locale is never changed as a side effect of some other routine.
 125 .Sh RETURN VALUES
 126 Upon successful completion,
 127 .Fn setlocale
 128 returns the string associated with the specified
 129 .Fa category
 130 for the requested
 131 .Fa locale .
 132 The
 133 .Fn setlocale
 134 function returns
 135 .Dv NULL
 136 and fails to change the locale
 137 if the given combination of
 138 .Fa category
 139 and
 140 .Fa locale
 141 makes no sense.
 142 .Sh FILES
 143 .Bl -tag -width /usr/share/locale/locale/category -compact
 144 .It Pa $PATH_LOCALE/ Ns Em locale/category
 145 .It Pa /usr/share/locale/ Ns Em locale/category
 146 locale file for the locale
 147 .Em locale
 148 and the category
 149 .Em category .
 150 .El
 151 .Sh ERRORS
 152 No errors are defined.
 153 .Sh SEE ALSO
 154 .Xr colldef 1 ,
 155 .Xr mklocale 1 ,
 156 .Xr catopen 3 ,
 157 .Xr ctype 3 ,
 158 .Xr localeconv 3 ,
 159 .Xr multibyte 3 ,
 160 .Xr strcoll 3 ,
 161 .Xr strxfrm 3 ,
 162 .Xr euc 5 ,
 163 .Xr utf8 5 ,
 164 .Xr environ 7
 165 .Sh STANDARDS
 166 The
 167 .Fn setlocale
 168 function conforms to
 169 .St -isoC-99 .
 170 .Sh HISTORY
 171 The
 172 .Fn setlocale
 173 function first appeared in
 174 .Bx 4.4 .