man3/uselocale.3

   1 .\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .TH uselocale 3 (date) "Linux man-pages (unreleased)"
   6 .SH NAME
   7 uselocale \- set/get the locale for the calling thread
   8 .SH LIBRARY
   9 Standard C library
  10 .RI ( libc ", " \-lc )
  11 .SH SYNOPSIS
  12 .nf
  13 .B #include <locale.h>
  14 .PP
  15 .BI "locale_t uselocale(locale_t " newloc );
  16 .fi
  17 .PP
  18 .RS -4
  19 Feature Test Macro Requirements for glibc (see
  20 .BR feature_test_macros (7)):
  21 .RE
  22 .PP
  23 .BR uselocale ():
  24 .nf
  25     Since glibc 2.10:
  26         _XOPEN_SOURCE >= 700
  27     Before glibc 2.10:
  28         _GNU_SOURCE
  29 .fi
  30 .SH DESCRIPTION
  31 The
  32 .BR uselocale ()
  33 function sets the current locale for the calling thread,
  34 and returns the thread's previously current locale.
  35 After a successful call to
  36 .BR uselocale (),
  37 any calls by this thread to functions that depend on the locale
  38 will operate as though the locale has been set to
  39 .IR newloc .
  40 .PP
  41 The
  42 .I newloc
  43 argument can have one of the following values:
  44 .TP
  45 A handle returned by a call to \fBnewlocale\fP(3) or \fBduplocale\fP(3)
  46 The calling thread's current locale is set to the specified locale.
  47 .TP
  48 The special locale object handle \fBLC_GLOBAL_LOCALE\fP
  49 The calling thread's current locale is set to the global locale determined by
  50 .BR setlocale (3).
  51 .TP
  52 .I "(locale_t) 0"
  53 The calling thread's current locale is left unchanged
  54 (and the current locale is returned as the function result).
  55 .SH RETURN VALUE
  56 On success,
  57 .BR uselocale ()
  58 returns the locale handle that was set by the previous call to
  59 .BR uselocale ()
  60 in this thread, or
  61 .B LC_GLOBAL_LOCALE
  62 if there was no such previous call.
  63 On error, it returns
  64 .IR "(locale_t)\ 0" ,
  65 and sets
  66 .I errno
  67 to indicate the error.
  68 .SH ERRORS
  69 .TP
  70 .B EINVAL
  71 .I newloc
  72 does not refer to a valid locale object.
  73 .SH VERSIONS
  74 The
  75 .BR uselocale ()
  76 function first appeared in glibc 2.3.
  77 .SH STANDARDS
  78 POSIX.1-2008.
  79 .SH NOTES
  80 Unlike
  81 .BR setlocale (3),
  82 .BR uselocale ()
  83 does not allow selective replacement of individual locale categories.
  84 To employ a locale that differs in only a few categories from the current
  85 locale, use calls to
  86 .BR duplocale (3)
  87 and
  88 .BR newlocale (3)
  89 to obtain a locale object equivalent to the current locale and
  90 modify the desired categories in that object.
  91 .SH EXAMPLES
  92 See
  93 .BR newlocale (3)
  94 and
  95 .BR duplocale (3).
  96 .SH SEE ALSO
  97 .BR locale (1),
  98 .BR duplocale (3),
  99 .BR freelocale (3),
 100 .BR newlocale (3),
 101 .BR setlocale (3),
 102 .BR locale (5),
 103 .BR locale (7)