setlocale, _wsetlocale

Go Up to locale.h Index

Header File

locale.h

Category

Miscellaneous Routines

Prototype

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

wchar_t * _wsetlocale( int category, const wchar_t *locale); 

Description

Use the setlocale to select or query a locale.

C++Builder supports all locales supported in Win95/98/2000 operating systems. See your system documentation for details.

The possible values for the category argument are as follows:

LC_ALL	Affects all the following categories
LC_COLLATE	Affects strcoll and strxfrm
LC_CTYPE	Affects single-byte character handling functions. The mbstowcs and mbtowc functions are not affected.
LC_MONETARY	Affects monetary formatting by the localeconv function
LC_NUMERIC	Affects the decimal point of non-monetary data formatting. This includes the printf family of functions, and the information returned by localeconv.
LC_TIME	Affects strftime

The locale argument is a pointer to the name of the locale or named locale category. Passing a NULL pointer returns the current locale in effect. Passing a pointer that points to a null string requests setlocale to look for environment variables to determine which locale to set. The locale names are not case sensitive.

When setlocale is unable to honor a locale request, the preexisting locale in effect is unchanged and a null pointer is returned.

If the locale argument is a NULL pointer, the locale string for the category is returned. If category is LC_ALL, a complete locale string is returned. The structure of the complete locale string consists of the names of all the categories in the current locale concatenated and separated by semicolons. This string can be used as the locale parameter when calling setlocale with any of the LC_xxx values. This will reinstate all the locale categories that are named in the complete locale string, and allows saving and restoring of locale states. If the complete locale string is used with a single category, for example, LC_TIME, only that category will be restored from the locale string.

If an empty string "" is used as the locale parameter an implementation-defined locale is used. This is the ANSI C specified behavior.

To take advantage of dynamically loadable locales in your application, define __USELOCALES__ for each module. If __USELOCALES__ is not defined, all locale-sensitive functions and macros will work only with the default C locale.

If a NULL pointer is used as the argument for the locale parameter, setlocale returns a string that specifies the current locale in effect. If the category parameter specifies a single category, such as LC_COLLATE, the string pointed to will be the name of that category. If LC_ALL is used as the category parameter then the string pointed to will be a full locale string that will indicate the name of each category in effect.

.
.
.
localenameptr = setlocale( LC_COLLATE, NULL );
if (localenameptr)
   printf( "%s\n", localenameptr );
.
.
.

The output here will be one of the module names together with the specified code page. For example, the output could be LC_COLLATE = English_United States.437.

.
.
.
localenameptr = setlocale( LC_ALL, NULL );
if (localenameptr)
  printf( "%s\n", localenameptr );
.
.
.

An example of the output here could be the following:

 LC_COLLATE=English_United States.437;
 LC_TIME=English_United States.437;
 LC_CTYPE=English_United States.437;

Each category in this full string is delimited by a semicolon. This string can be copied and saved by an application and then used again to restore the same locale categories at another time. Each delimited name corresponds to the locale category constants defined in locale.h. Therefore, the first name is the name of the LC_COLLATE category, the second is the LC_CTYPE category, and so on. Any other categories named in the locale.h header file are reserved for future implementation.

To set all default categories for the specified French locale:

 setlocale( LC_ALL, "French_France.850" ); 

To find out which code page is currently being used:

 localenameptr = setlocale( LC_ALL, NULL ); 

Return value

If selection is successful, setlocale returns a pointer to a string that is associated with the selected category (or possibly all categories) for the new locale.

If UNICODE is defined, _wsetlocale returns a wchar_t string.

On failure, a NULL pointer is returned and the locale is unchanged. All other possible returns are discussed in the Remarks section above.

Example

#include <locale.h>
#include <stdio.h>
int main(void)
{
   char *old_locale;
   old_locale = setlocale(LC_ALL,"C");
   printf("Old locale was %s\n",old_locale);
   return 0;
}

Portability

	POSIX	Win32	ANSI C	ANSI C++
setlocale	+	+	+	+
_wsetlocale		+