man3/uselocale.3

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