man3/towupper.3

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