man3/t-v.3: srcfix: Use a single-font-style macro for a single argument

[thirdparty/man-pages.git] / man3 / toupper.3

diff --git a/man3/toupper.3 b/man3/toupper.3
index c516514b97f790ca18c1c0e3f96fc24349f702b0..f036acf8c10fe93933196b28306b09b6ebec7ab7 100644 (file)
--- a/man3/toupper.3
+++ b/man3/toupper.3
@@ -25,26 +25,25 @@
 .\"
 .\" 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  2014-03-07 "GNU" "Linux Programmer's Manual"
+.TH TOUPPER 3  2017-09-15 "GNU" "Linux Programmer's Manual"
 .SH NAME
 toupper, tolower, toupper_l, tolower_l \- convert uppercase or lowercase
 .SH SYNOPSIS
 .nf
 .B #include <ctype.h>
-.sp
+.PP
 .BI "int toupper(int " "c" );
-.br
 .BI "int tolower(int " "c" );
-
+.PP
 .BI "int toupper_l(int " c ", locale_t " locale );
 .BI "int tolower_l(int " c ", locale_t " locale );
 .fi
-.sp
+.PP
 .in -4n
 Feature Test Macro Requirements for glibc (see
 .BR feature_test_macros (7)):
 .in
-.sp
+.PP
 .BR toupper_l (),
 .BR tolower_l ():
 .PD 0
@@ -59,7 +58,7 @@ _GNU_SOURCE
 .PD
 .SH DESCRIPTION
 These functions convert lowercase letters to uppercase, and vice versa.
-
+.PP
 If
 .I c
 is a lowercase letter,
@@ -73,11 +72,11 @@ The
 function performs the same task,
 but uses the locale referred to by the locale handle
 .IR locale .
-
+.PP
 If
 .I c
-is a uppercase letter,
-.BR toupper ()
+is an uppercase letter,
+.BR tolower ()
 returns its lowercase equivalent,
 if a lowercase representation exists in the current locale.
 Otherwise, it returns
@@ -96,7 +95,7 @@ value nor
 .BR EOF ,
 the behavior of these functions
 is undefined.
-
+.PP
 The behavior of
 .BR toupper_l ()
 and
@@ -104,7 +103,7 @@ and
 is undefined if
 .I locale
 is the special locale object
-.BR LC_GLOBAL_LOCALE
+.B LC_GLOBAL_LOCALE
 (see
 .BR duplocale (3))
 or is not a valid locale object handle.
@@ -113,26 +112,62 @@ 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()
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbw24 lb lb
+l l l.
+Interface      Attribute       Value
+T{
+.BR toupper (),
+.BR tolower (),
+.br
+.BR toupper_l (),
+.BR tolower_l ()
+T}     Thread safety   MT-Safe
+.TE
 .SH CONFORMING TO
 .BR toupper (),
 .BR tolower ():
 C89, C99, 4.3BSD, POSIX.1-2001, POSIX.1-2008.
-
+.PP
 .BR toupper_l (),
 .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:
+.PP
+.in +4n
+.EX
+char c;
+\&...
+res = toupper((unsigned char) c);
+.EE
+.in
+.PP
+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" .
+.PP
 The details of what constitutes an uppercase or lowercase letter depend
 on the locale.
 For example, the default
@@ -141,7 +176,7 @@ 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;
-.\" FIXME: One day the statement about "sharp s" needs to be reworked,
+.\" 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.
@@ -149,7 +184,7 @@ the German sharp s is one example.
 .BR isalpha (3),
 .BR newlocale (3),
 .BR setlocale (3),
-.BR uselocale (3),
 .BR towlower (3),
 .BR towupper (3),
+.BR uselocale (3),
 .BR locale (7)