]>
Commit | Line | Data |
---|---|---|
bf5a7247 | 1 | .\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) |
9cfaf64e | 2 | .\" and Copyright 2014 Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 3 | .\" |
5fbde956 | 4 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
c08df37a | 5 | .\" |
fea681da | 6 | .\" Modified Sat Jul 24 17:45:39 1993 by Rik Faith (faith@cs.unc.edu) |
e00c3a07 | 7 | .\" Modified 2000-02-13 by Nicolás Lichtmaier <nick@debian.org> |
45186a5d | 8 | .TH TOUPPER 3 2021-03-22 "Linux man-pages (unreleased)" |
fea681da | 9 | .SH NAME |
9cfaf64e | 10 | toupper, tolower, toupper_l, tolower_l \- convert uppercase or lowercase |
ebf7bddf AC |
11 | .SH LIBRARY |
12 | Standard C library | |
8fc3b2cf | 13 | .RI ( libc ", " \-lc ) |
fea681da MK |
14 | .SH SYNOPSIS |
15 | .nf | |
16 | .B #include <ctype.h> | |
68e4db0a | 17 | .PP |
fea681da | 18 | .BI "int toupper(int " "c" ); |
fea681da | 19 | .BI "int tolower(int " "c" ); |
dbfe9c70 | 20 | .PP |
9cfaf64e MK |
21 | .BI "int toupper_l(int " c ", locale_t " locale ); |
22 | .BI "int tolower_l(int " c ", locale_t " locale ); | |
fea681da | 23 | .fi |
68e4db0a | 24 | .PP |
d39ad78f | 25 | .RS -4 |
9cfaf64e MK |
26 | Feature Test Macro Requirements for glibc (see |
27 | .BR feature_test_macros (7)): | |
d39ad78f | 28 | .RE |
68e4db0a | 29 | .PP |
9cfaf64e MK |
30 | .BR toupper_l (), |
31 | .BR tolower_l (): | |
9d2adbae MK |
32 | .nf |
33 | Since glibc 2.10: | |
5c10d2c5 | 34 | _XOPEN_SOURCE >= 700 |
9d2adbae MK |
35 | Before glibc 2.10: |
36 | _GNU_SOURCE | |
37 | .fi | |
fea681da | 38 | .SH DESCRIPTION |
b410b6d9 | 39 | These functions convert lowercase letters to uppercase, and vice versa. |
847e0d88 | 40 | .PP |
b410b6d9 | 41 | If |
fea681da | 42 | .I c |
b410b6d9 MK |
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 . | |
9cfaf64e MK |
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 . | |
847e0d88 | 54 | .PP |
b410b6d9 | 55 | If |
fea681da | 56 | .I c |
bb492d9d | 57 | is an uppercase letter, |
8a9849f2 | 58 | .BR tolower () |
b410b6d9 MK |
59 | returns its lowercase equivalent, |
60 | if a lowercase representation exists in the current locale. | |
61 | Otherwise, it returns | |
62 | .IR c . | |
9cfaf64e MK |
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 . | |
fea681da MK |
68 | .PP |
69 | If | |
70 | .I c | |
b410b6d9 | 71 | is neither an |
d9a10d9d | 72 | .I "unsigned char" |
b410b6d9 | 73 | value nor |
cab87712 MK |
74 | .BR EOF , |
75 | the behavior of these functions | |
fea681da | 76 | is undefined. |
847e0d88 | 77 | .PP |
9cfaf64e MK |
78 | The behavior of |
79 | .BR toupper_l () | |
80 | and | |
81 | .BR tolower_l () | |
82 | is undefined if | |
83 | .I locale | |
f6b6f860 | 84 | is the special locale object |
d8a86e74 | 85 | .B LC_GLOBAL_LOCALE |
9cfaf64e MK |
86 | (see |
87 | .BR duplocale (3)) | |
88 | or is not a valid locale object handle. | |
47297adb | 89 | .SH RETURN VALUE |
fea681da MK |
90 | The value returned is that of the converted letter, or |
91 | .I c | |
92 | if the conversion was not possible. | |
0462e392 | 93 | .SH ATTRIBUTES |
17dfad67 PH |
94 | For an explanation of the terms used in this section, see |
95 | .BR attributes (7). | |
c466875e MK |
96 | .ad l |
97 | .nh | |
17dfad67 PH |
98 | .TS |
99 | allbox; | |
c466875e | 100 | lbx lb lb |
17dfad67 PH |
101 | l l l. |
102 | Interface Attribute Value | |
103 | T{ | |
104 | .BR toupper (), | |
9b45c6d8 | 105 | .BR tolower (), |
17dfad67 PH |
106 | .BR toupper_l (), |
107 | .BR tolower_l () | |
108 | T} Thread safety MT-Safe | |
109 | .TE | |
c466875e MK |
110 | .hy |
111 | .ad | |
112 | .sp 1 | |
3113c7f3 | 113 | .SH STANDARDS |
b410b6d9 MK |
114 | .BR toupper (), |
115 | .BR tolower (): | |
116 | C89, C99, 4.3BSD, POSIX.1-2001, POSIX.1-2008. | |
847e0d88 | 117 | .PP |
9cfaf64e MK |
118 | .BR toupper_l (), |
119 | .BR tolower_l (): | |
120 | POSIX.1-2008. | |
29c94b34 | 121 | .SH NOTES |
d8188973 MK |
122 | The standards require that the argument |
123 | .I c | |
124 | for these functions is either | |
125 | .B EOF | |
126 | or a value that is representable in the type | |
127 | .IR "unsigned char" . | |
128 | If the argument | |
129 | .I c | |
130 | is of type | |
131 | .IR char , | |
132 | it must be cast to | |
133 | .IR "unsigned char" , | |
134 | as in the following example: | |
847e0d88 | 135 | .PP |
d8188973 | 136 | .in +4n |
b8302363 | 137 | .EX |
d8188973 MK |
138 | char c; |
139 | \&... | |
140 | res = toupper((unsigned char) c); | |
b8302363 | 141 | .EE |
e646a1ba | 142 | .in |
847e0d88 | 143 | .PP |
d8188973 MK |
144 | This is necessary because |
145 | .I char | |
146 | may be the equivalent | |
147 | .IR "signed char" , | |
148 | in which case a byte where the top bit is set would be sign extended when | |
149 | converting to | |
150 | .IR int , | |
151 | yielding a value that is outside the range of | |
152 | .IR "unsigned char" . | |
847e0d88 | 153 | .PP |
fea681da | 154 | The details of what constitutes an uppercase or lowercase letter depend |
b410b6d9 | 155 | on the locale. |
c13182ef | 156 | For example, the default |
fea681da MK |
157 | .B """C""" |
158 | locale does not know about umlauts, so no conversion is done for them. | |
159 | .PP | |
4d9b6984 | 160 | In some non-English locales, there are lowercase letters with no |
0aa633ab | 161 | corresponding uppercase equivalent; |
bea08fec | 162 | .\" FIXME One day the statement about "sharp s" needs to be reworked, |
0aa633ab MK |
163 | .\" since there is nowadays a capital "sharp s" that has a codepoint |
164 | .\" in Unicode 5.0; see https://en.wikipedia.org/wiki/Capital_%E1%BA%9E | |
165 | the German sharp s is one example. | |
47297adb | 166 | .SH SEE ALSO |
fea681da | 167 | .BR isalpha (3), |
9cfaf64e | 168 | .BR newlocale (3), |
fea681da | 169 | .BR setlocale (3), |
1709027c MK |
170 | .BR towlower (3), |
171 | .BR towupper (3), | |
ea7378c3 | 172 | .BR uselocale (3), |
fea681da | 173 | .BR locale (7) |