May 30, 2003 SETLOCALE 3

### NAME

setlocale, localeconv - natural language formatting for C

### LIBRARY

Standard C Library (libc, -lc)

### SYNOPSIS

```char``*` setlocale(```int category``, const char *locale`)
```struct` `lconv``*` localeconv(```void`)

### DESCRIPTION

The setlocale(``) function sets the C library's notion of natural language formatting style for particular sets of routines. Each such style is called a `locale' and is invoked using an appropriate name passed as a C string. The localeconv(``) routine returns the current locale's parameters for formatting numbers.

The setlocale(``) function recognizes several categories of routines. These are the categories and the sets of routines they select:

```LC_ALL`
  Set the entire locale generically.

```LC_COLLATE`
  Set a locale for string collation routines. This controls alphabetic ordering in strcoll(``) and strxfrm(``).

```LC_CTYPE`
  Set a locale for the ctype(3) functions. This controls recognition of upper and lower case, alphabetic or non-alphabetic characters, and so on. The real work is done by the setrunelocale(``) function.

```LC_MESSAGES`
  Set a locale for message catalogs. This controls the selection of message catalogs by the catgets(3) and gettext(3) families of functions.

```LC_MONETARY`
  Set a locale for formatting monetary values; this affects the localeconv(``) function.

```LC_NUMERIC`
  Set a locale for formatting numbers. This controls the formatting of decimal points in input and output of floating point numbers in functions such as printf(``) and scanf(``), as well as values returned by localeconv(``).

```LC_TIME`
  Set a locale for formatting dates and times using the strftime(``) function.

Only three locales are defined by default, the empty string ```""` which denotes the native environment, and the ```"C"` and ```"POSIX"` locales, which denote the C language environment. A ```locale` argument of ```NULL` causes setlocale(``) to return the current locale. By default, C programs start in the ```"C"` locale. The format of the locale string is described in nls(7).

The only function in the library that sets the locale is setlocale(``); the locale is never changed as a side effect of some other routine.

Changing the setting of ```LC_MESSAGES` has no effect on catalogs that have already been opened by catopen(3).

The localeconv(``) function returns a pointer to a structure which provides parameters for formatting numbers, especially currency values:

  `

      struct lconv {
              char    *decimal_point;
              char    *thousands_sep;
              char    *grouping;
              char    *int_curr_symbol;
              char    *currency_symbol;
              char    *mon_decimal_point;
              char    *mon_thousands_sep;
              char    *mon_grouping;
              char    *positive_sign;
              char    *negative_sign;
              char    int_frac_digits;
              char    frac_digits;
              char    p_cs_precedes;
              char    p_sep_by_space;
              char    n_cs_precedes;
              char    n_sep_by_space;
              char    p_sign_posn;
              char    n_sign_posn;
              char    int_p_cs_precedes;
              char    int_n_cs_precedes;
              char    int_p_sep_by_space;
              char    int_n_sep_by_space;
              char    int_p_sign_posn;
              char    int_n_sign_posn;
      };

  `

The individual fields have the following meanings:

```decimal_point`
  The decimal point character, except for monetary values.

```thousands_sep`
  The separator between groups of digits before the decimal point, except for monetary values.

```grouping`
  The sizes of the groups of digits, except for monetary values. This is a pointer to a vector of integers, each of size char, representing group size from low order digit groups to high order (right to left). The list may be terminated with 0 or ```CHAR_MAX`. If the list is terminated with 0, the last group size before the 0 is repeated to account for all the digits. If the list is terminated with ```CHAR_MAX`, no more grouping is performed.

```int_curr_symbol`
  The standardized (ISO 4217:1995) international currency symbol.

```currency_symbol`
  The local currency symbol.

```mon_decimal_point`
  The decimal point character for monetary values.

```mon_thousands_sep`
  The separator for digit groups in monetary values.

```mon_grouping`
  Like ```grouping` but for monetary values.

```positive_sign`
  The character used to denote nonnegative monetary values, usually the empty string.

```negative_sign`
  The character used to denote negative monetary values, usually a minus sign.

```int_frac_digits`
  The number of digits after the decimal point in an internationally formatted monetary value.

```frac_digits`
  The number of digits after the decimal point in an locally formatted monetary value.

```p_cs_precedes`
  1 if the currency symbol precedes the monetary value for nonnegative values, 0 if it follows.

```p_sep_by_space`
  1 if a space is inserted between the currency symbol and the monetary value for nonnegative values, 0 otherwise.

```n_cs_precedes`
  Like ```p_cs_precedes` but for negative values.

```n_sep_by_space`
  Like ```p_sep_by_space` but for negative values.

```p_sign_posn`
  The location of the ```positive_sign` with respect to a nonnegative quantity and the ```currency_symbol`.

```n_sign_posn`
  Like ```p_sign_posn` but for negative currency values.

```int_p_cs_precedes`
  1 if the currency symbol precedes the internationally formatted monetary value for nonnegative values, 0 if it follows.

```int_n_cs_precedes`
  Like ```int_p_cs_precedes` but for negative values.

```int_p_sep_by_space`
  1 if a space is inserted between the currency symbol and the internationally formatted monetary value for nonnegative values, 0 otherwise.

```int_n_sep_by_space`
  Like ```int_p_sep_by_space` but for negative values.

```int_p_sign_posn`
  The location of the ```positive_sign` with respect to a nonnegative quantity and the ```currency_symbol`, for internationally formatted nonnegative monetary values.

```int_n_sign_posn`
  Like ```int_p_sign_posn` but for negative values.

The positional parameters in ```p_sign_posn`, ```n_sign_posn`, ```int_p_sign_posn` and ```int_n_sign_posn` are encoded as follows:

```0`
  Parentheses around the entire string.
```1`
  Before the string.
```2`
  After the string.
```3`
  Just before ```currency_symbol`.
```4`
  Just after ```currency_symbol`.

Unless mentioned above, an empty string as a value for a field indicates a zero length result or a value that is not in the current locale. A ```CHAR_MAX` result similarly denotes an unavailable value.

### RETURN VALUES

The setlocale(``) function returns ```NULL` and fails to change the locale if the given combination of ```category` and ```locale` makes no sense. The localeconv(``) function returns a pointer to a static object which may be altered by later calls to setlocale(``) or localeconv(``).

### EXAMPLES

The following code illustrates how a program can initialize the international environment for one language, while selectively modifying the program's locale such that regular expressions and string operations can be applied to text recorded in a different language: `

            setlocale(LC_ALL, "de");
            setlocale(LC_COLLATE, "fr");

`

When a process is started, its current locale is set to the C or POSIX locale. An internationalized program that depends on locale data not defined in the C or POSIX locale must invoke the setlocale subroutine in the following manner before using any of the locale-specific information: ``

            setlocale(LC_ALL, "");

### SEE ALSO

catopen(3), gettext(3), nl_langinfo(3), nls(7)

### STANDARDS

The setlocale(``) and localeconv(``) functions conform to ANSI X3.159-1989 (``ANSI C89'') and ISO/IEC 9899:1990 (``ISO C90'') .

The ```int_p_cs_precedes`, ```int_n_cs_precedes`, ```int_p_sep_by_space`, ```int_n_sep_by_space`, ```int_p_sign_posn` and ```int_n_sign_posn` members of
```struct` `lconv` were introduced in ISO/IEC 9899:1999 (``ISO C99'') .

### HISTORY

The setlocale(``) and localeconv(``) functions first appeared in 4.4BSD.

### BUGS

The current implementation supports only the ```"C"` and ```"POSIX"` locales for all but the ```LC_CTYPE` locale.

In spite of the gnarly currency support in localeconv(``), the standards don't include any functions for generalized currency formatting.

```LC_COLLATE` does not make sense for many languages. Use of ```LC_MONETARY` could lead to misleading results until we have a real time currency conversion function. ```LC_NUMERIC` and ```LC_TIME` are personal choices and should not be wrapped up with the other categories.

Multibyte locales aren't supported for static binaries.