man3/toupper.3

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