Previous Next Contents Index Doc Set Home


Math Libraries

10

This chapter describes how to use the libm and libsunmath functions in Pascal programs. The math libraries are always accessible from a Pascal program because the Pascal compiler driver pc calls ld, the linker and loader, with the -lsunmath -lm options. If you compile Pascal program with the -v option, it prints the command-line used to call each of the compilation passes.

For convenience, Pascal supports special Pascal header files, math_p.h and sunmath_p.h, which contain prototypes of math functions, procedures, and some useful constants. The math_p.h file refers to sunmath_p.h by an #include directive.

This chapter contains the following sections:

Contents of the Math Libraries

page 226

libm Functions

page 227

IEEE Support Functions

page 228

SPARC Libraries

page 230

Arithmetic Exceptions

page 231

Math Library Exception-Handling Function: matherr()

page 232

libsunmath Support for IEEE Modes and Exceptions

page 234

Contents of the Math Libraries

Altogether, there are three math libraries:

Table 10-1 lists the contents of the math libraries.

Table  10-1 Contents of Math Libraries  

Algebraic functions

Rootsm+

Euclidean distancem+, s

Transcendental functions

Elementary transcendental functions

Trigonometric functions

Trigonometric functions of radian argumentsm+

Trigonometric functions of degree arguments s

Trigonometric functions (scaled in Pi)s

Trigonometric functions (with double precision Pi) s

Hyperbolic functionsm+

Exponential, logarithm, powerm+, s

Financial functionss

Higher transcendental functions

Besselm+

Gammam+

Error functionm+

Integral rounding functionsm+, s

Random number generators

Additive pseudo-random generatorss

Linear pseudo-random generatorss

Random number shufflerss

IEEE support functions

IEEE functionsm+

IEEE testm+

IEEE valuess

IEEE suns

Control flagss

Floating-point trap handling

IEEE handlings

Handling for specific SIGFPE codes (in libc)

Error handling functionm

Data conversions

BSD miscellaneouss

Base conversion routines (in libc)

FORTRAN intrinsic functionss

Legend:

m Functions available in bundled libm

m+ Functions available in bundled libm and as single-precision version only in libsunmath

s Functions available in unbundled libm (libsunmath)

libm Functions

Most numerical functions are available in double- and single-precision version. In general, the names of the single-precision version are formed by adding f to the names of the double-precision version.

The following Pascal program is an example of how to use math functions.







program TestLibm(output);





#include <math_p.h>









var

  d0,d1,d2: double;

  f0,f1,f2: single;









begin

  d0 := 0.0; d1 := 1.0; d2 := 2.0;

  f0 := 0.0; f1 := 1.0; f2 := 2.0;









  writeln('Trigonometric functions');









  writeln(sin(d0));

  writeln(sinf(f0));









  sincos(M_PI_2, d1, d2);

  writeln(d1, d2);

  sincosf(M_PI_2, f1, f2);

  writeln(f1, f2);









  writeln('Exponential, logarithm, power');









  writeln(exp(d1));

  writeln(log(d1));

  writeln(pow(d1, d1));





  writeln(expf(f1));

  writeln(logf(f1));

  writeln(powf(f1, f1));

end.







 














 IEEE Support Functions




This section describes the IEEE support functions, including ieee_functions(), ieee_values(), and ieeee_retrospective().




 ieee_functions()




The functions described in ieee_functions(3M) provide capabilities either required by the IEEE standard or recommended in its appendix.  Example:










program TestIEEEFunctions(output);









#include "math_p.h"









var





  d1: double := 1.0;

  d2: double := 2.0;

  i1: integer := 1;









begin





  writeln('IEEE functions');









  writeln(ilogb(d1));

  writeln(isnan(d1));

  writeln(copysign(d1, d2));

  writeln(fabs(d1));

  writeln(fmod(d1, d1));

  writeln(nextafter(d1, d1));

  writeln(remainder(d1, d1));

  writeln(scalbn(d1, i1));

end.







 












 ieee_values()




IEEE values, such as infinity, NaN, minimum and maximum positive floating-point numbers, are provided by special functions described in the ieee_values(3M) man page.  Another example follows.










program TestIEEEValues(output);









#include "math_p.h"









var





  l0: integer32 := 0;





begin





  writeln('IEEE values');









  writeln(infinity);





  writeln(signaling_nan(l0));





  writeln(quiet_nan(l0));





  writeln(max_normal);





  writeln(max_subnormal);





  writeln(min_normal);





  writeln(min_subnormal);





end.







 












 ieee_retrospective()




The libm function ieee_retrospective() prints to stderr information about unrequited exceptions and nonstandard IEEE modes.  Pascal programs call ieee_retrospective() on exit by default.






 SPARC Libraries




The libm and libsunmath libraries also contain:




There are two facilities for generating uniform pseudo-random numbers, addrans(3M) and lcrans(3M).  addrans is an additive random number generator; lcrans is a linear congruential random number generator.  In addition, shufrans(3M) shuffles a set of pseudo-random numbers to provide even more randomness for applications that need it.










program TestRandom(output);









#include "math_p.h"









var

  n: integer := 100;

  i: integer;

  ilb,          { Lower bound }

  iub: integer; { Upper bound }

  ia: array [1..100] of integer;









begin

  writeln('Integer linear congruential random number generator');

  ilb := I_LCRAN_LB;

  iub := I_LCRAN_UB;

  i_lcrans_(ia, n, ilb, iub);

  for i := 1 to n do

    writeln(ia[i]);









  writeln('Integer additive random number generator');

  ilb := minint;

  iub := maxint;

  i_addrans_(ia, n, ilb, iub);

  for i := 1 to n do

    writeln(ia[i]);









  writeln('Integer random number shufflers');

  i_shufrans_(ia, n, ilb, iub);

  for i := 1 to n do

    writeln(ia[i]);

end.







 














 Arithmetic Exceptions




An arithmetic exception arises when an attempted atomic arithmetic operation does not produce an acceptable result.  The meaning of the terms "atomic" and "acceptable" may vary, depending on the context.



Following are the five types of IEEE floating-point exceptions:







 Math Library Exception-Handling Function: matherr()




Some libm functions are specified to call matherr()when an exception is detected.  You can redefine matherr() by including a function named matherr() in the program.  When an exception occurs, a pointer to the exception structure, exc, is passed to the user-supplied matherr() function.  This structure, defined in the math_p.h header file, is as follows:










type





  exception = record

    kind: integer;

    name: ^string;

    arg1: double;

    arg2: double;

    retval: double;

  end;







 











The element kind is an integer constant that describes the type of exception that occurred, and is one of the following constants.  These constants are defined in the header file.










DOMAIN




Argument domain exception





SING




Argument singularity





OVERFLOW




Overflow range exception





UNDERFLOW




Underflow range exception





TLOSS




Total loss of significance





PLOSS




Partial loss of significance





 











If your matherr() function returns a non-zero result, no exception message is printed, and errno is not set.










program TestMatherr(output);









#include <math_p.h>









function matherr(var info: exception): integer;

begin

  case info.kind of

    DOMAIN: begin

      { change sqrt to return sqrt(-arg1), not NaN }





      if substr(info.name^, 1, length('sqrt')) = 'sqrt' then begin

        info.retval := sqrt(-info.arg1);

        matherr := 1; { No exception message will be printed }

      end;

    end;

    otherwise





      matherr := 0;

  end;

end;









begin

  writeln('Error handling function');

  writeln('sqrt(-1)= ', sqrt(-1));

end.







 














 libsunmath Support for IEEE Modes and Exceptions




ieee_handler() is used primarily to establish a signal handler for a particular floating-point exception or group of exceptions.



The syntax of this function is described in the ieee_handler(3M) man page.



This following Pascal program demonstrates how to abort on division by zero.










program TestIEEEHandler(output);









#include <math_p.h>









procedure DivisionHandler(

  sig: integer;

  sip: univ_ptr;

  uap: univ_ptr);

begin





  writeln('Bad data - division by zero.');

end; { DivisionHandler }









var

  FpAction, FpException: string;

  Zero: integer := 0;









begin

  FpAction := 'set';

  FpException := 'division';









  writeln(ieee_handler(FpAction, FpException,

    addr(DivisionHandler)));

  writeln('1/0 = ', 1 / Zero);









  writeln(ieee_handler(FpAction, FpException, SIGFPE_DEFAULT));

  writeln('1/0 = ', 1 / Zero);





end.







 











ieee_flags() is the recommended interface to:




The syntax of this function is described in the ieee_flags(3M) man page.



If an exception is raised at any time during program execution, then its flag is set, unless it is explicitly cleared.  Clearing accrued exceptions is done by a call, as shown in the following Pascal program.










program TestIEEEFlags(output);









#include "math_p.h"









var





  FlAction, FlMode, FlIn: string;

  FlOut: string_pointer;

  Zero: integer := 0;









begin





  writeln(sqr(-1));     { Invalid operation }

  writeln(1 / Zero);    { Division by zero }

  writeln(exp(709.8));  { Overflow }

  writeln(exp(-708.5)); { Underflow }

  writeln(log(1.1));    { Inexact }









  FlAction := 'clear';

  FlMode := 'exception';

  FlIn := 'all';

  writeln(ieee_flags(FlAction, FlMode, FlIn, FlOut));





end.







 













 



Previous


Next

Contents

Index

Doc Set

Home