Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
std::setlocale(3)	      C++ Standard Libary	     std::setlocale(3)

NAME
       std::setlocale -	std::setlocale

Synopsis
	  Defined in header <clocale>
	  char*	setlocale( int category, const char* locale );

	  The  setlocale  function installs the	specified system locale	or its
       portion as the
	  new C	locale.	The modifications remain in effect and influences  the
       execution of all
	  locale-sensitive  C  library functions until the next	call to	setlo-
       cale. If	locale is
	  a null pointer, setlocale queries the	current	C locale without modi-
       fying it.

Parameters
	  category - locale category identifier, one of	the LC_xxx macros. May
       be 0.
	  locale   - system-specific locale identifier.	 Can  be  ""  for  the
       user-preferred
		     locale or "C" for the minimal locale

Return value
	  Pointer  to a	narrow null-terminated string identifying the C	locale
       after applying
	  the changes, if any, or null pointer on failure.

	  A copy of the	returned string	along with the category	used  in  this
       call to
	  std::setlocale  may  be used later in	the program to restore the lo-
       cale back to the
	  state	at the end of this call.

Notes
	  During program startup,  the	equivalent  of	std::setlocale(LC_ALL,
       "C"); is	executed
	  before any user code is run.

	  Although  the	return type is char*, modifying	the pointed-to charac-
       ters is undefined
	  behavior.

	  Because setlocale modifies global state which	affects	 execution  of
       locale-dependent
	  functions,  it  is  undefined	 behavior  to call it from one thread,
       while another thread
	  is executing any of the following functions: std::fprintf,  std::is-
       print,
	  std::iswdigit,  std::localeconv, std::tolower, std::fscanf, std::is-
       punct,
	  std::iswgraph, std::mblen, std::toupper, std::isalnum, std::isspace,
       std::iswlower,
	  std::mbstowcs, std::towlower,	std::isalpha, std::isupper,  std::isw-
       print,
	  std::mbtowc,	std::towupper,	std::isblank, std::iswalnum, std::isw-
       punct,
	  std::setlocale, std::wcscoll,	std::iscntrl, std::iswalpha, std::isw-
       space,
	  std::strcoll,	std::wcstod, std::isdigit, std::iswblank,  std::iswup-
       per,
	  std::strerror,     std::wcstombs,    std::isgraph,	std::iswcntrl,
       std::iswxdigit,
	  std::strtod,	   std::wcsxfrm,     std::islower,	std::iswctype,
       std::isxdigit.

	  POSIX	 also defines a	locale named "POSIX", which is always accessi-
       ble and is exactly
	  equivalent to	the default minimal "C"	locale.

	  POSIX	also specifies that the	returned pointer, not  just  the  con-
       tents of	the
	  pointed-to  string, may be invalidated by subsequent calls to	setlo-
       cale.

Example
       // Run this code

	#include <clocale>
	#include <cstdio>
	#include <ctime>
	#include <cwchar>
	#include <iterator>
	#include <string>

	int main()
	{
	    // Make a "deep copy" of current locale name.
	    std::string	prev_loc = std::setlocale(LC_ALL, nullptr);

	    // The C locale will be UTF-8 enabled English,
	    // decimal dot will	be German,
	    // date and	time formatting	will be	Japanese.
	    if (const char* loc	= std::setlocale(LC_ALL, "en_US.UTF-8"))
		std::wprintf(L"New LC_ALL locale: %s\n", loc);
	    if (const char* loc	= std::setlocale(LC_NUMERIC, "de_DE.UTF-8"))
		std::wprintf(L"New LC_NUMERIC locale: %s\n", loc);
	    if (const char* loc	= std::setlocale(LC_TIME, "ja_JP.UTF-8"))
		std::wprintf(L"New LC_TIME locale: %s\n", loc);

	    wchar_t buf[100];
	    std::time_t	t = std::time(nullptr);
	    std::wcsftime(buf, std::size(buf), L"%A %c", std::localtime(&t));
	    std::wprintf(L"Number: %.2f\nDate: %Ls\n", 3.14, buf);

	    // Restore the previous locale.
	    if (const char* loc	= std::setlocale(LC_ALL, prev_loc.c_str()))
		std::wprintf(L"Restorred LC_ALL	locale:	%s\n", loc);
	}

Possible output:
	New LC_ALL locale: en_US.UTF-8
	New LC_NUMERIC locale: de_DE.UTF-8
	New LC_TIME locale: ja_JP.UTF-8
	Number:	3,14
	Date:  20221106	204059
	Restorred LC_ALL locale: C

See also
	  LC_ALL
	  LC_COLLATE
	  LC_CTYPE    locale categories	for std::setlocale
	  LC_MONETARY (macro constant)
	  LC_NUMERIC
	  LC_TIME
	  locale      set of polymorphic facets	that encapsulate cultural dif-
       ferences
		      (class)
	  C documentation for
	  setlocale

External links
	  1.  List of Windows locale names.
	  2.  List of Linux locale names.

http://cppreference.com		  2024.06.10		     std::setlocale(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::setlocale&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>

home | help