setlocale, _wsetlocale

Sets or retrieves the run-time locale.

Syntax

Parameters

category
Category affected by locale.

locale
Locale specifier.

Return value

If a valid locale and category are given, returns a pointer to the string associated with the specified locale and category. If the locale or category isn’t valid, returns a null pointer, and the current locale settings of the program are unchanged.

For example, the call

sets all categories, returning only the string

You can copy the string returned by setlocale to restore that part of the program’s locale information. Global or thread local storage is used for the string returned by setlocale . Later calls to setlocale overwrite the string, which invalidates string pointers returned by earlier calls.

Remarks

Use the setlocale function to set, change, or query some or all of the current program locale information specified by locale and category. locale refers to the locality (country/region and language) for which you can customize certain aspects of your program. Some locale-dependent categories include the formatting of dates and the display format for monetary values. If you set locale to the default string for a language that has multiple forms supported on your computer, you should check the setlocale return value to see which language is in effect. For example, if you set locale to «chinese» the return value could be either «chinese-simplified» or «chinese-traditional».

_wsetlocale is a wide-character version of setlocale ; the locale argument and return value of _wsetlocale are wide-character strings. _wsetlocale and setlocale behave identically otherwise.

By default, this function’s global state is scoped to the application. To change this, see Global state in the CRT.

Generic-Text Routine Mappings

TCHAR.H routine	_UNICODE & _MBCS not defined	_MBCS defined	_UNICODE defined
_tsetlocale	setlocale	setlocale	_wsetlocale

The category argument specifies the parts of a program’s locale information that are affected. The macros used for category and the parts of the program they affect are as follows:

category flag	Affects
LC_ALL	All categories, as listed below.
LC_COLLATE	The strcoll , _stricoll , wcscoll , _wcsicoll , strxfrm , _strncoll , _strnicoll , _wcsncoll , _wcsnicoll , and wcsxfrm functions.
LC_CTYPE	The character-handling functions (except isdigit , isxdigit , mbstowcs , and mbtowc , which are unaffected).
LC_MONETARY	Monetary-formatting information returned by the localeconv function.
LC_NUMERIC	Decimal-point character for the formatted output routines (such as printf ), for the data-conversion routines, and for the non-monetary formatting information returned by localeconv . In addition to the decimal-point character, LC_NUMERIC sets the thousands separator and the grouping control string returned by localeconv.
LC_TIME	The strftime and wcsftime functions.

This function validates the category parameter. If the category parameter isn’t one of the values given in the previous table, the invalid parameter handler is invoked, as described in Parameter Validation. If execution is allowed to continue, the function sets errno to EINVAL and returns NULL .

The locale argument is a pointer to a string that specifies the locale. For information about the format of the locale argument, see Locale Names, Languages, and Country/Region Strings. If locale points to an empty string, the locale is the implementation-defined native environment. A value of C specifies the minimal ANSI conforming environment for C translation. The C locale assumes that all char data types are 1 byte and that their value is always less than 256.

At program startup, the equivalent of the following statement is executed:

setlocale( LC_ALL, «C» );

The locale argument can take a locale name, a language string, a language string and country/region code, a code page, or a language string, country/region code, and code page. The set of available locale names, languages, country/region codes, and code pages includes all those supported by the Windows NLS API. The set of locale names supported by setlocale are described in Locale Names, Languages, and Country/Region Strings. The set of language and country/region strings supported by setlocale are listed in Language Strings and Country/Region Strings. We recommend the locale name form for performance and for maintainability of locale strings embedded in code or serialized to storage. The locale name strings are less likely to be changed by an operating system update than the language and country/region name form.

A null pointer that’s passed as the locale argument tells setlocale to query instead of to set the international environment. If the locale argument is a null pointer, the program’s current locale setting isn’t changed. Instead, setlocale returns a pointer to the string that’s associated with the category of the thread’s current locale. If the category argument is LC_ALL , the function returns a string that indicates the current setting of each category, separated by semicolons. For example, the sequence of calls

which is the string that’s associated with the LC_ALL category.

The following examples pertain to the LC_ALL category. Either of the strings «.OCP» and «.ACP» can be used instead of a code page number to specify use of the user-default OEM code page and user-default ANSI code page for that locale name, respectively.

Sets the locale to the default, which is the user-default ANSI code page obtained from the operating system. The locale name is set to the value returned by GetUserDefaultLocaleName. The code page is set to the value returned by GetACP.

setlocale( LC_ALL, «.OCP» );

Sets the locale to the current OEM code page obtained from the operating system. The locale name is set to the value returned by GetUserDefaultLocaleName. The code page is set to the LOCALE_IDEFAULTCODEPAGE value for the user-default locale name by GetLocaleInfoEx.

setlocale( LC_ALL, «.ACP» );

Sets the locale to the ANSI code page obtained from the operating system. The locale name is set to the value returned by GetUserDefaultLocaleName. The code page is set to the LOCALE_IDEFAULTANSICODEPAGE value for the user-default locale name by GetLocaleInfoEx.

Sets the locale to the locale name that’s indicated by . The code page is set to the LOCALE_IDEFAULTANSICODEPAGE value for the specified locale name by GetLocaleInfoEx.

setlocale( LC_ALL, » _ » );

Sets the locale to the language and country/region indicated by and , together with the default code page obtained from the host operating system. The code page is set to the LOCALE_IDEFAULTANSICODEPAGE value for the specified locale name by GetLocaleInfoEx.

setlocale( LC_ALL, » _ . » );

Sets the locale to the language, country/region, and code page indicated by the , , and strings. You can use various combinations of language, country/region, and code page. For example, this call sets the locale to French Canada with code page 1252:

setlocale( LC_ALL, «French_Canada.1252» );

This call sets the locale to French Canada with the default ANSI code page:

setlocale( LC_ALL, «French_Canada.ACP» );

This call sets the locale to French Canada with the default OEM code page:

setlocale( LC_ALL, «French_Canada.OCP» );

Sets the locale to the language that’s indicated by , and uses the default country/region for the specified language and the user-default ANSI code page for that country/region as obtained from the host operating system. For example, the following calls to setlocale are functionally equivalent:

setlocale( LC_ALL, «en-US» );

setlocale( LC_ALL, «English» );

setlocale( LC_ALL, «English_United States.1252» );

We recommend the first form for performance and maintainability.

Sets the code page to the value indicated by , together with the default country/region and language (as defined by the host operating system) for the specified code page.

The category must be either LC_ALL or LC_CTYPE to effect a change of code page. For example, if the default country/region and language of the host operating system are «United States» and «English,» the following two calls to setlocale are functionally equivalent:

setlocale( LC_ALL, «.1252» );

setlocale( LC_ALL, «English_United States.1252»);

For more information, see the setlocale pragma directive in the C/C++ Preprocessor Reference.

The function _configthreadlocale is used to control whether setlocale affects the locale of all threads in a program or only the locale of the calling thread.

UTF-8 Support

Starting in Windows 10 build 17134 (April 2018 Update), the Universal C Runtime supports using a UTF-8 code page. This means that char strings passed to C runtime functions will expect strings in the UTF-8 encoding. To enable UTF-8 mode, use «UTF-8» as the code page when using setlocale . For example, setlocale(LC_ALL, «.utf8») will use the current default Windows ANSI code page (ACP) for the locale and UTF-8 for the code page.

After calling setlocale(LC_ALL, «.UTF8») , you may pass «рџ˜Љ» to mbtowcs and it will be properly translated to a wchar_t string, whereas previously there was not a locale setting available to do this.

UTF-8 mode is also enabled for functions that have historically translated char strings using the default Windows ANSI code page (ACP). For example, calling _mkdir(«рџ˜Љ») while using a UTF-8 code page will correctly produce a directory with that emoji as the folder name, instead of requiring the ACP to be changed to UTF-8 prior to running your program. Likewise, calling _getcwd() inside of that folder will return a UTF-8 encoded string. For compatibility, the ACP is still used if the C locale code page is not set to UTF-8.

The following aspects of the C Runtime that are not able to use UTF-8 because they are set during program startup and must use the default Windows ANSI code page (ACP): __argv , _acmdln , and _pgmptr .

Previous to this support, mbrtoc16 , mbrtoc32 , c16rtomb , and c32rtomb existed to translate between UTF-8 narrow strings, UTF-16 (same encoding as wchar_t on Windows platforms) and UTF-32. For compatibility reasons, these APIs still only translate to and from UTF-8 and not the code page set via setlocale .

To use this feature on an OS prior to Windows 10, such as Windows 7, you must use app-local deployment or link statically using version 17134 of the Windows SDK or later. For Windows 10 operating systems prior to 17134, only static linking is supported.

Requirements

Routine	Required header
setlocale
_wsetlocale	or

For additional compatibility information, see Compatibility.

SystemLocale (microsoft-windows-international-core-winpe-systemlocale)

SystemLocale specifies the default language to use for non-Unicode programs.

This setting is used by both Windows Setup and Windows Deployment Services.

The system locale specifies which bitmap fonts and code pages (for example, ANSI or DOS) are used on the system by default. The system locale setting affects only ANSI applications (non-Unicode) applications. The language for non-Unicode programs is a per-system setting.

Users can change the system locale by using the Administrative tab in the Region and Language Options item in Control Panel.

For the list of supported languages, locales, and identifiers, see Supported Language Packs and Default Settings.

Values

Specifies the locale of the system.

The System_locale string is based on the language-tagging conventions of RFC 3066. The pattern language-region is used, where language is a language code and region is a country or region identifier (for example, en-US, fr-FR, or es-ES).

This value is not case-sensitive.

This string type supports empty elements.

Parent Hierarchy

Valid Configuration Passes

Applies To

For the list of the Windows editions and architectures that this component supports, see microsoft-windows-international-core-winpe—.

XML Example

The following example shows how to set the system locale to English (United States).

Локали и кодировки

Введение

При разработке веб-приложений есть три важных момента, связанных с кодировками: информация в файлах-сценариях, информация в базе данных и браузер пользователя. Если выставить хотя бы одну кодировку неверно, то, в лучшем случае, данные отобразятся неверно, в худшем, безвозвратно потеряются. Чтобы этого не произошло, а приложение работало корректно при любых настройках сервера, нужно правильно выставить кодировки.

Работа с локалями в PHP

Работа с локалями в PHP выглядит одинаково и в UNIX, и в Windows, и в любой другой платформе. Для установки значений локали служит всего одна функция setlocale() . Чтобы выставить локаль, нужно передать функции первым аргументом категорию, на которую эта локаль распространяется, последующими список возможных локалей. Результатом будет название первой подходящей локали, которая и была установлена.

Локали в Windows

Для того, чтобы узнать, какие локали доступны в Windows, нужно зайти в панель управления, «Язык и региональные стандарты».

На вкладке «Дополнительно», в разделе «Кодовые страницы таблиц преобразования» показан список всех возможных локалей для Windows, которые можно использовать в PHP. Кодовые страницы, которые отмечены в списке, из PHP могут быть использованы по их номеру. В общем случае, использование выглядит по следующей схеме: Язык_Регион.Номер_кодовой_страницы Для России это может выглядеть как Russian_Russia.1251 (cp1251) или Russian_Russia.20866 (KOI8-R). Для Украины — Ukrainian_Ukraine.1251 (cp1251). Вместо длинных названий можно использовать сокращённые russian , american , ukrainian и так далее. При этом кодовая страница выставится с учётом региональных настроек, для России и Украины — 1251, для Америки — 1252. Единственная кодировка, с которой у меня возникли проблемы, как ни странно, оказалась UTF-8. При попытке выставить эту кодировку, выставляются все категории локалей, кроме основной. Вывод локализованных сообщений при этом идёт в cp1251. Пока это можно списать на внутренний механизм PHP работы со строками. С шестой версии PHP вся обработка строк должна будет вестись в UTF-8, но до тех пор надо просто знать об этом и делать поправку. Ещё одной странностью при работе с локалями в PHP на Windows является неправильная работа с категориями локалей. Так, например, я выставляю локаль на функции времени KOI8-R, setlocale(LC_TIME, ‘Russian_Russia.20866’) , но почему-то выставляется cp1251 на все категории. Суть проблемы я так и не понял, возможно, это просто баг (проверялось на PHP 5.2.3), а возможно, что внутренний механизм Windows просто не позволяет этого делать. Хотя по мне, так это чистой воды баг. В общем-то, на этом можно и закончить разговор о локалях на Windows. Главное, запомнить, что локали, которые портированы из UNIX, под WIndows работают только для «галочки». Шаг влево, шаг вправо и результат будет непредсказуемым. Безопасно можно использовать только cp1251 (windows-1251) и KOI8-R, и только для LC_ALL . Локали в UNIX Выше я описал работу с локалями в Windows, теперь можно заострить внимание на UNIX-like системах. Для простоты, я буду их называть UNIX, а подразумевать FreeBSD :). В контексте данной статьи это не особо важно. Итак, дистрибутивы UNIX поставляются в одном виде для всех, и работа рассчитана на многопользовательский режим, поэтому о правильной настройке локали должен заботиться сам пользователь, например: Так может выглядеть работа системной команды locale , которая выводит текущие настройки локали для пользователя. А так, обычно, выглядят настройки локали для пользователя, под которым работает PHP: Функция ucwords() должна была сделать заглавными первые буквы всех слов. А перед этим strtolower() должна была предварительно все заглавные буквы сделать строчными. Но ничего не произошло. Так же не будет работать следующий код: Хотя \w является множеством знаков, из которых может состоять слово (алфавит, цифры и _), регулярное выражение не срабатывает. Причина как раз в том, что, работая с cp1251, мы не сказали об этом php. Чтобы исправить положение, достаточно воспользоваться функцией setlocale() и указать правильную локаль, например, так: Здесь первый аргумент — это категория, на которую будет распространяться локаль (константа LC_*), второй — название локали. Начиная с версии 4.3.0 можно указывать несколько имён локалей в виде массива или в качестве дополнительных аргументов. После вызова функция установит первую подходящую локаль и вернёт её имя: С помощью команды grep я отобрал локали, которые поддерживают русский язык. Любую из них можно использовать, однако следует понимать, что данные должны быть в кодировке, на которую рассчитана локаль. Если же это правило не будет соблюдено, то результат может оказаться весьма неожиданным: Если учесть, что koi8-r достаточно популярная кодировка для UNIX-севреров, а windows-1251 для русскоязычных сайтов, то подобное «необычное» поведение не такая уж и редкость. Когда-то я и сам столкнулся с этой проблемой при портировании проекта на реальный хостинг. После установки правильной локали все примеры, которые не работали выше, будут работать как нужно! По-русски заговорит и функция strftime(), которая корректно работает с локалями, а также и всё остальное, что зависит от локали. Кодировки в MySQL Напомню, что возможность задавать кодировки появилась только в MySQL 4.1.11 и выше. В отличие от php, проблемы с кодировками базы данных проявляют себя гораздо быстрее, чем проблемы с локалью. И связано это прежде всего с хранением и выборкой данных, поскольку от этого зависит информация на сайте. Я не буду подробно расписывать все тонкости, поскольку есть отдельная статья, остановлюсь на самых важных моментах. Первое, чему необходимо научиться, смотреть текущие настройки соединения с mysql: Критичными для пользователя являются character_set_client и character_set_results, которые отвечают за кодировку, в которой данные поступают в базу, и кодировку, в которой данные поступают из базы к пользователю. Если эти две кодировки отличаются от той, в которой работает клиент, в нашем случае php-скрипты, то неминуемо будут «странности», например, при сортировке выборки или внесении данных в базу. Второе, что необходимо знать, как правильно сообщить mysql о кодировках. Самый простой и правильный способ, это использовать запрос set names: После этого три переменные character_set_client, character_set_connection и character_set_results примут значение cp1251. Это будет означать — клиент работает в кодировке windows-1251 (cp1251). Помимо этого можно устанавливать непосредственно серверные переменные: Теперь данные поступают и извлекаются в разных кодировках. Список доступных кодировок можно просмотреть так: И третье, что необходимо знать, — правила создания таблиц для хранения данных в нужной кодировке. К слову, данные можно хранить в любой кодировке, а работать с ними в кодировке клиента. Однако, важно понимать, что кодировки носят национальный характер и должны соответствовать вносимым данным. Иначе будут потери. Для русского языка есть три национальных кодировки koi8r, cp866, cp1251, которые могут конвертироваться друг в друга без потерь. Также можно использовать интернациональную кодировку UTF8. Кодировку можно выставить на базу данных, таблицу и поле таблицы. Так, например, можно создать базу данных в кодировке koi8r: Следует отметить, что кодировка базы данных влияет только на дефолтные значения кодировок при создании таблиц. Это значит, что неважно в какой кодировке была создана база, если кодировка таблицы была задана явно. Это же правило относится и к полям таблицы. Следующим шагом я создам таблицу в cp1251 и одним полем в utf8: После того, как таблица создана с нужными параметрами кодировки, mysql автоматически начинает переводить данные при внесении и выборке. Данные хранятся в разном виде, но поступают к пользователю именно так, как надо! Подробнее с кодировками и проблемами их использования можно ознакомиться на http://dev.mysql.com/doc/refman/5.1/en/charset.html. Кодировка HTML-страниц Объявить кодировку html-страницы можно двумя способами: через заголовки и мета-тег в самой странице. Мета-тег используется только в статичных страницах. Я не буду его разбирать, это проблемы html. Во всех остальных случаях предпочтительней использовать HTTP-заголовок Content-Type. PHP позволяет работать с HTTP-заголовками посредством функции header(): Но браузер отобразит страницу корректно только в том случае, когда php-файлы сами были созданы в кодировке cp1251. Также нужно понимать, что заголовки должны быть отправлены до любого вывода на экран. При необходимости перекодировать страницы «на лету», достаточно воспользоваться буферизацией и iconv: Надпись «Привет, мир!» будет выведена в юникоде, при этом браузер получит информацию о кодировке через заголовки и правильно отобразит страницу. Но важно понимать, что внутри скрипта и при соединении с базой данных надо использовать windows-1251 (cp1251), поскольку страница должна быть сформирована в одной кодировке. Важно помнить, что функции iconv доступны не всегда, и проверка на доступность этих функций не будет лишней. Заключение Для безопасной разработки русскоязычных веб-проектов необходимо включать в файл с общими настройками следующие команды: Как ни странно, но эти три строчки кода значительно повышают портируемость веб-проектов. © 2021 Антон Прибора. При копировании материалов с сайта, пожалуйста, указывайте ссылку на источник. Читайте также:  Windows uninstall all programs Оцените статью Вам также может понравиться Windows или Linux: Что лучше выбрать? Есть много причин выбирать между Windows и Linux, но Файл владелец изменить linux Команда Chown в Linux Chown Command in Linux (File Установка шлюза по умолчанию linux Настройка сети вручную Содержание Краткое описание Чем разбить диск для linux ИТ База знаний Курс по Asterisk Полезно — Узнать IP — Правообладателям Политика конфиденциальности Контакты