'\" t
.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
.\" and Copyright 2014 Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.\" Modified Sat Jul 24 17:45:39 1993 by Rik Faith (faith@cs.unc.edu)
.\" Modified 2000-02-13 by Nicolás Lichtmaier <nick@debian.org>
.TH toupper 3 2024-02-25 "Linux man-pages 6.7"
.SH NAME
toupper, tolower, toupper_l, tolower_l \- convert uppercase or lowercase
.SH LIBRARY
Standard C library
.RI ( libc ", " \-lc )
.SH SYNOPSIS
.nf
.B #include <ctype.h>
.P
.BI "int toupper(int " "c" );
.BI "int tolower(int " "c" );
.P
.BI "int toupper_l(int " c ", locale_t " locale );
.BI "int tolower_l(int " c ", locale_t " locale );
.fi
.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
.P
.BR toupper_l (),
.BR tolower_l ():
.nf
    Since glibc 2.10:
        _XOPEN_SOURCE >= 700
    Before glibc 2.10:
        _GNU_SOURCE
.fi
.SH DESCRIPTION
These functions convert lowercase letters to uppercase, and vice versa.
.P
If
.I c
is a lowercase letter,
.BR toupper ()
returns its uppercase equivalent,
if an uppercase representation exists in the current locale.
Otherwise, it returns
.IR c .
The
.BR toupper_l ()
function performs the same task,
but uses the locale referred to by the locale handle
.IR locale .
.P
If
.I c
is an uppercase letter,
.BR tolower ()
returns its lowercase equivalent,
if a lowercase representation exists in the current locale.
Otherwise, it returns
.IR c .
The
.BR tolower_l ()
function performs the same task,
but uses the locale referred to by the locale handle
.IR locale .
.P
If
.I c
is neither an
.I "unsigned char"
value nor
.BR EOF ,
the behavior of these functions
is undefined.
.P
The behavior of
.BR toupper_l ()
and
.BR tolower_l ()
is undefined if
.I locale
is the special locale object
.B LC_GLOBAL_LOCALE
(see
.BR duplocale (3))
or is not a valid locale object handle.
.SH RETURN VALUE
The value returned is that of the converted letter, or
.I c
if the conversion was not possible.
.SH ATTRIBUTES
For an explanation of the terms used in this section, see
.BR attributes (7).
.TS
allbox;
lbx lb lb
l l l.
Interface	Attribute	Value
T{
.na
.nh
.BR toupper (),
.BR tolower (),
.BR toupper_l (),
.BR tolower_l ()
T}	Thread safety	MT-Safe
.TE
.SH STANDARDS
.TP
.BR toupper ()
.TQ
.BR tolower ()
C11, POSIX.1-2008.
.TP
.BR toupper_l ()
.TQ
.BR tolower_l ()
POSIX.1-2008.
.SH HISTORY
.TP
.BR toupper ()
.TQ
.BR tolower ()
C89, 4.3BSD, POSIX.1-2001.
.TP
.BR toupper_l ()
.TQ
.BR tolower_l ()
POSIX.1-2008.
.SH NOTES
The standards require that the argument
.I c
for these functions is either
.B EOF
or a value that is representable in the type
.IR "unsigned char" .
If the argument
.I c
is of type
.IR char ,
it must be cast to
.IR "unsigned char" ,
as in the following example:
.P
.in +4n
.EX
char c;
\&...
res = toupper((unsigned char) c);
.EE
.in
.P
This is necessary because
.I char
may be the equivalent
.IR "signed char" ,
in which case a byte where the top bit is set would be sign extended when
converting to
.IR int ,
yielding a value that is outside the range of
.IR "unsigned char" .
.P
The details of what constitutes an uppercase or lowercase letter depend
on the locale.
For example, the default
.B \[dq]C\[dq]
locale does not know about umlauts, so no conversion is done for them.
.P
In some non-English locales, there are lowercase letters with no
corresponding uppercase equivalent;
.\" FIXME One day the statement about "sharp s" needs to be reworked,
.\" since there is nowadays a capital "sharp s" that has a codepoint
.\" in Unicode 5.0; see https://en.wikipedia.org/wiki/Capital_%E1%BA%9E
the German sharp s is one example.
.SH SEE ALSO
.BR isalpha (3),
.BR newlocale (3),
.BR setlocale (3),
.BR towlower (3),
.BR towupper (3),
.BR uselocale (3),
.BR locale (7)