Man Linux: Main Page and Category List

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
       IEEE Std 1003.1-2001,  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 the 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
       IEEE Std 1003.1-2001, 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   IEEE Std 1003.1-2001,   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  IEEE Std 1003.1-2001,  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
              IEEE Std 1003.1-2001, 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.  This
              capability   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  IEEE Std 1003.1-2001,
       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  IEEE Std 1003.1-2001,
       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 IEEE Std 1003.1-2001, 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
              IEEE Std 1003.1-2001,    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, localedef shall generate a warning.

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.

        * If a non-printable character has a width specified other than -1.

       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 IEEE Std 1003.1-2001, 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 IEEE Std 1003.1-2001, Section
       7.3, Locale Definition

COPYRIGHT

       Portions of this text are reprinted and reproduced in  electronic  form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
       Specifications  Issue  6,  Copyright  (C) 2001-2003 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 .