man3/hypot.3

   1 '\" t
   2 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .\" References consulted:
   7 .\"     Linux libc source code
   8 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
   9 .\"     386BSD man pages
  10 .\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu)
  11 .\" Modified 2002-07-27 by Walter Harms
  12 .\"     (walter.harms@informatik.uni-oldenburg.de)
  13 .\"
  14 .TH hypot 3 (date) "Linux man-pages (unreleased)"
  15 .SH NAME
  16 hypot, hypotf, hypotl \- Euclidean distance function
  17 .SH LIBRARY
  18 Math library
  19 .RI ( libm ", " \-lm )
  20 .SH SYNOPSIS
  21 .nf
  22 .B #include <math.h>
  23 .PP
  24 .BI "double hypot(double " x ", double " y );
  25 .BI "float hypotf(float " x ", float " y );
  26 .BI "long double hypotl(long double " x ", long double " y );
  27 .fi
  28 .PP
  29 .RS -4
  30 Feature Test Macro Requirements for glibc (see
  31 .BR feature_test_macros (7)):
  32 .RE
  33 .PP
  34 .BR hypot ():
  35 .nf
  36     _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
  37         || _XOPEN_SOURCE
  38         || /* Since glibc 2.19: */ _DEFAULT_SOURCE
  39         || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  40 .fi
  41 .PP
  42 .BR hypotf (),
  43 .BR hypotl ():
  44 .nf
  45     _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
  46         || /* Since glibc 2.19: */ _DEFAULT_SOURCE
  47         || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  48 .fi
  49 .SH DESCRIPTION
  50 These functions return
  51 .RI sqrt( x * x + y * y ).
  52 This is the length of the hypotenuse of a right-angled triangle
  53 with sides of length
  54 .I x
  55 and
  56 .IR y ,
  57 or the distance of the point
  58 .RI ( x , y )
  59 from the origin.
  60 .PP
  61 The calculation is performed without undue overflow or underflow
  62 during the intermediate steps of the calculation.
  63 .\" e.g., hypot(DBL_MIN, DBL_MIN) does the right thing, as does, say
  64 .\" hypot(DBL_MAX/2.0, DBL_MAX/2.0).
  65 .SH RETURN VALUE
  66 On success, these functions return the length of the hypotenuse of
  67 a right-angled triangle
  68 with sides of length
  69 .I x
  70 and
  71 .IR y .
  72 .PP
  73 If
  74 .I x
  75 or
  76 .I y
  77 is an infinity,
  78 positive infinity is returned.
  79 .PP
  80 If
  81 .I x
  82 or
  83 .I y
  84 is a NaN,
  85 and the other argument is not an infinity,
  86 a NaN is returned.
  87 .PP
  88 If the result overflows,
  89 a range error occurs,
  90 and the functions return
  91 .BR HUGE_VAL ,
  92 .BR HUGE_VALF ,
  93 or
  94 .BR HUGE_VALL ,
  95 respectively.
  96 .PP
  97 If both arguments are subnormal, and the result is subnormal,
  98 .\" Actually, could the result not be subnormal if both arguments
  99 .\" are subnormal?  I think not -- mtk, Jul 2008
 100 a range error occurs,
 101 and the correct result is returned.
 102 .SH ERRORS
 103 See
 104 .BR math_error (7)
 105 for information on how to determine whether an error has occurred
 106 when calling these functions.
 107 .PP
 108 The following errors can occur:
 109 .TP
 110 Range error: result overflow
 111 .I errno
 112 is set to
 113 .BR ERANGE .
 114 An overflow floating-point exception
 115 .RB ( FE_OVERFLOW )
 116 is raised.
 117 .TP
 118 Range error: result underflow
 119 An underflow floating-point exception
 120 .RB ( FE_UNDERFLOW )
 121 is raised.
 122 .IP
 123 These functions do not set
 124 .I errno
 125 for this case.
 126 .\" This is intentional; see
 127 .\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6795
 128 .SH ATTRIBUTES
 129 For an explanation of the terms used in this section, see
 130 .BR attributes (7).
 131 .TS
 132 allbox;
 133 lbx lb lb
 134 l l l.
 135 Interface       Attribute       Value
 136 T{
 137 .na
 138 .nh
 139 .BR hypot (),
 140 .BR hypotf (),
 141 .BR hypotl ()
 142 T}      Thread safety   MT-Safe
 143 .TE
 144 .sp 1
 145 .SH STANDARDS
 146 C11, POSIX.1-2008.
 147 .SH HISTORY
 148 C99, POSIX.1-2001.
 149 .PP
 150 The variant returning
 151 .I double
 152 also conforms to
 153 SVr4, 4.3BSD.
 154 .SH SEE ALSO
 155 .BR cabs (3),
 156 .BR sqrt (3)