man3/atanh.3

   1 '\" t
   2 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   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 .\" References consulted:
   9 .\"     Linux libc source code
  10 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
  11 .\"     386BSD man pages
  12 .\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu)
  13 .\" Modified 2002-07-27 by Walter Harms
  14 .\"     (walter.harms@informatik.uni-oldenburg.de)
  15 .\"
  16 .TH atanh 3 (date) "Linux man-pages (unreleased)"
  17 .SH NAME
  18 atanh, atanhf, atanhl \- inverse hyperbolic tangent function
  19 .SH LIBRARY
  20 Math library
  21 .RI ( libm ", " \-lm )
  22 .SH SYNOPSIS
  23 .nf
  24 .B #include <math.h>
  25 .P
  26 .BI "double atanh(double " x );
  27 .BI "float atanhf(float " x );
  28 .BI "long double atanhl(long double " x );
  29 .P
  30 .fi
  31 .RS -4
  32 Feature Test Macro Requirements for glibc (see
  33 .BR feature_test_macros (7)):
  34 .RE
  35 .P
  36 .BR atanh ():
  37 .nf
  38     _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
  39         || _XOPEN_SOURCE >= 500
  40 .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
  41         || /* Since glibc 2.19: */ _DEFAULT_SOURCE
  42         || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  43 .fi
  44 .P
  45 .BR atanhf (),
  46 .BR atanhl ():
  47 .nf
  48     _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
  49         || /* Since glibc 2.19: */ _DEFAULT_SOURCE
  50         || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  51 .fi
  52 .SH DESCRIPTION
  53 These functions calculate the inverse hyperbolic tangent of
  54 .IR x ;
  55 that is the value whose hyperbolic tangent is
  56 .IR x .
  57 .SH RETURN VALUE
  58 On success, these functions return the inverse hyperbolic tangent of
  59 .IR x .
  60 .P
  61 If
  62 .I x
  63 is a NaN, a NaN is returned.
  64 .P
  65 If
  66 .I x
  67 is +0 (\-0), +0 (\-0) is returned.
  68 .P
  69 If
  70 .I x
  71 is +1 or \-1,
  72 a pole error occurs,
  73 and the functions return
  74 .BR HUGE_VAL ,
  75 .BR HUGE_VALF ,
  76 or
  77 .BR HUGE_VALL ,
  78 respectively, with the mathematically correct sign.
  79 .P
  80 If the absolute value of
  81 .I x
  82 is greater than 1,
  83 a domain error occurs,
  84 and a NaN is returned.
  85 .\"
  86 .\" POSIX.1-2001 documents an optional range error for subnormal x;
  87 .\" glibc 2.8 does not do this.
  88 .SH ERRORS
  89 See
  90 .BR math_error (7)
  91 for information on how to determine whether an error has occurred
  92 when calling these functions.
  93 .P
  94 The following errors can occur:
  95 .TP
  96 Domain error: \fIx\fP less than \-1 or greater than +1
  97 .I errno
  98 is set to
  99 .BR EDOM .
 100 An invalid floating-point exception
 101 .RB ( FE_INVALID )
 102 is raised.
 103 .TP
 104 Pole error: \fIx\fP is +1 or \-1
 105 .I errno
 106 is set to
 107 .B ERANGE
 108 (but see BUGS).
 109 A divide-by-zero floating-point exception
 110 .RB ( FE_DIVBYZERO )
 111 is raised.
 112 .SH ATTRIBUTES
 113 For an explanation of the terms used in this section, see
 114 .BR attributes (7).
 115 .TS
 116 allbox;
 117 lbx lb lb
 118 l l l.
 119 Interface       Attribute       Value
 120 T{
 121 .na
 122 .nh
 123 .BR atanh (),
 124 .BR atanhf (),
 125 .BR atanhl ()
 126 T}      Thread safety   MT-Safe
 127 .TE
 128 .SH STANDARDS
 129 C11, POSIX.1-2008.
 130 .SH HISTORY
 131 C99, POSIX.1-2001.
 132 .P
 133 The variant returning
 134 .I double
 135 also conforms to
 136 SVr4, 4.3BSD.
 137 .SH BUGS
 138 In glibc 2.9 and earlier,
 139 .\" Bug: https://www.sourceware.org/bugzilla/show_bug.cgi?id=6759
 140 .\" This can be seen in sysdeps/ieee754/k_standard.c
 141 when a pole error occurs,
 142 .I errno
 143 is set to
 144 .B EDOM
 145 instead of the POSIX-mandated
 146 .BR ERANGE .
 147 Since glibc 2.10, glibc does the right thing.
 148 .SH SEE ALSO
 149 .BR acosh (3),
 150 .BR asinh (3),
 151 .BR catanh (3),
 152 .BR cosh (3),
 153 .BR sinh (3),
 154 .BR tanh (3)