---
name: "setlocale"
section: "3"
platform: "linux"
package: "man-pages"
version: "6.19-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux", "freebsd", "macos"]
url: "https://new.carta.tech/setlocale"
---

# setlocale(3)

set the current locale

## NAME

setlocale - set the current locale

## LIBRARY

Standard C library (*libc*, *-lc*)

## SYNOPSIS

```
#include <locale.h>
```

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

## DESCRIPTION

The **setlocale**() function is used to set or query the program's current locale.

If *locale* is not NULL, the program's current locale is modified according to the arguments. The argument *category* determines which parts of the program's current locale should be modified.

| | |
| --- | --- |
| **Category** | **Governs** |
| **LC\_ALL** | All of the locale |
| **LC\_ADDRESS** | Formatting of addresses and geography-related items (\*) |
| **LC\_COLLATE** | String collation |
| **LC\_CTYPE** | Character classification |
| **LC\_IDENTIFICATION** | Metadata describing the locale (\*) |
| **LC\_MEASUREMENT** | Settings related to measurements (metric versus US customary) (\*) |
| **LC\_MESSAGES** | Localizable natural-language messages |
| **LC\_MONETARY** | Formatting of monetary values |
| **LC\_NAME** | Formatting of salutations for persons (\*) |
| **LC\_NUMERIC** | Formatting of nonmonetary numeric values |
| **LC\_PAPER** | Settings related to the standard paper size (\*) |
| **LC\_TELEPHONE** | Formats to be used with telephone services (\*) |
| **LC\_TIME** | Formatting of date and time values |

The categories marked with an asterisk in the above table are GNU extensions. For further information on these locale categories, see [**locale**(7)](/locale/7.md).

The argument *locale* is a pointer to a character string containing the required setting of *category*. Such a string is either a well-known constant like "C" or "da\_DK" (see below), or an opaque string that was returned by another call of **setlocale**().

If *locale* is an empty string, **""**, each part of the locale that should be modified is set according to the environment variables. The details are implementation-dependent. For glibc, first (regardless of *category*), the environment variable **LC\_ALL** is inspected, next the environment variable with the same name as the category (see the table above), and finally the environment variable **LANG**. The first existing environment variable is used. If its value is not a valid locale specification, the locale is unchanged, and **setlocale**() returns NULL.

The locale **"C"** or **"POSIX"** is a portable locale; it exists on all conforming systems.

A locale name is typically of the form *language*\[\_*territory*\]\[.*codeset*\]\[@*modifier*\], where *language* is an ISO 639 language code, *territory* is an ISO 3166 country code, and *codeset* is a character set or encoding identifier like **ISO-8859-1** or **UTF-8**. For a list of all supported locales, try "locale -a" (see [**locale**(1)](/locale/1.md)).

If *locale* is NULL, the current locale is only queried, not modified.

On startup of the main program, the portable **"C"** locale is selected as default. A program may be made portable to all locales by calling:

```
setlocale(LC_ALL, "");
```

after program initialization, and then:

- •

  using the values returned from a [**localeconv**(3)](/localeconv/3.md) call for locale-dependent information;

- •

  using the multibyte and wide character functions for text processing if **MB\_CUR\_MAX \> 1**;

- •

  using [**strcoll**(3)](/strcoll/3.md) and [**strxfrm**(3)](/strxfrm/3.md) to compare strings; and

- •

  using [**wcscoll**(3)](/wcscoll/3.md) and [**wcsxfrm**(3)](/wcsxfrm/3.md) to compare wide-character strings.

## RETURN VALUE

A successful call to **setlocale**() returns an opaque string that corresponds to the locale set. This string may be allocated in static storage. The string returned is such that a subsequent call with that string and its associated category will restore that part of the process's locale. The return value is NULL if the request cannot be honored.

## ATTRIBUTES

For an explanation of the terms used in this section, see [**attributes**(7)](/attributes/7.md).

| | | |
| --- | --- | --- |
| **Interface** | **Attribute** | **Value** |
| **setlocale**() | Thread safety | MT-Unsafe const:locale env |

## STANDARDS

C11, POSIX.1-2008.

### Categories

- **LC\_ALL** **LC\_COLLATE** **LC\_CTYPE** **LC\_MONETARY** **LC\_NUMERIC** **LC\_TIME**

  C11, POSIX.1-2008.

- **LC\_MESSAGES**

  POSIX.1-2008.

- Others:

  GNU.

## HISTORY

POSIX.1-2001, C89.

### Categories

- **LC\_ALL** **LC\_COLLATE** **LC\_CTYPE** **LC\_MONETARY** **LC\_NUMERIC** **LC\_TIME**

  C89, POSIX.1-2001.

- **LC\_MESSAGES**

  POSIX.1-2001.

- Others:

  GNU.

## SEE ALSO

[**locale**(1)](/locale/1.md), [**localedef**(1)](/localedef/1.md), [**isalpha**(3)](/isalpha/3.md), [**localeconv**(3)](/localeconv/3.md), [**nl\_langinfo**(3)](/nl_langinfo/3.md), [**rpmatch**(3)](/rpmatch/3.md), [**strcoll**(3)](/strcoll/3.md), [**strftime**(3)](/strftime/3.md), [**charsets**(7)](/charsets/7.md), [**locale**(7)](/locale/7.md)