Debian Codegraph @

upstream/debian-unstable/man1/localedef.1

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