unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

SETLOCALE(3V)                                                    SETLOCALE(3V)



NAME
       setlocale, nl_init - set international environment

SYNOPSIS
       #include <&lt;locale.h>&gt;

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

       int nl_init(lang)
       char *lang;

DESCRIPTION
       setlocale()  selects  the  appropriate piece of the program's locale as
       specified by category, and may be used to change or query the program's
       international environment.  The entire locale may be changed by calling
       setlocale() with category set to LC_ALL.  The other possible values for
       category query or change only a part of the program's complete interna-
       tional locale:

       LC_CTYPE
              Affects the behavior of the character classification and conver-
              sion functions.  See ctype(3V), and mblen(3).

       LC_COLLATE
              Affects  the  behavior of the string collation functions strcoll
              (3) and strxfrm(3V).

       LC_TIME
              Affects the behavior of  the  time  conversion  functions.   See
              printf(3V),  scanf(3V), strtod(3), and ctime(3V) for strftime(),
              strptime(), and ctime().

       LC_NUMERIC
              Affects the radix character for the formatted input/output func-
              tions and the string conversion functions, gcvt(3V), printf(3V),
              strtod(3),   gconvert(),    sgconvert()    (see    econvert(3)),
              file_to_decimal(),  and  func_to_decimal()  (see string_to_deci-
              mal(3)).  Also affects the non-monetary  formatting  information
              returned by the localeconv() function.

       LC_MONETARY
              Affects  the  monetary  formatting  information  returned by the
              localeconv() function.

       LC_MESSAGES
              Affects the behavior of functions that present messages,  namely
              gettext(), and textdomain().

       The  locale  argument is a pointer to a character string containing the
       required setting of category.  The following preset  values  of  locale
       are defined for all settings of category:

       "C"    Specifies  the minimal environment for C translation.  If setlo-
              cale() is not invoked, the "C" locale is  the  default.   Opera-
              tional  behavior within the "C" locale is defined separately for
              each interface function.

       At program startup, the equivalent of:

       ""     In this case, setlocale() will first check the value of the cor-
              responding  environment  variable (for example, LC_CTYPE for the
              LC_CTYPE category) and if valid (that is, points to the name  of
              a  valid locale), setlocale() sets the specified category of the
              international environment to that value and returns  the  string
              corresponding to the locale set (that is, the value of the envi-
              ronment variable, not "").  If the value is invalid, setlocale()
              returns  a NULL pointer and the international environment is not
              changed by this call.

              If the environment variable corresponding to the specified cate-
              gory  is not set or is set to the empty string, setlocale() will
              examine the LANG environment variable.  If both the  LANG  envi-
              ronment  variable, and the environment variable corresponding to
              the specified category are not set  or  are  set  to  the  empty
              string,  then  the  LC_default environment variable is examined.
              If this contains a valid setting, then the category  is  set  to
              the  value  of  LC_default.  If the LANG environment variable is
              set and valid this will set the category  to  the  corresponding
              value  of  LANG.   If  LC_default  is  not set, then setlocale()
              returns that category to the default "C" locale.

       To set all categories in the international environment, setlocale()  is
       invoked in the following manner:

              setlocale (LC_ALL,  "" );

       To  satisfy  this  request,  setlocale()  first checks all the relevant
       environment  variables  LC_CTYPE,  LC_COLLATE,   LC_TIME,   LC_NUMERIC,
       LC_MONETARY,  LC_MESSAGES.   If  any  one of these relevant environment
       variables is invalid, this call  to  setlocale()  will  return  a  NULL
       pointer, and the international environment will not be changed.  If all
       the relevant environment variables  are  valid,  setlocale()  sets  the
       international  environment  to  reflect  the  values of the environment
       variables.  The categories are set in the following order:

              LC_CTYPE
              LC_COLLATE
              LC_TIME
              LC_NUMERIC
              LC_MONETARY
              LC_MESSAGES

       Using this scheme, the  categories  corresponding  to  the  environment
       variables  will  override the value of the LANG and LC_default environ-
       ment variables for a particular category.

       nl_init() is equivalent to

              setlocale(LC_ALL, "");

       and is supplied for compatibility with X/Open XPG2.

RETURN VALUES
       If a valid string is given for the locale parameter, and the  selection
       can  be  honored,  setlocale()  returns  the string associated with the
       specified category for the new locale.  If the selection cannot be hon-
       ored,  setlocale()  returns  a null pointer and the program's locale is
       not changed.

       A NULL pointer for locale causes setlocale() to return the string asso-
       ciated  with  the  category  for the program's current locale; the pro-
       gram's locale is not changed.  The string contains information relating
       to  each  piece  part  of  the  whole  international environment.  This
       inquiry can fail by  returning  a  null  pointer  if  any  category  is
       invalid.

       The  string  returned  by such a setlocale() call is such that a subse-
       quent call with the string and its  associated  category  will  restore
       that part of the program's locale.  The string returned by:

              ptr = setlocale(LC_ALL, (char *) 0);

       is such that in a subsequent call:

              setlocale(LC_ALL, ptr);

       will  reset  each  and  every category to the state when the string was
       first returned.  The string returned must not be modified by  the  pro-
       gram, but will be overwritten by a subsequent call to setlocale().

FILES
       /etc/locale/locale/category
                           locale  is  the  directory  that  contains numerous
                           files (categories), each relating to a single cate-
                           gory  of  a  valid  locale  as selected by category
                           argument to setlocale().  Generally this is classed
                           as a private directory.  This directory is searched
                           by setlocale(), prior to searching:
       /usr/share/lib/locale/locale/category
                           locale is  the  directory  that  contains  numerous
                           files (categories), each relating to a single cate-
                           gory of a valid  locale  as  selected  by  category
                           argument  to  setlocale().   Generally this data is
                           classed as global and sharable.

DIAGNOSTICS
       setlocale() returns a null pointer if a relevant  environment  variable
       has  an  invalid  setting.   setlocale() also returns a null pointer if
       category is invalid.



                                21 January 1990                  SETLOCALE(3V)