Print this page
Garrett's man page edits.

Split Close
Expand all
Collapse all
          --- old/usr/src/man/man3c/newlocale.3c
          +++ new/usr/src/man/man3c/newlocale.3c
↓ open down ↓ 3 lines elided ↑ open up ↑
   4    4  .\" Common Development and Distribution License ("CDDL"), version 1.0.
   5    5  .\" You may only use this file in accordance with the terms of version
   6    6  .\" 1.0 of the CDDL.
   7    7  .\"
   8    8  .\" A full copy of the text of the CDDL should have accompanied this
   9    9  .\" source.  A copy of the CDDL is also available via the Internet at
  10   10  .\" http://www.illumos.org/license/CDDL.
  11   11  .\"
  12   12  .\"
  13   13  .\" Copyright (c) 2014 Joyent, Inc.  All rights reserved.
       14 +.\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
  14   15  .\"
  15      -.TH NEWLOCALE 3C "Jun 11, 2014"
  16      -
       16 +.TH NEWLOCALE 3C "Jun 23, 2014"
  17   17  .SH NAME
  18      -
  19   18  duplocale, freelocale, newlocale \- create, duplicate, and destroy locale objects
  20      -
  21   19  .SH SYNOPSIS
  22      -
  23   20  .LP
  24   21  .nf
  25   22  #include <locale.h>
  26   23  
  27      -.BI "locale_t newlocale(int " category_mask, " const char *" locale,
  28      -.BI "    locale_t " base );
       24 +\fBlocale_t\fR \fBnewlocale\fR(\fBint\fR \fIcategory_mask\fR, \fBconst char *\fR \fIlocale\fR,
       25 +    \fBlocale_t\fR \fIbase\fR);
       26 +.fi
  29   27  .LP
  30      -.BI "locale_t duplocale(locale_t " loc );
       28 +.nf
       29 +\fBlocale_t\fR \fBduplocale\fR(\fBlocale_t\fR \fIloc\fR);
       30 +.fi
  31   31  .LP
  32      -.BI "void freelocale(locale_t " loc );
  33      -
       32 +.nf
       33 +\fBvoid\fR \fBfreelocale\fR(\fBlocale_t\fR \fIloc\fR);
       34 +.fi
  34   35  .SH DESCRIPTION
  35   36  .LP
  36   37  These functions manipulate locale objects that can be used
  37   38  .BR uselocale (3C)
  38   39  and functions that take arguments of type
  39   40  .BR locale_t .
  40      -
  41   41  .LP
  42   42  The function
  43      -.I newlocale
       43 +.B newlocale()
  44   44  can be used to create a new locale object. It can also be used to modify an
  45   45  existing locale object, the new locale object will be a replacement for the
  46   46  modified locale object. To create a new locale, the argument
  47   47  .I base
  48   48  should be passed the special argument
  49   49  .RB ( locale_t )0.
  50   50  This will use a copy of the current global locale as a starting point. To modify
  51   51  an existing locale object, it should be passed in as the argument
  52   52  .IR base .
  53   53  The new locale object is constructed by taking the categories specified in
  54   54  .I category_mask
  55   55  from the locale specified by the string
  56   56  .IR locale ,
  57   57  and filling in the remaining categories from the locale
  58   58  .IR base .
  59   59  When
  60      -.B newlocale
       60 +.B newlocale()
  61   61  returns, callers must no longer use
  62   62  .IR base
  63   63  and assume that
  64   64  .BR freelocale (3C)
  65   65  has been called on it. In addition to locales defined on the system, the
  66   66  following three locales may always be passed in as the string
  67   67  .IR locale :
  68      -
  69      -.sp
  70      -.ne 2
  71      -.na
       68 +.TP
  72   69  "C"
  73      -.ad
  74      -.sp .6
  75      -.RS 4n
  76   70  Specifies the traditional UNIX system behavior.
  77      -.RE
  78      -
  79      -.sp
  80      -.ne 2
  81      -.na
       71 +.TP
  82   72  "POSIX"
  83      -.ad
  84      -.sp .6
  85      -.RS 4n
  86   73  An alternate name fo the locale "C".
  87      -.RE
  88      -
  89      -.sp
  90      -.ne 2
  91      -.na
       74 +.TP
  92   75  ""
  93      -.ad
  94      -.sp .6
  95      -.RS 4n
  96   76  Indicates that the locale should be processed based in the values in the
  97   77  environment. See
  98      -.BR setlocale "(3C) and " environ (5)
       78 +.BR setlocale (3C)
       79 +and 
       80 +.BR environ (5)
  99   81  for more information.
 100      -.RE
 101      -
 102      -
 103      -
 104   82  .LP
 105   83  The value of
 106   84  .I category_mask
 107   85  is a bitwise-inclusive or of the following macros which correspond to categories
 108   86  as defined in
 109      -.BR locale "(5) and " environ" (5):
 110      -
 111      -.sp
 112      -.ne 2
 113      -.na
 114      -LC_CTYPE_MASK
 115      -.ad
 116      -.sp .6
 117      -.RS 4n
       87 +.BR locale (5)
       88 +and
       89 +.BR environ (5):
       90 +.TP
       91 +.B LC_CTYPE_MASK
 118   92  Character classification and case conversion.
 119      -.RE
 120      -
 121      -.sp
 122      -.ne 2
 123      -.na
 124      -LC_NUMERIC_MASK
 125      -.ad
 126      -.sp .6
 127      -.RS 4n
       93 +.TP
       94 +.B LC_NUMERIC_MASK
 128   95  Numeric formatting.
 129      -.RE
 130      -
 131      -.sp
 132      -.ne 2
 133      -.na
 134      -LC_TIME_MASK
 135      -.ad
 136      -.sp .6
 137      -.RS 4n
       96 +.TP
       97 +.B LC_TIME_MASK
 138   98  Date and time formatting.
 139      -.RE
 140      -
 141      -.sp
 142      -.ne 2
 143      -.na
 144      -LC_COLLATE_MASK
 145      -.ad
 146      -.sp .6
 147      -.RS 4n
       99 +.TP
      100 +.B LC_COLLATE_MASK
 148  101  Collation order.
 149      -.RE
 150      -
 151      -.sp
 152      -.ne 2
 153      -.na
 154      -LC_MONETARY_MASK
 155      -.ad
 156      -.sp .6
 157      -.RS 4n
 158      -Monetary formating.
 159      -.RE
 160      -
 161      -.sp
 162      -.ne 2
 163      -.na
 164      -LC_MESSAGES_MASK
 165      -.ad
 166      -.sp .6
 167      -.RS 4n
      102 +.TP
      103 +.B LC_MONETARY_MASK
      104 +Monetary formatting.
      105 +.TP
      106 +.B LC_MESSAGES_MASK
 168  107  Formats of informative and diagnostic messages and interactive responses.
 169      -.RE
 170      -
 171      -.sp
 172      -.ne 2
 173      -.na
 174      -LC_ALL_MASK
 175      -.ad
 176      -.sp .6
 177      -.RS 4n
 178      -Instructs that all the categories defined above, be used.
 179      -.RE
 180      -
      108 +.TP
      109 +.B LC_ALL_MASK
      110 +Mask of all categories.
 181  111  .LP
 182  112  The function
 183  113  .B duplocale()
 184  114  duplicates the locale object specified by
 185  115  .IR loc .
 186  116  If the locale object passed is
 187  117  .BR LC_GLOBAL_LOCALE ,
 188  118  .B duplocale()
 189  119  creates a copy of the current global locale as defined through calls to
 190  120  .BR setlocale (3C).
 191      -
 192  121  .LP
 193  122  The function
 194  123  .B freelocale()
 195  124  removes and releases all resources associated with the locale object
 196  125  .IR loc .
 197  126  Programs must not call
 198  127  .B freelocale()
 199  128  on
 200  129  .BR LC_GLOBAL_LOCALE .
 201      -
 202  130  .SH RETURN VALUES
 203      -
      131 +.LP
 204  132  On success, the functions
 205  133  .B newlocale()
 206  134  and
 207  135  .B duplocale()
 208  136  return a new locale object that can be used with functions that take a
 209  137  .BR locale_t .
 210  138  Locale objects created this way should be freed with
 211  139  .BR freelocale() .
 212  140  On error, the functions
 213  141  .B newlocale()
 214  142  and
 215  143  .B duplocale()
 216  144  return
 217  145  .BR (locale_t) 0
 218  146  and
 219  147  .B errno
 220  148  is set to indicate the error. The
 221  149  .B freelocale()
 222  150  function does not set
 223  151  .B errno.
 224      -
 225  152  .SH ERRORS
 226  153  .LP
 227  154  The
 228  155  .B newlocale()
 229  156  and
 230  157  .B duplocale()
 231  158  functions will fail if:
 232      -.sp
 233      -.ne 2
 234      -.na
      159 +.TP
 235  160  .B ENOMEM
 236      -.ad
 237      -.RS 10n
 238  161  Insufficient memory was available to create the locale object or to load the
 239  162  requested locale data.
 240      -.RE
 241      -
 242  163  .LP
 243  164  The
 244  165  .B newlocale()
 245  166  function will fail if:
 246      -.sp
 247      -.ne 2
 248      -.na
      167 +.TP
 249  168  .B EINVAL
 250      -.ad
 251      -.RS 10n
 252  169  An unknown bit is specified in
 253  170  .IR category_mask .
 254      -.RE
 255      -.sp
 256      -.ne 2
 257      -.na
      171 +.TP
 258  172  .B ENOENT
 259      -.ad
 260      -.RS 10n
 261  173  Locale data was not found for a category specified in
 262      -.IR category_mask .
 263      -.RE
 264      -
 265  174  .SH ATTRIBUTES
 266      -.sp
 267  175  .TS
 268  176  box;
 269  177  c | c
 270  178  l | l .
 271  179  ATTRIBUTE TYPE  ATTRIBUTE VALUE
 272  180  _
 273  181  Interface Stability     Standard
 274  182  _
 275  183  MT-Level        Safe
 276  184  .TE
 277  185  
 278  186  .SH SEE ALSO
 279  187  .BR locale (1),
 280  188  .BR setlocale (3C),
 281  189  .BR uselocale (3C),
 282  190  .BR environ (5),
 283  191  .BR locale (5)
    
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX