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