setlocale.3p (13318B)
- '\" et
- .TH SETLOCALE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- setlocale
- \(em set program locale
- .SH SYNOPSIS
- .LP
- .nf
- #include <locale.h>
- .P
- char *setlocale(int \fIcategory\fP, const char *\fIlocale\fP);
- .fi
- .SH DESCRIPTION
- The functionality described on this reference page is aligned with the
- ISO\ C standard. Any conflict between the requirements described here and the
- ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard.
- .P
- The
- \fIsetlocale\fR()
- function selects the appropriate piece of the global locale, as specified
- by the
- .IR category
- and
- .IR locale
- arguments, and can be used to change or query the entire global locale
- or portions thereof. The value LC_ALL for
- .IR category
- names the entire global locale; other values for
- .IR category
- name only a part of the global locale:
- .IP LC_COLLATE 12
- Affects the behavior of regular expressions and the collation
- functions.
- .IP LC_CTYPE 12
- Affects the behavior of regular expressions, character classification,
- character conversion functions, and wide-character functions.
- .IP LC_MESSAGES 12
- Affects the affirmative and negative response expressions returned by
- \fInl_langinfo\fR()
- and the way message catalogs are located. It may also affect the
- behavior of functions that return or write message strings.
- .IP LC_MONETARY 12
- Affects the behavior of functions that handle monetary values.
- .IP LC_NUMERIC 12
- Affects the behavior of functions that handle numeric values.
- .IP LC_TIME 12
- Affects the behavior of the time conversion functions.
- .P
- The
- .IR locale
- argument is a pointer to a character string containing the required
- setting of
- .IR category .
- The contents of this string are implementation-defined. In addition,
- the following preset values of
- .IR locale
- are defined for all settings of
- .IR category :
- .IP "\&\(dqPOSIX\(dq" 12
- Specifies the minimal environment for C-language translation called the
- POSIX locale. The POSIX locale is the default global locale at entry to
- \fImain\fR().
- .IP "\&\(dqC\(dq" 12
- Equivalent to
- .BR \(dqPOSIX\(dq .
- .IP "\&\(dq\|\(dq" 12
- Specifies an implementation-defined native environment.
- The determination of the name of the new locale for the specified
- category depends on the value of the associated environment
- variables,
- .IR LC_*
- and
- .IR LANG ;
- see the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Chapter 7" ", " "Locale"
- and
- .IR "Chapter 8" ", " "Environment Variables".
- .IP "A\ null\ pointer" 12
- Directs
- \fIsetlocale\fR()
- to query the current global locale setting and return the name
- of the locale if
- .IR category
- is not LC_ALL, or a string which encodes the locale name(s) for all of
- the individual categories if
- .IR category
- is LC_ALL.
- .P
- Setting all of the categories of the global locale is similar to
- successively setting each individual category of the global locale, except
- that all error checking is done before any actions are performed. To
- set all the categories of the global locale,
- \fIsetlocale\fR()
- can be invoked as:
- .sp
- .RS 4
- .nf
- setlocale(LC_ALL, "");
- .fi
- .P
- .RE
- .P
- In this case,
- \fIsetlocale\fR()
- shall first verify that the values of all the environment variables it
- needs according to the precedence rules (described in the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Chapter 8" ", " "Environment Variables")
- indicate supported locales. If the value of any of these environment
- variable searches yields a locale that is not supported (and non-null),
- \fIsetlocale\fR()
- shall return a null pointer and the global locale shall not be changed. If
- all environment variables name supported locales,
- \fIsetlocale\fR()
- shall proceed as if it had been called for each category, using the
- appropriate value from the associated environment variable or from the
- implementation-defined default if there is no such value.
- .P
- The global locale established using
- \fIsetlocale\fR()
- shall only be used in threads for which no current locale has been
- set using
- \fIuselocale\fR()
- or whose current locale has been set to the global locale using
- .IR uselocale (LC_GLOBAL_LOCALE) .
- .P
- The implementation shall behave as if no function defined in this volume of POSIX.1\(hy2017 calls
- \fIsetlocale\fR().
- .P
- The
- \fIsetlocale\fR()
- function need not be thread-safe.
- .SH "RETURN VALUE"
- Upon successful completion,
- \fIsetlocale\fR()
- shall return the string associated with the specified category for the
- new locale. Otherwise,
- \fIsetlocale\fR()
- shall return a null pointer and the global locale shall not be changed.
- .P
- A null pointer for
- .IR locale
- shall cause
- \fIsetlocale\fR()
- to return a pointer to the string associated with the specified
- .IR category
- for the current global locale. The global locale shall not be changed.
- .P
- The string returned by
- \fIsetlocale\fR()
- is such that a subsequent call with that string and its associated
- .IR category
- shall restore that part of the global locale. The application shall
- not modify the string returned.
- The returned string pointer might be invalidated or
- the string content might be overwritten by a subsequent call to
- \fIsetlocale\fR().
- The returned pointer might also be invalidated if the calling
- thread is terminated.
- .SH ERRORS
- No errors are defined.
- .LP
- .IR "The following sections are informative."
- .SH EXAMPLES
- None.
- .SH "APPLICATION USAGE"
- The following code illustrates how a program can initialize the
- international environment for one language, while selectively modifying
- the global locale such that regular expressions and string operations
- can be applied to text recorded in a different language:
- .sp
- .RS 4
- .nf
- setlocale(LC_ALL, "De");
- setlocale(LC_COLLATE, "Fr@dict");
- .fi
- .P
- .RE
- .P
- Internationalized programs can initiate language operation according
- to environment variable settings (see the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 8.2" ", " "Internationalization Variables")
- by calling
- \fIsetlocale\fR()
- as follows:
- .sp
- .RS 4
- .nf
- setlocale(LC_ALL, "");
- .fi
- .P
- .RE
- .P
- Changing the setting of
- .IR LC_MESSAGES
- has no effect on catalogs that have already been opened by calls to
- \fIcatopen\fR().
- .P
- In order to make use of different locale settings while multiple
- threads are running, applications should use
- \fIuselocale\fR()
- in preference to
- \fIsetlocale\fR().
- .SH RATIONALE
- References to the international environment or locale in the following
- text relate to the global locale for the process. This can be overridden
- for individual threads using
- \fIuselocale\fR().
- .P
- The ISO\ C standard
- defines a collection of functions to support internationalization.
- One of the most significant aspects of these functions is a facility
- to set and query the \fIinternational environment\fP.
- The international environment is a repository of information that
- affects the behavior of certain functionality, namely:
- .IP " 1." 4
- Character handling
- .IP " 2." 4
- Collating
- .IP " 3." 4
- Date/time formatting
- .IP " 4." 4
- Numeric editing
- .IP " 5." 4
- Monetary formatting
- .IP " 6." 4
- Messaging
- .P
- The
- \fIsetlocale\fR()
- function provides the application developer with the ability to set all
- or portions, called \fIcategories\fP, of the international environment.
- These categories correspond to the areas of functionality mentioned
- above. The syntax for
- \fIsetlocale\fR()
- is as follows:
- .sp
- .RS 4
- .nf
- char *setlocale(int \fIcategory\fP, const char *\fIlocale\fP);
- .fi
- .P
- .RE
- .P
- where
- .IR category
- is the name of one of following categories, namely:
- .sp
- .RS
- LC_COLLATE
- LC_CTYPE
- LC_MESSAGES
- LC_MONETARY
- LC_NUMERIC
- LC_TIME
- .RE
- .P
- In addition, a special value called LC_ALL
- directs
- \fIsetlocale\fR()
- to set all categories.
- .P
- There are two primary uses of
- \fIsetlocale\fR():
- .IP " 1." 4
- Querying the international environment to find out what it is set to
- .IP " 2." 4
- Setting the international environment, or
- .IR locale ,
- to a specific value
- .P
- The behavior of
- \fIsetlocale\fR()
- in these two areas is described below. Since it is difficult to
- describe the behavior in words, examples are used to illustrate the
- behavior of specific uses.
- .P
- To query the international environment,
- \fIsetlocale\fR()
- is invoked with a specific category and the null pointer as the
- locale. The null pointer is a special directive to
- \fIsetlocale\fR()
- that tells it to query rather than set the international environment.
- The following syntax is used to query the name of the international
- environment:
- .sp
- .RS 4
- .nf
- setlocale({LC_ALL, LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, \e
- LC_NUMERIC, LC_TIME},(char *) NULL);
- .fi
- .P
- .RE
- .P
- The
- \fIsetlocale\fR()
- function shall return the string corresponding to the current
- international environment. This value may be used by a subsequent call to
- \fIsetlocale\fR()
- to reset the international environment to this value. However, it
- should be noted that the return value from
- \fIsetlocale\fR()
- may be a pointer to a static area within the function and is not
- guaranteed to remain unchanged (that is, it may be modified by a
- subsequent call to
- \fIsetlocale\fR()).
- Therefore, if the purpose of calling
- \fIsetlocale\fR()
- is to save the value of the current international environment so it can
- be changed and reset later, the return value should be copied to an
- array of
- .BR char
- in the calling program.
- .P
- There are three ways to set the international environment with
- \fIsetlocale\fR():
- .IP "\fIsetlocale\fP(\fIcategory\fP,\ \fIstring\fP)" 6
- .br
- This usage sets a specific
- .IR category
- in the international environment to a specific value corresponding to
- the value of the
- .IR string .
- A specific example is provided below:
- .RS 6
- .sp
- .RS 4
- .nf
- setlocale(LC_ALL, "fr_FR.ISO-8859-1");
- .fi
- .P
- .RE
- .P
- In this example, all categories of the international environment are
- set to the locale corresponding to the string
- .BR \(dqfr_FR.ISO-8859-1\(dq ,
- or to the French language as spoken in France using the ISO/IEC\ 8859\(hy1:\|1998 standard codeset.
- .P
- If the string does not correspond to a valid locale,
- \fIsetlocale\fR()
- shall return a null pointer and the international environment is not
- changed. Otherwise,
- \fIsetlocale\fR()
- shall return the name of the locale just set.
- .RE
- .IP "\&\fIsetlocale\fP(\fIcategory\fP,\ \(dqC\(dq)" 6
- .br
- The ISO\ C standard states that one locale must exist on all conforming
- implementations. The name of the locale is C and corresponds to a
- minimal international environment needed to support the C programming
- language.
- .IP "\&\fIsetlocale\fP(\fIcategory\fP,\ \(dq\^\(dq)" 6
- .br
- This sets a specific category to an implementation-defined default.
- This corresponds to the value of the environment variables.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .ad l
- .IR "\fIcatopen\fR\^(\|)",
- .IR "\fIexec\fR\^",
- .IR "\fIfprintf\fR\^(\|)",
- .IR "\fIfscanf\fR\^(\|)",
- .IR "\fIisalnum\fR\^(\|)",
- .IR "\fIisalpha\fR\^(\|)",
- .IR "\fIisblank\fR\^(\|)",
- .IR "\fIiscntrl\fR\^(\|)",
- .IR "\fIisdigit\fR\^(\|)",
- .IR "\fIisgraph\fR\^(\|)",
- .IR "\fIislower\fR\^(\|)",
- .IR "\fIisprint\fR\^(\|)",
- .IR "\fIispunct\fR\^(\|)",
- .IR "\fIisspace\fR\^(\|)",
- .IR "\fIisupper\fR\^(\|)",
- .IR "\fIiswalnum\fR\^(\|)",
- .IR "\fIiswalpha\fR\^(\|)",
- .IR "\fIiswblank\fR\^(\|)",
- .IR "\fIiswcntrl\fR\^(\|)",
- .IR "\fIiswctype\fR\^(\|)",
- .IR "\fIiswdigit\fR\^(\|)",
- .IR "\fIiswgraph\fR\^(\|)",
- .IR "\fIiswlower\fR\^(\|)",
- .IR "\fIiswprint\fR\^(\|)",
- .IR "\fIiswpunct\fR\^(\|)",
- .IR "\fIiswspace\fR\^(\|)",
- .IR "\fIiswupper\fR\^(\|)",
- .IR "\fIiswxdigit\fR\^(\|)",
- .IR "\fIisxdigit\fR\^(\|)",
- .IR "\fIlocaleconv\fR\^(\|)",
- .IR "\fImblen\fR\^(\|)",
- .IR "\fImbstowcs\fR\^(\|)",
- .IR "\fImbtowc\fR\^(\|)",
- .IR "\fInewlocale\fR\^(\|)",
- .IR "\fInl_langinfo\fR\^(\|)",
- .IR "\fIperror\fR\^(\|)",
- .IR "\fIpsiginfo\fR\^(\|)",
- .IR "\fIstrcoll\fR\^(\|)",
- .IR "\fIstrerror\fR\^(\|)",
- .IR "\fIstrfmon\fR\^(\|)",
- .IR "\fIstrsignal\fR\^(\|)",
- .IR "\fIstrtod\fR\^(\|)",
- .IR "\fIstrxfrm\fR\^(\|)",
- .IR "\fItolower\fR\^(\|)",
- .IR "\fItoupper\fR\^(\|)",
- .IR "\fItowlower\fR\^(\|)",
- .IR "\fItowupper\fR\^(\|)",
- .IR "\fIuselocale\fR\^(\|)",
- .IR "\fIwcscoll\fR\^(\|)",
- .IR "\fIwcstod\fR\^(\|)",
- .IR "\fIwcstombs\fR\^(\|)",
- .IR "\fIwcsxfrm\fR\^(\|)",
- .IR "\fIwctomb\fR\^(\|)"
- .ad b
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "Chapter 7" ", " "Locale",
- .IR "Chapter 8" ", " "Environment Variables",
- .IR "\fB<langinfo.h>\fP",
- .IR "\fB<locale.h>\fP"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 by the Institute of
- Electrical and Electronics Engineers, Inc and The Open Group.
- In the event of any discrepancy between this version and the original IEEE and
- The Open Group Standard, the original IEEE and The Open Group Standard
- is the referee document. The original Standard can be obtained online at
- http://www.opengroup.org/unix/online.html .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .