Sun WorkShop(TM) 6 Math Libraries README Updated 2000/04/04 This document contains last minute information about the Sun WorkShop 6 Math Libraries. It describes the software corrections addressed by this release and lists the known problems, limitations, and incompatibilities. To view the text version of this document, type the following at a command prompt: example% more /opt/SUNWspro/READMEs/math_libraries To access the HTML version of this document, point your Netscape(TM) Communicator 4 or compatible browser to: file:/opt/SUNWspro/docs/index.html Note: If your Sun WorkShop software is not installed in the standard /opt directory, ask your system administrator for the equivalent path on your system. For more information about this product, see: * Sun WorkShop 6 Release Notes -- Describes installation-related and late-breaking information about this Sun WorkShop 6 release. Information in the release notes overrides information in all readme files. * About Sun WorkShop 6 Documentation -- Describes the documentation available with this Sun WorkShop release and how to access it. * What's New in Sun WorkShop 6 -- Describes the new features in this release. * Man pages for the math libraries, which appear in man pages section 3M (man -s 3M function_name ) These documents are accessible in HTML by pointing your browser to file:/opt/SUNWspro/docs/index.html. If your Sun WorkShop software is not installed in the /opt directory, ask your system administrator for the equivalent path on your system. ------------------------------------------------------------------------ Contents * Introduction * Features * Software Corrections * Problems and Workarounds * Limitations and Incompatibilities * Documentation * Shippable Libraries ------------------------------------------------------------------------ Introduction Sun WorkShop 6 compilers include floating-point arithmetic support and mathematical subroutine libraries for SPARC(TM) processors running Solaris(TM) Operating Environment SPARC Platform Edition versions 2.6, Solaris 7, or Solaris 8 and Intel(R) x86 processors running Solaris Operating Environment Intel Platform Edition, versions 2.6, Solaris 7, or Solaris 8. ------------------------------------------------------------------------ Features The Sun WorkShop 6 Math Libraries contain the following features: 64-Bit Math Libraries (SPARC only) With the exception of libcx and the profiling libraries, all of the math libraries provided with Sun WorkShop Compilers are available in versions that can be used with programs compiled for the 64-bit Solaris operating environments. 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. Single Precision Vector Functions and the -xvector Compiler Flag (SPARC Only) libmvec.a and libmvec_mt.a contain single precision counterparts 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 performance. This optimization is controlled by the -xvector flag. See the compiler manuals and the libmvec(3M) and clibmvec(3M) man pages for more information. C99 Floating Point Environment Functions and Extensions libm9x.so implements the Floating Point Environment features specified by the C99 standard. The library also includes extensions to those features that provide improved support for floating-point exception handling. See the Numerical Computation Guide 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 library. 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. * 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: * When linking, either specify -R/opt/SUNWspro/lib or include /opt/SUNWspro/lib in the list of directories specified by the environment variable LD_RUN_PATH. * At runtime, include /opt/SUNWspro/lib in the list of directories specified by the environment variable LD_LIBRARY_PATH. To use libm9x.so with programs compiled for a 64-bit Solaris operating environment, 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 Performance Library (libsunperf.so or libsunperf_mt.so) to use a different 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, and f95 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. Multiply-With-Carry Random Number Generators libsunmath contains a new family of pseudo-random number generators 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. ------------------------------------------------------------------------ Software Corrections There is no new information at this time. ------------------------------------------------------------------------ Problems and Workarounds The following software bugs could not be fixed in time for this release. (Check Hot News for Sun WorkShop 6 (http://www.sun.com/workshop/users/ws.html) for updated information): Undefined Symbols When Linking With -lmvec_mt Attempting to link with the parallel vector math library libmvec_mt.a (using -xparallel -lmvec_mt) produces an error message similar to the following: Undefined first referenced symbol in file __mt_inepc_ /opt/SUNWspro/WS6/lib/libmvec_mt.a(vatan2_.o) __mt_inapc_ /opt/SUNWspro/WS6/lib/libmvec_mt.a(vatan2_.o) ld: fatal: Symbol referencing errors. No output written to a.out This error does not occur when linking with the serial library libmvec.a. ------------------------------------------------------------------------ Limitations and Incompatibilities This section discusses the following incompatibilities between Sun WorkShop 6 Math Libraries and previous releases. Numerical Differences Between Libraries In the Sun WorkShop 6 release, new optimized versions of several math functions have been added to libmopt.a and some of the existing scalar and vector functions in libmopt.a and libmvec.a have been changed to provide better performance. Some of these functions may occasionally give slightly different results (usually differing only in the least significant bit) from those delivered by previous releases of the math libraries. For most programs, these differences should not be noticeable. ieee_handler return value In order to accommodate the LP64 data model used in 64-bit Solaris operating environments, 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".) ------------------------------------------------------------------------ Documentation Errata There is no new information at this time. ------------------------------------------------------------------------ Shippable Libraries If your executable uses a Sun dynamic library listed in the file named below, your license includes the right to redistribute the library to your customer. /SUNWspro/READMEs/runtime.libraries In a default install of Sun WorkShop, will be /opt You may not redistribute or otherwise disclose the header files, source code, object modules, or static libraries of object modules in any form. The License to Use appears in the End User Object Code License, viewable from the back of the plastic case containing the CD-ROM. ------------------------------------------------------------------------ Copyright 2000 Sun Microsystems, Inc., 901 San Antonio Road, Palo Alto, CA 94303, U.S.A. All rights reserved. Sun, Sun Microsystems, the Sun logo, docs.sun.com, and Solaris are trademarks, registered trademarks, or service marks of Sun Microsystems, Inc. in the U.S. and other countries.