setlocale(3p) - phpMan

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

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.
NAME
       setlocale - set program locale
SYNOPSIS
       #include <locale.h>
       char *setlocale(int category, const char *locale);

DESCRIPTION
       The setlocale() function selects the appropriate piece of the program's
       locale,  as  specified by the category and locale arguments, and may be
       used to change  or  query  the  program's  entire  locale  or  portions
       thereof.  The  value  LC_ALL  for  category  names the program's entire
       locale; other values for category name only a  part  of  the  program's
       locale:
       LC_COLLATE
              Affects  the  behavior  of regular expressions and the collation
              functions.
       LC_CTYPE
              Affects the behavior of regular expressions, character classifi-
              cation, character conversion functions, and wide-character func-
              tions.
       LC_MESSAGES
              Affects what strings are expected by commands and  utilities  as
              affirmative or negative responses.
       It  also  affects  what  strings are given by commands and utilities as
       affirmative or negative responses, and the content of messages.
       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.

       The locale argument is a pointer to a character string  containing  the
       required setting of category. The contents of this string are implemen-
       tation-defined. In addition, the following preset values of locale  are
       defined for all settings of category:
       "POSIX"
              Specifies  the  minimal  environment  for C-language translation
              called the POSIX locale. If  setlocale()  is  not  invoked,  the
              POSIX locale is the default at entry to main().
       "C"    Equivalent to "POSIX" .
       ""     Specifies  an  implementation-defined  native environment.  This
              corresponds to the value of  the  associated  environment  vari-
              ables,  LC_*  and  LANG  ;  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 Vari-
              ables.
       A null pointer
              Used to direct setlocale() to query the  current  international-
              ized environment and return the name of the locale.

       The locale state is common to all threads within a process.
RETURN VALUE
       Upon successful completion, setlocale() shall return the string associ-
       ated with the specified category for the new locale. Otherwise,  setlo-
       cale()  shall  return  a  null  pointer and the program's locale is not
       changed.
       A null pointer for locale causes setlocale() to return a pointer to the
       string  associated  with the category for the program's current locale.
       The program's locale shall not be changed.
       The string returned by setlocale() is such that a subsequent call  with
       that  string and its associated category 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 setlocale().
ERRORS
       No errors are defined.
       The following sections are informative.
EXAMPLES
       None.
APPLICATION USAGE
       The  following code illustrates how a program can initialize the inter-
       national 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:

              setlocale(LC_ALL, "De");
              setlocale(LC_COLLATE, "Fr@dict");
       Internationalized programs must call setlocale() to initiate a specific
       language operation. This can be done by calling setlocale() as follows:

              setlocale(LC_ALL, "");
       Changing the setting of LC_MESSAGES has no effect on catalogs that have
       already been opened by calls to catopen().
RATIONALE
       The ISO C standard defines a collection of functions to support  inter-
       nationalization.   One  of  the most significant aspects of these func-
       tions is a facility to set and query the international environment. 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
       The setlocale() function provides the application  developer  with  the
       ability to set all or portions, called categories, of the international
       environment. These categories correspond to the areas of  functionality
       mentioned above. The syntax for setlocale() is as follows:

              char *setlocale(int category, const char *locale);
       where category 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 directs setlocale() to set
       all categories.
       There are two primary uses of setlocale():
        1. Querying the international environment to find out what it  is  set
           to
        2. Setting  the  international  environment,  or locale, to a specific
           value
       The behavior of setlocale() 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 to setlocale() 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);
       The setlocale() function shall return the string corresponding  to  the
       current  international  environment. This value may be used by a subse-
       quent call to setlocale() to reset  the  international  environment  to
       this value. However, it should be noted that the return value from set-
       locale() 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 setlocale()). Therefore, if the purpose  of  calling
       setlocale()  is to save the value of the current international environ-
       ment so it can be changed and reset later, the return value  should  be
       copied to an array of char in the calling program.
       There  are  three ways to set the international environment with setlo-
       cale():
       setlocale(category, string)
              This usage sets a specific category in the  international  envi-
              ronment  to  a  specific value corresponding to the value of the
              string. 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 con-
              forming implementations. The name of the locale is C and  corre-
              sponds  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 vari-
              ables.

FUTURE DIRECTIONS
       None.
SEE ALSO
       exec(),  isalnum(),   isalpha(),   isblank(),   iscntrl(),   isdigit(),
       isgraph(),   islower(),  isprint(),  ispunct(),  isspace(),  isupper(),
       iswalnum(), iswalpha(), iswblank(), iswcntrl(), iswctype(), iswdigit(),
       iswgraph(), iswlower(), iswprint(), iswpunct(), iswspace(), iswupper(),
       iswxdigit(), isxdigit(), localeconv(), mblen(),  mbstowcs(),  mbtowc(),
       nl_langinfo(),  printf(),  scanf(),  setlocale,  strcoll(), strerror(),
       strfmon() ,  strtod(),  strxfrm(),  tolower(),  toupper(),  towlower(),
       towupper(),  wcscoll(),  wcstod(), wcstombs(), wcsxfrm(), wctomb(), the
       Base  Definitions   volume   of   IEEE Std 1003.1-2001,   <langinfo.h>,
       <locale.h>
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 .

IEEE/The Open Group                  2003                        SETLOCALE(3P)