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