man3/towupper.3

   1
   2 .\" and Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA)
   5 .\" This is free documentation; you can redistribute it and/or
   6 .\" modify it under the terms of the GNU General Public License as
   7 .\" published by the Free Software Foundation; either version 2 of
   8 .\" the License, or (at your option) any later version.
   9 .\" %%%LICENSE_END
  10 .\"
  11 .\" References consulted:
  12 .\"   GNU glibc-2 source code and manual
  13 .\"   Dinkumware C library reference http://www.dinkumware.com/
  14 .\"   OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
  15 .\"   ISO/IEC 9899:1999
  16 .\"
  17 .TH TOWUPPER 3  2015-03-02 "GNU" "Linux Programmer's Manual"
  18 .SH NAME
  19 towupper, towupper_l \- convert a wide character to uppercase
  20 .SH SYNOPSIS
  21 .nf
  22 .B #include <wctype.h>
  23 .sp
  24 .BI "wint_t towupper(wint_t " wc );
  25
  26 .BI "wint_t towupper_l(wint_t " wc ", locale_t " locale );
  27 .fi
  28 .sp
  29 .in -4n
  30 Feature Test Macro Requirements for glibc (see
  31 .BR feature_test_macros (7)):
  32 .in
  33 .sp
  34 .BR towupper_l ():
  35 .PD 0
  36 .RS 4
  37 .TP
  38 Since glibc 2.10:
  39 _XOPEN_SOURCE\ >=\ 700
  40 .TP
  41 Before glibc 2.10:
  42 _GNU_SOURCE
  43 .RE
  44 .PD
  45 .SH DESCRIPTION
  46 The
  47 .BR towupper ()
  48 function is the wide-character equivalent of the
  49 .BR toupper (3)
  50 function.
  51 If
  52 .I wc
  53 is a lowercase wide character,
  54 and there exists an uppercase equivalent in the current locale,
  55 it returns the uppercase equivalent of
  56 .IR wc .
  57 In all other cases,
  58 .I wc
  59 is returned unchanged.
  60
  61 The
  62 .BR towupper_l ()
  63 function performs the same task,
  64 but performs the conversion based on the character type information in
  65 the locale specified by
  66 .IR locale .
  67 The behavior of
  68 .BR towupper_l ()
  69 is undefined if
  70 .I locale
  71 is the special locale object
  72 .BR LC_GLOBAL_LOCALE
  73 (see
  74 .BR duplocale (3))
  75 or is not a valid locale object handle.
  76
  77 The argument
  78 .I wc
  79 must be representable as a
  80 .IR wchar_t
  81 and be a valid character in the locale or be the value
  82 .BR WEOF .
  83 .SH RETURN VALUE
  84 If
  85 .I wc
  86 was convertible to uppercase,
  87 .BR towupper ()
  88 returns its uppercase equivalent;
  89 otherwise it returns
  90 .IR wc .
  91 .SH ATTRIBUTES
  92 For an explanation of the terms used in this section, see
  93 .BR attributes (7).
  94 .TS
  95 allbox;
  96 lb lb lb
  97 l l l.
  98 Interface       Attribute       Value
  99 T{
 100 .BR towupper ()
 101 T}      Thread safety   MT-Safe locale
 102 T{
 103 .BR towupper_l ()
 104 T}      Thread safety   MT-Safe
 105 .TE
 106 .SH VERSIONS
 107 The
 108 .BR towupper_l ()
 109 function first appeared in glibc 2.3.
 110 .SH CONFORMING TO
 111 .BR towupper ():
 112 C99, POSIX.1-2001 (XSI);
 113 present as an XSI extension in POSIX.1-2008, but marked obsolete.
 114
 115 .BR towupper_l ():
 116 POSIX.1-2008.
 117 .SH NOTES
 118 The behavior of these functions depends on the
 119 .B LC_CTYPE
 120 category of the locale.
 121 .PP
 122 These functions are not very appropriate for dealing with Unicode characters,
 123 because Unicode knows about three cases: upper, lower and title case.
 124 .SH SEE ALSO
 125 .BR iswupper (3),
 126 .BR towctrans (3),
 127 .BR towlower (3),
 128 .BR locale (7)