setlocale.html

IEEE 1003.1-2003, Single Unix Specification v3

<p>Date/time formatting</p>
</li>

<li>
<p>Numeric editing</p>
</li>

<li>
<p>Monetary formatting</p>
</li>

<li>
<p>Messaging</p>
</li>
</ol>

<p>The <i>setlocale</i>() function provides the application developer with the ability to set all or portions, called
<i>categories</i>, of the international environment. These categories correspond to the areas of functionality mentioned above. The
syntax for <i>setlocale</i>() is as follows:</p>

<pre>
<tt>char *setlocale(int</tt> <i>category</i><tt>, const char *</tt><i>locale</i><tt>);
</tt>
</pre>

<p>where <i>category</i> is the name of one of following categories, namely:</p>

<blockquote>
<pre>
<i>LC_COLLATE

LC_CTYPE

LC_MESSAGES

LC_MONETARY

LC_NUMERIC

LC_TIME</i>

</pre>
</blockquote>

<p>In addition, a special value called <i>LC_ALL</i> directs <i>setlocale</i>() to set all categories.</p>

<p>There are two primary uses of <i>setlocale</i>():</p>

<ol>
<li>
<p>Querying the international environment to find out what it is set to</p>
</li>

<li>
<p>Setting the international environment, or <i>locale</i>, to a specific value</p>
</li>
</ol>

<p>The behavior of <i>setlocale</i>() 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.</p>

<p>To query the international environment, <i>setlocale</i>() is invoked with a specific category and the NULL pointer as the
locale. The NULL pointer is a special directive to <i>setlocale</i>() that tells it to query rather than set the international
environment. The following syntax is used to query the name of the international environment:</p>

<pre>
<tt>setlocale({LC_ALL, LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, \
    LC_NUMERIC, LC_TIME},(char *) NULL);
</tt>
</pre>

<p>The <i>setlocale</i>() function shall return the string corresponding to the current international environment. This value may
be used by a subsequent call to <i>setlocale</i>() to reset the international environment to this value. However, it should be
noted that the return value from <i>setlocale</i>() 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 <i>setlocale</i>()). Therefore, if the purpose of calling
<i>setlocale</i>() is to save the value of the current international environment so it can be changed and reset later, the return
value should be copied to an array of <b>char</b> in the calling program.</p>

<p>There are three ways to set the international environment with <i>setlocale</i>():</p>

<dl compact>
<dt><i>setlocale</i>(<i>category</i>,&nbsp;<i>string</i>)</dt>

<dd><br>
This usage sets a specific <i>category</i> in the international environment to a specific value corresponding to the value of the
<i>string</i>. A specific example is provided below: 

<pre>
<tt>setlocale(LC_ALL, "fr_FR.ISO-8859-1");
</tt>
</pre>

<p>In this example, all categories of the international environment are set to the locale corresponding to the string
<tt>"fr_FR.ISO-8859-1"</tt> , or to the French language as spoken in France using the ISO/IEC&nbsp;8859-1:1998 standard
codeset.</p>

<p>If the string does not correspond to a valid locale, <i>setlocale</i>() shall return a NULL pointer and the international
environment is not changed. Otherwise, <i>setlocale</i>() shall return the name of the locale just set.</p>
</dd>

<dt><i>setlocale</i>(<i>category</i>,&nbsp;"C")</dt>

<dd><br>
The ISO&nbsp;C standard states that one locale must exist on all conforming implementations. The name of the locale is C and
corresponds to a minimal international environment needed to support the C programming language.</dd>

<dt><i>setlocale</i>(<i>category</i>,&nbsp;"")</dt>

<dd><br>
This sets a specific category to an implementation-defined default. This corresponds to the value of the environment
variables.</dd>
</dl>
</blockquote>

<h4><a name="tag_03_655_09"></a>FUTURE DIRECTIONS</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_03_655_10"></a>SEE ALSO</h4>

<blockquote>
<p><a href="exec.html"><i><a href="../functions/exec.html">exec</a></i>()</a> , <a href="isalnum.html"><i>isalnum</i>()</a> , <a
href="isalpha.html"><i>isalpha</i>()</a> , <a href="isblank.html"><i>isblank</i>()</a> , <a href=
"iscntrl.html"><i>iscntrl</i>()</a> , <a href="isdigit.html"><i>isdigit</i>()</a> , <a href="isgraph.html"><i>isgraph</i>()</a> ,
<a href="islower.html"><i>islower</i>()</a> , <a href="isprint.html"><i>isprint</i>()</a> , <a href=
"ispunct.html"><i>ispunct</i>()</a> , <a href="isspace.html"><i>isspace</i>()</a> , <a href="isupper.html"><i>isupper</i>()</a> ,
<a href="iswalnum.html"><i>iswalnum</i>()</a> , <a href="iswalpha.html"><i>iswalpha</i>()</a> , <a href=
"iswblank.html"><i>iswblank</i>()</a> , <a href="iswcntrl.html"><i>iswcntrl</i>()</a> , <a href=
"iswctype.html"><i>iswctype</i>()</a> , <a href="iswdigit.html"><i>iswdigit</i>()</a> , <a href=
"iswgraph.html"><i>iswgraph</i>()</a> , <a href="iswlower.html"><i>iswlower</i>()</a> , <a href=
"iswprint.html"><i>iswprint</i>()</a> , <a href="iswpunct.html"><i>iswpunct</i>()</a> , <a href=
"iswspace.html"><i>iswspace</i>()</a> , <a href="iswupper.html"><i>iswupper</i>()</a> , <a href=
"iswxdigit.html"><i>iswxdigit</i>()</a> , <a href="isxdigit.html"><i>isxdigit</i>()</a> , <a href=
"localeconv.html"><i>localeconv</i>()</a> , <a href="mblen.html"><i>mblen</i>()</a> , <a href="mbstowcs.html"><i>mbstowcs</i>()</a>
, <a href="mbtowc.html"><i>mbtowc</i>()</a> , <a href="nl_langinfo.html"><i>nl_langinfo</i>()</a> , <a href=
"printf.html"><i>printf</i>()</a> , <a href="scanf.html"><i>scanf</i>()</a> , <a href="#">setlocale</a> , <a href=
"strcoll.html"><i>strcoll</i>()</a> , <a href="strerror.html"><i>strerror</i>()</a> , <a href="strfmon.html"><i>strfmon</i>()</a> ,
<a href="strtod.html"><i>strtod</i>()</a> , <a href="strxfrm.html"><i>strxfrm</i>()</a> , <a href=
"tolower.html"><i>tolower</i>()</a> , <a href="toupper.html"><i>toupper</i>()</a> , <a href="towlower.html"><i>towlower</i>()</a> ,
<a href="towupper.html"><i>towupper</i>()</a> , <a href="wcscoll.html"><i>wcscoll</i>()</a> , <a href=
"wcstod.html"><i>wcstod</i>()</a> , <a href="wcstombs.html"><i>wcstombs</i>()</a> , <a href="wcsxfrm.html"><i>wcsxfrm</i>()</a> ,
<a href="wctomb.html"><i>wctomb</i>()</a> , the Base Definitions volume of IEEE&nbsp;Std&nbsp;1003.1-2001, <a href=
"../basedefs/langinfo.h.html"><i>&lt;langinfo.h&gt;</i></a>, <a href="../basedefs/locale.h.html"><i>&lt;locale.h&gt;</i></a></p>
</blockquote>

<h4><a name="tag_03_655_11"></a>CHANGE HISTORY</h4>

<blockquote>
<p>First released in Issue 3.</p>
</blockquote>

<h4><a name="tag_03_655_12"></a>Issue 5</h4>

<blockquote>
<p>The DESCRIPTION is updated for alignment with the POSIX Threads Extension.</p>
</blockquote>

<h4><a name="tag_03_655_13"></a>Issue 6</h4>

<blockquote>
<p>Extensions beyond the ISO&nbsp;C standard are marked.</p>

<p>The DESCRIPTION is updated to avoid use of the term &quot;must&quot; for application requirements.</p>
</blockquote>

<div class="box"><em>End of informative text.</em></div>

<hr>
<hr size="2" noshade>
<center><font size="2"><!--footer start-->
UNIX &reg; is a registered Trademark of The Open Group.<br>
POSIX &reg; is a registered Trademark of The IEEE.<br>
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
]</font></center>

<!--footer end-->
<hr size="2" noshade>
</body>
</html>