man3/toupper.3

   1 .\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
   2 .\" and Copyright 2014 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .\" Modified Sat Jul 24 17:45:39 1993 by Rik Faith (faith@cs.unc.edu)
   7 .\" Modified 2000-02-13 by Nicolás Lichtmaier <nick@debian.org>
   8 .TH TOUPPER 3  2021-03-22 "Linux man-pages (unreleased)" "Linux Programmer's Manual"
   9 .SH NAME
  10 toupper, tolower, toupper_l, tolower_l \- convert uppercase or lowercase
  11 .SH LIBRARY
  12 Standard C library
  13 .RI ( libc ", " \-lc )
  14 .SH SYNOPSIS
  15 .nf
  16 .B #include <ctype.h>
  17 .PP
  18 .BI "int toupper(int " "c" );
  19 .BI "int tolower(int " "c" );
  20 .PP
  21 .BI "int toupper_l(int " c ", locale_t " locale );
  22 .BI "int tolower_l(int " c ", locale_t " locale );
  23 .fi
  24 .PP
  25 .RS -4
  26 Feature Test Macro Requirements for glibc (see
  27 .BR feature_test_macros (7)):
  28 .RE
  29 .PP
  30 .BR toupper_l (),
  31 .BR tolower_l ():
  32 .nf
  33     Since glibc 2.10:
  34         _XOPEN_SOURCE >= 700
  35     Before glibc 2.10:
  36         _GNU_SOURCE
  37 .fi
  38 .SH DESCRIPTION
  39 These functions convert lowercase letters to uppercase, and vice versa.
  40 .PP
  41 If
  42 .I c
  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 .
  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 .
  54 .PP
  55 If
  56 .I c
  57 is an uppercase letter,
  58 .BR tolower ()
  59 returns its lowercase equivalent,
  60 if a lowercase representation exists in the current locale.
  61 Otherwise, it returns
  62 .IR c .
  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 .
  68 .PP
  69 If
  70 .I c
  71 is neither an
  72 .I "unsigned char"
  73 value nor
  74 .BR EOF ,
  75 the behavior of these functions
  76 is undefined.
  77 .PP
  78 The behavior of
  79 .BR toupper_l ()
  80 and
  81 .BR tolower_l ()
  82 is undefined if
  83 .I locale
  84 is the special locale object
  85 .B LC_GLOBAL_LOCALE
  86 (see
  87 .BR duplocale (3))
  88 or is not a valid locale object handle.
  89 .SH RETURN VALUE
  90 The value returned is that of the converted letter, or
  91 .I c
  92 if the conversion was not possible.
  93 .SH ATTRIBUTES
  94 For an explanation of the terms used in this section, see
  95 .BR attributes (7).
  96 .ad l
  97 .nh
  98 .TS
  99 allbox;
 100 lbx lb lb
 101 l l l.
 102 Interface       Attribute       Value
 103 T{
 104 .BR toupper (),
 105 .BR tolower (),
 106 .BR toupper_l (),
 107 .BR tolower_l ()
 108 T}      Thread safety   MT-Safe
 109 .TE
 110 .hy
 111 .ad
 112 .sp 1
 113 .SH STANDARDS
 114 .BR toupper (),
 115 .BR tolower ():
 116 C89, C99, 4.3BSD, POSIX.1-2001, POSIX.1-2008.
 117 .PP
 118 .BR toupper_l (),
 119 .BR tolower_l ():
 120 POSIX.1-2008.
 121 .SH NOTES
 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:
 135 .PP
 136 .in +4n
 137 .EX
 138 char c;
 139 \&...
 140 res = toupper((unsigned char) c);
 141 .EE
 142 .in
 143 .PP
 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" .
 153 .PP
 154 The details of what constitutes an uppercase or lowercase letter depend
 155 on the locale.
 156 For example, the default
 157 .B """C"""
 158 locale does not know about umlauts, so no conversion is done for them.
 159 .PP
 160 In some non-English locales, there are lowercase letters with no
 161 corresponding uppercase equivalent;
 162 .\" FIXME One day the statement about "sharp s" needs to be reworked,
 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.
 166 .SH SEE ALSO
 167 .BR isalpha (3),
 168 .BR newlocale (3),
 169 .BR setlocale (3),
 170 .BR towlower (3),
 171 .BR towupper (3),
 172 .BR uselocale (3),
 173 .BR locale (7)