Movatterモバイル変換

setlocale(3p) — Linux manual page

PROLOG \|NAME \|SYNOPSIS \|DESCRIPTION \|RETURN VALUE \|ERRORS \|EXAMPLES \|APPLICATION USAGE \|RATIONALE \|FUTURE DIRECTIONS \|SEE ALSO \|COPYRIGHT

SETLOCALE(3P)           POSIX Programmer's ManualSETLOCALE(3P)

PROLOG top

       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.

NAME top

       setlocale — set program locale

SYNOPSIS top

       #include <locale.h>       char *setlocale(intcategory, const char *locale);

DESCRIPTION top

       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‐2017 defers to the ISO C standard.       Thesetlocale() function selects the appropriate piece of the       global locale, as specified by thecategory andlocale arguments,       and can be used to change or query the entire global locale or       portions thereof. The value LC_ALL forcategory names the entire       global locale; other values forcategory name only a part of the       global locale:       LC_COLLATE  Affects the behavior of regular expressions and the                   collation functions.       LC_CTYPE    Affects the behavior of regular expressions, character                   classification, character conversion functions, and                   wide-character functions.       LC_MESSAGES Affects the affirmative and negative response                   expressions returned bynl_langinfo() and the way                   message catalogs are located. It may also affect the                   behavior of functions that return or write message                   strings.       LC_MONETARY Affects the behavior of functions that handle monetary                   values.       LC_NUMERIC  Affects the behavior of functions that handle numeric                   values.       LC_TIME     Affects the behavior of the time conversion functions.       Thelocale argument is a pointer to a character string containing       the required setting ofcategory.  The contents of this string are       implementation-defined. In addition, the following preset values       oflocale are defined for all settings ofcategory:       "POSIX"     Specifies the minimal environment for C-language                   translation called the POSIX locale. The POSIX locale                   is the default global locale at entry tomain().       "C"         Equivalent to"POSIX".       ""          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,LC_* andLANG; see the Base Definitions volume of POSIX.1‐2017,Chapter 7,Locale andChapter 8,EnvironmentVariables.       A null pointer                   Directssetlocale() to query the current global locale                   setting and return the name of the locale ifcategory                   is not LC_ALL, or a string which encodes the locale                   name(s) for all of the individual categories ifcategory is LC_ALL.       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,setlocale() can be invoked as:           setlocale(LC_ALL, "");       In this case,setlocale() 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‐2017,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),setlocale() shall       return a null pointer and the global locale shall not be changed.       If all environment variables name supported locales,setlocale()       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.       The global locale established usingsetlocale() shall only be used       in threads for which no current locale has been set usinguselocale() or whose current locale has been set to the global       locale usinguselocale(LC_GLOBAL_LOCALE).       The implementation shall behave as if no function defined in this       volume of POSIX.1‐2017 callssetlocale().       Thesetlocale() function need not be thread-safe.

RETURN VALUE top

       Upon successful completion,setlocale() shall return the string       associated with the specified category for the new locale.       Otherwise,setlocale() shall return a null pointer and the global       locale shall not be changed.       A null pointer forlocale shall causesetlocale() to return a       pointer to the string associated with the specifiedcategory for       the current global locale. The global locale shall not be changed.       The string returned bysetlocale() is such that a subsequent call       with that string and its associatedcategory 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 tosetlocale().  The returned pointer might also be invalidated if       the calling thread is terminated.

ERRORS top

       No errors are defined.The following sections are informative.

EXAMPLES top

       None.

APPLICATION USAGE top

       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:           setlocale(LC_ALL, "De");           setlocale(LC_COLLATE, "Fr@dict");       Internationalized programs can initiate language operation       according to environment variable settings (see the Base       Definitions volume of POSIX.1‐2017,Section 8.2,Internationalization Variables) by callingsetlocale() as follows:           setlocale(LC_ALL, "");       Changing the setting ofLC_MESSAGES has no effect on catalogs that       have already been opened by calls tocatopen().       In order to make use of different locale settings while multiple       threads are running, applications should useuselocale() in       preference tosetlocale().

RATIONALE top

       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 usinguselocale().       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 theinternationalenvironment.  The international environment is a repository of       information that affects the behavior of certain functionality,       namely:        1. Character handling        2. Collating        3. Date/time formatting        4. Numeric editing        5. Monetary formatting        6. Messaging       Thesetlocale() function provides the application developer with       the ability to set all or portions, calledcategories, of the       international environment.  These categories correspond to the       areas of functionality mentioned above. The syntax forsetlocale()       is as follows:           char *setlocale(intcategory, const char *locale);       wherecategory is the name of one of following categories, namely:              LC_COLLATE LC_CTYPE LC_MESSAGES LC_MONETARY LC_NUMERIC              LC_TIME       In addition, a special value called LC_ALL directssetlocale() to       set all categories.       There are two primary uses ofsetlocale():        1. Querying the international environment to find out what it is           set to        2. Setting the international environment, orlocale, to a           specific value       The behavior ofsetlocale() 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.       To query the international environment,setlocale() is invoked       with a specific category and the null pointer as the locale. The       null pointer is a special directive tosetlocale() that tells it       to query rather than set the international environment.  The       following syntax is used to query the name of the international       environment:           setlocale({LC_ALL, LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, \               LC_NUMERIC, LC_TIME},(char *) NULL);       Thesetlocale() function shall return the string corresponding to       the current international environment. This value may be used by a       subsequent call tosetlocale() to reset the international       environment to this value. However, it should be noted that the       return value fromsetlocale() 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 tosetlocale()).       Therefore, if the purpose of callingsetlocale() 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 ofcharin the calling program.       There are three ways to set the international environment withsetlocale():setlocale(category,string)             This usage sets a specificcategory in the international             environment to a specific value corresponding to the value             of thestring.  A specific example is provided below:                 setlocale(LC_ALL, "fr_FR.ISO-8859-1");             In this example, all categories of the international             environment are set to the locale corresponding to the             string"fr_FR.ISO-8859-1", or to the French language as             spoken in France using the ISO/IEC 8859‐1:1998 standard             codeset.             If the string does not correspond to a valid locale,setlocale() shall return a null pointer and the             international environment is not changed. Otherwise,setlocale() shall return the name of the locale just set.setlocale(category, "C")             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.setlocale(category, "")             This sets a specific category to an implementation-defined             default.  This corresponds to the value of the environment             variables.

FUTURE DIRECTIONS top

       None.

COPYRIGHT top

       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  athttp://www.opengroup.org/unix/online.html .       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,  seehttps://www.kernel.org/doc/man-pages/reporting_bugs.html .IEEE/The Open Group                2017SETLOCALE(3P)

Pages that refer to this page:ctype.h(0p), locale.h(0p), wctype.h(0p), awk(1p), exec(3p), fprintf(3p), fscanf(3p), fwprintf(3p), fwscanf(3p), getdate(3p), isalnum(3p), isalpha(3p), isblank(3p), iscntrl(3p), isgraph(3p), islower(3p), isprint(3p), ispunct(3p), isspace(3p), isupper(3p), iswalnum(3p), iswalpha(3p), iswblank(3p), iswcntrl(3p), iswctype(3p), iswdigit(3p), iswgraph(3p), iswlower(3p), iswprint(3p), iswpunct(3p), iswspace(3p), iswupper(3p), iswxdigit(3p), localeconv(3p), nl_langinfo(3p), strsignal(3p), strtod(3p), tolower(3p), toupper(3p), towlower(3p), towupper(3p), uselocale(3p), wcstod(3p)