mirror of https://github.com/mkerrisk/man-pages
316 lines
9.9 KiB
Plaintext
316 lines
9.9 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "SETLOCALE" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" setlocale
|
|
.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 \- set program locale
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fB#include <locale.h>
|
|
.br
|
|
.sp
|
|
char *setlocale(int\fP \fIcategory\fP\fB, const char *\fP\fIlocale\fP\fB);
|
|
.br
|
|
\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fIsetlocale\fP() function selects the appropriate piece of the
|
|
program's locale, as specified by the \fIcategory\fP and
|
|
\fIlocale\fP arguments, and may be used to change or query the program's
|
|
entire locale or portions thereof. The value
|
|
\fILC_ALL\fP for \fIcategory\fP names the program's entire locale;
|
|
other values for \fIcategory\fP name only a part of the
|
|
program's locale:
|
|
.TP 7
|
|
\fILC_COLLATE\fP
|
|
Affects the behavior of regular expressions and the collation functions.
|
|
.TP 7
|
|
\fILC_CTYPE\fP
|
|
Affects the behavior of regular expressions, character classification,
|
|
character conversion functions, and wide-character
|
|
functions.
|
|
.TP 7
|
|
\fILC_MESSAGES\fP
|
|
Affects what strings are expected by commands and utilities as affirmative
|
|
or negative responses.
|
|
.LP
|
|
It also affects what strings are given by commands and utilities as
|
|
affirmative or negative responses, and the content of messages.
|
|
.TP 7
|
|
\fILC_MONETARY\fP
|
|
Affects the behavior of functions that handle monetary values.
|
|
.TP 7
|
|
\fILC_NUMERIC\fP
|
|
Affects the behavior of functions that handle numeric values.
|
|
.TP 7
|
|
\fILC_TIME\fP
|
|
Affects the behavior of the time conversion functions.
|
|
.sp
|
|
.LP
|
|
The \fIlocale\fP argument is a pointer to a character string containing
|
|
the required setting of \fIcategory\fP. The contents
|
|
of this string are implementation-defined. In addition, the following
|
|
preset values of \fIlocale\fP are defined for all settings
|
|
of \fIcategory\fP:
|
|
.TP 7
|
|
"POSIX"
|
|
Specifies the minimal environment for C-language translation called
|
|
the POSIX locale. If \fIsetlocale\fP() is not invoked, the
|
|
POSIX locale is the default at entry to \fImain\fP().
|
|
.TP 7
|
|
"C"
|
|
Equivalent to \fB"POSIX"\fP .
|
|
.TP 7
|
|
""
|
|
Specifies an implementation-defined native environment. This corresponds
|
|
to the value of the associated environment
|
|
variables, \fILC_*\fP and \fILANG ;\fP see the Base Definitions volume
|
|
of IEEE\ Std\ 1003.1-2001, Chapter 7, Locale and the Base Definitions
|
|
volume of IEEE\ Std\ 1003.1-2001, Chapter 8, Environment Variables.
|
|
.TP 7
|
|
A\ null\ pointer
|
|
Used to direct \fIsetlocale\fP() to query the current internationalized
|
|
environment and return the name of the locale.
|
|
.sp
|
|
.LP
|
|
The locale state is common to all threads within a process.
|
|
.SH RETURN VALUE
|
|
.LP
|
|
Upon successful completion, \fIsetlocale\fP() shall return the string
|
|
associated with the specified category for the new
|
|
locale. Otherwise, \fIsetlocale\fP() shall return a null pointer and
|
|
the program's locale is not changed.
|
|
.LP
|
|
A null pointer for \fIlocale\fP causes \fIsetlocale\fP() to return
|
|
a pointer to the string associated with the \fIcategory\fP
|
|
for the program's current locale. The program's locale shall not be
|
|
changed.
|
|
.LP
|
|
The string returned by \fIsetlocale\fP() is such that a subsequent
|
|
call with that string and its associated \fIcategory\fP
|
|
shall restore that part of the program's locale. The application shall
|
|
not modify the string returned which may be overwritten by a
|
|
subsequent call to \fIsetlocale\fP().
|
|
.SH ERRORS
|
|
.LP
|
|
No errors are defined.
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH EXAMPLES
|
|
.LP
|
|
None.
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
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:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBsetlocale(LC_ALL, "De");
|
|
setlocale(LC_COLLATE, "Fr@dict");
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
Internationalized programs must call \fIsetlocale\fP() to initiate
|
|
a specific language operation. This can be done by calling
|
|
\fIsetlocale\fP() as follows:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBsetlocale(LC_ALL, "");
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
Changing the setting of \fILC_MESSAGES\fP has no effect on catalogs
|
|
that have already been opened by calls to \fIcatopen\fP().
|
|
.SH RATIONALE
|
|
.LP
|
|
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
|
|
.LP
|
|
.IP " 2." 4
|
|
Collating
|
|
.LP
|
|
.IP " 3." 4
|
|
Date/time formatting
|
|
.LP
|
|
.IP " 4." 4
|
|
Numeric editing
|
|
.LP
|
|
.IP " 5." 4
|
|
Monetary formatting
|
|
.LP
|
|
.IP " 6." 4
|
|
Messaging
|
|
.LP
|
|
.LP
|
|
The \fIsetlocale\fP() 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\fP() is as follows:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBchar *setlocale(int\fP \fIcategory\fP\fB, const char *\fP\fIlocale\fP\fB);
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
where \fIcategory\fP is the name of one of following categories, namely:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fILC_COLLATE
|
|
|
|
LC_CTYPE
|
|
|
|
LC_MESSAGES
|
|
|
|
LC_MONETARY
|
|
|
|
LC_NUMERIC
|
|
|
|
LC_TIME\fP
|
|
|
|
.fi
|
|
.RE
|
|
.LP
|
|
In addition, a special value called \fILC_ALL\fP directs \fIsetlocale\fP()
|
|
to set all categories.
|
|
.LP
|
|
There are two primary uses of \fIsetlocale\fP():
|
|
.IP " 1." 4
|
|
Querying the international environment to find out what it is set
|
|
to
|
|
.LP
|
|
.IP " 2." 4
|
|
Setting the international environment, or \fIlocale\fP, to a specific
|
|
value
|
|
.LP
|
|
.LP
|
|
The behavior of \fIsetlocale\fP() 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.
|
|
.LP
|
|
To query the international environment, \fIsetlocale\fP() is invoked
|
|
with a specific category and the NULL pointer as the
|
|
locale. The NULL pointer is a special directive to \fIsetlocale\fP()
|
|
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
|
|
.nf
|
|
|
|
\fBsetlocale({LC_ALL, LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, \\
|
|
LC_NUMERIC, LC_TIME},(char *) NULL);
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
The \fIsetlocale\fP() function shall return the string corresponding
|
|
to the current international environment. This value may
|
|
be used by a subsequent call to \fIsetlocale\fP() to reset the international
|
|
environment to this value. However, it should be
|
|
noted that the return value from \fIsetlocale\fP() 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\fP()). Therefore, if the purpose of calling
|
|
\fIsetlocale\fP() 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 \fBchar\fP in the calling program.
|
|
.LP
|
|
There are three ways to set the international environment with \fIsetlocale\fP():
|
|
.TP 7
|
|
\fIsetlocale\fP(\fIcategory\fP,\ \fIstring\fP)
|
|
.sp
|
|
This usage sets a specific \fIcategory\fP in the international environment
|
|
to a specific value corresponding to the value of the
|
|
\fIstring\fP. A specific example is provided below:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBsetlocale(LC_ALL, "fr_FR.ISO-8859-1");
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
In this example, all categories of the international environment are
|
|
set to the locale corresponding to the string
|
|
\fB"fr_FR.ISO-8859-1"\fP, or to the French language as spoken in
|
|
France using the ISO/IEC\ 8859-1:1998 standard
|
|
codeset.
|
|
.LP
|
|
If the string does not correspond to a valid locale, \fIsetlocale\fP()
|
|
shall return a NULL pointer and the international
|
|
environment is not changed. Otherwise, \fIsetlocale\fP() shall return
|
|
the name of the locale just set.
|
|
.TP 7
|
|
\fIsetlocale\fP(\fIcategory\fP,\ "C")
|
|
.sp
|
|
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.
|
|
.TP 7
|
|
\fIsetlocale\fP(\fIcategory\fP,\ "")
|
|
.sp
|
|
This sets a specific category to an implementation-defined default.
|
|
This corresponds to the value of the environment
|
|
variables.
|
|
.sp
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fIexec\fP(), \fIisalnum\fP(), \fIisalpha\fP(), \fIisblank\fP(),
|
|
\fIiscntrl\fP(), \fIisdigit\fP(), \fIisgraph\fP(),
|
|
\fIislower\fP(), \fIisprint\fP(), \fIispunct\fP(), \fIisspace\fP(),
|
|
\fIisupper\fP(),
|
|
\fIiswalnum\fP(), \fIiswalpha\fP(), \fIiswblank\fP(), \fIiswcntrl\fP(),
|
|
\fIiswctype\fP(), \fIiswdigit\fP(), \fIiswgraph\fP(), \fIiswlower\fP(),
|
|
\fIiswprint\fP(), \fIiswpunct\fP(), \fIiswspace\fP(), \fIiswupper\fP(),
|
|
\fIiswxdigit\fP(), \fIisxdigit\fP(), \fIlocaleconv\fP(), \fImblen\fP(),
|
|
\fImbstowcs\fP(),
|
|
\fImbtowc\fP(), \fInl_langinfo\fP(), \fIprintf\fP(), \fIscanf\fP(),
|
|
setlocale, \fIstrcoll\fP(), \fIstrerror\fP(), \fIstrfmon\fP()
|
|
,
|
|
\fIstrtod\fP(), \fIstrxfrm\fP(), \fItolower\fP(), \fItoupper\fP(),
|
|
\fItowlower\fP(),
|
|
\fItowupper\fP(), \fIwcscoll\fP(), \fIwcstod\fP(), \fIwcstombs\fP(),
|
|
\fIwcsxfrm\fP(),
|
|
\fIwctomb\fP(), the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
|
|
\fI<langinfo.h>\fP, \fI<locale.h>\fP
|
|
.SH COPYRIGHT
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Specifications Issue 6, Copyright (C) 2001-2003 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 .
|