1<html lang="en"> 2<head> 3<title>setlocale - Untitled</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="Untitled"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="up" href="Locale.html#Locale" title="Locale"> 9<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 10<meta http-equiv="Content-Style-Type" content="text/css"> 11<style type="text/css"><!-- 12 pre.display { font-family:inherit } 13 pre.format { font-family:inherit } 14 pre.smalldisplay { font-family:inherit; font-size:smaller } 15 pre.smallformat { font-family:inherit; font-size:smaller } 16 pre.smallexample { font-size:smaller } 17 pre.smalllisp { font-size:smaller } 18 span.sc { font-variant:small-caps } 19 span.roman { font-family:serif; font-weight:normal; } 20 span.sansserif { font-family:sans-serif; font-weight:normal; } 21--></style> 22<link rel="stylesheet" type="text/css" href="../cs.css"> 23</head> 24<body> 25<div class="node"> 26<a name="setlocale"></a> 27<p> 28Up: <a rel="up" accesskey="u" href="Locale.html#Locale">Locale</a> 29<hr> 30</div> 31 32<h3 class="section">9.1 <code>setlocale</code>, <code>localeconv</code>—select or query locale</h3> 33 34<p><a name="index-setlocale-445"></a><a name="index-localeconv-446"></a><a name="index-g_t_005fsetlocale_005fr-447"></a><a name="index-g_t_005flocaleconv_005fr-448"></a><strong>Synopsis</strong> 35<pre class="example"> #include <locale.h> 36 char *setlocale(int <var>category</var>, const char *<var>locale</var>); 37 lconv *localeconv(void); 38 39 char *_setlocale_r(void *<var>reent</var>, 40 int <var>category</var>, const char *<var>locale</var>); 41 lconv *_localeconv_r(void *<var>reent</var>); 42 43</pre> 44 <p><strong>Description</strong><br> 45<code>setlocale</code> is the facility defined by ANSI C to condition the 46execution environment for international collating and formatting 47information; <code>localeconv</code> reports on the settings of the current 48locale. 49 50 <p>This is a minimal implementation, supporting only the required <code>"POSIX"</code> 51and <code>"C"</code> values for <var>locale</var>; strings representing other locales are not 52honored unless _MB_CAPABLE is defined. 53 54 <p>If _MB_CAPABLE is defined, POSIX locale strings are allowed, following 55the form 56 57 <p>language[_TERRITORY][.charset][@modifier] 58 59 <p><code>"language"</code> is a two character string per ISO 639, or, if not available 60for a given language, a three character string per ISO 639-3. 61<code>"TERRITORY"</code> is a country code per ISO 3166. For <code>"charset"</code> and 62<code>"modifier"</code> see below. 63 64 <p>Additionally to the POSIX specifier, the following extension is supported 65for backward compatibility with older implementations using newlib: 66<code>"C-charset"</code>. 67Instead of <code>"C-"</code>, you can also specify <code>"C."</code>. Both variations allow 68to specify language neutral locales while using other charsets than ASCII, 69for instance <code>"C.UTF-8"</code>, which keeps all settings as in the C locale, 70but uses the UTF-8 charset. 71 72 <p>The following charsets are recognized: 73<code>"UTF-8"</code>, <code>"JIS"</code>, <code>"EUCJP"</code>, <code>"SJIS"</code>, <code>"KOI8-R"</code>, <code>"KOI8-U"</code>, 74<code>"GEORGIAN-PS"</code>, <code>"PT154"</code>, <code>"TIS-620"</code>, <code>"ISO-8859-x"</code> with 751 <= x <= 16, or <code>"CPxxx"</code> with xxx in [437, 720, 737, 775, 850, 852, 855, 76857, 858, 862, 866, 874, 932, 1125, 1250, 1251, 1252, 1253, 1254, 1255, 1256, 771257, 1258]. 78 79 <p>Charsets are case insensitive. For instance, <code>"EUCJP"</code> and <code>"eucJP"</code> 80are equivalent. Charset names with dashes can also be written without 81dashes, as in <code>"UTF8"</code>, <code>"iso88591"</code> or <code>"koi8r"</code>. <code>"EUCJP"</code> and 82<code>"EUCKR"</code> are also recognized with dash, <code>"EUC-JP"</code> and <code>"EUC-KR"</code>. 83 84 <p>Full support for all of the above charsets requires that newlib has been 85build with multibyte support and support for all ISO and Windows Codepage. 86Otherwise all singlebyte charsets are simply mapped to ASCII. Right now, 87only newlib for Cygwin is built with full charset support by default. 88Under Cygwin, this implementation additionally supports the charsets 89<code>"GBK"</code>, <code>"GB2312"</code>, <code>"eucCN"</code>, <code>"eucKR"</code>, and <code>"Big5"</code>. Cygwin 90does not support <code>"JIS"</code>. 91 92 <p>Cygwin additionally supports locales from the file 93/usr/share/locale/locale.alias. 94 95 <p>(<code>""</code> is also accepted; if given, the settings are read from the 96corresponding LC_* environment variables and $LANG according to POSIX rules. 97 98 <p>This implementation also supports the modifier <code>"cjknarrow"</code>, which 99affects how the functions <code>wcwidth</code> and <code>wcswidth</code> handle characters 100from the "CJK Ambiguous Width" category of characters described at 101http://www.unicode.org/reports/tr11/#Ambiguous. These characters have a width 102of 1 for singlebyte charsets and a width of 2 for multibyte charsets 103other than UTF-8. For UTF-8, their width depends on the language specifier: 104it is 2 for <code>"zh"</code> (Chinese), <code>"ja"</code> (Japanese), and <code>"ko"</code> (Korean), 105and 1 for everything else. Specifying <code>"cjknarrow"</code> forces a width of 1, 106independent of charset and language. 107 108 <p>If you use <code>NULL</code> as the <var>locale</var> argument, <code>setlocale</code> returns a 109pointer to the string representing the current locale. The acceptable 110values for <var>category</var> are defined in `<code>locale.h</code>' as macros 111beginning with <code>"LC_"</code>. 112 113 <p><code>localeconv</code> returns a pointer to a structure (also defined in 114`<code>locale.h</code>') describing the locale-specific conventions currently 115in effect. 116 117 <p><code>_localeconv_r</code> and <code>_setlocale_r</code> are reentrant versions of 118<code>localeconv</code> and <code>setlocale</code> respectively. The extra argument 119<var>reent</var> is a pointer to a reentrancy structure. 120 121 <p><br> 122<strong>Returns</strong><br> 123A successful call to <code>setlocale</code> returns a pointer to a string 124associated with the specified category for the new locale. The string 125returned by <code>setlocale</code> is such that a subsequent call using that 126string will restore that category (or all categories in case of LC_ALL), 127to that state. The application shall not modify the string returned 128which may be overwritten by a subsequent call to <code>setlocale</code>. 129On error, <code>setlocale</code> returns <code>NULL</code>. 130 131 <p><code>localeconv</code> returns a pointer to a structure of type <code>lconv</code>, 132which describes the formatting and collating conventions in effect (in 133this implementation, always those of the C locale). 134 135 <p><br> 136<strong>Portability</strong><br> 137ANSI C requires <code>setlocale</code>, but the only locale required across all 138implementations is the C locale. 139 140 <p><br> 141 142 </body></html> 143 144