]>
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> |
b8efb414 | 28 | .TH TOUPPER 3 2016-10-08 "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" ); |
defcceb3 | 36 | .br |
fea681da | 37 | .BI "int tolower(int " "c" ); |
dbfe9c70 | 38 | .PP |
9cfaf64e MK |
39 | .BI "int toupper_l(int " c ", locale_t " locale ); |
40 | .BI "int tolower_l(int " c ", locale_t " locale ); | |
fea681da | 41 | .fi |
68e4db0a | 42 | .PP |
9cfaf64e MK |
43 | .in -4n |
44 | Feature Test Macro Requirements for glibc (see | |
45 | .BR feature_test_macros (7)): | |
46 | .in | |
68e4db0a | 47 | .PP |
9cfaf64e MK |
48 | .BR toupper_l (), |
49 | .BR tolower_l (): | |
50 | .PD 0 | |
51 | .RS 4 | |
52 | .TP | |
53 | Since glibc 2.10: | |
54 | _XOPEN_SOURCE\ >=\ 700 | |
55 | .TP | |
56 | Before glibc 2.10: | |
57 | _GNU_SOURCE | |
58 | .RE | |
59 | .PD | |
fea681da | 60 | .SH DESCRIPTION |
b410b6d9 MK |
61 | These functions convert lowercase letters to uppercase, and vice versa. |
62 | ||
63 | If | |
fea681da | 64 | .I c |
b410b6d9 MK |
65 | is a lowercase letter, |
66 | .BR toupper () | |
67 | returns its uppercase equivalent, | |
68 | if an uppercase representation exists in the current locale. | |
69 | Otherwise, it returns | |
70 | .IR c . | |
9cfaf64e MK |
71 | The |
72 | .BR toupper_l () | |
73 | function performs the same task, | |
74 | but uses the locale referred to by the locale handle | |
75 | .IR locale . | |
b410b6d9 MK |
76 | |
77 | If | |
fea681da | 78 | .I c |
bb492d9d | 79 | is an uppercase letter, |
8a9849f2 | 80 | .BR tolower () |
b410b6d9 MK |
81 | returns its lowercase equivalent, |
82 | if a lowercase representation exists in the current locale. | |
83 | Otherwise, it returns | |
84 | .IR c . | |
9cfaf64e MK |
85 | The |
86 | .BR tolower_l () | |
87 | function performs the same task, | |
88 | but uses the locale referred to by the locale handle | |
89 | .IR locale . | |
fea681da MK |
90 | .PP |
91 | If | |
92 | .I c | |
b410b6d9 | 93 | is neither an |
d9a10d9d | 94 | .I "unsigned char" |
b410b6d9 | 95 | value nor |
cab87712 MK |
96 | .BR EOF , |
97 | the behavior of these functions | |
fea681da | 98 | is undefined. |
9cfaf64e MK |
99 | |
100 | The behavior of | |
101 | .BR toupper_l () | |
102 | and | |
103 | .BR tolower_l () | |
104 | is undefined if | |
105 | .I locale | |
f6b6f860 | 106 | is the special locale object |
9cfaf64e MK |
107 | .BR LC_GLOBAL_LOCALE |
108 | (see | |
109 | .BR duplocale (3)) | |
110 | or is not a valid locale object handle. | |
47297adb | 111 | .SH RETURN VALUE |
fea681da MK |
112 | The value returned is that of the converted letter, or |
113 | .I c | |
114 | if the conversion was not possible. | |
0462e392 | 115 | .SH ATTRIBUTES |
17dfad67 PH |
116 | For an explanation of the terms used in this section, see |
117 | .BR attributes (7). | |
118 | .TS | |
119 | allbox; | |
120 | lbw24 lb lb | |
121 | l l l. | |
122 | Interface Attribute Value | |
123 | T{ | |
124 | .BR toupper (), | |
9b45c6d8 MS |
125 | .BR tolower (), |
126 | .br | |
17dfad67 PH |
127 | .BR toupper_l (), |
128 | .BR tolower_l () | |
129 | T} Thread safety MT-Safe | |
130 | .TE | |
47297adb | 131 | .SH CONFORMING TO |
b410b6d9 MK |
132 | .BR toupper (), |
133 | .BR tolower (): | |
134 | C89, C99, 4.3BSD, POSIX.1-2001, POSIX.1-2008. | |
9cfaf64e MK |
135 | |
136 | .BR toupper_l (), | |
137 | .BR tolower_l (): | |
138 | POSIX.1-2008. | |
29c94b34 | 139 | .SH NOTES |
d8188973 MK |
140 | The standards require that the argument |
141 | .I c | |
142 | for these functions is either | |
143 | .B EOF | |
144 | or a value that is representable in the type | |
145 | .IR "unsigned char" . | |
146 | If the argument | |
147 | .I c | |
148 | is of type | |
149 | .IR char , | |
150 | it must be cast to | |
151 | .IR "unsigned char" , | |
152 | as in the following example: | |
153 | ||
154 | .nf | |
155 | .in +4n | |
156 | char c; | |
157 | \&... | |
158 | res = toupper((unsigned char) c); | |
159 | .in | |
160 | .fi | |
161 | ||
162 | This is necessary because | |
163 | .I char | |
164 | may be the equivalent | |
165 | .IR "signed char" , | |
166 | in which case a byte where the top bit is set would be sign extended when | |
167 | converting to | |
168 | .IR int , | |
169 | yielding a value that is outside the range of | |
170 | .IR "unsigned char" . | |
171 | ||
fea681da | 172 | The details of what constitutes an uppercase or lowercase letter depend |
b410b6d9 | 173 | on the locale. |
c13182ef | 174 | For example, the default |
fea681da MK |
175 | .B """C""" |
176 | locale does not know about umlauts, so no conversion is done for them. | |
177 | .PP | |
4d9b6984 | 178 | In some non-English locales, there are lowercase letters with no |
0aa633ab | 179 | corresponding uppercase equivalent; |
bea08fec | 180 | .\" FIXME One day the statement about "sharp s" needs to be reworked, |
0aa633ab MK |
181 | .\" since there is nowadays a capital "sharp s" that has a codepoint |
182 | .\" in Unicode 5.0; see https://en.wikipedia.org/wiki/Capital_%E1%BA%9E | |
183 | the German sharp s is one example. | |
47297adb | 184 | .SH SEE ALSO |
fea681da | 185 | .BR isalpha (3), |
9cfaf64e | 186 | .BR newlocale (3), |
fea681da | 187 | .BR setlocale (3), |
1709027c MK |
188 | .BR towlower (3), |
189 | .BR towupper (3), | |
ea7378c3 | 190 | .BR uselocale (3), |
fea681da | 191 | .BR locale (7) |