man3/rint.3

   1 '\" t
   2 .\" Copyright 2001 Andries Brouwer <aeb@cwi.nl>.
   3 .\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk
   4 .\"     <mtk.manpages@gmail.com>
   5 .\"
   6 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   7 .\"
   8 .TH rint 3 (date) "Linux man-pages (unreleased)"
   9 .SH NAME
  10 nearbyint, nearbyintf, nearbyintl, rint, rintf, rintl \- round
  11 to nearest integer
  12 .SH LIBRARY
  13 Math library
  14 .RI ( libm ", " \-lm )
  15 .SH SYNOPSIS
  16 .nf
  17 .B #include <math.h>
  18 .PP
  19 .BI "double nearbyint(double " x );
  20 .BI "float nearbyintf(float " x );
  21 .BI "long double nearbyintl(long double " x );
  22 .PP
  23 .BI "double rint(double " x );
  24 .BI "float rintf(float " x );
  25 .BI "long double rintl(long double " x );
  26 .fi
  27 .PP
  28 .RS -4
  29 Feature Test Macro Requirements for glibc (see
  30 .BR feature_test_macros (7)):
  31 .RE
  32 .PP
  33 .BR nearbyint (),
  34 .BR nearbyintf (),
  35 .BR nearbyintl ():
  36 .nf
  37     _POSIX_C_SOURCE >= 200112L || _ISOC99_SOURCE
  38 .fi
  39 .PP
  40 .BR rint ():
  41 .nf
  42     _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
  43         || _XOPEN_SOURCE >= 500
  44 .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
  45         || /* Since glibc 2.19: */ _DEFAULT_SOURCE
  46         || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  47 .fi
  48 .PP
  49 .BR rintf (),
  50 .BR rintl ():
  51 .nf
  52     _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
  53         || /* Since glibc 2.19: */ _DEFAULT_SOURCE
  54         || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  55 .fi
  56 .SH DESCRIPTION
  57 The
  58 .BR nearbyint (),
  59 .BR nearbyintf (),
  60 and
  61 .BR nearbyintl ()
  62 functions round their argument to an integer value in floating-point
  63 format, using the current rounding direction (see
  64 .BR fesetround (3))
  65 and without raising the
  66 .I inexact
  67 exception.
  68 When the current rounding direction is to nearest, these
  69 functions round halfway cases to the even integer in accordance with
  70 IEEE-754.
  71 .PP
  72 The
  73 .BR rint (),
  74 .BR rintf (),
  75 and
  76 .BR rintl ()
  77 functions do the same, but will raise the
  78 .I inexact
  79 exception
  80 .RB ( FE_INEXACT ,
  81 checkable via
  82 .BR fetestexcept (3))
  83 when the result differs in value from the argument.
  84 .SH RETURN VALUE
  85 These functions return the rounded integer value.
  86 .PP
  87 If
  88 .I x
  89 is integral, +0, \-0, NaN, or infinite,
  90 .I x
  91 itself is returned.
  92 .SH ERRORS
  93 No errors occur.
  94 POSIX.1-2001 documents a range error for overflows, but see NOTES.
  95 .SH ATTRIBUTES
  96 For an explanation of the terms used in this section, see
  97 .BR attributes (7).
  98 .ad l
  99 .nh
 100 .TS
 101 allbox;
 102 lbx lb lb
 103 l l l.
 104 Interface       Attribute       Value
 105 T{
 106 .BR nearbyint (),
 107 .BR nearbyintf (),
 108 .BR nearbyintl (),
 109 .BR rint (),
 110 .BR rintf (),
 111 .BR rintl ()
 112 T}      Thread safety   MT-Safe
 113 .TE
 114 .hy
 115 .ad
 116 .sp 1
 117 .SH STANDARDS
 118 C99, POSIX.1-2001, POSIX.1-2008.
 119 .SH NOTES
 120 SUSv2 and POSIX.1-2001 contain text about overflow (which might set
 121 .I errno
 122 to
 123 .BR ERANGE ,
 124 or raise an
 125 .B FE_OVERFLOW
 126 exception).
 127 In practice, the result cannot overflow on any current machine,
 128 so this error-handling stuff is just nonsense.
 129 (More precisely, overflow can happen only when the maximum value
 130 of the exponent is smaller than the number of mantissa bits.
 131 For the IEEE-754 standard 32-bit and 64-bit floating-point numbers
 132 the maximum value of the exponent is 127 (respectively, 1023),
 133 and the number of mantissa bits
 134 including the implicit bit
 135 is 24 (respectively, 53).)
 136 .PP
 137 If you want to store the rounded value in an integer type,
 138 you probably want to use one of the functions described in
 139 .BR lrint (3)
 140 instead.
 141 .SH SEE ALSO
 142 .BR ceil (3),
 143 .BR floor (3),
 144 .BR lrint (3),
 145 .BR round (3),
 146 .BR trunc (3)