.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
+.\" and Copyright 2014 Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" %%%LICENSE_END
.\"
.\" 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 1993-04-04 "GNU" "Linux Programmer's Manual"
+.\" Modified 2000-02-13 by Nicolás Lichtmaier <nick@debian.org>
+.TH TOUPPER 3 2014-03-18 "GNU" "Linux Programmer's Manual"
.SH NAME
-toupper, tolower \- convert letter to upper or lower case
+toupper, tolower, toupper_l, tolower_l \- convert uppercase or lowercase
.SH SYNOPSIS
.nf
.B #include <ctype.h>
.BI "int toupper(int " "c" );
.br
.BI "int tolower(int " "c" );
+
+.BI "int toupper_l(int " c ", locale_t " locale );
+.BI "int tolower_l(int " c ", locale_t " locale );
.fi
+.sp
+.in -4n
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.in
+.sp
+.BR toupper_l (),
+.BR tolower_l ():
+.PD 0
+.RS 4
+.TP
+Since glibc 2.10:
+_XOPEN_SOURCE\ >=\ 700
+.TP
+Before glibc 2.10:
+_GNU_SOURCE
+.RE
+.PD
.SH DESCRIPTION
-.BR toupper ()
-converts the letter
+These functions convert lowercase letters to uppercase, and vice versa.
+
+If
.I c
-to upper case, if possible.
-.PP
-.BR tolower ()
-converts the letter
+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 .
+
+If
.I c
-to lower case, if possible.
+is a uppercase letter,
+.BR toupper ()
+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 .
.PP
If
.I c
-is not an
+is neither an
.I "unsigned char"
-value, or
+value nor
.BR EOF ,
the behavior of these functions
is undefined.
+
+The behavior of
+.BR toupper_l ()
+and
+.BR tolower_l ()
+is undefined if
+.I locale
+is the special locale object
+.BR 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
+.SS Multithreading (see pthreads(7))
+The
+.BR toupper ()
+and
+.BR tolower ()
+functions are thread-safe with exceptions.
+These functions can be safely used in multithreaded applications,
+as long as
+.BR setlocale (3)
+is not called to change the locale during their execution.
+.\" FIXME Add toupper_l() and tolower_l()
.SH CONFORMING TO
-C89, C99, 4.3BSD.
-.SH BUGS
+.BR toupper (),
+.BR tolower ():
+C89, C99, 4.3BSD, POSIX.1-2001, POSIX.1-2008.
+
+.BR toupper_l (),
+.BR tolower_l ():
+POSIX.1-2008.
+.SH NOTES
The details of what constitutes an uppercase or lowercase letter depend
-on the current locale.
+on the locale.
For example, the default
.B """C"""
locale does not know about umlauts, so no conversion is done for them.
.PP
In some non-English locales, there are lowercase letters with no
-corresponding uppercase equivalent; the German sharp s is one
-example.
+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 uselocale (3),
.BR towlower (3),
.BR towupper (3),
.BR locale (7)
OSDN Git Service
