diff options
Diffstat (limited to 'man-pages-posix-2003/man3p/setlocale.3p')
| -rw-r--r-- | man-pages-posix-2003/man3p/setlocale.3p | 315 |
1 files changed, 315 insertions, 0 deletions
diff --git a/man-pages-posix-2003/man3p/setlocale.3p b/man-pages-posix-2003/man3p/setlocale.3p new file mode 100644 index 0000000..89fd41e --- /dev/null +++ b/man-pages-posix-2003/man3p/setlocale.3p @@ -0,0 +1,315 @@ +.\" 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 . |