1LOCALEDEF(1P)              POSIX Programmer's Manual             LOCALEDEF(1P)
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       localedef — define locale environment
14

SYNOPSIS

16       localedef [−c] [−f charmap] [−i sourcefile] [−u code_set_name] name
17

DESCRIPTION

19       The localedef utility shall convert source definitions for locale cate‐
20       gories into a format usable by the functions and utilities whose opera‐
21       tional behavior is determined by the setting of the locale  environment
22       variables defined in the Base Definitions volume of POSIX.1‐2008, Chap‐
23       ter 7, Locale.  It is implementation-defined  whether  users  have  the
24       capability  to create new locales, in addition to those supplied by the
25       implementation. If the symbolic constant POSIX2_LOCALEDEF  is  defined,
26       the  system  supports  the  creation of new locales.  On XSI-conformant
27       systems, the symbolic constant POSIX2_LOCALEDEF shall be defined.
28
29       The utility shall read source definitions for one or more locale  cate‐
30       gories  belonging  to  the  same  locale  from the file named in the −i
31       option (if specified) or from standard input.
32
33       The name operand identifies the target locale. The utility  shall  sup‐
34       port  the  creation of public, or generally accessible locales, as well
35       as private, or restricted-access locales. Implementations may  restrict
36       the  capability to create or modify public locales to users with appro‐
37       priate privileges.
38
39       Each category source definition shall be identified by the  correspond‐
40       ing  environment  variable  name and terminated by an END category-name
41       statement. The following categories shall be  supported.  In  addition,
42       the input may contain source for implementation-defined categories.
43
44       LC_CTYPE  Defines character classification and case conversion.
45
46       LC_COLLATE
47                 Defines collation rules.
48
49       LC_MONETARY
50                 Defines the format and symbols used in formatting of monetary
51                 information.
52
53       LC_NUMERIC
54                 Defines the decimal delimiter, grouping, and grouping  symbol
55                 for non-monetary numeric editing.
56
57       LC_TIME   Defines the format and content of date and time information.
58
59       LC_MESSAGES
60                 Defines  the  format  and  values of affirmative and negative
61                 responses.
62

OPTIONS

64       The localedef utility shall conform to the Base Definitions  volume  of
65       POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.
66
67       The following options shall be supported:
68
69       −c        Create  permanent  output  even if warning messages have been
70                 issued.
71
72       −f charmap
73                 Specify the pathname of a file containing a mapping of  char‐
74                 acter symbols and collating element symbols to actual charac‐
75                 ter encodings.  The format of the charmap is described in the
76                 Base Definitions volume of POSIX.1‐2008, Section 6.4, Charac‐
77                 ter Set Description File.  The application shall ensure  that
78                 this  option  is specified if symbolic names (other than col‐
79                 lating symbols defined in  a  collating-symbol  keyword)  are
80                 used.  If  the  −f  option is not present, an implementation-
81                 defined character mapping shall be used.
82
83       −i inputfile
84                 The pathname of a file containing the source definitions.  If
85                 this  option is not present, source definitions shall be read
86                 from standard input. The format of the inputfile is described
87                 in  the Base Definitions volume of POSIX.1‐2008, Section 7.3,
88                 Locale Definition.
89
90       −u code_set_name
91                 Specify the name of a codeset used as the target  mapping  of
92                 character  symbols and collating element symbols whose encod‐
93                 ing values are defined in terms of  the  ISO/IEC 10646‐1:2000
94                 standard position constant values.
95

OPERANDS

97       The following operand shall be supported:
98
99       name      Identifies  the  locale;  see  the Base Definitions volume of
100                 POSIX.1‐2008, Chapter 7, Locale for a description of the  use
101                 of  this name. If the name contains one or more <slash> char‐
102                 acters, name shall be interpreted as  a  pathname  where  the
103                 created  locale definitions shall be stored. If name does not
104                 contain any <slash> characters,  the  interpretation  of  the
105                 name  is  implementation-defined and the locale shall be pub‐
106                 lic. The ability to create public locales in this way may  be
107                 restricted to users with appropriate privileges. (As a conse‐
108                 quence of specifying one name,  although  several  categories
109                 can  be processed in one execution, only categories belonging
110                 to the same locale can be processed.)
111

STDIN

113       Unless the −i option is specified, the standard input shall be  a  text
114       file  containing  one  or  more  locale category source definitions, as
115       described in the Base Definitions volume of POSIX.1‐2008, Section  7.3,
116       Locale Definition.  When lines are continued using the escape character
117       mechanism, there is no limit to the length of the accumulated continued
118       line.
119

INPUT FILES

121       The character set mapping file specified as the charmap option-argument
122       is described in the Base Definitions volume  of  POSIX.1‐2008,  Section
123       6.4, Character Set Description File.  If a locale category source defi‐
124       nition contains a copy statement, as defined in  the  Base  Definitions
125       volume of POSIX.1‐2008, Chapter 7, Locale, and the copy statement names
126       a valid, existing locale, then localedef shall behave as if the  source
127       definition  had  contained  a  valid category source definition for the
128       named locale.
129

ENVIRONMENT VARIABLES

131       The following environment  variables  shall  affect  the  execution  of
132       localedef:
133
134       LANG      Provide  a  default  value for the internationalization vari‐
135                 ables that are unset or null. (See the Base Definitions  vol‐
136                 ume  of POSIX.1‐2008, Section 8.2, Internationalization Vari‐
137                 ables for the precedence  of  internationalization  variables
138                 used to determine the values of locale categories.)
139
140       LC_ALL    If  set  to  a non-empty string value, override the values of
141                 all the other internationalization variables.
142
143       LC_COLLATE
144                 (This variable has no affect on localedef; the  POSIX  locale
145                 is used for this category.)
146
147       LC_CTYPE  Determine  the  locale for the interpretation of sequences of
148                 bytes of text data as characters (for example, single-byte as
149                 opposed  to  multi-byte  characters  in  arguments  and input
150                 files). This variable has no  affect  on  the  processing  of
151                 localedef  input data; the POSIX locale is used for this pur‐
152                 pose, regardless of the value of this variable.
153
154       LC_MESSAGES
155                 Determine the locale that should be used to affect the format
156                 and  contents  of  diagnostic  messages  written  to standard
157                 error.
158
159       NLSPATH   Determine the location of message catalogs for the processing
160                 of LC_MESSAGES.
161

ASYNCHRONOUS EVENTS

163       Default.
164

STDOUT

166       The  utility  shall report all categories successfully processed, in an
167       unspecified format.
168

STDERR

170       The standard error shall be used only for diagnostic messages.
171

OUTPUT FILES

173       The format of the created output is unspecified. If  the  name  operand
174       does  not  contain  a  <slash>, the existence of an output file for the
175       locale is unspecified.
176

EXTENDED DESCRIPTION

178       When the −u option is used, the code_set_name option-argument shall  be
179       interpreted as an implementation-defined name of a codeset to which the
180       ISO/IEC 10646‐1:2000 standard position constant values  shall  be  con‐
181       verted    via    an    implementation-defined    method.    Both    the
182       ISO/IEC 10646‐1:2000 standard position constant values and  other  for‐
183       mats (decimal, hexadecimal, or octal) shall be valid as encoding values
184       within the charmap file. The codeset represented by the implementation-
185       defined  name  can  be any codeset that is supported by the implementa‐
186       tion.
187
188       When   conflicts   occur   between   the   charmap   specification   of
189       <code_set_name>,  <mb_cur_max>, or <mb_cur_min> and the implementation-
190       defined interpretation of these respective items for the codeset repre‐
191       sented  by the −u option-argument code_set_name, the result is unspeci‐
192       fied.
193
194       When conflicts occur between the charmap encoding values specified  for
195       symbolic  names  of  characters  of  the portable character set and the
196       implementation-defined assignment of  character  encoding  values,  the
197       result is unspecified.
198
199       If  a non-printable character in the charmap has a width specified that
200       is not −1, the result will be undefined.
201

EXIT STATUS

203       The following exit values shall be returned:
204
205        0    No errors occurred and the locales were successfully created.
206
207        1    Warnings occurred and the locales were successfully created.
208
209        2    The locale specification exceeded implementation  limits  or  the
210             coded character set or sets used were not supported by the imple‐
211             mentation, and no locale was created.
212
213        3    The capability to create new locales  is  not  supported  by  the
214             implementation.
215
216       >3    Warnings or errors occurred and no output was created.
217

CONSEQUENCES OF ERRORS

219       If an error is detected, no permanent output shall be created.
220
221       If  warnings  occur, permanent output shall be created if the −c option
222       was specified. The following conditions shall cause warning messages to
223       be issued:
224
225        *  If  a  symbolic  name not found in the charmap file is used for the
226           descriptions of the LC_CTYPE or LC_COLLATE  categories  (for  other
227           categories, this shall be an error condition).
228
229        *  If  the  number  of  operands  to  the  order  keyword  exceeds the
230           {COLL_WEIGHTS_MAX} limit.
231
232        *  If optional  keywords  not  supported  by  the  implementation  are
233           present in the source.
234
235       Other implementation-defined conditions may also cause warnings.
236
237       The following sections are informative.
238

APPLICATION USAGE

240       The charmap definition is optional, and is contained outside the locale
241       definition. This allows both completely self-defined source files,  and
242       generic sources (applicable to more than one codeset). To aid portabil‐
243       ity, all charmap definitions must use the same symbolic names  for  the
244       portable  character set. As explained in the Base Definitions volume of
245       POSIX.1‐2008, Section 6.4, Character Set Description File, it is imple‐
246       mentation-defined  whether  or  not  users  or applications can provide
247       additional character set description files. Therefore,  the  −f  option
248       might be operable only when an implementation-defined charmap is named.
249

EXAMPLES

251       None.
252

RATIONALE

254       The output produced by the localedef utility is implementation-defined.
255       The name operand is used to identify the specific locale. (As a  conse‐
256       quence,  although several categories can be processed in one execution,
257       only categories belonging to the same locale can be processed.)
258

FUTURE DIRECTIONS

260       None.
261

SEE ALSO

263       locale
264
265       The Base Definitions volume of POSIX.1‐2008, Section 6.4, Character Set
266       Description  File, Chapter 7, Locale, Chapter 8, Environment Variables,
267       Section 12.2, Utility Syntax Guidelines
268
270       Portions of this text are reprinted and reproduced in  electronic  form
271       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
272       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
273       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
274       cal and Electronics Engineers,  Inc  and  The  Open  Group.   (This  is
275       POSIX.1-2008  with  the  2013  Technical Corrigendum 1 applied.) In the
276       event of any discrepancy between this version and the original IEEE and
277       The  Open Group Standard, the original IEEE and The Open Group Standard
278       is the referee document. The original Standard can be  obtained  online
279       at http://www.unix.org/online.html .
280
281       Any  typographical  or  formatting  errors that appear in this page are
282       most likely to have been introduced during the conversion of the source
283       files  to  man page format. To report such errors, see https://www.ker
284       nel.org/doc/man-pages/reporting_bugs.html .
285
286
287
288IEEE/The Open Group                  2013                        LOCALEDEF(1P)
Impressum