Libc-583.tar.gz

[apple/libc.git] / locale / toupper.3

diff --git a/locale/toupper.3 b/locale/toupper.3
index e4edd22367e734240e762510e330a6e0d3c9350d..12b67bbd854090ba26bf063d23150bc8f4bf5ffd 100644 (file)
--- a/locale/toupper.3
+++ b/locale/toupper.3
@@ -34,20 +34,30 @@
 .\" SUCH DAMAGE.
 .\"
 .\"    @(#)toupper.3   8.1 (Berkeley) 6/4/93
-.\" $FreeBSD: src/lib/libc/locale/toupper.3,v 1.5.2.5 2001/12/14 18:33:55 ru Exp $
+.\" $FreeBSD: src/lib/libc/locale/toupper.3,v 1.16 2004/08/21 07:37:08 tjr Exp $
 .\"
-.Dd June 4, 1993
+.Dd August 21, 2004
 .Dt TOUPPER 3
 .Os
 .Sh NAME
-.Nm toupper
+.Nm toupper ,
+.Nm toupper_l
 .Nd lower case to upper case letter conversion
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
 .In ctype.h
 .Ft int
-.Fn toupper "int c"
+.Fo toupper
+.Fa "int c"
+.Fc
+.In ctype.h
+.In xlocale.h
+.Ft int
+.Fo toupper_l
+.Fa "int c"
+.Fa "locale_t loc"
+.Fc
 .Sh DESCRIPTION
 The
 .Fn toupper
@@ -56,35 +66,41 @@ upper-case letter.
 For single C
 .Va char Ns s
 locales (see
-.Xr multibyte 3 )
+.Xr multibyte 3 ) ,
 the value of the argument is
 representable as an
 .Li unsigned char
 or the value of
 .Dv EOF .
+.Pp
+Although the
+.Fn toupper
+function uses the current locale, the
+.Fn toupper_l
+function may be passed a locale directly. See
+.Xr xlocale 3
+for more information.
 .Sh RETURN VALUES
 If the argument is a lower-case letter, the
 .Fn toupper
 function returns the corresponding upper-case letter if there is
-one; otherwise the argument is returned unchanged.
+one; otherwise, the argument is returned unchanged.
+.Sh COMPATIBILITY
+The
+.Bx 4.4
+extension of accepting arguments outside of the range of the
+.Vt "unsigned char"
+type in locales with large character sets is considered obsolete
+and may not be supported in future releases.
+The
+.Fn towupper
+function should be used instead.
 .Sh SEE ALSO
-.Xr isalnum 3 ,
-.Xr isalpha 3 ,
-.Xr isascii 3 ,
-.Xr iscntrl 3 ,
-.Xr isdigit 3 ,
-.Xr isgraph 3 ,
-.Xr islower 3 ,
-.Xr isprint 3 ,
-.Xr ispunct 3 ,
-.Xr isspace 3 ,
+.Xr ctype 3 ,
 .Xr isupper 3 ,
-.Xr isxdigit 3 ,
 .Xr multibyte 3 ,
-.Xr stdio 3 ,
-.Xr toascii 3 ,
-.Xr tolower 3 ,
-.Xr ascii 7
+.Xr towupper 3 ,
+.Xr xlocale 3
 .Sh STANDARDS
 The
 .Fn toupper