Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 185 insertions, 0 deletions

diff --git a/man/man3/toupper.3 b/man/man3/toupper.3
new file mode 100644
index 0000000..c2ab04a
--- /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 2024-05-02 "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)