1 '\" te
   2 .\"
   3 .\" This file and its contents are supplied under the terms of the
   4 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   5 .\" You may only use this file in accordance with the terms of version
   6 .\" 1.0 of the CDDL.
   7 .\"
   8 .\" A full copy of the text of the CDDL should have accompanied this
   9 .\" source.  A copy of the CDDL is also available via the Internet at
  10 .\" http://www.illumos.org/license/CDDL.
  11 .\"
  12 .\"
  13 .\" Copyright (c) 2014 Joyent, Inc.  All rights reserved.
  14 .\"
  15 .TH USELOCALE 3C "Jun 11, 2014"
  16 
  17 .SH NAME
  18 
  19 uselocale \- get and set the locale for an individual thread
  20 
  21 .SH SYNOPSIS
  22 
  23 .LP
  24 .nf
  25 #include <locale.h>
  26 
  27 .BI "locale_t uselocale(locale_t " loc );
  28 
  29 .SH DESCRIPTION
  30 .LP
  31 
  32 The
  33 .B uselocale()
  34 function is used to obtain and set the current locale for a thread. When
  35 a thread is created, it uses the global locale as specified by calls to
  36 .BR setlocale() .
  37 A call to
  38 .B uselocale()
  39 causes all operations in the thread to use the locale specified in
  40 .IR loc .
  41 The thread ignores all subsequent changes to the global locale that
  42 occur through calls to
  43 .BR setlocale() .
  44 When the special locale,
  45 .BR LC_GLOBAL_LOCALE ,
  46 is passed in to
  47 .BR uselocale() ,
  48 the thread returns to using the global locale, and subsequent calls to
  49 .B setlocale()
  50 cause changes for the thread.
  51 
  52 .LP
  53 In addition,
  54 .B uselocale()
  55 can be used to obtain the current locale in use by thread, this is done
  56 by passing in the special locale
  57 .BR (locale_t) 0.
  58 If the thread has never set a locale through
  59 .BR uselocale() ,
  60 then the current global locale as determined through calls to
  61 .B setlocale()
  62 will be returned.
  63 
  64 .LP
  65 Locale objects to pass in to
  66 .B uselocale()
  67 can be created and destroyed with the functions
  68 .BR duplocale (3C),
  69 .BR newlocale (3C),
  70 and
  71 .BR freelocale (3C).
  72 
  73 .SH RETURN VALUES
  74 
  75 Upon successful completion, the
  76 .B uselocale()
  77 function always returns the previous locale that was set. If no locale
  78 was previously set, the global locale,
  79 .BR LC_GLOBAL_LOCALE ,
  80 is returned. If the locale object
  81 .I loc
  82 is the special locale
  83 .BR (lcoale_t) 0,
  84 then the current locale of the thread is not updated. On failure, the
  85 .B uselocale()
  86 function returns
  87 .B (locale_t) 0, and sets
  88 .B errno
  89 to indicate the error.
  90 
  91 .SH ERRORS
  92 
  93 .sp
  94 .ne 2
  95 .na
  96 .B EINVAL
  97 .ad
  98 .RS 10n
  99 An invalid locale was encountered or an internal error occurred that
 100 caused the system to be unable to update the locale.
 101 .RE
 102 
 103 .SH ATTRIBUTES
 104 .sp
 105 .TS
 106 box;
 107 c | c
 108 l | l .
 109 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 110 _
 111 Interface Stability     Standard
 112 _
 113 MT-Level        Safe
 114 .TE
 115 
 116 .SH SEE ALSO
 117 .BR locale (1),
 118 .BR duplocale (3C),
 119 .BR newlocale (3C),
 120 .BR setlocale (3C),
 121 .BR environ (5),
 122 .BR locale (5)