setlocale - modify and query a program's locale


     #include <locale.h>

     char *setlocale(int category, const char *locale);


     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

     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

          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_CTIME:     |  LC_ALL        | LC_CTIME       | 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.


     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

     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().


     No errors are defined.


           locale database directory for locale


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

    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    | MT-Level                    | MT-Safe with exceptions     |
    | CSI                         | Enabled                     |


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


     To change locale in a multithreaded application, setlocale()
     should  be  called  prior to using any locale-sensitive rou-
     tine.  Using setlocale() to query the current locale is safe
     and can be used anywhere in a multithreaded application.

     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.

     Internationalization functions by setlocale() are  supported
     only  when  the  dynamic  linking  version  of libc has been
     linked with the application. If the static  linking  version
     of  libc  has  been linked with the application, setlocale()
     can handle only C and POSIX locales.

Man(1) output converted with man2html