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.

Split Close
Expand all
Collapse all
          --- old/usr/src/man/man3c/newlocale.3c
          +++ new/usr/src/man/man3c/newlocale.3c
   1      -'\" te
   2    1  .\"
   3    2  .\" This file and its contents are supplied under the terms of the
   4    3  .\" Common Development and Distribution License ("CDDL"), version 1.0.
   5    4  .\" You may only use this file in accordance with the terms of version
   6    5  .\" 1.0 of the CDDL.
   7    6  .\"
   8    7  .\" A full copy of the text of the CDDL should have accompanied this
   9    8  .\" source.  A copy of the CDDL is also available via the Internet at
  10    9  .\" http://www.illumos.org/license/CDDL.
  11   10  .\"
  12   11  .\"
  13   12  .\" Copyright (c) 2014 Joyent, Inc.  All rights reserved.
  14   13  .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
  15   14  .\"
  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)
       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
  39   45  and functions that take arguments of type
  40      -.BR locale_t .
  41      -.LP
  42      -The function
  43      -.B newlocale()
       46 +.Vt locale_t .
       47 +.Lp
       48 +The
       49 +.Fn newlocale
       50 +function
  44   51  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
       52 +existing locale object; the new locale object will be a replacement for the
  46   53  modified locale object. To create a new locale, the argument
  47      -.I base
       54 +.Fa base
  48   55  should be passed the special argument
  49      -.RB ( locale_t )0.
       56 +.Po Vt locale_t Pc 0.
  50   57  This will use a copy of the current global locale as a starting point. To modify
  51   58  an existing locale object, it should be passed in as the argument
  52      -.IR base .
       59 +.Fa base .
  53   60  The new locale object is constructed by taking the categories specified in
  54      -.I category_mask
       61 +.Fa category_mask
  55   62  from the locale specified by the string
  56      -.IR locale ,
       63 +.Fa locale ,
  57   64  and filling in the remaining categories from the locale
  58      -.IR base .
       65 +.Fa base .
  59   66  When
  60      -.B newlocale()
       67 +.Fn newlocale
  61   68  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
       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
  66   75  following three locales may always be passed in as the string
  67      -.IR locale :
  68      -.TP
  69      -"C"
       76 +.Fa locale :
       77 +.Bl -tag -offset indent -width Dq
       78 +.It \\"C\\"
  70   79  Specifies the traditional UNIX system behavior.
  71      -.TP
  72      -"POSIX"
       80 +.It \\"POSIX\\"
  73   81  An alternate name fo the locale "C".
  74      -.TP
  75      -""
       82 +.It \\"\\"
  76   83  Indicates that the locale should be processed based in the values in the
  77   84  environment. See
  78      -.BR setlocale (3C)
       85 +.Xr setlocale 3C
  79   86  and
  80      -.BR environ (5)
       87 +.Xr environ 5
  81   88  for more information.
  82      -.LP
       89 +.El
       90 +.Lp
  83   91  The value of
  84      -.I category_mask
       92 +.Fa category_mask
  85   93  is a bitwise-inclusive or of the following macros which correspond to categories
  86   94  as defined in
  87      -.BR locale (5)
       95 +.Xr locale 5
  88   96  and
  89      -.BR environ (5):
  90      -.TP
  91      -.B LC_CTYPE_MASK
       97 +.Xr environ 5 :
       98 +.Bl -tag -offset indent -width Dv
       99 +.It Dv LC_CTYPE_MASK
  92  100  Character classification and case conversion.
  93      -.TP
  94      -.B LC_NUMERIC_MASK
      101 +.It Dv LC_NUMERIC_MASK
  95  102  Numeric formatting.
  96      -.TP
  97      -.B LC_TIME_MASK
      103 +.It Dv LC_TIME_MASK
  98  104  Date and time formatting.
  99      -.TP
 100      -.B LC_COLLATE_MASK
      105 +.It Dv LC_COLLATE_MASK
 101  106  Collation order.
 102      -.TP
 103      -.B LC_MONETARY_MASK
      107 +.It Dv LC_MONETARY_MASK
 104  108  Monetary formatting.
 105      -.TP
 106      -.B LC_MESSAGES_MASK
      109 +.It Dv LC_MESSAGES_MASK
 107  110  Formats of informative and diagnostic messages and interactive responses.
 108      -.TP
 109      -.B LC_ALL_MASK
      111 +.It Dv LC_ALL_MASK
 110  112  Mask of all categories.
 111      -.LP
 112      -The function
 113      -.B duplocale()
 114      -duplicates the locale object specified by
 115      -.IR loc .
      113 +.El
      114 +.Lp
      115 +The
      116 +.Fn duplocale
      117 +function duplicates the locale object specified by
      118 +.Fa loc .
 116  119  If the locale object passed is
 117      -.BR LC_GLOBAL_LOCALE ,
 118      -.B duplocale()
      120 +.Dv LC_GLOBAL_LOCALE ,
      121 +.Fn duplocale
 119  122  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 .
      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 .
 126  129  Programs must not call
 127      -.B freelocale()
      130 +.Fn freelocale
 128  131  on
 129      -.BR LC_GLOBAL_LOCALE .
 130      -.SH RETURN VALUES
 131      -.LP
      132 +.Dv LC_GLOBAL_LOCALE .
      133 +.Sh RETURN VALUES
 132  134  On success, the functions
 133      -.B newlocale()
      135 +.Fn newlocale
 134  136  and
 135      -.B duplocale()
      137 +.Fn duplocale
 136  138  return a new locale object that can be used with functions that take a
 137      -.BR locale_t .
      139 +.Vt locale_t .
 138  140  Locale objects created this way should be freed with
 139      -.BR freelocale() .
      141 +.Fn freelocale .
 140  142  On error, the functions
 141      -.B newlocale()
      143 +.Fn newlocale
 142  144  and
 143      -.B duplocale()
      145 +.Fn duplocale
 144  146  return
 145      -.BR (locale_t) 0
      147 +.Po Vt locale_t Pc 0
 146  148  and
 147      -.B errno
      149 +.Va errno
 148  150  is set to indicate the error. The
 149      -.B freelocale()
      151 +.Fn freelocale
 150  152  function does not set
 151      -.B errno.
 152      -.SH ERRORS
 153      -.LP
      153 +.Va errno .
      154 +.Sh ERRORS
 154  155  The
 155      -.B newlocale()
      156 +.Fn newlocale
 156  157  and
 157      -.B duplocale()
      158 +.Fn duplocale
 158  159  functions will fail if:
 159      -.TP
 160      -.B ENOMEM
      160 +.Bl -tag -width Er
      161 +.It Er ENOMEM
 161  162  Insufficient memory was available to create the locale object or to load the
 162  163  requested locale data.
 163      -.LP
      164 +.El
      165 +.Lp
 164  166  The
 165      -.B newlocale()
      167 +.Fn newlocale
 166  168  function will fail if:
 167      -.TP
 168      -.B EINVAL
      169 +.Bl -tag -width Er
      170 +.It Er EINVAL
 169  171  An unknown bit is specified in
 170      -.IR category_mask .
 171      -.TP
 172      -.B ENOENT
      172 +.Fa category_mask .
      173 +.It Er ENOENT
 173  174  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)
      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 .
    
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX