Standard C Library Functions                        setlocale(3C)


NAME

     setlocale - modify and query a program's 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. The category  argument  may  have  the  following
     values:     LC_CTYPE,   LC_NUMERIC,   LC_TIME,   LC_COLLATE,
     LC_MONETARY,  LC_MESSAGES,  and  LC_ALL.   These  names  are
     defined in the <locale.h> header.  The LC_ALL variable names
     all of a program's locale categories.

     The LC_CTYPE variable affects the behavior of character han-
     dling  functions  such  as  isdigit(3C) and tolower(3C), and
     multibyte  character  functions  such  as   mbtowc(3C)   and
     wctomb(3C).

     The LC_NUMERIC variable affects the decimal point  character
     and   thousands   separator   character  for  the  formatted
     input/output functions and string conversion functions.

     The LC_TIME variable affects the date  and  time  format  as
     delivered    by   ascftime(3C),   cftime(3C),   getdate(3C),
     strftime(3C), and strptime(3C).

     The LC_COLLATE variable affects the sort order  produced  by
     collating functions such as strcoll(3C) and strxfrm(3C).

     The LC_MONETARY  variable  affects  the  monetary  formatted
     information returned by localeconv(3C).

     The LC_MESSAGES variable affects the behavior  of  messaging
     functions such as dgettext(3C), gettext(3C), and gettxt(3C).

     A value of "C" for locale  specifies  the  traditional  UNIX
     system behavior. At program startup, the equivalent of

SunOS 5.11          Last change: 19 Sep 2005                    1


Standard C Library Functions                        setlocale(3C)

     setlocale(LC_ALL, "C")

     is executed.  This  has  the  effect  of  initializing  each
     category to the locale described by the environment "C".

     A value of "" for locale specifies that the locale should be
     taken  from  environment  variables.  The order in which the
     environment variables are checked for the various categories
     is given below:

     __________________________________________________________________
    |    Category   |   1st Env Var  |   2nd Env Var  |  3rd Env Var  |
    |_______________|________________|________________|_______________|
    | LC_CTYPE:     |  LC_ALL        |  LC_CTYPE      | LANG          |
    |_______________|________________|________________|_______________|
    | LC_COLLATE:   |  LC_ALL        |  LC_COLLATE    | LANG          |
    |_______________|________________|________________|_______________|
    | LC_TIME:      |  LC_ALL        |  LC_TIME       | LANG          |
    |_______________|________________|________________|_______________|
    | LC_NUMERIC:   |  LC_ALL        |  LC_NUMERIC    | LANG          |
    |_______________|________________|________________|_______________|
    | LC_MONETARY:  |  LC_ALL        |  LC_MONETARY   | LANG          |
    |_______________|________________|________________|_______________|
    | LC_MESSAGES:  |  LC_ALL        |  LC_MESSAGES   | LANG          |
    |_______________|________________|________________|_______________|

     If a pointer to a string is given  for  locale,  setlocale()
     attempts to set the locale for the given category to locale.
     If setlocale() succeeds, locale is returned. If  setlocale()
     fails,  a  null pointer is returned and the program's locale
     is not changed.

     For category LC_ALL, the behavior is slightly different.  If
     a  pointer  to  a  string  is given for locale and LC_ALL is
     given for category, setlocale() attempts to set  the  locale
     for  all the categories to locale.  The locale may be a sim-
     ple locale, consisting of a single locale,  or  a  composite
     locale.  If  the locales for all the categories are the same
     after all the attempted  locale  changes,  setlocale()  will
     return  a pointer to the common simple locale. If there is a
     mixture of locales among the  categories,  setlocale()  will
     return a composite locale.


RETURN VALUES


SunOS 5.11          Last change: 19 Sep 2005                    2


Standard C Library Functions                        setlocale(3C)

     Upon successful completion, setlocale() returns  the  string
     associated  with  the specified category for the new locale.
     Otherwise,  setlocale()  returns  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  is  not
     changed.

     The string returned by setlocale() is such that a subsequent
     call  with  that  string  and  its  associated category will
     restore that  part  of  the  program's  locale.  The  string
     returned  must  not  be  modified by the program, but may be
     overwritten by a subsequent call to setlocale().


ERRORS

     No errors are defined.


FILES

     /usr/lib/locale/locale    locale  database   directory   for
                               locale


ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | CSI                         | Enabled                     |
    |_____________________________|_____________________________|
    | Interface Stability         | Standard                    |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe with exceptions     |
    |_____________________________|_____________________________|


SEE ALSO

     locale(1), ctype(3C), getdate(3C)  gettext(3C),  gettxt(3C),
     isdigit(3C),    libc(3LIB),    localeconv(3C),   mbtowc(3C),
     strcoll(3C),    strftime(3C),    strptime(3C)    strxfrm(3C)
     tolower(3C),    wctomb(3C),    attributes(5),    environ(5),
     locale(5), standards(5)


NOTES


SunOS 5.11          Last change: 19 Sep 2005                    3


Standard C Library Functions                        setlocale(3C)

     It is unsafe for any thread to  change  locale  (by  calling
     setlocale()  with  a  non-null  locale  argument)  in a mul-
     tithreaded application while any other thread in the  appli-
     cation  is  using  any  locale-sensitive  routine. To change
     locale in a multithreaded application, setlocale() should be
     called  prior  to  using any locale-sensitive routine. Using
     setlocale() to query the current locale is safe and  can  be
     used  anywhere  in  a  multithreaded application except when
     some other thread is changing locale.

     It is the user's responsibility to ensure that mixed  locale
     categories  are  compatible. For example, setting LC_CTYPE=C
     and LC_TIME=ja (where ja indicates Japanese) will not  work,
     because  Japanese  time  cannot  be  represented  in the "C"
     locale's ASCII codeset.

SunOS 5.11          Last change: 19 Sep 2005                    4


Man(1) output converted with man2html


FhG Schily's Home VED powered