Setting-the-Locale.html

/glibc/libc/Setting-the-Locale.html

https://gitlab.com/Gentio/my-pdf
HTML | 212 lines | 148 code | 17 blank | 47 comment | 0 complexity | e5d4a3a0cd429cc3281afc49829ec734 MD5 | raw file

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- This file documents the GNU C Library.

This is
The GNU C Library Reference Manual, for version
2.23.

Copyright (C) 1993-2016 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version
1.3 or any later version published by the Free
Software Foundation; with the Invariant Sections being "Free Software
Needs Free Documentation" and "GNU Lesser General Public License",
the Front-Cover texts being "A GNU Manual", and with the Back-Cover
Texts as in (a) below.  A copy of the license is included in the
section entitled "GNU Free Documentation License".

(a) The FSF's Back-Cover Text is: "You have the freedom to
copy and modify this GNU manual.  Buying copies from the FSF
supports it in developing GNU and promoting software freedom." -->
<!-- Created by GNU Texinfo 6.0, http://www.gnu.org/software/texinfo/ -->
<head>
<title>The GNU C Library: Setting the Locale</title>

<meta name="description" content="The GNU C Library: Setting the Locale">
<meta name="keywords" content="The GNU C Library: Setting the Locale">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Locales.html#Locales" rel="up" title="Locales">
<link href="Standard-Locales.html#Standard-Locales" rel="next" title="Standard Locales">
<link href="Locale-Categories.html#Locale-Categories" rel="prev" title="Locale Categories">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smalllisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space: nowrap}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: serif; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en">
<a name="Setting-the-Locale"></a>
<div class="header">
<p>
Next: <a href="Standard-Locales.html#Standard-Locales" accesskey="n" rel="next">Standard Locales</a>, Previous: <a href="Locale-Categories.html#Locale-Categories" accesskey="p" rel="prev">Locale Categories</a>, Up: <a href="Locales.html#Locales" accesskey="u" rel="up">Locales</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="How-Programs-Set-the-Locale"></a>
<h3 class="section">7.4 How Programs Set the Locale</h3>

<p>A C program inherits its locale environment variables when it starts up.
This happens automatically.  However, these variables do not
automatically control the locale used by the library functions, because
ISO&nbsp;C<!-- /@w --> says that all programs start by default in the standard &lsquo;<samp>C</samp>&rsquo;
locale.  To use the locales specified by the environment, you must call
<code>setlocale</code>.  Call it as follows:
</p>
<div class="smallexample">
<pre class="smallexample">setlocale (LC_ALL, &quot;&quot;);
</pre></div>

<p>to select a locale based on the user choice of the appropriate
environment variables.
</p>
<a name="index-changing-the-locale"></a>
<a name="index-locale_002c-changing"></a>
<p>You can also use <code>setlocale</code> to specify a particular locale, for
general use or for a specific category.
</p>
<a name="index-locale_002eh"></a>
<p>The symbols in this section are defined in the header file <samp>locale.h</samp>.
</p>
<dl>
<dt><a name="index-setlocale"></a>Function: <em>char *</em> <strong>setlocale</strong> <em>(int <var>category</var>, const char *<var>locale</var>)</em></dt>
<dd><p>Preliminary:
| MT-Unsafe const:locale env
| AS-Unsafe init lock heap corrupt
| AC-Unsafe init corrupt lock mem fd
| See <a href="POSIX-Safety-Concepts.html#POSIX-Safety-Concepts">POSIX Safety Concepts</a>.
</p>

<p>The function <code>setlocale</code> sets the current locale for category
<var>category</var> to <var>locale</var>.
</p>
<p>If <var>category</var> is <code>LC_ALL</code>, this specifies the locale for all
purposes.  The other possible values of <var>category</var> specify an
single purpose (see <a href="Locale-Categories.html#Locale-Categories">Locale Categories</a>).
</p>
<p>You can also use this function to find out the current locale by passing
a null pointer as the <var>locale</var> argument.  In this case,
<code>setlocale</code> returns a string that is the name of the locale
currently selected for category <var>category</var>.
</p>
<p>The string returned by <code>setlocale</code> can be overwritten by subsequent
calls, so you should make a copy of the string (see <a href="Copying-Strings-and-Arrays.html#Copying-Strings-and-Arrays">Copying Strings and Arrays</a>) if you want to save it past any further calls to
<code>setlocale</code>.  (The standard library is guaranteed never to call
<code>setlocale</code> itself.)
</p>
<p>You should not modify the string returned by <code>setlocale</code>.  It might
be the same string that was passed as an argument in a previous call to
<code>setlocale</code>.  One requirement is that the <var>category</var> must be
the same in the call the string was returned and the one when the string
is passed in as <var>locale</var> parameter.
</p>
<p>When you read the current locale for category <code>LC_ALL</code>, the value
encodes the entire combination of selected locales for all categories.
If you specify the same &ldquo;locale name&rdquo; with <code>LC_ALL</code> in a
subsequent call to <code>setlocale</code>, it restores the same combination
of locale selections.
</p>
<p>To be sure you can use the returned string encoding the currently selected
locale at a later time, you must make a copy of the string.  It is not
guaranteed that the returned pointer remains valid over time.
</p>
<p>When the <var>locale</var> argument is not a null pointer, the string returned
by <code>setlocale</code> reflects the newly-modified locale.
</p>
<p>If you specify an empty string for <var>locale</var>, this means to read the
appropriate environment variable and use its value to select the locale
for <var>category</var>.
</p>
<p>If a nonempty string is given for <var>locale</var>, then the locale of that
name is used if possible.
</p>
<p>The effective locale name (either the second argument to
<code>setlocale</code>, or if the argument is an empty string, the name
obtained from the process environment) must be valid locale name.
See <a href="Locale-Names.html#Locale-Names">Locale Names</a>.
</p>
<p>If you specify an invalid locale name, <code>setlocale</code> returns a null
pointer and leaves the current locale unchanged.
</p></dd></dl>

<p>Here is an example showing how you might use <code>setlocale</code> to
temporarily switch to a new locale.
</p>
<div class="smallexample">
<pre class="smallexample">#include &lt;stddef.h&gt;
#include &lt;locale.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;string.h&gt;

void
with_other_locale (char *new_locale,
                   void (*subroutine) (int),
                   int argument)
{
  char *old_locale, *saved_locale;

  /* <span class="roman">Get the name of the current locale.</span>  */
  old_locale = setlocale (LC_ALL, NULL);

  /* <span class="roman">Copy the name so it won&rsquo;t be clobbered by <code>setlocale</code>.</span> */
  saved_locale = strdup (old_locale);
  if (saved_locale == NULL)
    fatal (&quot;Out of memory&quot;);

  /* <span class="roman">Now change the locale and do some stuff with it.</span> */
  setlocale (LC_ALL, new_locale);
  (*subroutine) (argument);

  /* <span class="roman">Restore the original locale.</span> */
  setlocale (LC_ALL, saved_locale);
  free (saved_locale);
}
</pre></div>

<p><strong>Portability Note:</strong> Some ISO&nbsp;C<!-- /@w --> systems may define additional
locale categories, and future versions of the library will do so.  For
portability, assume that any symbol beginning with &lsquo;<samp>LC_</samp>&rsquo; might be
defined in <samp>locale.h</samp>.
</p>
<hr>
<div class="header">
<p>
Next: <a href="Standard-Locales.html#Standard-Locales" accesskey="n" rel="next">Standard Locales</a>, Previous: <a href="Locale-Categories.html#Locale-Categories" accesskey="p" rel="prev">Locale Categories</a>, Up: <a href="Locales.html#Locales" accesskey="u" rel="up">Locales</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>