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 <fenv.h> 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.

    <install-directory>/SUNWspro/READMEs/runtime.libraries
    In a default install of Sun WorkShop, <install-directory> 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.