original/man3/uselocale.3

   1 '\" t
   2 .\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .TH USELOCALE 3 2014-03-10 "Linux" "Linux Programmer's Manual"
  27 .SH NAME
  28 uselocale \- set/get the locale for the calling thread
  29 .SH SYNOPSIS
  30 .nf
  31 .B #include <locale.h>
  32
  33 .BI "locale_t uselocale(locale_t " newloc );
  34 .fi
  35 .sp
  36 .in -4n
  37 Feature Test Macro Requirements for glibc (see
  38 .BR feature_test_macros (7)):
  39 .in
  40 .sp
  41 .BR uselocale ():
  42 .PD 0
  43 .RS 4
  44 .TP
  45 Since glibc 2.10:
  46 _XOPEN_SOURCE\ >=\ 700
  47 .TP
  48 Before glibc 2.10:
  49 _GNU_SOURCE
  50 .RE
  51 .PD
  52 .SH DESCRIPTION
  53 The
  54 .BR uselocale ()
  55 function sets the current locale for the calling thread,
  56 and returns the thread's previously current locale.
  57 After a successful call to
  58 .BR uselocale (),
  59 any calls by this thread to functions that depend on the locale
  60 will operate as though the locale has been set to
  61 .IR newloc .
  62
  63 The
  64 .I newloc
  65 argument can have one of the following values:
  66 .TP
  67 A handle returned by a call to \fBnewlocale\fP(3) or \fBduplocale\fP(3)
  68 The calling thread's current locale is set to the specified locale.
  69 .TP
  70 The special locale object handle \fBLC_GLOBAL_LOCALE\fP
  71 The calling thread's current locale is set to the global locale determined by
  72 .BR setlocale (3).
  73 .TP
  74 .I "(locale_t) 0"
  75 The calling thread's current locale is left unchanged
  76 (and the current locale is returned as the function result).
  77 .SH RETURN VALUE
  78 On success,
  79 .BR uselocale ()
  80 returns the locale handle that was set by the previous call to
  81 .BR uselocale ()
  82 in this thread, or
  83 .BR LC_GLOBAL_HANDLE
  84 if there was no such previous call.
  85 On error, it returns
  86 .IR "(locale_t)\ 0",
  87 and sets
  88 .I errno
  89 to indicate the cause of the error.
  90 .SH ERRORS
  91 .TP
  92 .B EINVAL
  93 .I newloc
  94 does not refer to a valid locale object.
  95 .SH VERSIONS
  96 The
  97 .BR uselocale ()
  98 function first appeared in version 2.3 of the GNU C library.
  99 .SH CONFORMING TO
 100 POSIX.1-2008.
 101 .SH NOTES
 102 Unlike
 103 .BR setlocale (3),
 104 .BR uselocale ()
 105 does not allow selective replacement of individual locale categories.
 106 To employ a locale that differs in only a few categories from the current
 107 locale, use calls to
 108 .BR duplocale (3)
 109 and
 110 .BR newlocale (3)
 111 to obtain a locale object equivalent to the current locale and
 112 modify the desired categories in that object.
 113 .SH EXAMPLE
 114 See
 115 .BR newlocale (3)
 116 and
 117 .BR duplocale (3).
 118 .SH SEE ALSO
 119 .BR locale (1),
 120 .BR duplocale (3),
 121 .BR freelocale (3),
 122 .BR newlocale (3),
 123 .BR setlocale (3),
 124 .BR locale (5),
 125 .BR locale (7)
 126 .SH COLOPHON
 127 This page is part of release 3.68 of the Linux
 128 .I man-pages
 129 project.
 130 A description of the project,
 131 information about reporting bugs,
 132 and the latest version of this page,
 133 can be found at
 134 \%http://www.kernel.org/doc/man\-pages/.