Description

   The setlocale function sets or queries the appropriate portion
   of the program's locale as specified by the category and locale
   arguments. Specifying LC_ALL for the category argument names the
   entire locale; specifying the other values name only a portion of
   the program's locale.

   The locale argument points to a character string that identifies
   the locale to be used. This argument can be one of the following:

   o  Name of the public locale

      Specifies the public locale in the following format:

      language_country.codeset[@modifier]

      The function searches for the public locale binary file in
      the location defined by the logical name SYS$I18N_LOCALE. The
      file type defaults to .LOCALE. The period (.)  and at-sign (@)
      characters in the name are replaced by an underscore (_).

      For example, if the specified name is
      "zh_CN.dechanzi@radical", the function searches for the
      SYS$I18N_LOCALE:ZH_CN_DECHANZI_RADICAL.LOCALE binary locale
      file.

   o  A file specification

      Specifies the binary locale file. It can be any valid file
      specification. If either the device or directory is omitted,
      the function first applies the current caller's device and
      directory as defaults for any missing component. If the file
      is not found, the function applies the device and directory
      defined by the SYS$I18N_LOCALE logical name as defaults. The
      file type defaults to .LOCALE.

      No wildcards are allowed. The binary locale file cannot reside
      on a remote node.

   o  "C"

      Specifies the C locale. If a program does not call setlocale,
      the C locale is the default.

   o  "POSIX"

      This is the same as the C locale.

   o  ""

      Specifies that the locale is initialized from the setting
      of the international environment logical names. The function
      checks the following logical names in the order shown until it
      finds a logical that is defined:

      1. LC_ALL

      2. Logical names corresponding to the category. For example,
         if LC_NUMERIC is specified as the category, then the first
         logical name that setlocale checks is LC_NUMERIC.

      3. LANG

      4. SYS$LC_ALL

      5. The system default for the category, which is defined by
         the SYS$LC_* logical names. For example, the default for
         the LC_NUMERIC category is defined by the SYS$LC_NUMERIC
         logical name.

      6. SYS$LANG

         If none of the logical names is defined, the C locale is
         used as the default. The SYS$LC_* logical names are set up
         at the system startup time.

      Like the locale argument, the equivalence name of the
      international environment logical name can be either the name
      of the public locale or the file specification. The setlocale
      function treats this equivalence name as if it were specified
      as the locale argument.

   o  NULL

      Causes setlocale to query the current locale. The function
      returns a pointer to a string describing the portion of the
      program's locale associated with category. Specifying the LC_
      ALL category returns the string describing the entire locale.
      The locale is not changed.

   o  The string returned from the previous call to setlocale

      Causes the function to restore the portion of the program's
      locale associated with category. If the string contains the
      description of the entire locale, the part of the string
      corresponding to category is used. If the string describes the
      portion of the program's locale for a single category, this
      locale is used. For example, this means that you can use the
      string returned from the call setlocale with the LC_COLLATE
      category to set the same locale for the LC_MESSAGES category.

      If the specified locale is available, then setlocale returns
      a pointer to the string that describes the portion of the
      program's locale associated with category. For the LC_ALL
      category, the returned string describes the entire program's
      locale. If an error occurs, a NULL pointer is returned and the
      program's locale is not changed.

      Subsequent calls to setlocale overwrite the returned string.
      If that part of the locale needs to be restored, the program
      should save the string. The calling program should make no
      assumptions about the format or length of the returned string.