Print this page
Add locale.h ref
Ensured various XPG7 stuff are declared properly in sys/stat.h (and cleanup)
New documentation for wcslen, wcsnlen, wcscasecmp (and friends), wcsdup.
Various other tweaks and markup improvements.
Note standards conformance for newlocale, convert to mdocml.
   1 '\" te
   2 .\"
   3 .\" This file and its contents are supplied under the terms of the
   4 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   5 .\" You may only use this file in accordance with the terms of version
   6 .\" 1.0 of the CDDL.
   7 .\"
   8 .\" A full copy of the text of the CDDL should have accompanied this
   9 .\" source.  A copy of the CDDL is also available via the Internet at
  10 .\" http://www.illumos.org/license/CDDL.
  11 .\"
  12 .\"
  13 .\" Copyright (c) 2014 Joyent, Inc.  All rights reserved.
  14 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
  15 .\"
  16 .TH NEWLOCALE 3C "Jun 23, 2014"
  17 .SH NAME
  18 duplocale, freelocale, newlocale \- create, duplicate, and destroy locale objects
  19 .SH SYNOPSIS
  20 .LP
  21 .nf
  22 #include <locale.h>
  23 
  24 \fBlocale_t\fR \fBnewlocale\fR(\fBint\fR \fIcategory_mask\fR, \fBconst char *\fR \fIlocale\fR,
  25     \fBlocale_t\fR \fIbase\fR);
  26 .fi
  27 .LP
  28 .nf
  29 \fBlocale_t\fR \fBduplocale\fR(\fBlocale_t\fR \fIloc\fR);
  30 .fi
  31 .LP
  32 .nf
  33 \fBvoid\fR \fBfreelocale\fR(\fBlocale_t\fR \fIloc\fR);
  34 .fi
  35 .SH DESCRIPTION
  36 .LP
  37 These functions manipulate locale objects that can be used
  38 .BR uselocale (3C)







  39 and functions that take arguments of type
  40 .BR locale_t .
  41 .LP
  42 The function
  43 .B newlocale()

  44 can be used to create a new locale object. It can also be used to modify an
  45 existing locale object, the new locale object will be a replacement for the
  46 modified locale object. To create a new locale, the argument
  47 .I base
  48 should be passed the special argument
  49 .RB ( locale_t )0.
  50 This will use a copy of the current global locale as a starting point. To modify
  51 an existing locale object, it should be passed in as the argument
  52 .IR base .
  53 The new locale object is constructed by taking the categories specified in
  54 .I category_mask
  55 from the locale specified by the string
  56 .IR locale ,
  57 and filling in the remaining categories from the locale
  58 .IR base .
  59 When
  60 .B newlocale()
  61 returns, callers must no longer use
  62 .IR base
  63 and assume that
  64 .BR freelocale (3C)
  65 has been called on it. In addition to locales defined on the system, the


  66 following three locales may always be passed in as the string
  67 .IR locale :
  68 .TP
  69 "C"
  70 Specifies the traditional UNIX system behavior.
  71 .TP
  72 "POSIX"
  73 An alternate name fo the locale "C".
  74 .TP
  75 ""
  76 Indicates that the locale should be processed based in the values in the
  77 environment. See
  78 .BR setlocale (3C)
  79 and
  80 .BR environ (5)
  81 for more information.
  82 .LP

  83 The value of
  84 .I category_mask
  85 is a bitwise-inclusive or of the following macros which correspond to categories
  86 as defined in
  87 .BR locale (5)
  88 and
  89 .BR environ (5):
  90 .TP
  91 .B LC_CTYPE_MASK
  92 Character classification and case conversion.
  93 .TP
  94 .B LC_NUMERIC_MASK
  95 Numeric formatting.
  96 .TP
  97 .B LC_TIME_MASK
  98 Date and time formatting.
  99 .TP
 100 .B LC_COLLATE_MASK
 101 Collation order.
 102 .TP
 103 .B LC_MONETARY_MASK
 104 Monetary formatting.
 105 .TP
 106 .B LC_MESSAGES_MASK
 107 Formats of informative and diagnostic messages and interactive responses.
 108 .TP
 109 .B LC_ALL_MASK
 110 Mask of all categories.
 111 .LP
 112 The function
 113 .B duplocale()
 114 duplicates the locale object specified by
 115 .IR loc .

 116 If the locale object passed is
 117 .BR LC_GLOBAL_LOCALE ,
 118 .B duplocale()
 119 creates a copy of the current global locale as defined through calls to
 120 .BR setlocale (3C).
 121 .LP
 122 The function
 123 .B freelocale()
 124 removes and releases all resources associated with the locale object
 125 .IR loc .
 126 Programs must not call
 127 .B freelocale()
 128 on
 129 .BR LC_GLOBAL_LOCALE .
 130 .SH RETURN VALUES
 131 .LP
 132 On success, the functions
 133 .B newlocale()
 134 and
 135 .B duplocale()
 136 return a new locale object that can be used with functions that take a
 137 .BR locale_t .
 138 Locale objects created this way should be freed with
 139 .BR freelocale() .
 140 On error, the functions
 141 .B newlocale()
 142 and
 143 .B duplocale()
 144 return
 145 .BR (locale_t) 0
 146 and
 147 .B errno
 148 is set to indicate the error. The
 149 .B freelocale()
 150 function does not set
 151 .B errno.
 152 .SH ERRORS
 153 .LP
 154 The
 155 .B newlocale()
 156 and
 157 .B duplocale()
 158 functions will fail if:
 159 .TP
 160 .B ENOMEM
 161 Insufficient memory was available to create the locale object or to load the
 162 requested locale data.
 163 .LP

 164 The
 165 .B newlocale()
 166 function will fail if:
 167 .TP
 168 .B EINVAL
 169 An unknown bit is specified in
 170 .IR category_mask .
 171 .TP
 172 .B ENOENT
 173 Locale data was not found for a category specified in
 174 .SH ATTRIBUTES
 175 .TS
 176 box;
 177 c | c
 178 l | l .
 179 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 180 _
 181 Interface Stability     Standard
 182 _
 183 MT-Level        Safe
 184 .TE
 185 
 186 .SH SEE ALSO
 187 .BR locale (1),
 188 .BR setlocale (3C),
 189 .BR uselocale (3C),
 190 .BR environ (5),
 191 .BR locale (5)




   1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright (c) 2014 Joyent, Inc.  All rights reserved.
  13 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
  14 .\"
  15 .Dd "Jul 23, 2014"
  16 .Dt NEWLOCALE 3C
  17 .Os
  18 .Sh NAME
  19 .Nm duplocale ,
  20 .Nm freelocale ,
  21 .Nm newlocale
  22 .Nd create, duplicate, and destroy locale objects
  23 .Sh SYNOPSIS
  24 .In locale.h
  25 .
  26 .Ft locale_t
  27 .Fo newlocale
  28 .Fa "int category_mask"
  29 .Fa "const char *locale"
  30 .Fa "locale_t base"
  31 .Fc
  32 .
  33 .Ft locale_t
  34 .Fo duplocale
  35 .Fa "locale_t loc"
  36 .Fc
  37 .
  38 .Ft void
  39 .Fo freelocale
  40 .Fa "locale_t loc"
  41 .Fc
  42 .Sh DESCRIPTION
  43 These functions manipulate locale objects that can be used with
  44 .Xr uselocale 3C
  45 and functions that take arguments of type
  46 .Vt locale_t .
  47 .Lp
  48 The
  49 .Fn newlocale
  50 function
  51 can be used to create a new locale object. It can also be used to modify an
  52 existing locale object; the new locale object will be a replacement for the
  53 modified locale object. To create a new locale, the argument
  54 .Fa base
  55 should be passed the special argument
  56 .Po Vt locale_t Pc 0.
  57 This will use a copy of the current global locale as a starting point. To modify
  58 an existing locale object, it should be passed in as the argument
  59 .Fa base .
  60 The new locale object is constructed by taking the categories specified in
  61 .Fa category_mask
  62 from the locale specified by the string
  63 .Fa locale ,
  64 and filling in the remaining categories from the locale
  65 .Fa base .
  66 When
  67 .Fn newlocale
  68 returns, callers must no longer use
  69 .Fa base .
  70 They should assume that
  71 .Fn freelocale
  72 has been called on it.
  73 .Lp
  74 In addition to locales defined on the system, the
  75 following three locales may always be passed in as the string
  76 .Fa locale :
  77 .Bl -tag -offset indent -width Dq
  78 .It \\"C\\"
  79 Specifies the traditional UNIX system behavior.
  80 .It \\"POSIX\\"

  81 An alternate name fo the locale "C".
  82 .It \\"\\"

  83 Indicates that the locale should be processed based in the values in the
  84 environment. See
  85 .Xr setlocale 3C
  86 and
  87 .Xr environ 5
  88 for more information.
  89 .El
  90 .Lp
  91 The value of
  92 .Fa category_mask
  93 is a bitwise-inclusive or of the following macros which correspond to categories
  94 as defined in
  95 .Xr locale 5
  96 and
  97 .Xr environ 5 :
  98 .Bl -tag -offset indent -width Dv
  99 .It Dv LC_CTYPE_MASK
 100 Character classification and case conversion.
 101 .It Dv LC_NUMERIC_MASK

 102 Numeric formatting.
 103 .It Dv LC_TIME_MASK

 104 Date and time formatting.
 105 .It Dv LC_COLLATE_MASK

 106 Collation order.
 107 .It Dv LC_MONETARY_MASK

 108 Monetary formatting.
 109 .It Dv LC_MESSAGES_MASK

 110 Formats of informative and diagnostic messages and interactive responses.
 111 .It Dv LC_ALL_MASK

 112 Mask of all categories.
 113 .El
 114 .Lp
 115 The
 116 .Fn duplocale
 117 function duplicates the locale object specified by
 118 .Fa loc .
 119 If the locale object passed is
 120 .Dv LC_GLOBAL_LOCALE ,
 121 .Fn duplocale
 122 creates a copy of the current global locale as defined through calls to
 123 .Xr setlocale 3C .
 124 .Lp
 125 The
 126 .Fn freelocale
 127 function removes and releases all resources associated with the locale object
 128 .Fa loc .
 129 Programs must not call
 130 .Fn freelocale
 131 on
 132 .Dv LC_GLOBAL_LOCALE .
 133 .Sh RETURN VALUES

 134 On success, the functions
 135 .Fn newlocale
 136 and
 137 .Fn duplocale
 138 return a new locale object that can be used with functions that take a
 139 .Vt locale_t .
 140 Locale objects created this way should be freed with
 141 .Fn freelocale .
 142 On error, the functions
 143 .Fn newlocale
 144 and
 145 .Fn duplocale
 146 return
 147 .Po Vt locale_t Pc 0
 148 and
 149 .Va errno
 150 is set to indicate the error. The
 151 .Fn freelocale
 152 function does not set
 153 .Va errno .
 154 .Sh ERRORS

 155 The
 156 .Fn newlocale
 157 and
 158 .Fn duplocale
 159 functions will fail if:
 160 .Bl -tag -width Er
 161 .It Er ENOMEM
 162 Insufficient memory was available to create the locale object or to load the
 163 requested locale data.
 164 .El
 165 .Lp
 166 The
 167 .Fn newlocale
 168 function will fail if:
 169 .Bl -tag -width Er
 170 .It Er EINVAL
 171 An unknown bit is specified in
 172 .Fa category_mask .
 173 .It Er ENOENT

 174 Locale data was not found for a category specified in
 175 .Fa category_mask .
 176 .El
 177 .Sh INTERFACE STABILITY
 178 .Sy Standard .
 179 .Sh MT-LEVEL
 180 .Sy MT-Safe .
 181 .Sh SEE ALSO
 182 .Xr locale 1 ,
 183 .Xr setlocale 3C ,
 184 .Xr uselocale 3C ,
 185 .Xr locale.h 3HEAD  ,
 186 .Xr environ 5 ,
 187 .Xr locale 5
 188 .Sh STANDARDS
 189 The
 190 .Fn newlocale ,
 191 .Fn duplocale ,
 192 and
 193 .Fn freelocale
 194 functions were introduced in
 195 .St -p1003.1-2008 .