man1/localedef.1

   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 2017-09-15 "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 \-\-list\-archive"
  45 .RI [ options ]
  46 .br
  47 .B "localedef \-\-delete\-from\-archive"
  48 .RI [ options ]
  49 .IR localename " ..."
  50 .br
  51 .B "localedef \-\-add\-to\-archive"
  52 .RI [ options ]
  53 .IR compiledpath
  54 .br
  55 .B "localedef \-\-version"
  56 .br
  57 .B "localedef \-\-help"
  58 .br
  59 .B "localedef \-\-usage"
  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 \-\-delete\-from\-archive
 132 Delete the named locales from the locale archive file.
 133 .TP
 134 .B \-\-list\-archive
 135 List the locales contained in the locale archive file.
 136 .TP
 137 .B \-\-add\-to\-archive
 138 Add the
 139 .I compiledpath
 140 directories to the locale archive file.
 141 The directories should have been created by previous runs of
 142 .BR localedef ,
 143 using
 144 .BR \-\-no\-archive .
 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 .BI \-\-prefix= pathname
 216 Set the prefix to be prepended to the full archive pathname.
 217 By default, the prefix is empty.
 218 Setting the prefix to
 219 .IR foo ,
 220 the archive would be placed in
 221 .IR foo/usr/lib/locale/locale-archive .
 222 .TP
 223 .BR \-c ", " \-\-force
 224 Write the output files even if warnings were generated about the input
 225 file.
 226 .TP
 227 .BR \-v ", " \-\-verbose
 228 Generate extra warnings about errors that are normally ignored.
 229 .TP
 230 .B \-\-quiet
 231 Suppress all notifications and warnings, and report only fatal errors.
 232 .TP
 233 .B \-\-posix
 234 Conform strictly to POSIX.  Implies
 235 .BR \-\-verbose .
 236 This option currently has no other effect.
 237 POSIX conformance is assumed if the environment variable
 238 .B POSIXLY_CORRECT
 239 is set.
 240 .TP
 241 .B \-\-replace
 242 Replace a locale in the locale archive file.
 243 Without this option, if the locale is in the archive file already,
 244 an error occurs.
 245 .TP
 246 .B \-\-no\-archive
 247 Do not use the locale archive file, instead create
 248 .I outputpath
 249 as a subdirectory in the same directory as the locale archive file,
 250 and create separate output files for locale categories in it.
 251 This is helpful to prevent system locale archive updates from overwriting
 252 custom locales created with
 253 .BR localedef .
 254 .TP
 255 .BR \-? ", " \-\-help
 256 Print a usage summary and exit.
 257 Also prints the default paths used by
 258 .BR localedef .
 259 .TP
 260 .B "\-\-usage"
 261 Print a short usage summary and exit.
 262 .TP
 263 .BR \-V ", " \-\-version
 264 Print the version number, license, and disclaimer of warranty for
 265 .BR localedef .
 266 .SH EXIT STATUS
 267 One of the following exit values can be returned by
 268 .BR localedef :
 269 .RS 3
 270 .TP 10
 271 .B 0
 272 Command completed successfully.
 273 .TP
 274 .B 1
 275 Warnings or errors occurred, output files were written.
 276 .TP
 277 .B 4
 278 Errors encountered, no output created.
 279 .RE
 280 .SH ENVIRONMENT
 281 .TP
 282 .B POSIXLY_CORRECT
 283 The
 284 .B \-\-posix
 285 flag is assumed if this environment variable is set.
 286 .TP
 287 .B I18NPATH
 288 A colon-separated list of search directories for files.
 289 .SH FILES
 290 .TP
 291 .I /usr/share/i18n/charmaps
 292 Usual default character map path.
 293 .TP
 294 .I /usr/share/i18n/locales
 295 Usual default path for locale definition files.
 296 .TP
 297 .I /usr/share/i18n/repertoiremaps
 298 Usual default repertoire map path.
 299 .TP
 300 .I /usr/lib/locale/locale-archive
 301 Usual default locale archive location.
 302 .TP
 303 .I /usr/lib/locale
 304 Usual default path for compiled individual locale data files.
 305 .TP
 306 .I outputpath/LC_ADDRESS
 307 An output file that contains information about formatting of
 308 addresses and geography-related items.
 309 .TP
 310 .I outputpath/LC_COLLATE
 311 An output file that contains information about the rules for comparing
 312 strings.
 313 .TP
 314 .I outputpath/LC_CTYPE
 315 An output file that contains information about character classes.
 316 .TP
 317 .I outputpath/LC_IDENTIFICATION
 318 An output file that contains metadata about the locale.
 319 .TP
 320 .I outputpath/LC_MEASUREMENT
 321 An output file that contains information about locale measurements
 322 (metric versus US customary).
 323 .TP
 324 .I outputpath/LC_MESSAGES/SYS_LC_MESSAGES
 325 An output file that contains information about the language messages
 326 should be printed in, and what an affirmative or negative answer looks
 327 like.
 328 .TP
 329 .I outputpath/LC_MONETARY
 330 An output file that contains information about formatting of monetary
 331 values.
 332 .TP
 333 .I outputpath/LC_NAME
 334 An output file that contains information about salutations for persons.
 335 .TP
 336 .I outputpath/LC_NUMERIC
 337 An output file that contains information about formatting of nonmonetary
 338 numeric values.
 339 .TP
 340 .I outputpath/LC_PAPER
 341 An output file that contains information about settings related to
 342 standard paper size.
 343 .TP
 344 .I outputpath/LC_TELEPHONE
 345 An output file that contains information about formats to be used with
 346 telephone services.
 347 .TP
 348 .I outputpath/LC_TIME
 349 An output file that contains information about formatting of data and
 350 time values.
 351 .SH CONFORMING TO
 352 POSIX.1-2008.
 353 .SH EXAMPLE
 354 Compile the locale files for Finnish in the UTF\-8 character set
 355 and add it to the default locale archive with the name
 356 .BR fi_FI.UTF\-8 :
 357 .PP
 358 .in +4n
 359 .EX
 360 localedef \-f UTF\-8 \-i fi_FI fi_FI.UTF\-8
 361 .EE
 362 .in
 363 .PP
 364 The next example does the same thing, but generates files into the
 365 .I fi_FI.UTF\-8
 366 directory which can then be used by programs when the environment
 367 variable
 368 .B LOCPATH
 369 is set to the current directory (note that the last argument must
 370 contain a slash):
 371 .PP
 372 .in +4n
 373 .EX
 374 localedef \-f UTF\-8 \-i fi_FI ./fi_FI.UTF\-8
 375 .EE
 376 .in
 377 .SH SEE ALSO
 378 .BR locale (1),
 379 .BR charmap (5),
 380 .BR locale (5),
 381 .BR repertoiremap (5),
 382 .BR locale (7)