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

If category is LC_ALL, this specifies the locale for all purposes. The other possible values of category specify an individual purpose (see section Categories of Activities that Locales Affect).

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 (see section 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.

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.

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 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 (old_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. For portability, assume that any symbol beginning with `LC_' might be defined in `locale.h'.

Go to the first, previous, next, last section, table of contents.