| blob | 3b9f8adf1b858d74eaf58ce6b97063df2e8c5c47 |
1 .\" Copyright (C) 2001 Richard Braakman
2 .\" Copyright (C) 2004 Alastair McKinstry
3 .\" Copyright (C) 2005 Lars Wirzenius
4 .\" Copyright (C) 2014 Marko Myllynen
5 .\"
6 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
7 .\" This is free documentation; you can redistribute it and/or
8 .\" modify it under the terms of the GNU General Public License as
9 .\" published by the Free Software Foundation; either version 2 of
10 .\" the License, or (at your option) any later version.
11 .\"
12 .\" The GNU General Public License's references to "object code"
13 .\" and "executables" are to be interpreted as the output of any
14 .\" document formatting or typesetting system, including
15 .\" intermediate and printed output.
16 .\"
17 .\" This manual is distributed in the hope that it will be useful,
18 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
19 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 .\" GNU General Public License for more details.
21 .\"
22 .\" You should have received a copy of the GNU General Public
23 .\" License along with this manual; if not, see
24 .\" <http://www.gnu.org/licenses/>.
25 .\" %%%LICENSE_END
26 .\"
27 .\" This manual page was initially written by Richard Braakman
28 .\" on behalf of the Debian GNU/Linux Project and anyone else
29 .\" who wants it. It was amended by Alastair McKinstry to
30 .\" explain new ISO 14652 elements, and amended further by
31 .\" Lars Wirzenius to document new functionality (as of GNU
32 .\" C library 2.3.5).
33 .\"
34 .TH LOCALEDEF 1 2021-03-22 "Linux" "Linux User Manual"
35 .SH NAME
36 localedef \- compile locale definition files
37 .SH SYNOPSIS
38 .ad l
39 .nh
40 .B localedef
41 .RI [ options ]
42 .I outputpath
43 .br
44 .B "localedef \-\-add\-to\-archive"
45 .RI [ options ]
46 .I compiledpath
47 .br
48 .B "localedef \-\-delete\-from\-archive"
49 .RI [ options ]
50 .IR localename " ..."
51 .br
52 .B "localedef \-\-list\-archive"
53 .RI [ options ]
54 .br
55 .B "localedef \-\-help"
56 .br
57 .B "localedef \-\-usage"
58 .br
59 .B "localedef \-\-version"
60 .ad b
61 .hy
62 .SH DESCRIPTION
63 The
64 .B localedef
65 program reads the indicated
66 .I charmap
67 and
68 .I input
69 files, compiles them to a binary form quickly usable by the
70 locale functions in the C library
71 .RB ( setlocale (3),
72 .BR localeconv (3),
73 etc.), and places the output in
74 .IR outputpath .
75 .PP
76 The
77 .I outputpath
78 argument is interpreted as follows:
79 .IP * 3
80 If
81 .I outputpath
82 contains a slash character ('/'), it is interpreted as the name of the
83 directory where the output definitions are to be stored.
84 In this case, there is a separate output file for each locale category
85 .RI ( LC_TIME ,
86 .IR LC_NUMERIC ,
87 and so on).
88 .IP *
89 If the
90 .B \-\-no\-archive
91 option is used,
92 .I outputpath
93 is the name of a subdirectory in
94 .I /usr/lib/locale
95 where per-category compiled files are placed.
96 .IP *
97 Otherwise,
98 .I outputpath
99 is the name of a locale and the compiled locale data is added to the
100 archive file
101 .IR /usr/lib/locale/locale\-archive .
102 A locale archive is a memory-mapped file which contains all the
103 system-provided locales;
104 it is used by all localized programs when the environment variable
105 .B LOCPATH
106 is not set.
107 .PP
108 In any case,
109 .B localedef
110 aborts if the directory in which it tries to write locale files has
111 not already been created.
112 .PP
113 If no
114 .I charmapfile
115 is given, the value
116 .I ANSI_X3.4\-1968
117 (for ASCII) is used by default.
118 If no
119 .I inputfile
120 is given, or if it is given as a dash
121 (\-),
122 .B localedef
123 reads from standard input.
124 .SH OPTIONS
125 .SS Operation-selection options
126 A few options direct
127 .B localedef
128 to do something other than compile locale definitions.
129 Only one of these options should be used at a time.
130 .TP
131 .B \-\-add\-to\-archive
132 Add the
133 .I compiledpath
134 directories to the locale archive file.
135 The directories should have been created by previous runs of
136 .BR localedef ,
137 using
138 .BR \-\-no\-archive .
139 .TP
140 .B \-\-delete\-from\-archive
141 Delete the named locales from the locale archive file.
142 .TP
143 .B \-\-list\-archive
144 List the locales contained in the locale archive file.
145 .SS Other options
146 Some of the following options are sensible only for certain operations;
147 generally, it should be self-evident which ones.
148 Notice that
149 .B \-f
150 and
151 .B \-c
152 are reversed from what you might expect; that is,
153 .B \-f
154 is not the same as
155 .BR \-\-force .
156 .TP
157 .BI \-f " charmapfile" "\fR, \fP\-\-charmap=" charmapfile
158 Specify the file that defines the character set
159 that is used by the input file.
160 If
161 .I charmapfile
162 contains a slash character ('/'),
163 it is interpreted as the name of the character map.
164 Otherwise, the file is sought in the current directory
165 and the default directory for character maps.
166 If the environment variable
167 .B I18NPATH
168 is set,
169 .I $I18NPATH/charmaps/
170 and
171 .I $I18NPATH/
172 are also searched after the current directory.
173 The default directory for character maps is printed by
174 .BR "localedef \-\-help" .
175 .TP
176 .BI \-i " inputfile" "\fR, \fP\-\-inputfile=" inputfile
177 Specify the locale definition file to compile.
178 The file is sought in the current directory
179 and the default directory for locale definition files.
180 If the environment variable
181 .B I18NPATH
182 is set,
183 .I $I18NPATH/locales/
184 and
185 .I $I18NPATH
186 are also searched after the current directory.
187 The default directory for locale definition files is printed by
188 .BR "localedef \-\-help" .
189 .TP
190 .BI \-u " repertoirefile" "\fR, \fP\-\-repertoire\-map=" repertoirefile
191 Read mappings from symbolic names to Unicode code points from
192 .IR repertoirefile .
193 If
194 .I repertoirefile
195 contains a slash character ('/'),
196 it is interpreted as the pathname of the repertoire map.
197 Otherwise, the file is sought in the current directory
198 and the default directory for repertoire maps.
199 If the environment variable
200 .B I18NPATH
201 is set,
202 .I $I18NPATH/repertoiremaps/
203 and
204 .I $I18NPATH
205 are also searched after the current directory.
206 The default directory for repertoire maps is printed by
207 .BR "localedef \-\-help" .
208 .TP
209 .BI \-A " aliasfile" "\fR, \fP\-\-alias\-file=" aliasfile
210 Use
211 .I aliasfile
212 to look up aliases for locale names.
213 There is no default aliases file.
214 .TP
215 .BR \-c ", " \-\-force
216 Write the output files even if warnings were generated about the input
217 file.
218 .TP
219 .BR \-v ", " \-\-verbose
220 Generate extra warnings about errors that are normally ignored.
221 .TP
222 .B \-\-big\-endian
223 Generate big-endian output.
224 .TP
225 .B \-\-little\-endian
226 Generate little-endian output.
227 .TP
228 .B \-\-no\-archive
229 Do not use the locale archive file, instead create
230 .I outputpath
231 as a subdirectory in the same directory as the locale archive file,
232 and create separate output files for locale categories in it.
233 This is helpful to prevent system locale archive updates from overwriting
234 custom locales created with
235 .BR localedef .
236 .TP
237 .B \-\-no\-hard\-links
238 Do not create hard links between installed locales.
239 .TP
240 .BI \-\-no\-warnings= warnings
241 Comma-separated list of warnings to disable.
242 Supported warnings are
243 .I ascii
244 and
245 .IR intcurrsym .
246 .TP
247 .B \-\-posix
248 Conform strictly to POSIX.
249 Implies
250 .BR \-\-verbose .
251 This option currently has no other effect.
252 POSIX conformance is assumed if the environment variable
253 .B POSIXLY_CORRECT
254 is set.
255 .TP
256 .BI \-\-prefix= pathname
257 Set the prefix to be prepended to the full archive pathname.
258 By default, the prefix is empty.
259 Setting the prefix to
260 .IR foo ,
261 the archive would be placed in
262 .IR foo/usr/lib/locale/locale\-archive .
263 .TP
264 .B \-\-quiet
265 Suppress all notifications and warnings, and report only fatal errors.
266 .TP
267 .B \-\-replace
268 Replace a locale in the locale archive file.
269 Without this option, if the locale is in the archive file already,
270 an error occurs.
271 .TP
272 .BI \-\-warnings= warnings
273 Comma-separated list of warnings to enable.
274 Supported warnings are
275 .I ascii
276 and
277 .IR intcurrsym .
278 .TP
279 .BR \-? ", " \-\-help
280 Print a usage summary and exit.
281 Also prints the default paths used by
282 .BR localedef .
283 .TP
284 .B "\-\-usage"
285 Print a short usage summary and exit.
286 .TP
287 .BR \-V ", " \-\-version
288 Print the version number, license, and disclaimer of warranty for
289 .BR localedef .
290 .SH EXIT STATUS
291 One of the following exit values can be returned by
292 .BR localedef :
293 .TP
294 .B 0
295 Command completed successfully.
296 .TP
297 .B 1
298 Warnings or errors occurred, output files were written.
299 .TP
300 .B 4
301 Errors encountered, no output created.
302 .SH ENVIRONMENT
303 .TP
304 .B POSIXLY_CORRECT
305 The
306 .B \-\-posix
307 flag is assumed if this environment variable is set.
308 .TP
309 .B I18NPATH
310 A colon-separated list of search directories for files.
311 .SH FILES
312 .TP
313 .I /usr/share/i18n/charmaps
314 Usual default character map path.
315 .TP
316 .I /usr/share/i18n/locales
317 Usual default path for locale definition files.
318 .TP
319 .I /usr/share/i18n/repertoiremaps
320 Usual default repertoire map path.
321 .TP
322 .I /usr/lib/locale/locale\-archive
323 Usual default locale archive location.
324 .TP
325 .I /usr/lib/locale
326 Usual default path for compiled individual locale data files.
327 .TP
328 .I outputpath/LC_ADDRESS
329 An output file that contains information about formatting of
330 addresses and geography-related items.
331 .TP
332 .I outputpath/LC_COLLATE
333 An output file that contains information about the rules for comparing
334 strings.
335 .TP
336 .I outputpath/LC_CTYPE
337 An output file that contains information about character classes.
338 .TP
339 .I outputpath/LC_IDENTIFICATION
340 An output file that contains metadata about the locale.
341 .TP
342 .I outputpath/LC_MEASUREMENT
343 An output file that contains information about locale measurements
344 (metric versus US customary).
345 .TP
346 .I outputpath/LC_MESSAGES/SYS_LC_MESSAGES
347 An output file that contains information about the language messages
348 should be printed in, and what an affirmative or negative answer looks
349 like.
350 .TP
351 .I outputpath/LC_MONETARY
352 An output file that contains information about formatting of monetary
353 values.
354 .TP
355 .I outputpath/LC_NAME
356 An output file that contains information about salutations for persons.
357 .TP
358 .I outputpath/LC_NUMERIC
359 An output file that contains information about formatting of nonmonetary
360 numeric values.
361 .TP
362 .I outputpath/LC_PAPER
363 An output file that contains information about settings related to
364 standard paper size.
365 .TP
366 .I outputpath/LC_TELEPHONE
367 An output file that contains information about formats to be used with
368 telephone services.
369 .TP
370 .I outputpath/LC_TIME
371 An output file that contains information about formatting of data and
372 time values.
373 .SH CONFORMING TO
374 POSIX.1-2008.
375 .SH EXAMPLES
376 Compile the locale files for Finnish in the UTF\-8 character set
377 and add it to the default locale archive with the name
378 .BR fi_FI.UTF\-8 :
379 .PP
380 .in +4n
381 .EX
382 localedef \-f UTF\-8 \-i fi_FI fi_FI.UTF\-8
383 .EE
384 .in
385 .PP
386 The next example does the same thing, but generates files into the
387 .I fi_FI.UTF\-8
388 directory which can then be used by programs when the environment
389 variable
390 .B LOCPATH
391 is set to the current directory (note that the last argument must
392 contain a slash):
393 .PP
394 .in +4n
395 .EX
396 localedef \-f UTF\-8 \-i fi_FI ./fi_FI.UTF\-8
397 .EE
398 .in
399 .SH SEE ALSO
400 .BR locale (1),
401 .BR charmap (5),
402 .BR locale (5),
403 .BR repertoiremap (5),
404 .BR locale (7)