lib/libc/locale/newlocale.3

   1 .\" Copyright (c) 2011 The FreeBSD Foundation
   2 .\"
   3 .\" This documentation was written by David Chisnall under sponsorship from
   4 .\" the FreeBSD Foundation.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .\" $FreeBSD$
  28 .Dd October 2, 2020
  29 .Dt NEWLOCALE 3
  30 .Os
  31 .Sh NAME
  32 .Nm newlocale
  33 .Nd Creates a new locale
  34 .Sh LIBRARY
  35 .Lb libc
  36 .Sh SYNOPSIS
  37 .In locale.h
  38 .Ft locale_t
  39 .Fn newlocale "int mask" "const char * locale" "locale_t base"
  40 .Sh DESCRIPTION
  41 Creates a new locale, inheriting some properties from an existing locale.
  42 The
  43 .Fa mask
  44 defines the components that the new locale will have set to the locale with the
  45 name specified in the
  46 .Fa locale
  47 parameter.
  48 Any components not specified in
  49 .Fa mask
  50 will be inherited from the locale referenced by
  51 .Fa base ,
  52 if
  53 .Fa base
  54 is not
  55 .Dv NULL .
  56 If the call is successful, the state of the locale referenced by
  57 .Fa base
  58 is unspecified, and it must not be accessed.
  59 The special locale
  60 .Dv LC_GLOBAL_LOCALE
  61 may not be specified for
  62 .Fa base .
  63 The
  64 .Fa mask
  65 is either
  66 .Fa LC_ALL_MASK ,
  67 indicating all possible locale components,
  68 or the logical OR of some combination of the following:
  69 .Bl -tag -width "LC_MESSAGES_MASK" -offset indent
  70 .It LC_COLLATE_MASK
  71 The locale for string collation routines.
  72 This controls alphabetic ordering in
  73 .Xr strcoll 3
  74 and
  75 .Xr strxfrm 3 .
  76 .It LC_CTYPE_MASK
  77 The locale for the
  78 .Xr ctype 3
  79 and
  80 .Xr multibyte 3
  81 functions.
  82 This controls recognition of upper and lower case, alphabetic or
  83 non-alphabetic characters, and so on.
  84 .It LC_MESSAGES_MASK
  85 Set a locale for message catalogs, see
  86 .Xr catopen 3
  87 function.
  88 .It LC_MONETARY_MASK
  89 Set a locale for formatting monetary values; this affects
  90 the
  91 .Xr localeconv 3
  92 function.
  93 .It LC_NUMERIC_MASK
  94 Set a locale for formatting numbers.
  95 This controls the formatting of decimal points in input and output of floating
  96 point numbers in functions such as
  97 .Xr printf 3
  98 and
  99 .Xr scanf 3 ,
 100 as well as values returned by
 101 .Xr localeconv 3 .
 102 .It LC_TIME_MASK
 103 Set a locale for formatting dates and times using the
 104 .Xr strftime 3
 105 function.
 106 .El
 107 This function uses the same rules for loading locale components as
 108 .Xr setlocale 3 .
 109 .Sh RETURN VALUES
 110 Returns a new, valid,
 111 .Fa locale_t
 112 or NULL if an error occurs.
 113 You must free the returned locale with
 114 .Xr freelocale 3 .
 115 .Sh SEE ALSO
 116 .Xr duplocale 3 ,
 117 .Xr freelocale 3 ,
 118 .Xr localeconv 3 ,
 119 .Xr querylocale 3 ,
 120 .Xr uselocale 3 ,
 121 .Xr xlocale 3
 122 .Sh STANDARDS
 123 This function conforms to
 124 .St -p1003.1-2008 .