Debian Codegraph @

upstream/debian-trixie/man1/localedef.1

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