usr/src/man/man3c/uselocale.3c

   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 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
  15 .\"
  16 .TH USELOCALE 3C "Jun 24, 2014"
  17
  18 .SH NAME
  19 uselocale \- get and set the locale for an individual thread
  20 .SH SYNOPSIS
  21 .LP
  22 .nf
  23 #include <locale.h>
  24
  25 \fBlocale_t\fR \fBuselocale\fR(\fBlocale_t\fR \fIloc\fR);
  26 .fi
  27 .SH DESCRIPTION
  28 .LP
  29 The
  30 .B uselocale()
  31 function is used to obtain and set the current locale for a thread. When
  32 a thread is created, it uses the global locale as specified by calls to
  33 .BR setlocale() .
  34 .LP
  35 If
  36 .BR (locale_t) 0
  37 is supplied for
  38 .IR loc ,
  39 then no change is made to the thread's locale setting.  This can be used
  40 to query the thread's locale without making any change.
  41 .LP
  42 If
  43 .B LC_GLOBAL_LOCALE
  44 is supplied for
  45 .IR loc ,
  46 then the thread will use the global locale, undoing the effect of any
  47 prior call to establish a thread-specific locale.
  48 .LP
  49 Otherwise the thread will use the supplied
  50 .I loc
  51 locale object as a thread-specific locale. Changes to the global
  52 locale, or to the locale of any other thread, will not affect this thread.
  53 .LP
  54 Locale objects for use with
  55 .B uselocale()
  56 can be created with the functions
  57 .BR duplocale (3C)
  58 and
  59 .BR newlocale (3C).
  60 .SH RETURN VALUES
  61 Upon successful completion, the
  62 .B uselocale()
  63 function always returns the previous locale that was set. If no locale
  64 was previously set, the global locale,
  65 .BR LC_GLOBAL_LOCALE ,
  66 is returned. On failure, the
  67 .B uselocale()
  68 function returns
  69 .BR (locale_t) 0,
  70 and sets
  71 .B errno
  72 to indicate the error.
  73 .SH ERRORS
  74 .TP
  75 .B EINVAL
  76 An invalid locale was encountered or an internal error occurred that
  77 caused the system to be unable to update the locale.
  78 .SH ATTRIBUTES
  79 .TS
  80 box;
  81 c | c
  82 l | l .
  83 ATTRIBUTE TYPE  ATTRIBUTE VALUE
  84 _
  85 Interface Stability     Standard
  86 _
  87 MT-Level        MT-Safe
  88 .TE
  89
  90 .SH SEE ALSO
  91 .BR locale (1),
  92 .BR duplocale (3C),
  93 .BR newlocale (3C),
  94 .BR setlocale (3C),
  95 .BR locale (5)