GNU Info

(libc.info)Setting the Locale

---

Next: Standard Locales Prev: Locale Categories Up: Locales

---

Enter node , (file) or (file)node

How Programs Set the Locale
===========================

   A C program inherits its locale environment variables when it starts
up.  This happens automatically.  However, these variables do not
automatically control the locale used by the library functions, because
ISO C says that all programs start by default in the standard `C'
locale.  To use the locales specified by the environment, you must call
`setlocale'.  Call it as follows:

     setlocale (LC_ALL, "");

to select a locale based on the user choice of the appropriate
environment variables.

   You can also use `setlocale' to specify a particular locale, for
general use or for a specific category.

   The symbols in this section are defined in the header file
`locale.h'.

 - Function: char * setlocale (int CATEGORY, const char *LOCALE)
     The function `setlocale' sets the current locale for category
     CATEGORY to LOCALE.  A list of all the locales the system provides
     can be created by running

            locale -a

     If CATEGORY is `LC_ALL', this specifies the locale for all
     purposes.  The other possible values of CATEGORY specify an single
     purpose (Note: Locale Categories).

     You can also use this function to find out the current locale by
     passing a null pointer as the LOCALE argument.  In this case,
     `setlocale' returns a string that is the name of the locale
     currently selected for category CATEGORY.

     The string returned by `setlocale' can be overwritten by subsequent
     calls, so you should make a copy of the string (Note: Copying and
     Concatenation) if you want to save it past any further calls to
     `setlocale'.  (The standard library is guaranteed never to call
     `setlocale' itself.)

     You should not modify the string returned by `setlocale'.  It might
     be the same string that was passed as an argument in a previous
     call to `setlocale'.  One requirement is that the CATEGORY must be
     the same in the call the string was returned and the one when the
     string is passed in as LOCALE parameter.

     When you read the current locale for category `LC_ALL', the value
     encodes the entire combination of selected locales for all
     categories.  In this case, the value is not just a single locale
     name.  In fact, we don't make any promises about what it looks
     like.  But if you specify the same "locale name" with `LC_ALL' in
     a subsequent call to `setlocale', it restores the same combination
     of locale selections.

     To be sure you can use the returned string encoding the currently
     selected locale at a later time, you must make a copy of the
     string.  It is not guaranteed that the returned pointer remains
     valid over time.

     When the LOCALE argument is not a null pointer, the string returned
     by `setlocale' reflects the newly-modified locale.

     If you specify an empty string for LOCALE, this means to read the
     appropriate environment variable and use its value to select the
     locale for CATEGORY.

     If a nonempty string is given for LOCALE, then the locale of that
     name is used if possible.

     If you specify an invalid locale name, `setlocale' returns a null
     pointer and leaves the current locale unchanged.

   Here is an example showing how you might use `setlocale' to
temporarily switch to a new locale.

     #include <stddef.h>
     #include <locale.h>
     #include <stdlib.h>
     #include <string.h>
     
     void
     with_other_locale (char *new_locale,
                        void (*subroutine) (int),
                        int argument)
     {
       char *old_locale, *saved_locale;
     
       /* Get the name of the current locale.  */
       old_locale = setlocale (LC_ALL, NULL);
     
       /* Copy the name so it won't be clobbered by `setlocale'. */
       saved_locale = strdup (old_locale);
       if (saved_locale == NULL)
         fatal ("Out of memory");
     
       /* Now change the locale and do some stuff with it. */
       setlocale (LC_ALL, new_locale);
       (*subroutine) (argument);
     
       /* Restore the original locale. */
       setlocale (LC_ALL, saved_locale);
       free (saved_locale);
     }

   *Portability Note:* Some ISO C systems may define additional locale
categories, and future versions of the library will do so.  For
portability, assume that any symbol beginning with `LC_' might be
defined in `locale.h'.