Unix/Linux Go Back    


Linux 2.6 - man page for tgmath.h (linux section 7posix)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


<tgmath.h>(P)			    POSIX Programmer's Manual			    <tgmath.h>(P)

NAME
       tgmath.h - type-generic macros

SYNOPSIS
       #include <tgmath.h>

DESCRIPTION
       The  <tgmath.h> header shall include the headers <math.h> and <complex.h> and shall define
       several type-generic macros.

       Of the functions contained within the <math.h> and <complex.h>  headers	without  an  f	(
       float) or l ( long double) suffix, several have one or more parameters whose corresponding
       real type is double. For each such function, except modf(), there shall be a corresponding
       type-generic  macro.   The parameters whose corresponding real type is double in the func-
       tion synopsis are generic parameters. Use of the macro invokes  a  function  whose  corre-
       sponding real type and type domain are determined by the arguments for the generic parame-
       ters.

       Use of the macro invokes a function whose generic parameters have the  corresponding  real
       type determined as follows:

	* First, if any argument for generic parameters has type long double, the type determined
	  is long double.

	* Otherwise, if any argument for generic parameters has type  double  or  is  of  integer
	  type, the type determined is double.

	* Otherwise, the type determined is float.

       For  each  unsuffixed function in the <math.h> header for which there is a function in the
       <complex.h> header with the same name except for  a  c  prefix,	the  corresponding  type-
       generic	macro  (for  both  functions)  has  the same name as the function in the <math.h>
       header. The corresponding type-generic macro for fabs() and cabs() is fabs().

				 <math.h>   <complex.h>   Type-Generic
				 Function   Function	  Macro
				 acos()     cacos()	  acos()
				 asin()     casin()	  asin()
				 atan()     catan()	  atan()
				 acosh()    cacosh()	  acosh()
				 asinh()    casinh()	  asinh()
				 atanh()    catanh()	  atanh()
				 cos()	    ccos()	  cos()
				 sin()	    csin()	  sin()
				 tan()	    ctan()	  tan()
				 cosh()     ccosh()	  cosh()
				 sinh()     csinh()	  sinh()
				 tanh()     ctanh()	  tanh()
				 exp()	    cexp()	  exp()
				 log()	    clog()	  log()
				 pow()	    cpow()	  pow()
				 sqrt()     csqrt()	  sqrt()
				 fabs()     cabs()	  fabs()

       If at least one argument for a generic parameter is complex, then use of the macro invokes
       a complex function; otherwise, use of the macro invokes a real function.

       For  each  unsuffixed  function in the <math.h> header without a c-prefixed counterpart in
       the <complex.h> header, the corresponding type-generic macro has  the  same  name  as  the
       function. These type-generic macros are:

	 atan2()	       fma()		     llround()		   remainder()
	 cbrt() 	       fmax()		     log10()		   remquo()
	 ceil() 	       fmin()		     log1p()		   rint()
	 copysign()	       fmod()		     log2()		   round()
	 erf()		       frexp()		     logb()		   scalbn()
	 erfc() 	       hypot()		     lrint()		   scalbln()
	 exp2() 	       ilogb()		     lround()		   tgamma()
	 expm1()	       ldexp()		     nearbyint()	   trunc()
	 fdim() 	       lgamma() 	     nextafter()
	 floor()	       llrint() 	     nexttoward()

       If  all	arguments  for	generic parameters are real, then use of the macro invokes a real
       function; otherwise, use of the macro results in undefined behavior.

       For each unsuffixed function in the <complex.h> header that is not a  c-prefixed  counter-
       part  to  a  function in the <math.h> header, the corresponding type-generic macro has the
       same name as the function.  These type-generic macros are:

	      carg()
	      cimag()
	      conj()
	      cproj()
	      creal()

       Use of the macro with any real or complex argument invokes a complex function.

       The following sections are informative.

APPLICATION USAGE
       With the declarations:

	      #include <tgmath.h>
	      int n;
	      float f;
	      double d;
	      long double ld;
	      float complex fc;
	      double complex dc;
	      long double complex ldc;

       functions invoked by use of type-generic macros are shown in the following table:

			    Macro	      Use Invokes
			    exp(n)	      exp(n), the function
			    acosh(f)	      acoshf(f)
			    sin(d)	      sin(d), the function
			    atan(ld)	      atanl(ld)
			    log(fc)	      clogf(fc)
			    sqrt(dc)	      csqrt(dc)
			    pow(ldc,f)	      cpowl(ldc, f)
			    remainder(n,n)    remainder(n, n), the function
			    nextafter(d,f)    nextafter(d, f), the function
			    nexttoward(f,ld)  nexttowardf(f, ld)
			    copysign(n,ld)    copysignl(n, ld)
			    ceil(fc)	      Undefined behavior
			    rint(dc)	      Undefined behavior
			    fmax(ldc,ld)      Undefined behavior
			    carg(n)	      carg(n), the function
			    cproj(f)	      cprojf(f)
			    creal(d)	      creal(d), the function
			    cimag(ld)	      cimagl(ld)
			    cabs(fc)	      cabsf(fc)

			    carg(dc)	      carg(dc), the function
			    cproj(ldc)	      cprojl(ldc)

RATIONALE
       Type-generic macros allow calling a function whose type	is  determined	by  the  argument
       type,  as  is  the  case  for  C operators such as '+' and '*' . For example, with a type-
       generic cos() macro, the expression cos(( float) x) will have type  float.   This  feature
       enables	writing  more portably efficient code and alleviates need for awkward casting and
       suffixing in the process of porting or adjusting precision. Generic math functions  are	a
       widely appreciated feature of Fortran.

       The  only arguments that affect the type resolution are the arguments corresponding to the
       parameters that have type double in the synopsis. Hence the type of a type-generic call to
       nexttoward(),  whose second parameter is long double in the synopsis, is determined solely
       by the type of the first argument.

       The term "type-generic" was chosen over the proposed alternatives of intrinsic  and  over-
       loading.  The  term  is	more specific than intrinsic, which already is widely used with a
       more general meaning, and reflects a closer match to Fortran's generic functions  than  to
       C++ overloading.

       The macros are placed in their own header in order not to silently break old programs that
       include the <math.h> header; for example, with:

	      printf ("%e", sin(x))

       modf( double, double *) is excluded because no way was seen to make it safe  without  com-
       plicating the type resolution.

       The  implementation  might,  as	an  extension,	endow appropriate ones of the macros that
       IEEE Std 1003.1-2001 specifies only for real arguments with the ability to invoke the com-
       plex functions.

       IEEE Std 1003.1-2001  does  not	prescribe  any	particular  implementation  mechanism for
       generic macros. It could be implemented simply with built-in macros. The generic macro for
       sqrt(), for example, could be implemented with:

	      #undef sqrt
	      #define sqrt(x) __BUILTIN_GENERIC_sqrt(x)

       Generic	macros	are  designed  for a useful level of consistency with C++ overloaded math
       functions.

       The great majority of  existing	C  programs  are  expected  to	be  unaffected	when  the
       <tgmath.h>  header  is  included  instead  of the <math.h> or <complex.h> headers. Generic
       macros are similar to the ISO/IEC 9899:1999 standard library masking  macros,  though  the
       semantic types of return values differ.

       The  ability  to  overload on integer as well as floating types would have been useful for
       some functions; for example, copysign().  Overloading with different numbers of	arguments
       would  have  allowed  reusing names; for example, remainder() for remquo(). However, these
       facilities would have complicated the specification; and  their	natural  consistent  use,
       such  as  for  a  floating  abs()  or a two-argument atan(), would have introduced further
       inconsistencies with the ISO/IEC 9899:1999 standard for insufficient benefit.

       The ISO C standard in no way limits the implementation's options for efficiency, including
       inlining library functions.

FUTURE DIRECTIONS
       None.

SEE ALSO
       <math.h>  ,  <complex.h>  ,  the System Interfaces volume of IEEE Std 1003.1-2001, cabs(),
       fabs(), modf()

COPYRIGHT
       Portions of this text are reprinted and	reproduced  in	electronic  form  from	IEEE  Std
       1003.1,	2003  Edition,	Standard  for Information Technology -- Portable Operating System
       Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003  by
       the  Institute  of  Electrical  and  Electronics Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE  and  The  Open  Group
       Standard, the original IEEE and The Open Group Standard is the referee document. The orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003				    <tgmath.h>(P)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 02:41 AM.