mirror of https://github.com/mkerrisk/man-pages
311 lines
9.7 KiB
Plaintext
311 lines
9.7 KiB
Plaintext
|
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
||
|
.TH "SETLOCALE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
||
|
.\" setlocale
|
||
|
.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 .
|