HELPLIB.HLB  —  CRTL  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);

1  –  Arguments

 category

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

    o  LC_COLLATE

    o  LC_CTYPE

    o  LC_MESSAGES

    o  LC_MONETARY

    o  LC_NUMERIC

    o  LC_TIME

 locale

    Pointer to a string that specifies the locale.

2  –  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.

3  –  Return Values

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

4  –  Example

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

        /* This program 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 successful\n");

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

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

            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(" returned error");
            else
                printf(" call was successful\n");
        }

      Running the example program produces the following result:

        setlocale (LC_ALL, "POSIX") call was successful

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

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