Manual Pages for UNIX Operating System command usage for man setlocale

Standard C Library Functions                        setlocale(3C)



NAME
     setlocale - modify and query a program's locale

SYNOPSIS
     #include 

     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  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 simple
     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         | Committed                   |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe with exceptions     |
    |_____________________________|_____________________________|
    | Standard                    | See standards(5).           |
    |_____________________________|_____________________________|


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)




SunOS 5.11          Last change: 19 Sep 2005                    3






Standard C Library Functions                        setlocale(3C)



NOTES
     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