1NEWLOCALE(3P)              POSIX Programmer's Manual             NEWLOCALE(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10
11

NAME

13       newlocale — create or modify a locale object
14

SYNOPSIS

16       #include <locale.h>
17
18       locale_t newlocale(int category_mask, const char *locale,
19           locale_t base);
20

DESCRIPTION

22       The newlocale() function shall create a new locale object or modify  an
23       existing one.  If the base argument is (locale_t)0, a new locale object
24       shall be created. It is unspecified whether the locale  object  pointed
25       to by base shall be modified, or freed and a new locale object created.
26
27       The category_mask argument specifies the locale categories to be set or
28       modified.  Values for category_mask shall be constructed by a  bitwise-
29       inclusive  OR of the symbolic constants LC_CTYPE_MASK, LC_NUMERIC_MASK,
30       LC_TIME_MASK, LC_COLLATE_MASK, LC_MONETARY_MASK, and  LC_MESSAGES_MASK,
31       or  any of the other implementation-defined LC_*_MASK values defined in
32       <locale.h>.
33
34       For each category with the corresponding bit set in  category_mask  the
35       data from the locale named by locale shall be used. In the case of mod‐
36       ifying an existing locale object, the data from  the  locale  named  by
37       locale  shall  replace the existing data within the locale object. If a
38       completely new locale object is created, the data for all sections  not
39       requested by category_mask shall be taken from the default locale.
40
41       The  following  preset values of locale are defined for all settings of
42       category_mask:
43
44       "POSIX"     Specifies the minimal environment for  C-language  transla‐
45                   tion called the POSIX locale.
46
47       "C"         Equivalent to "POSIX".
48
49       ""          Specifies  an  implementation-defined  native  environment.
50                   This corresponds to the value of the associated environment
51                   variables,  LC_*  and LANG; see the Base Definitions volume
52                   of POSIX.1‐2008, Chapter 7, Locale and Chapter 8,  Environ‐
53                   ment Variables.
54
55       If  the  base  argument is not (locale_t)0 and the newlocale() function
56       call succeeds, the contents of base are unspecified. Applications shall
57       ensure  that  they  stop  using  base as a locale object before calling
58       newlocale().  If the function call fails and the base argument  is  not
59       (locale_t)0, the contents of base shall remain valid and unchanged.
60
61       The  behavior  is  undefined if the base argument is the special locale
62       object LC_GLOBAL_LOCALE, or is not a valid locale object handle and  is
63       not (locale_t)0.
64

RETURN VALUE

66       Upon  successful  completion,  the  newlocale() function shall return a
67       handle which the caller may use on  subsequent  calls  to  duplocale(),
68       freelocale(), and other functions taking a locale_t argument.
69
70       Upon failure, the newlocale() function shall return (locale_t)0 and set
71       errno to indicate the error.
72

ERRORS

74       The newlocale() function shall fail if:
75
76       ENOMEM There is not enough memory available to create the locale object
77              or load the locale data.
78
79       EINVAL The  category_mask  contains a bit that does not correspond to a
80              valid category.
81
82       ENOENT For any of the categories in category_mask, the locale  data  is
83              not available.
84
85       The newlocale() function may fail if:
86
87       EINVAL The locale argument is not a valid string pointer.
88
89       The following sections are informative.
90

EXAMPLES

92   Constructing a Locale Object from Different Locales
93       The  following  example  shows  the  construction of a locale where the
94       LC_CTYPE category data comes from a locale loc1 and the  LC_TIME  cate‐
95       gory data from a locale tok2:
96
97           #include <locale.h>
98           ...
99           locale_t loc, new_loc;
100
101           /* Get the "loc1" data. */
102
103           loc = newlocale (LC_CTYPE_MASK, "loc1", (locale_t)0);
104           if (loc == (locale_t) 0)
105               abort ();
106
107           /* Get the "loc2" data. */
108
109           new_loc = newlocale (LC_TIME_MASK, "loc2", loc);
110           if (new_loc != (locale_t) 0)
111               /* We don t abort if this fails. In this case this
112                  simply used to unchanged locale object. */
113               loc = new_loc;
114
115           ...
116
117   Freeing up a Locale Object
118       The  following  example  shows  a code fragment to free a locale object
119       created by newlocale():
120
121           #include <locale.h>
122           ...
123
124           /* Every locale object allocated with newlocale() should be
125            * freed using freelocale():
126            */
127
128           locale_t loc;
129
130           /* Get the locale. */
131
132           loc = newlocale (LC_CTYPE_MASK | LC_TIME_MASK, "locname", (locale_t)0);
133
134           /* ... Use the locale object ... */
135           ...
136
137           /* Free the locale object resources. */
138           freelocale (loc);
139

APPLICATION USAGE

141       Handles for locale objects created by the newlocale()  function  should
142       either  be released by a corresponding call to freelocale(), or be used
143       as a base locale to another newlocale() call.
144
145       The special locale object LC_GLOBAL_LOCALE must not be passed  for  the
146       base argument, even when returned by the uselocale() function.
147

RATIONALE

149       None.
150

FUTURE DIRECTIONS

152       None.
153

SEE ALSO

155       duplocale(), freelocale(), uselocale()
156
157       The Base Definitions volume of POSIX.1‐2008, Chapter 7, Locale, Chapter
158       8, Environment Variables, <locale.h>
159
161       Portions of this text are reprinted and reproduced in  electronic  form
162       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
163       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
164       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
165       cal and Electronics Engineers,  Inc  and  The  Open  Group.   (This  is
166       POSIX.1-2008  with  the  2013  Technical Corrigendum 1 applied.) In the
167       event of any discrepancy between this version and the original IEEE and
168       The  Open Group Standard, the original IEEE and The Open Group Standard
169       is the referee document. The original Standard can be  obtained  online
170       at http://www.unix.org/online.html .
171
172       Any  typographical  or  formatting  errors that appear in this page are
173       most likely to have been introduced during the conversion of the source
174       files  to  man page format. To report such errors, see https://www.ker
175       nel.org/doc/man-pages/reporting_bugs.html .
176
177
178
179IEEE/The Open Group                  2013                        NEWLOCALE(3P)
Impressum