man3/towupper.3

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