]>
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 | .\" |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
5 | .\" Permission is granted to make and distribute verbatim copies of this |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
c13182ef | 13 | .\" |
fea681da MK |
14 | .\" Since the Linux kernel and libraries are constantly changing, this |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. The author(s) may not | |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
c13182ef | 21 | .\" |
fea681da MK |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
c08df37a | 25 | .\" |
fea681da | 26 | .\" Modified Sat Jul 24 17:45:39 1993 by Rik Faith (faith@cs.unc.edu) |
e00c3a07 | 27 | .\" Modified 2000-02-13 by Nicolás Lichtmaier <nick@debian.org> |
4b8c67d9 | 28 | .TH TOUPPER 3 2017-09-15 "GNU" "Linux Programmer's Manual" |
fea681da | 29 | .SH NAME |
9cfaf64e | 30 | toupper, tolower, toupper_l, tolower_l \- convert uppercase or lowercase |
fea681da MK |
31 | .SH SYNOPSIS |
32 | .nf | |
33 | .B #include <ctype.h> | |
68e4db0a | 34 | .PP |
fea681da | 35 | .BI "int toupper(int " "c" ); |
fea681da | 36 | .BI "int tolower(int " "c" ); |
dbfe9c70 | 37 | .PP |
9cfaf64e MK |
38 | .BI "int toupper_l(int " c ", locale_t " locale ); |
39 | .BI "int tolower_l(int " c ", locale_t " locale ); | |
fea681da | 40 | .fi |
68e4db0a | 41 | .PP |
9cfaf64e MK |
42 | .in -4n |
43 | Feature Test Macro Requirements for glibc (see | |
44 | .BR feature_test_macros (7)): | |
45 | .in | |
68e4db0a | 46 | .PP |
9cfaf64e MK |
47 | .BR toupper_l (), |
48 | .BR tolower_l (): | |
49 | .PD 0 | |
50 | .RS 4 | |
51 | .TP | |
52 | Since glibc 2.10: | |
53 | _XOPEN_SOURCE\ >=\ 700 | |
54 | .TP | |
55 | Before glibc 2.10: | |
56 | _GNU_SOURCE | |
57 | .RE | |
58 | .PD | |
fea681da | 59 | .SH DESCRIPTION |
b410b6d9 | 60 | These functions convert lowercase letters to uppercase, and vice versa. |
847e0d88 | 61 | .PP |
b410b6d9 | 62 | If |
fea681da | 63 | .I c |
b410b6d9 MK |
64 | is a lowercase letter, |
65 | .BR toupper () | |
66 | returns its uppercase equivalent, | |
67 | if an uppercase representation exists in the current locale. | |
68 | Otherwise, it returns | |
69 | .IR c . | |
9cfaf64e MK |
70 | The |
71 | .BR toupper_l () | |
72 | function performs the same task, | |
73 | but uses the locale referred to by the locale handle | |
74 | .IR locale . | |
847e0d88 | 75 | .PP |
b410b6d9 | 76 | If |
fea681da | 77 | .I c |
bb492d9d | 78 | is an uppercase letter, |
8a9849f2 | 79 | .BR tolower () |
b410b6d9 MK |
80 | returns its lowercase equivalent, |
81 | if a lowercase representation exists in the current locale. | |
82 | Otherwise, it returns | |
83 | .IR c . | |
9cfaf64e MK |
84 | The |
85 | .BR tolower_l () | |
86 | function performs the same task, | |
87 | but uses the locale referred to by the locale handle | |
88 | .IR locale . | |
fea681da MK |
89 | .PP |
90 | If | |
91 | .I c | |
b410b6d9 | 92 | is neither an |
d9a10d9d | 93 | .I "unsigned char" |
b410b6d9 | 94 | value nor |
cab87712 MK |
95 | .BR EOF , |
96 | the behavior of these functions | |
fea681da | 97 | is undefined. |
847e0d88 | 98 | .PP |
9cfaf64e MK |
99 | The behavior of |
100 | .BR toupper_l () | |
101 | and | |
102 | .BR tolower_l () | |
103 | is undefined if | |
104 | .I locale | |
f6b6f860 | 105 | is the special locale object |
d8a86e74 | 106 | .B LC_GLOBAL_LOCALE |
9cfaf64e MK |
107 | (see |
108 | .BR duplocale (3)) | |
109 | or is not a valid locale object handle. | |
47297adb | 110 | .SH RETURN VALUE |
fea681da MK |
111 | The value returned is that of the converted letter, or |
112 | .I c | |
113 | if the conversion was not possible. | |
0462e392 | 114 | .SH ATTRIBUTES |
17dfad67 PH |
115 | For an explanation of the terms used in this section, see |
116 | .BR attributes (7). | |
117 | .TS | |
118 | allbox; | |
119 | lbw24 lb lb | |
120 | l l l. | |
121 | Interface Attribute Value | |
122 | T{ | |
123 | .BR toupper (), | |
9b45c6d8 MS |
124 | .BR tolower (), |
125 | .br | |
17dfad67 PH |
126 | .BR toupper_l (), |
127 | .BR tolower_l () | |
128 | T} Thread safety MT-Safe | |
129 | .TE | |
47297adb | 130 | .SH CONFORMING TO |
b410b6d9 MK |
131 | .BR toupper (), |
132 | .BR tolower (): | |
133 | C89, C99, 4.3BSD, POSIX.1-2001, POSIX.1-2008. | |
847e0d88 | 134 | .PP |
9cfaf64e MK |
135 | .BR toupper_l (), |
136 | .BR tolower_l (): | |
137 | POSIX.1-2008. | |
29c94b34 | 138 | .SH NOTES |
d8188973 MK |
139 | The standards require that the argument |
140 | .I c | |
141 | for these functions is either | |
142 | .B EOF | |
143 | or a value that is representable in the type | |
144 | .IR "unsigned char" . | |
145 | If the argument | |
146 | .I c | |
147 | is of type | |
148 | .IR char , | |
149 | it must be cast to | |
150 | .IR "unsigned char" , | |
151 | as in the following example: | |
847e0d88 | 152 | .PP |
d8188973 | 153 | .in +4n |
b8302363 | 154 | .EX |
d8188973 MK |
155 | char c; |
156 | \&... | |
157 | res = toupper((unsigned char) c); | |
b8302363 | 158 | .EE |
e646a1ba | 159 | .in |
847e0d88 | 160 | .PP |
d8188973 MK |
161 | This is necessary because |
162 | .I char | |
163 | may be the equivalent | |
164 | .IR "signed char" , | |
165 | in which case a byte where the top bit is set would be sign extended when | |
166 | converting to | |
167 | .IR int , | |
168 | yielding a value that is outside the range of | |
169 | .IR "unsigned char" . | |
847e0d88 | 170 | .PP |
fea681da | 171 | The details of what constitutes an uppercase or lowercase letter depend |
b410b6d9 | 172 | on the locale. |
c13182ef | 173 | For example, the default |
fea681da MK |
174 | .B """C""" |
175 | locale does not know about umlauts, so no conversion is done for them. | |
176 | .PP | |
4d9b6984 | 177 | In some non-English locales, there are lowercase letters with no |
0aa633ab | 178 | corresponding uppercase equivalent; |
bea08fec | 179 | .\" FIXME One day the statement about "sharp s" needs to be reworked, |
0aa633ab MK |
180 | .\" since there is nowadays a capital "sharp s" that has a codepoint |
181 | .\" in Unicode 5.0; see https://en.wikipedia.org/wiki/Capital_%E1%BA%9E | |
182 | the German sharp s is one example. | |
47297adb | 183 | .SH SEE ALSO |
fea681da | 184 | .BR isalpha (3), |
9cfaf64e | 185 | .BR newlocale (3), |
fea681da | 186 | .BR setlocale (3), |
1709027c MK |
187 | .BR towlower (3), |
188 | .BR towupper (3), | |
ea7378c3 | 189 | .BR uselocale (3), |
fea681da | 190 | .BR locale (7) |