diff options
Diffstat (limited to 'man/man3/toupper.3')
| -rw-r--r-- | man/man3/toupper.3 | 185 |
1 files changed, 185 insertions, 0 deletions
diff --git a/man/man3/toupper.3 b/man/man3/toupper.3 new file mode 100644 index 000000000..98a111c81 --- /dev/null +++ b/man/man3/toupper.3 @@ -0,0 +1,185 @@ +'\" 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 (date) "Linux man-pages (unreleased)" +.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) |