toupper.3: Note circumstances where 'c' must be cast to 'unsigned char'

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

diff --git a/man3/toupper.3 b/man3/toupper.3
index d7ff86dbfd38b85d0fb113a6bc585521f224d98a..649e08d1276557ca55da0fc12e15f394c5d7c53e 100644 (file)
--- a/man3/toupper.3
+++ b/man3/toupper.3
@@ -137,6 +137,38 @@ C89, C99, 4.3BSD, POSIX.1-2001, POSIX.1-2008.
 .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:
+
+.nf
+.in +4n
+char c;
+\&...
+res = toupper((unsigned char) c);
+.in
+.fi
+
+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" .
+
 The details of what constitutes an uppercase or lowercase letter depend
 on the locale.
 For example, the default