logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

tgmath.h.0p (10588B)


  1. '\" et
  2. .TH tgmath.h "0P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. tgmath.h
  12. \(em type-generic macros
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <tgmath.h>
  17. .fi
  18. .SH DESCRIPTION
  19. The functionality described on this reference page is aligned with the
  20. ISO\ C standard. Any conflict between the requirements described here and the
  21. ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard.
  22. .P
  23. The
  24. .IR <tgmath.h>
  25. header shall include the headers
  26. .IR <math.h>
  27. and
  28. .IR <complex.h>
  29. and shall define several type-generic macros.
  30. .P
  31. Of the functions contained within the
  32. .IR <math.h>
  33. and
  34. .IR <complex.h>
  35. headers without an
  36. .IR f
  37. (\c
  38. .BR float )
  39. or
  40. .IR l
  41. (\c
  42. .BR "long double" )
  43. suffix, several have one or more parameters whose corresponding real
  44. type is
  45. .BR double .
  46. For each such function, except
  47. \fImodf\fR(),
  48. \fIj0\fR(),
  49. \fIj1\fR(),
  50. \fIjn\fR(),
  51. \fIy0\fR(),
  52. \fIy1\fR(),
  53. and
  54. \fIyn\fR(),
  55. there shall be a corresponding type-generic macro. The parameters
  56. whose corresponding real type is
  57. .BR double
  58. in the function synopsis are generic parameters. Use of the macro
  59. invokes a function whose corresponding real type and type domain are
  60. determined by the arguments for the generic parameters.
  61. .P
  62. Use of the macro invokes a function whose generic parameters have the
  63. corresponding real type determined as follows:
  64. .IP " *" 4
  65. First, if any argument for generic parameters has type
  66. .BR "long double" ,
  67. the type determined is
  68. .BR "long double" .
  69. .IP " *" 4
  70. Otherwise, if any argument for generic parameters has type
  71. .BR double
  72. or is of integer type, the type determined is
  73. .BR double .
  74. .IP " *" 4
  75. Otherwise, the type determined is
  76. .BR float .
  77. .P
  78. For each unsuffixed function in the
  79. .IR <math.h>
  80. header for which there is a function in the
  81. .IR <complex.h>
  82. header with the same name except for a
  83. .IR c
  84. prefix, the corresponding type-generic macro (for both functions) has
  85. the same name as the function in the
  86. .IR <math.h>
  87. header. The corresponding type-generic macro for
  88. \fIfabs\fR()
  89. and
  90. \fIcabs\fR()
  91. is
  92. \fIfabs\fR().
  93. .TS
  94. center box tab(!);
  95. cB | cB | cB
  96. l | l | l.
  97. <math.h> Function!<complex.h> Function!Type-Generic Macro
  98. _
  99. \fIacos\fR\^(\|)!\fIcacos\fR\^(\|)!\fIacos\fR\^(\|)
  100. \fIasin\fR\^(\|)!\fIcasin\fR\^(\|)!\fIasin\fR\^(\|)
  101. \fIatan\fR\^(\|)!\fIcatan\fR\^(\|)!\fIatan\fR\^(\|)
  102. \fIacosh\fR\^(\|)!\fIcacosh\fR\^(\|)!\fIacosh\fR\^(\|)
  103. \fIasinh\fR\^(\|)!\fIcasinh\fR\^(\|)!\fIasinh\fR\^(\|)
  104. \fIatanh\fR\^(\|)!\fIcatanh\fR\^(\|)!\fIatanh\fR\^(\|)
  105. \fIcos\fR\^(\|)!\fIccos\fR\^(\|)!\fIcos\fR\^(\|)
  106. \fIsin\fR\^(\|)!\fIcsin\fR\^(\|)!\fIsin\fR\^(\|)
  107. \fItan\fR\^(\|)!\fIctan\fR\^(\|)!\fItan\fR\^(\|)
  108. \fIcosh\fR\^(\|)!\fIccosh\fR\^(\|)!\fIcosh\fR\^(\|)
  109. \fIsinh\fR\^(\|)!\fIcsinh\fR\^(\|)!\fIsinh\fR\^(\|)
  110. \fItanh\fR\^(\|)!\fIctanh\fR\^(\|)!\fItanh\fR\^(\|)
  111. \fIexp\fR\^(\|)!\fIcexp\fR\^(\|)!\fIexp\fR\^(\|)
  112. \fIlog\fR\^(\|)!\fIclog\fR\^(\|)!\fIlog\fR\^(\|)
  113. \fIpow\fR\^(\|)!\fIcpow\fR\^(\|)!\fIpow\fR\^(\|)
  114. \fIsqrt\fR\^(\|)!\fIcsqrt\fR\^(\|)!\fIsqrt\fR\^(\|)
  115. \fIfabs\fR\^(\|)!\fIcabs\fR\^(\|)!\fIfabs\fR\^(\|)
  116. .TE
  117. .P
  118. If at least one argument for a generic parameter is complex, then use
  119. of the macro invokes a complex function; otherwise, use of the macro
  120. invokes a real function.
  121. .P
  122. For each unsuffixed function in the
  123. .IR <math.h>
  124. header without a
  125. .IR c -prefixed
  126. counterpart in the
  127. .IR <complex.h>
  128. header, except for
  129. \fImodf\fR(),
  130. \fIj0\fR(),
  131. \fIj1\fR(),
  132. \fIjn\fR(),
  133. \fIy0\fR(),
  134. \fIy1\fR(),
  135. and
  136. \fIyn\fR(),
  137. the corresponding type-generic macro has the same name as the function.
  138. These type-generic macros are:
  139. .sp
  140. .RS
  141. .TS
  142. tab(!);
  143. l l l l.
  144. T{
  145. .nf
  146. \fIatan2\fR()
  147. \fIcbrt\fR()
  148. \fIceil\fR()
  149. \fIcopysign\fR()
  150. \fIerf\fR()
  151. \fIerfc\fR()
  152. \fIexp2\fR()
  153. \fIexpm1\fR()
  154. \fIfdim\fR()
  155. \fIfloor\fR()
  156. T}!T{
  157. .nf
  158. \fIfma\fR()
  159. \fIfmax\fR()
  160. \fIfmin\fR()
  161. \fIfmod\fR()
  162. \fIfrexp\fR()
  163. \fIhypot\fR()
  164. \fIilogb\fR()
  165. \fIldexp\fR()
  166. \fIlgamma\fR()
  167. \fIllrint\fR()
  168. T}!T{
  169. .nf
  170. \fIllround\fR()
  171. \fIlog10\fR()
  172. \fIlog1p\fR()
  173. \fIlog2\fR()
  174. \fIlogb\fR()
  175. \fIlrint\fR()
  176. \fIlround\fR()
  177. \fInearbyint\fR()
  178. \fInextafter\fR()
  179. \fInexttoward\fR()
  180. T}!T{
  181. .nf
  182. \fIremainder\fR()
  183. \fIremquo\fR()
  184. \fIrint\fR()
  185. \fIround\fR()
  186. \fIscalbln\fR()
  187. \fIscalbn\fR()
  188. \fItgamma\fR()
  189. \fItrunc\fR()
  190. .fi
  191. T}
  192. .TE
  193. .RE
  194. .P
  195. If all arguments for generic parameters are real, then use of the macro
  196. invokes a real function; otherwise, use of the macro results in
  197. undefined behavior.
  198. .P
  199. For each unsuffixed function in the
  200. .IR <complex.h>
  201. header that is not a
  202. .IR c -prefixed
  203. counterpart to a function in the
  204. .IR <math.h>
  205. header, the corresponding type-generic macro has the same name as the
  206. function. These type-generic macros are:
  207. .sp
  208. .RS
  209. \fIcarg\fR()
  210. \fIcimag\fR()
  211. \fIconj\fR()
  212. \fIcproj\fR()
  213. \fIcreal\fR()
  214. .RE
  215. .P
  216. Use of the macro with any real or complex argument invokes a complex
  217. function.
  218. .LP
  219. .IR "The following sections are informative."
  220. .SH "APPLICATION USAGE"
  221. With the declarations:
  222. .sp
  223. .RS 4
  224. .nf
  225. #include <tgmath.h>
  226. int n;
  227. float f;
  228. double d;
  229. long double ld;
  230. float complex fc;
  231. double complex dc;
  232. long double complex ldc;
  233. .fi
  234. .P
  235. .RE
  236. .P
  237. functions invoked by use of type-generic macros are shown in the
  238. following table:
  239. .TS
  240. center box tab(!);
  241. cB | cB
  242. l | l.
  243. Macro!Use Invokes
  244. _
  245. \fIexp\fR(\fIn\fR)!\fIexp\fR(\fIn\fR), the function
  246. \fIacosh\fR(\fIf\fR)!\fIacoshf\fR(\fIf\fR)
  247. \fIsin\fR(\fId\fR)!\fIsin\fR(\fId\fR), the function
  248. \fIatan\fR(\fIld\fR)!\fIatanl\fR(\fIld\fR)
  249. \fIlog\fR(\fIfc\fR)!\fIclogf\fR(\fIfc\fR)
  250. \fIsqrt\fR(\fIdc\fR)!\fIcsqrt\fR(\fIdc\fR)
  251. \fIpow\fR(\fIldc,f\fR)!\fIcpowl\fR(\fIldc, f\fR)
  252. \fIremainder\fR(\fIn,n\fR)!\fIremainder\fR(\fIn, n\fR), the function
  253. \fInextafter\fR(\fId,f\fR)!\fInextafter\fR(\fId, f\fR), the function
  254. \fInexttoward\fR(\fIf,ld\fR)!\fInexttowardf\fR(\fIf, ld\fR)
  255. \fIcopysign\fR(\fIn,ld\fR)!\fIcopysignl\fR(\fIn, ld\fR)
  256. \fIceil\fR(\fIfc\fR)!Undefined behavior
  257. \fIrint\fR(\fIdc\fR)!Undefined behavior
  258. \fIfmax\fR(\fIldc,ld\fR)!Undefined behavior
  259. \fIcarg\fR(\fIn\fR)!\fIcarg\fR(\fIn\fR), the function
  260. \fIcproj\fR(\fIf\fR)!\fIcprojf\fR(\fIf\fR)
  261. \fIcreal\fR(\fId\fR)!\fIcreal\fR(\fId\fR), the function
  262. \fIcimag\fR(\fIld\fR)!\fIcimagl\fR(\fIld\fR)
  263. \fIcabs\fR(\fIfc\fR)!\fIcabsf\fR(\fIfc\fR)
  264. \fIcarg\fR(\fIdc\fR)!\fIcarg\fR(\fIdc\fR), the function
  265. \fIcproj\fR(\fIldc\fR)!\fIcprojl\fR(\fIldc\fR)
  266. .TE
  267. .SH RATIONALE
  268. Type-generic macros allow calling a function whose type is determined
  269. by the argument type, as is the case for C operators such as
  270. .BR '+'
  271. and
  272. .BR '*' .
  273. For example, with a type-generic
  274. \fIcos\fR()
  275. macro, the expression
  276. .IR cos ((\c
  277. .BR float )\c
  278. .IR x )
  279. will have type
  280. .BR float .
  281. This feature enables writing more portably efficient code and
  282. alleviates need for awkward casting and suffixing in the process of
  283. porting or adjusting precision. Generic math functions are a widely
  284. appreciated feature of Fortran.
  285. .P
  286. The only arguments that affect the type resolution are the arguments
  287. corresponding to the parameters that have type
  288. .BR double
  289. in the synopsis. Hence the type of a type-generic call to
  290. \fInexttoward\fR(),
  291. whose second parameter is
  292. .BR "long double"
  293. in the synopsis, is determined solely by the type of the first
  294. argument.
  295. .P
  296. The term ``type-generic'' was chosen over the proposed alternatives of
  297. intrinsic and overloading. The term is more specific than intrinsic,
  298. which already is widely used with a more general meaning, and reflects
  299. a closer match to Fortran's generic functions than to C++ overloading.
  300. .P
  301. The macros are placed in their own header in order not to silently
  302. break old programs that include the
  303. .IR <math.h>
  304. header; for example, with:
  305. .sp
  306. .RS 4
  307. .nf
  308. printf ("%e", sin(x))
  309. .fi
  310. .P
  311. .RE
  312. .P
  313. .IR modf (\c
  314. .BR double ,
  315. .BR "double *" )
  316. is excluded because no way was seen to make it safe without
  317. complicating the type resolution.
  318. .P
  319. The implementation might, as an extension, endow appropriate ones of
  320. the macros that POSIX.1\(hy2008 specifies only for real arguments with the
  321. ability to invoke the complex functions.
  322. .P
  323. POSIX.1\(hy2008 does not prescribe any particular implementation mechanism
  324. for generic macros. It could be implemented simply with built-in
  325. macros. The generic macro for
  326. \fIsqrt\fR(),
  327. for example, could be implemented with:
  328. .sp
  329. .RS 4
  330. .nf
  331. #undef sqrt
  332. #define sqrt(x) __BUILTIN_GENERIC_sqrt(x)
  333. .fi
  334. .P
  335. .RE
  336. .P
  337. Generic macros are designed for a useful level of consistency with C++
  338. overloaded math functions.
  339. .P
  340. The great majority of existing C programs are expected to be unaffected
  341. when the
  342. .IR <tgmath.h>
  343. header is included instead of the
  344. .IR <math.h>
  345. or
  346. .IR <complex.h>
  347. headers. Generic macros are similar to the ISO/IEC\ 9899:\|1999 standard library masking
  348. macros, though the semantic types of return values differ.
  349. .P
  350. The ability to overload on integer as well as floating types would have
  351. been useful for some functions; for example,
  352. \fIcopysign\fR().
  353. Overloading with different numbers of arguments would have allowed
  354. reusing names; for example,
  355. \fIremainder\fR()
  356. for
  357. \fIremquo\fR().
  358. However, these facilities would have complicated the specification; and
  359. their natural consistent use, such as for a floating
  360. \fIabs\fR()
  361. or a two-argument
  362. \fIatan\fR(),
  363. would have introduced further inconsistencies with the ISO/IEC\ 9899:\|1999 standard for
  364. insufficient benefit.
  365. .P
  366. The ISO\ C standard in no way limits the implementation's options for efficiency,
  367. including inlining library functions.
  368. .SH "FUTURE DIRECTIONS"
  369. None.
  370. .SH "SEE ALSO"
  371. .IR "\fB<math.h>\fP",
  372. .IR "\fB<complex.h>\fP"
  373. .P
  374. The System Interfaces volume of POSIX.1\(hy2017,
  375. .IR "\fIcabs\fR\^(\|)",
  376. .IR "\fIfabs\fR\^(\|)",
  377. .IR "\fImodf\fR\^(\|)"
  378. .\"
  379. .SH COPYRIGHT
  380. Portions of this text are reprinted and reproduced in electronic form
  381. from IEEE Std 1003.1-2017, Standard for Information Technology
  382. -- Portable Operating System Interface (POSIX), The Open Group Base
  383. Specifications Issue 7, 2018 Edition,
  384. Copyright (C) 2018 by the Institute of
  385. Electrical and Electronics Engineers, Inc and The Open Group.
  386. In the event of any discrepancy between this version and the original IEEE and
  387. The Open Group Standard, the original IEEE and The Open Group Standard
  388. is the referee document. The original Standard can be obtained online at
  389. http://www.opengroup.org/unix/online.html .
  390. .PP
  391. Any typographical or formatting errors that appear
  392. in this page are most likely
  393. to have been introduced during the conversion of the source files to
  394. man page format. To report such errors, see
  395. https://www.kernel.org/doc/man-pages/reporting_bugs.html .