November 1998 Sun WorkShop 5.0 README: Sun WorkShop(TM) Floating-point and Mathematical Libraries __________________________________________________________________________ WorkShop Compiler 5.0 includes floating-point arithmetic support and mathematical subroutine libraries for the Solaris(TM) 2.5.1, 2.6, and Solaris 7 operating environments. __________________________________________________________________________ Contents: A. New and Changed Features B. Compatibility C. Documentation A. New and Changed Features o 64 bit math libraries (SPARC only) With the exception of libcx (see below) and the profiling libraries, all of the math libraries provided with WorkShop Compilers are now available in versions that can be used with programs compiled for the 64 bit Solaris operating system. Unless otherwise noted, you do not need to specify any additional options to link with these versions of the libraries; the compilers will automatically select the correct set of libraries based on the -xarch option specified on the link line. o Single precision vector functions and the -xvector compiler flag (SPARC only) libmvec.a and libmvec_mt.a now contain single precision counter- parts to the double precision vector elementary functions present in previous releases: Double precision Single precision vatan_ vatanf_ vatan2_ vatan2f_ vcos_ vcosf_ vexp_ vexpf_ vhypot_ vhypotf_ vlog_ vlogf_ vpow_ vpowf_ vsin_ vsinf_ vsincos_ vsincosf_ vz_abs_ vc_abs_ vz_exp_ vc_exp_ vz_log_ vc_log_ vz_pow_ vc_pow_ In some cases, the compiler can automatically recognize situations when the vector functions may be used to potentially improve per- formance. This optimization is controlled by the -xvector flag. See the compiler manuals and the libmvec(3M) and clibmvec(3M) man pages for more information. o C9X Floating Point Environment functions and extensions libm9x.so implements the Floating Point Environment features specified by the C9X draft standard. The library also includes extensions to those features that provide improved sup- port for floating-point exception handling. See the Numerical Computation Guide and the man pages listed below for further information. libm9x.so is provided as a shared object only. There is no libm9x.a. To use libm9x.so with programs linked with cc, you must enable both the static linker and the runtime linker to locate the lib- rary. To enable the static linker to locate libm9x.so, you can do one of the following when linking: - specify -L/opt/SUNWspro/lib before -lm9x on the command line, - specify the full path name /opt/SUNWspro/lib/libm9x.so on the command line, or - add /opt/SUNWspro/lib to the list of directories specified by the environment variable LD_LIBRARY_PATH To enable the runtime linker to locate libm9x.so, you can do one of the following: - specify -R/opt/SUNWspro/lib when linking, or - add /opt/SUNWspro/lib to the list of directories specified by either of the environment variables LD_LIBRARY_PATH or LD_RUN_PATH. To use libm9x.so with programs compiled for the 64 bit Solaris operating system, replace /opt/SUNWspro/lib with /opt/SUNWspro/ lib/sparcv9 in the preceding instructions. If you have installed the compilers in a location other than the default, replace /opt/SUNWspro with the name of the installation directory in the preceding instructions. Note: Adding /opt/SUNWspro/lib to the environment variable LD_LIBRARY_PATH can cause a program linked with the Sun Perform- ance Library (libsunperf.so or libsunperf_mt.so) to use a diff- erent version of that library than the one best suited for the system on which the program is run. To use both libm9x.so and the Sun Performance Library with programs linked with cc, do not add /opt/SUNWspro/lib to LD_LIBRARY_PATH. Instead, just specify -xlic_lib=sunperf before -lm9x on the command line. The CC, f77, f90, and pc compilers provide all the necessary options to enable both the static linker and the runtime linker to locate libm9x.so. To use libm9x.so with programs linked with any of these compilers, just specify -lm9x on the command line. o Architecture-specific quadruple precision support routines (SPARC only) libcx.a and libcx.so.1 provide alternate versions of the quadruple precision floating-point support routines found in the standard library libc. These routines are several times faster than those provided by libc in Solaris releases prior to 2.7* and can yield significant performance improvements in programs that use quadruple precision (i.e., long double in C or REAL*16 in Fortran). In SC5.0, libcx.a and libcx.so.1 have been split into separate libraries for each architecture (specified by the -xarch= compiler flag). For best performance, be sure that you use the appropriate -xarch= value for your system when linking. Also, if you use the LD_PRELOAD environment variable to preload libcx.so.1 for programs that have previously been linked with libc, be sure that you include the appropriate architecture-specific library directory in the path name. Example: Assuming you have installed the SC5.0 compilers under /opt/SUNWspro, to preload libcx.so.1 for an UltraSPARC system: csh: setenv LD_PRELOAD /opt/SUNWspro/lib/v8plus/libcx.so.1 sh: set LD_PRELOAD=/opt/SUNWspro/lib/v8plus/libcx.so.1 export LD_PRELOAD *In the Solaris 2.7 operating environment, these faster quadruple precision floating-point support routines are provided in the bundled libc. For this reason, SC5.0 does not provide a 64-bit version of libcx. o Multiply-with-carry random number generators libsunmath contains a new family of pseudo-random number genera- tors based on the multiply-with-carry algorithm due to Marsaglia. These functions use two 32 bit generators each with a period of about 2**50 to provide uniformly distributed sequences of signed and unsigned integers, long integers, and long long integers as well as single and double precision floating point numbers. See the mwcrans(3M) man page for more information. B. Compatibility o Numerical differences between libraries In 5.0, more of the vector math functions have been hand coded in assembly for UltraSPARC systems. (These functions are available in the v8plusa architecture-specific libmvec.a library.) The new implementations use different approximations than the C versions used in 4.2 and thus may deliver results that differ in the least significant bit from those produced by the previous version of the library. For most programs, this difference should not be notice- able. o ieee_handler return value In order to accommodate the LP64 data model used in the 64 bit Solaris operating system, the return value of the ieee_handler function has been changed from type int to long int. (Recall that ieee_handler actually returns a pointer when the requested action is "get".) C. Documentation o Changes to the Numerical Computation Guide in 5.0 Chapter 3 reflects the changes noted above to libcx and libmvec and includes new material describing libm9x.so and the multiply- with-carry random number generators. Chapter 4 has been expanded to include additional information about the floating-point exception handling features available in libm9x.so. Further examples of the use of these features have been added to Appendix A. An addendum discussing differences among current implementations of IEEE 754 arithmetic has been added to Appendix D, "What Every Computer Scientist Should Know About Floating-Point Arithmetic". o New manual pages The features available in libm9x.so are described in the following man pages: feclearexcept(3M), fegetenv(3M), fesetprec(3M), feset- round(3M), fex_set_handling(3M), fex_set_log(3M). The mwcrans(3M) man page describes the multiply-with-carry random number generators. Last Changed 12/22/98