Debian Codegraph @

upstream/debian-unstable/man3/toupper.3

raw
1 '\" t
2 .\" Copyright 1993, Thomas Koenig <[email protected]>
3 .\" Copyright 2014, Michael Kerrisk <[email protected]>
4 .\" Copyright, the authors of the Linux man-pages project
5 .\"
6 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
7 .\"
8 .TH toupper 3 2026-02-08 "Linux man-pages 6.18"
9 .SH NAME
10 toupper, tolower, toupper_l, tolower_l \- convert uppercase or lowercase
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS
15 .nf
16 .B #include <ctype.h>
17 .P
18 .BI "int toupper(int " "c" );
19 .BI "int tolower(int " "c" );
20 .P
21 .BI "int toupper_l(int " c ", locale_t " locale );
22 .BI "int tolower_l(int " c ", locale_t " locale );
23 .fi
24 .P
25 .RS -4
26 Feature Test Macro Requirements for glibc (see
27 .BR feature_test_macros (7)):
28 .RE
29 .P
30 .BR toupper_l (),
31 .BR tolower_l ():
32 .nf
33 Since glibc 2.10:
34 _XOPEN_SOURCE >= 700
35 Before glibc 2.10:
36 _GNU_SOURCE
37 .fi
38 .SH DESCRIPTION
39 These functions convert lowercase letters to uppercase, and vice versa.
40 .P
41 If
42 .I c
43 is a lowercase letter,
44 .BR toupper ()
45 returns its uppercase equivalent,
46 if an uppercase representation exists in the current locale.
47 Otherwise, it returns
48 .IR c .
49 The
50 .BR toupper_l ()
51 function performs the same task,
52 but uses the locale referred to by the locale handle
53 .IR locale .
54 .P
55 If
56 .I c
57 is an uppercase letter,
58 .BR tolower ()
59 returns its lowercase equivalent,
60 if a lowercase representation exists in the current locale.
61 Otherwise, it returns
62 .IR c .
63 The
64 .BR tolower_l ()
65 function performs the same task,
66 but uses the locale referred to by the locale handle
67 .IR locale .
68 .P
69 If
70 .I c
71 is neither an
72 .I "unsigned char"
73 value nor
74 .BR EOF ,
75 the behavior of these functions
76 is undefined.
77 .P
78 The behavior of
79 .BR toupper_l ()
80 and
81 .BR tolower_l ()
82 is undefined if
83 .I locale
84 is the special locale object
85 .B LC_GLOBAL_LOCALE
86 (see
87 .BR duplocale (3))
88 or is not a valid locale object handle.
89 .SH RETURN VALUE
90 The value returned is that of the converted letter, or
91 .I c
92 if the conversion was not possible.
93 .SH ATTRIBUTES
94 For an explanation of the terms used in this section, see
95 .BR attributes (7).
96 .TS
97 allbox;
98 lbx lb lb
99 l l l.
100 Interface Attribute Value
101 T{
102 .na
103 .nh
104 .BR toupper (),
105 .BR tolower (),
106 .BR toupper_l (),
107 .BR tolower_l ()
108 T} Thread safety MT-Safe
109 .TE
110 .SH STANDARDS
111 .TP
112 .BR toupper ()
113 .TQ
114 .BR tolower ()
115 C11, POSIX.1-2008.
116 .TP
117 .BR toupper_l ()
118 .TQ
119 .BR tolower_l ()
120 POSIX.1-2008.
121 .SH HISTORY
122 .TP
123 .BR toupper ()
124 .TQ
125 .BR tolower ()
126 C89, 4.3BSD, POSIX.1-2001.
127 .TP
128 .BR toupper_l ()
129 .TQ
130 .BR tolower_l ()
131 POSIX.1-2008.
132 .SH NOTES
133 The standards require that the argument
134 .I c
135 for these functions is either
136 .B EOF
137 or a value that is representable in the type
138 .IR "unsigned char" .
139 If the argument
140 .I c
141 is of type
142 .IR char ,
143 it must be cast to
144 .IR "unsigned char" ,
145 as in the following example:
146 .P
147 .in +4n
148 .EX
149 char c;
150 \&...
151 res = toupper((unsigned char) c);
152 .EE
153 .in
154 .P
155 This is necessary because
156 .I char
157 may be the equivalent
158 .IR "signed char" ,
159 in which case a byte where the top bit is set would be sign extended when
160 converting to
161 .IR int ,
162 yielding a value that is outside the range of
163 .IR "unsigned char" .
164 .P
165 The details of what constitutes an uppercase or lowercase letter depend
166 on the locale.
167 For example, the default
168 .B \[dq]C\[dq]
169 locale does not know about umlauts, so no conversion is done for them.
170 .P
171 In some non-English locales, there are lowercase letters with no
172 corresponding uppercase equivalent;
173 .\" FIXME One day the statement about "sharp s" needs to be reworked,
174 .\" since there is nowadays a capital "sharp s" that has a codepoint
175 .\" in Unicode 5.0; see https://en.wikipedia.org/wiki/Capital_%E1%BA%9E
176 the German sharp s is one example.
177 .SH SEE ALSO
178 .BR isalpha (3),
179 .BR newlocale (3),
180 .BR setlocale (3),
181 .BR towlower (3),
182 .BR towupper (3),
183 .BR uselocale (3),
184 .BR locale (7)