setlocale man page on CentOS

Man page or keyword search:  
man Server   8420 pages
apropos Keyword Search (all sections)
Output format
CentOS logo
[printable version]

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

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() , isws‐
       pace() , iswupper() , iswxdigit() , isxdigit() , localeconv() , mblen()
       ,  mbstowcs()  , mbtowc() , nl_langinfo() , printf() , scanf() , setlo‐
       cale , 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(P)
[top]

List of man pages available for CentOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net