SYNOPSIS: Added feature test macro requirements.

DESCRIPTION: Enhanced.
RETURN VALUE: Added details for special argument cases.
Rewrote ERRORS section.
Updated CONFORMING TO.
NOTES: Added some details.

man3/ceil.3

@@ -1,4 +1,6 @@
 .\" Copyright 2001 Andries Brouwer <aeb@cwi.nl>.
+.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk
+.\"     <mtk.manpages@gmail.com>
 .\"
 .\" Permission is granted to make and distribute verbatim copies of this
 .\" manual provided the copyright notice and this permission notice are
@@ -20,7 +22,7 @@
 .\" Formatted or processed versions of this manual, if unaccompanied by
 .\" the source, must acknowledge the copyright and authors of this work.
 .\"
-.TH CEIL 3  2001-05-31 "" "Linux Programmer's Manual"
+.TH CEIL 3  2008-07-29 "" "Linux Programmer's Manual"
 .SH NAME
 ceil, ceilf, ceill \- ceiling function: smallest integral value not
 less than argument
@@ -36,40 +38,67 @@ less than argument
 .fi
 .sp
 Link with \fI\-lm\fP.
+.sp
+.in -4n
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.in
+.sp
+.ad l
+.BR ceilf (),
+.BR ceill ():
+_BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE\ >=\ 600 || _ISOC99_SOURCE; or
+.I cc\ -std=c99
+.ad b
 .SH DESCRIPTION
-These functions round \fIx\fP up to the nearest integer.
+These functions return the smallest integral value that is not less than
+.IR x .
+
+For example,
+.IR ceil(0.5)
+is 1.0, and
+.IR ceil(\-0.5)
+is 0.0.
 .SH "RETURN VALUE"
-The rounded integer value.
+These functions return the ceiling of
-If \fIx\fP is integral or infinite,
+.IR x .
+
+If \fIx\fP is integral, +0, \-0, NaN, or infinite,
 \fIx\fP itself is returned.
 .SH ERRORS
-No errors other than
+No errors occur.
-.B EDOM
+POSIX.1-2001 documents a "range error" for overflows, but see NOTES.
-and
-.B ERANGE
-can occur.
-If \fIx\fP is NaN, then NaN is returned and
-.I errno
-may be set to
-.BR EDOM .
 .SH "CONFORMING TO"
-The
+C99, POSIX.1-2001.
-.BR ceil ()
+The variant returning
-function conforms to SVr4, POSIX.1-2001, 4.3BSD, C89, C99.
+.I double
-The other functions are from C99.
+also conforms to
+SVr4, 4.3BSD, C89.
 .SH NOTES
 SUSv2 and POSIX.1-2001 contain text about overflow (which might set
 .I errno
 to
 .BR ERANGE ,
-or raise an exception).
+or raise an
+.B FE_OVERFLOW
+exception).
 In practice, the result cannot overflow on any current machine,
 so this error-handling stuff is just nonsense.
+.\" The POSIX.1-2001 APPLICATION USAGE SECTION discusses this point.
 (More precisely, overflow can happen only when the maximum value
 of the exponent is smaller than the number of mantissa bits.
-For the IEEE-754 standard 32-bit and 64-bit floating point numbers
+For the IEEE-754 standard 32-bit and 64-bit floating-point numbers
-the maximum value of the exponent is 128 (resp. 1024), and the number
+the maximum value of the exponent is 128 (respectively, 1024),
-of mantissa bits is 24 (resp. 53).)
+and the number of mantissa bits is 24 (respectively, 53).)
+
+The integral value returned by these functions may be too large
+to store in an integer type
+.RI ( int ,
+.IR long ,
+etc.).
+To avoid an overflow, which will produce undefined results,
+an application should perform a range check on the returned value
+before assigning it to an integer type.
 .SH "SEE ALSO"
 .BR floor (3),
 .BR lrint (3),