setlocale

Selects the appropriate portion of the program's locale as specified by the category and locale arguments. You can use this function to change or query one category or the program's entire current locale.

Format

#include  <locale.h>

char *setlocale  (int category, const char
                 *locale);

Arguments

category

The name of the category. Specify LC_ALL to change or query the entire locale. Other valid category names are:

• LC_COLLATE

• LC_CTYPE

• LC_MESSAGES

• LC_MONETARY

• LC_NUMERIC

• LC_TIME

locale

Pointer to a string that specifies the locale.

Description

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

• 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.

• 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 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.

• "C"

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

• "POSIX"

  This is the same as the C locale.

• ""

  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.

• 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.

• 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.

Return Values

x	Pointer to a string describing the locale.
NULL	Indicates an error occurred; errno is set.

Example

#include <errno.h>
#include <stdio.h>
#include <locale.h>

/* This test calls setlocale() three times. The second call is for   */
/* a nonexistent locale. The third call is for an existing file that */
/* is not a locale file.                                             */

main()
  {
  char  *ret_str;

  errno = 0;
  printf ("setlocale (LC_ALL, \"POSIX\")");
  ret_str = (char *)setlocale (LC_ALL, "POSIX");
  if (ret_str == NULL)
   perror("setlocale error");
  else
   printf(" call was succesfull");

  errno = 0;
  printf ("\n\nsetlocale (LC_ALL, \"junk.junk_codeset\")");
  ret_str = (char *)setlocale (LC_ALL, "junk.junk_codeset");

  if (ret_str == NULL)
   perror("\rreturned error");
  else
   printf(" call was succesfull");

  errno = 0;
  printf ("\n\nsetlocale (LC_ALL, \"sys$login:login.com\")");
  ret_str = (char *)setlocale (LC_ALL, "sys$login:login.com");

  if (ret_str == NULL)
   perror("\rreturned error");
  else
   printf(" call was succesfull\n");

  }

Running the example program produces the following result:

setlocale (LC_ALL, "POSIX") call was succesfull

setlocale (LC_ALL, "junk.junk_codeset")
returned error: no such file or directory

setlocale (LC_ALL, "sys$login:login.com")
returned error: non-translatable vms error code: 0x35C07C
%c-f-localebad, not a locale file