Provided by: manpages-posix_2017a-2_all bug

PROLOG

       This  manual  page  is part of the POSIX Programmer's Manual.  The Linux implementation of
       this interface may differ (consult the corresponding Linux  manual  page  for  details  of
       Linux behavior), or the interface may not be implemented on Linux.

NAME

       localedef — define locale environment

SYNOPSIS

       localedef [-c] [-f charmap] [-i sourcefile] [-u code_set_name] name

DESCRIPTION

       The localedef utility shall convert source definitions for locale categories into a format
       usable by the functions and utilities whose operational  behavior  is  determined  by  the
       setting  of  the  locale  environment  variables defined in the Base Definitions volume of
       POSIX.1‐2017, Chapter 7, Locale.  It is  implementation-defined  whether  users  have  the
       capability  to create new locales, in addition to those supplied by the implementation. If
       the symbolic constant POSIX2_LOCALEDEF is defined, the system supports the creation of new
       locales.   On  XSI-conformant  systems,  the  symbolic  constant POSIX2_LOCALEDEF shall be
       defined.

       The utility shall read source definitions for one or more locale categories  belonging  to
       the  same  locale  from  the  file  named in the -i option (if specified) or from standard
       input.

       The name operand identifies the target locale. The utility shall support the  creation  of
       public, or generally accessible locales, as well as private, or restricted-access locales.
       Implementations may restrict the capability to create or modify public  locales  to  users
       with appropriate privileges.

       Each  category  source  definition  shall  be  identified by the corresponding environment
       variable name and terminated by an END category-name statement. The  following  categories
       shall  be  supported. In addition, the input may contain source for implementation-defined
       categories.

       LC_CTYPE  Defines character classification and case conversion.

       LC_COLLATE
                 Defines collation rules.

       LC_MONETARY
                 Defines the format and symbols used in formatting of monetary information.

       LC_NUMERIC
                 Defines the decimal delimiter, grouping, and grouping  symbol  for  non-monetary
                 numeric editing.

       LC_TIME   Defines the format and content of date and time information.

       LC_MESSAGES
                 Defines the format and values of affirmative and negative responses.

OPTIONS

       The  localedef  utility  shall  conform  to  the  Base Definitions volume of POSIX.1‐2017,
       Section 12.2, Utility Syntax Guidelines.

       The following options shall be supported:

       -c        Create permanent output even if warning messages have been issued.

       -f charmap
                 Specify the pathname of a file containing a mapping  of  character  symbols  and
                 collating  element  symbols  to  actual  character encodings.  The format of the
                 charmap is described in the Base Definitions  volume  of  POSIX.1‐2017,  Section
                 6.4,  Character  Set  Description  File.  The application shall ensure that this
                 option is specified if symbolic names (other than collating symbols defined in a
                 collating-symbol  keyword)  are  used.  If  the  -f  option  is  not present, an
                 implementation-defined character mapping shall be used.

       -i inputfile
                 The pathname of a file containing the source definitions. If this option is  not
                 present, source definitions shall be read from standard input. The format of the
                 inputfile is described in the Base Definitions volume of  POSIX.1‐2017,  Section
                 7.3, Locale Definition.

       -u code_set_name
                 Specify  the  name  of a codeset used as the target mapping of character symbols
                 and collating element symbols whose encoding values are defined in terms of  the
                 ISO/IEC 10646‐1:2000 standard position constant values.

OPERANDS

       The following operand shall be supported:

       name      Identifies  the locale; see the Base Definitions volume of POSIX.1‐2017, Chapter
                 7, Locale for a description of the use of this name. If the name contains one or
                 more  <slash>  characters,  name  shall  be  interpreted as a pathname where the
                 created locale definitions shall be stored. If name does not contain any <slash>
                 characters,  the  interpretation  of  the name is implementation-defined and the
                 locale shall be public. The ability to create public locales in this way may  be
                 restricted to users with appropriate privileges. (As a consequence of specifying
                 one name, although several categories can be processed in  one  execution,  only
                 categories belonging to the same locale can be processed.)

STDIN

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

INPUT FILES

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

ENVIRONMENT VARIABLES

       The following environment variables shall affect the execution of localedef:

       LANG      Provide a default value for the internationalization variables that are unset or
                 null.  (See  the  Base  Definitions  volume  of   POSIX.1‐2017,   Section   8.2,
                 Internationalization   Variables  for  the  precedence  of  internationalization
                 variables used to determine the values of locale categories.)

       LC_ALL    If set to a non-empty string  value,  override  the  values  of  all  the  other
                 internationalization variables.

       LC_COLLATE
                 (This  variable  has  no  affect on localedef; the POSIX locale is used for this
                 category.)

       LC_CTYPE  Determine the locale for the interpretation of sequences of bytes of  text  data
                 as  characters  (for example, single-byte as opposed to multi-byte characters in
                 arguments and input files). This variable has no affect  on  the  processing  of
                 localedef  input  data; the POSIX locale is used for this purpose, regardless of
                 the value of this variable.

       LC_MESSAGES
                 Determine the locale that should be used to affect the format  and  contents  of
                 diagnostic messages written to standard error.

       NLSPATH   Determine the location of message catalogs for the processing of LC_MESSAGES.

ASYNCHRONOUS EVENTS

       Default.

STDOUT

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

STDERR

       The standard error shall be used only for diagnostic messages.

OUTPUT FILES

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

EXTENDED DESCRIPTION

       When the -u option is used, the code_set_name option-argument shall be interpreted  as  an
       implementation-defined  name  of  a  codeset  to  which  the ISO/IEC 10646‐1:2000 standard
       position constant values shall be converted via an implementation-defined method. Both the
       ISO/IEC 10646‐1:2000  standard  position  constant  values  and  other  formats  (decimal,
       hexadecimal, or octal) shall be valid as encoding values  within  the  charmap  file.  The
       codeset  represented  by  the  implementation-defined  name  can  be  any  codeset that is
       supported by the implementation.

       When conflicts occur between the charmap specification of  <code_set_name>,  <mb_cur_max>,
       or  <mb_cur_min>  and  the implementation-defined interpretation of these respective items
       for the codeset represented  by  the  -u  option-argument  code_set_name,  the  result  is
       unspecified.

       When  conflicts  occur between the charmap encoding values specified for symbolic names of
       characters of the portable character set  and  the  implementation-defined  assignment  of
       character encoding values, the result is unspecified.

       If  a  non-printable  character  in  the charmap has a width specified that is not -1, the
       result will be undefined.

EXIT STATUS

       The following exit values shall be returned:

        0    No errors occurred and the locales were successfully created.

        1    Warnings occurred and the locales were successfully created.

        2    The locale specification exceeded implementation limits or the coded  character  set
             or sets used were not supported by the implementation, and no locale was created.

        3    The capability to create new locales is not supported by the implementation.

       >3    Warnings or errors occurred and no output was created.

CONSEQUENCES OF ERRORS

       If an error is detected, no permanent output shall be created.

       If  warnings  occur, permanent output shall be created if the -c option was specified. The
       following conditions shall cause warning messages to be issued:

        *  If a symbolic name not found in the charmap file is used for the descriptions  of  the
           LC_CTYPE  or  LC_COLLATE  categories  (for  other  categories,  this shall be an error
           condition).

        *  If the number of operands to the order keyword exceeds the {COLL_WEIGHTS_MAX} limit.

        *  If optional keywords not supported by the implementation are present in the source.

       Other implementation-defined conditions may also cause warnings.

       The following sections are informative.

APPLICATION USAGE

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

EXAMPLES

       None.

RATIONALE

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

FUTURE DIRECTIONS

       None.

SEE ALSO

       locale

       The Base Definitions volume of POSIX.1‐2017, Section 6.4, Character Set Description  File,
       Chapter  7,  Locale,  Chapter  8,  Environment  Variables,  Section  12.2,  Utility Syntax
       Guidelines

COPYRIGHT

       Portions of this text are reprinted and  reproduced  in  electronic  form  from  IEEE  Std
       1003.1-2017,  Standard  for  Information Technology -- Portable Operating System Interface
       (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C)  2018  by
       the  Institute  of  Electrical  and Electronics Engineers, Inc and The Open Group.  In the
       event of any discrepancy between this version and the original IEEE  and  The  Open  Group
       Standard,  the  original  IEEE  and  The  Open Group Standard is the referee document. The
       original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

       Any typographical or formatting errors that appear in this page are most  likely  to  have
       been  introduced  during  the conversion of the source files to man page format. To report
       such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .