Release notes for Purify version 2003.06.00  HP-UX


Contents
========

  o Changes from previous releases

  o Supported systems

  o Restrictions and known issues

New in This Release
===================

  - Bug fixes and compatibility with OS patches.

  - New option -merge to merge the data from multiple Purify log 
    files.  For details and usage of the option, please look under 
    "Miscellaneous options" in the online documentation.

  - Support for shared libraries built with +init or +fini linker option.

  - Support for gcc/g++ 3.0.x and 3.1 compiler (32-bit only).

New in Purify 2002a.06.00
=========================

  - Bug fixes and compatibility with OS patches.

  - Modified Support for Change Request Management Systems,
    including Rational's ClearQuest and ClearDDTS. Please
    see the online help for more details.

  - Support for aCC 3.31 and 3.33 compiler

  - Support for ld/dld version 11.30

  - Support for dlopen, dlclose, dlsym calls in 32-bit applications.
    You can make calls to the above dynamic library routines, and
    Purify will make sure those libraries are instrumented as well
    for error checking.

  - Two new options -lib-path-length and -replace-path have been
    added to Purify. These options help one to relocate the cache.
    For information on the options and how to move the cache,
    please refer to the online documentation.

  - Purify_home has been re-organized so that
    32-bit and 64-bit components reside in the
    same directory. There is no longer a need to
    link 32 and 64 bit homes, or put them in your
    path.

    Please see the section "Restrictions and Known Issues"
    for more details.

New in Purify 2002.05.00
=========================

  - Bug fixes and compatibility with OS patches.

  - Support for gcc 2.95.2 and 2.95.3 compilers.

  - Support for aCC 3.27 and 3.30 compilers.

  - This release supports the LD_PRELOAD environment variable. This
    feature is available on HP-UX 11.00, AR0301(DART52) or later
    releases (ld and linker tools patch PHSS_22478). Please see the
    section "Restrictions and Known Issues" for known issues with
    LD_PRELOAD usage.

New in Purify 2001a.04.00
=========================

  - Bug fixes and compatibility with OS patches.

  - HTML-based online help system. See the "HTML Help" topic in the 
    Restrictions and Known Issues section.

  - New product versioning system. This release is the successor of:

       Purify 5.2 for HP-UX

  - This release supports HP-UX 11.11.

  - This release does not support HP-UX 10.01 and 10.10.
  
  - This release supports objdebug style debug information generated by 
    cc and aCC compilers. This feature is supported on HP-UX versions 
    11.00 and higher only. With the +objdebug option to the compiler, 
    extra debug information is placed into each object file to help the
    debugger locate the object file and to quickly find global types 
    and constants.


==================================================

Supported systems
=================

  Operating system and Hardware
  -----------------------------

    Purify has been tested with HP-UX versions 10.20, 11.00 and 11.11 
    from Hewlett Packard.

    Purify also supports 64-bit wide-mode programs on HPUX 11.00 and 11.11.
    A wide-mode program is one that uses 64-bit longs and pointers, built 
    with the compiler option "+DA2.0W" or "+DD64"

  Compilers
  ---------

    Purify has been tested with the following compilers:
    - Bundled cc.
    - ANSI cc.
    - C++.
    - aCC versions 3.27, 3.30, 3.31, and 3.33.
    - GNU gcc and g++ versions 2.8.1, 2.95.X, 3.0.x, 3.1 (32-bit only)
    - Cygnus GNUpro v.98r2

  Threads
  -------

    Purify supports these threads packages:
    - DCE threads (either libdce or libcma).
    - HP-UX kernel threads.

==================================================

Restrictions and Known Issues
=============================

  Java Language Support
  ---------------------
  - To use Purify with JNI applications using JDK 1.2.X, please
    refer to Solution ID 22506 on:
    http://solutions.rational.com/
    or contact Rational Technical Support and reference Solution ID 22506.

  Licensing Troubleshooting
  -------------------------
  - When Purify is properly installed, a .lm_license_file file is
    created in the product home directory to allow Purify to locate
    your licenses even when LM_LICENSE_FILE is not set appropriately
    in the user's environment. If you get a message such as:

      Error: Unable to open /product_home/.lm_license_file.
      Your installation is incomplete. Did you run rs_install? ...

    Check your product home directory to see if .lm_license_file exists
    and is readable by you. If the file does not exist, your installation
    is incomplete. You may need to re-run rs_install or license_setup.
    If the permissions are incorrect, change them so that the file is
    readable by all expected users of Purify.

  - If you manually change the location of your licenses (e.g. without
    using license_setup), the .lm_license_file will not be updated and
    you will not be able to checkout a license unless you set the env
    var LM_LICENSE_FILE to point to the new location. You should always
    use license_setup to make changes to your licenses.

  - Be sure you install the products that correspond to your license(s).
    Do not install PurifyPlus unless you have a PurifyPlus license or 
    another valid license. To check your license, locate the "INCREMENT" 
    line(s) in your license file (*.dat) or license update file (*.upd). 
    The license feature name is the first word on the line after "INCREMENT". 
    For example:

      INCREMENT PurifyPlusUNIX rational 5.0 10-jan-2001 1 1234556789012
                ^^^^^^^^^^^^^^

  HTML Help
  ---------
  This product has an HTML based online help that incorporates all the
  information from the product user manual.

  The following restrictions and notes apply to using the HTML help system:

  - The only supported browser for the HTML based help system is 
    Netscape Navigator, versions 4.7.x. The HTML based help system
    does not work with pre 4.7 versions or with 6.x versions.

  - You may view the help in stand-alone mode by pointing your browser to
    the following:

      product_home/UI/html/punix.htm

    (Where "product_home" is the installation location of Purify. e.g. the 
    result of the -printhomedir option.)

  - Netscape must be on your path when you run your instrumented program. 
    Your path is used to locate the browser.

  - The first time you request help from a viewer, a new netscape session 
    will be started, even if you already have netscape running. This session 
    will be re-used by subsequent help requests unless you re-use the 
    launched browser for another purpose.  If you close the browser, a new 
    browser will be launched upon the next help request.

  - The new help system uses Javascript. On some platforms, the MOZILLA_HOME
    environment variable must be set in order for Javascript based web pages
    to work properly. If you experience Java related problems with the help:

    Make sure your netscape installation directory is on your path and that
    MOZILLA_HOME is either not set at all (we will set it for you) or is set 
    to the same installation directory.

    If MOZILLA_HOME is set but does not point to the same netscape 
    installation as the netscape on your path, the help may not work 
    correctly.

    If MOZILLA_HOME is not set at all, Purify will attempt to set it when
    we start netscape. But we will be unable to set it correctly if the 
    netscape found on your path does not resolve to an actual installation 
    directory. For example, if netscape actually references a wrapper script 
    in /usr/local/bin. In this case, you will need to set MOZILLA_HOME 
    explicitly.

    See the Netscape release notes for more information on MOZILLA_HOME.

  - Use the Help->Help Topics menu item to access the top level of the
    help system. 

  - Context sensitive help is available on leaf menu items and on buttons
    ONLY. For information about a window, use the Help->On Window menu item.

  - PDF versions of the Purify Quick Reference card is available in the
    doc/pdf section of your installation, if you have installed PDF
    documentation. Otherwise, see the corresponding area of your
    installation CD.

  64-bit Development
  ------------------
  - Purify supports both 32-bit and 64-bit application development, and 
    will select the correct mode of operation automatically based on inputs. 
    The product banner will report the mode of operation during 
    instrumentation and at runtime. However, the "-version" option will 
    always report 32-bit mode; the product version is the same for both modes.

    The product home directory has been reorganized to support both 
    32 and 64-bit development. This organization should be transparent 
    for all 32-bit users and most 64-bit users. However, the location of 
    the Purify stubs library is different for 64-bit applications:

    32-bit libraries have been moved to the lib32 sub-directory:

       purifyhome/lib32/purify_stubs.a
       purifyhome/lib32/libpurify_stubs.a

    To preserve backward compatibility, the following links are provided 
    in purifyhome:

       purifyhome/purify_stubs.a
       purifyhome/libpurify_stubs.a

    32-bit API users are encouraged to use the libraries from the lib32 
    sub-directory, and not from purifyhome.

    64-bit API users must link against the equivalent library in the 
    lib64 sub-directory:

       purifyhome/lib64/purify_stubs.a
       purifyhome/lib64/libpurify_stubs.a

    The API header file has not moved and is shared for both development 
    modes.

  General
  -------
  - Purify sometimes does not display line numbers for error messages 
    accurately if the code is compiled with both debug and optimization 
    flags.

  - If Purify is run in "/tmp" or "/usr/tmp" or "/var/tmp" the generated 
    instrumented *.o files are deleted in these directories.  Please do 
    not use commands such as:
    purify cc -nolink ld file.o
    in "/tmp" or "/usr/tmp" or "/var/tmp" . 
    However there is a work-around for this , You can use the option 
    "-save-tmp-files" to tell Purify not to delete the generated objects. 
    So using:
      purify -save-tmp-files cc -nolink ld file.o
    will generate the instrumented file_pure_*.o in "/tmp" or "/usr/tmp" 
    or "/var/tmp". Otherwise you can use -always-use-cache-dir so that 
    the generated file_pure*.o is generated in cache-dir where it is not 
    deleted (Note: if cache-directory is installed in "/tmp","/usr/tmp",
    "/var/tmp" the generated *_pure_*.o in cache are not deleted, so you 
    can have the cache-directory safely in "/tmp","/usr/tmp","/var/tmp").

  - Archive libraries containing both 32-bit and 64-bit libraries are 
    not supported.  All components of a link must be of the same file type.

  - gcc/g++ 3.1 compilers are not supported on HP-UX 10.20 platform.

  - 64-bit applications produced by gcc/g++ 3.1 compilers are not 
    supported.

  - gcc/g++ 2.8.1 is supported, but there are known problems with
    C++ shared libraries containing exception handling code.

  - If you are running your application on a different machine from the one
    on which it was built, please ensure that both the machines have the 
    same operating system. Further, the system libraries on the two machines
    should be identical. Otherwise, Purify might generate a warning message.
    For more details on how to build and run on different machines, please 
    please see Solution ID 5829 at:

      http://eservice.rational.com/solutions

    Or contact Rational Technical Support and reference Solution ID 5829.

  - Using Purify with HP-UX linker version 11.13 or older may cause
    instrumented 32-bit applications to hang. An upgrade of linker
    should solve the problem.

  - Purify does not have SDK / XDK support, a feature available with
    the HPUX Compiler Tool chain from the AR1201 release.

  - Purify does not support filtered libraries.

  - Instrumented programs now always use immediate binding for the initial 
    load of shared libraries and for any dynamic loads using shl_load(). 

  - Purify will not run on short (14-character) file systems.

  - Operating system revisions earlier than HP-UX 10.20 are no longer 
    supported. 

  - The PA-RISC 1.0 CPU is no longer supported.

  - Profile Based Optimization is not supported.

  - Applications which link to over 50 large dynamic libraries may 
    experience reduced startup times by setting the runtime option
    -lazy-dld-maps=1.

  - Shared libraries are never unloaded. When a program attempts to
    unload a shared library through a call to shl_unload or dlclose,
    the call will appear to succeed, but the library will not actually
    be closed or unloaded. As a consequence, the "fini" sections
    (which usually comprise the C++ "static destructors") are not run
    for shared libraries.

  Using LD_PRELOAD
  ----------------
  - For 64-bit applications, use of environment variable LD_PRELOAD
    is supported only with instrumented shared libraries. If any of
    of the libraries in the LD_PRELOAD environment variable are not
    instrumented, the application may crash.

  - For 64-bit applications running on HP-UX 11.00 or later systems
    with a version of dld which does not support LD_PRELOAD, the
    instrumented application will give an error message and quit,
    if the environment variable LD_PRELOAD is set and contains any
    uninstrumented shared libraries. In this case, unsetting the
    environment variable LD_PRELOAD will cause the application to
    execute normally.

  - For 32-bit applications running on HP-UX 11.00 or later systems
    with a version of dld which does not support LD_PRELOAD, the
    instrumented application will check the environment variable
    LD_PRELOAD and instrument any uninstrumented libraries given in
    the LD_PRELOAD value. This instrumentation is harmless and does
    not affect the functionality of the program in anyway. To prevent
    this unnecessary instrumentation, users should unset the
    environment variable LD_PRELOAD before running the application.

  - Invoking the viewer with "purify -view" or "purify -version"
    when LD_PRELOAD is set may sometimes cause the viewer to crash.
    This can be overcome by unsetting LD_PRELOAD and then
    invoking Purify.

  - For 32-bit applications using LD_PRELOAD environment variable, a
    Zero Page Read error may appear in some of the cases when dld
    is unable to find a shared library specified in LD_PRELOAD. This
    error can be ignored. To prevent this error from occurring, users
    can verify that all the libraries used in LD_PRELOAD environment
    variable are accessible to the dynamic loader program. One simple
    way to ensure that the file is accessible is, to specify the absolute
    pathname of the shared library in the LD_PRELOAD value.

  Using 32-bit vs 64-bit Purify
  ------------------------------
  Purify supports both 32- and 64-bit development. "Wide" mode, or 64-bit
  applications are those compiled with the +DA2.0W option - applications
  using 64-bit pointers. "Narrow" mode applications are traditional 
  32-bit programs. Both are installed on the same file system, but the 
  64-bit version can only be used on 64-bit HP-UX 11.x systems.

  From version 2002a, the 32-bit and 64-bit products are in one install 
  directory, so there is no need to put both install directories in your path,
  or link install directories. Purify will auto-select the correct wide or 
  narrow mode version.

  If you attempt to use the 64-bit Purify using -ptr64 on a non 
  11.x systems, execution will fail. It only runs on HP-UX 11.x and later.

  - Restrictions on the HP-UX 11.00-wide
    (64-bit) version of Purify:

    - Static data checking is not supported.

    - Using Purify with old versions of the HP-UX linker may cause the 
      install test to fail with an error from the linker saying the 
      "+nodynhash" option is not recognized. You should obtain a newer 
      linker from HP. This option is support by 64-bit linkers from 
      07-Jan-1999 and later.

      You may also work around this problem by include the following in your
      PUREOPTIONS environment variable:

         -force-no-dynhash=no

      The default setting of this option (to "yes") is used to work around an
      HP bug in newer linkers.

    - There is a bug in strlen in the 64-bit libc which causes the example 
      program "hello.c" to get numerous UMR's instead of only one, as you 
      might expect.

    - The open-file summary does not include the file position for 64-bit 
      programs.

    - Errors involving large amounts of memory do not report properly. For 
      instance, an FMR when copying a 17MB freed memory block would report 
      as a 1MB FMR.

    - When you want to set a breakpoint on purify_stop_here using HP's wdb 
      (or gdb) debugger, use this command:

        b *purify_stop_here

      When you stop at purify_stop_here in the debugger, the debugger's stack
      trace will not be correct: You won't see the stack trace for your 
      program, only for Purify's runtime libraries.

      The easiest way to get around this is to set a temporary breakpoint at 
      the address which is in register r15 using this wdb command:

         tb *$r15

      Then, you can use the "continue" command to stop in your program at
      the instruction that caused the Purify error report.

  - When a Japanese locale is specified using the LANG environment variable, 
    instrumentation of archive libraries may fail with the message:

      Error: Child process exited with status = 1.

    This is caused by an 'ar' failure in this locale.  A workaround is to 
    unsetenv LANG before instrumenting.

  User Interface
  --------------

  - If a large number of items are selected, "Expand all" followed by 
    "Collapse all" can crash some unpatched versions of the OpenWindows 
    3.0 server.
    This occurs if you are displaying on a SUN workstation.

  - If you expand or collapse messages while the "Continue" or "Reset" 
    buttons are displayed, the buttons may subsequently be incorrectly 
    positioned.

  - The "Edit" and "Coverage" toolbar items may be slow to respond.

  - If EDITOR is set to vuepad (/usr/vue/bin/vuepad), the edit button will be
    unable to position the editor window to the correct line.  This is a 
    vuepad limitation.  The workaround is to use a more capable editor.

  - The Purify GUI menus and buttons become inaccessible if either the 
    NumLock or ScrollLock key is activated. The workaround is to switch 
    them off, or add the following line(s) to your $HOME/.Xdefaults file.
 
      ! Ignore the NumLock and ScrollLock keys on 
      ! mouse buttons
      Purify*ignoreModifierMask: Mod3|Mod2
 
    This second workaround will take effect for a new Purify viewer after 
    you restart your X-session or run a command like 'xrdb -merge 
    $HOME/.Xdefaults'.

  Compilers
  ---------

  - The GNU gcc extensions are not tested against Purify.  Most gcc 
    extensions will probably work fine.  Known limitations at present 
    include problems with nested functions (e.g.: making a pointer to a 
    nested function and attempting to call through it will not work).

  - C revisions 9.61 through 9.65

     - These compilers generate incorrect debugging information for some 
       functions.  Programs compiled using these compilers may not be 
       debuggable after translation.  In this case Purify may produce a 
       message beginning "Failure relocating..."
       HP patch PHSS_4923 corrects this problem.

  - Exception handling

    g++ 2.7.2 exceptions are not supported.


  -  Aggressive Loading

     - Some compilers load data from memory but ignore the data that has 
       been read.  Purify will signal a UMR if the loaded data is
       uninitialized.  In some sense this is a false error report because the
       uninitialized data can not affect your program.

  Purify'ing X Applications
  -------------------------

  - When running a Purify'd X application, there is a potential for 
    deadlock if your application causes Purify to generate a message while 
    the application is holding the X lock, typically allocated and released
    with the XGrabServer()/XUngrabServer() Xlib API's, since Purify will 
    be unable to generate the message and the application is blocked until 
    the message is delivered.

    To avoid this kind of problem, you should run your application on a 
    different X server than the Purify UI or Purify stderr output, or you
    should use the -log-file= or -view-file= options to specify a file to 
    capture messages for inspection after your application is finished.

    A convenient way to debug on two displays is to pre-start the Purify 
    Viewer on one display ("slave"), and then start the application on
    the other display ("master"):

      % purify -display slave:0 -view a.out.X &
      % a.out.X -display master:0

    The two commands must be executed on the same computer, but it could be 
    the workstation associated with either display, or altogether another 
    computer remote from both displays. The application will connect to the 
    already started Purify Viewer, and messages will not conflict with the 
    X display interactions of the application under test.

  Debuggers
  ---------

  -  XDB & Softdebug

     - Use purifyhome/purify_xdb to
       invoke xdb on an instrumented program.

     - An instrumented program receives a signal 18 (death of child) during 
       its initialization.  Place "z 18 sir" in your ~/.xdbrc file to 
       suppress this warning.  Failure to suppress the warning will sometimes 
       cause xdb to fail.

     - XDB, when debugging a program that uses shared libraries, reads 
       the symbol table from /lib/dld.sl.  However, Purify has changed 
       your program to use an instrumented version of dld.sl.  The
       symptom of this mismatch is the message:

         Wait...loading shared-library map tables.
         xdb panic: Mapped addresses for dld
          overlap text segment for dld

       There is a simple workaround for this problem and we've implemented 
       it in the
       shell script purifyhome/purify_xdb.
       Whenever you use xdb on an instrumented program use this script to 
       invoke xdb.

     - Typing ^C while running an instrumented program under xdb requires 
       caution. There is a high probability that the interrupt will occur 
       inside the code Purify has added to your application.  If this is 
       the case, you must single step or set a breakpoint and continue 
       before you attempt to call any subroutines (the Purify API is an 
       example).

     - The XDB single stepping command, 's' sometimes fails to find the 
       next source line.  When this happens, usually near a subroutine 
       call, program execution continues until the next breakpoint.  The
       'S' command is always reliable.

  - DDE - Distributed Debugging Environment

    - The DDE debugger at release 2.10 has been used with instrumented 
      programs.  The shell
      script: purifyhome/purify_dde
      implements one of the workarounds.

    - Instrumented programs get a SIGCHLD signal at program initialization.  
      One workaround is to just hit "go" when the program stops.  The 
      following commands added to a .dderc file also help:

         prop system -on
         alias `after_debug delete intercept signal SIGCHLD; \
           prop system -off; \
           breakpoint -in main -entry -exit; \
           go

  - Attaching to a running process

    JIT debugging may fail to attach to your application if the executable 
    resides on an NFS file system mounted without the "nointr" option.  The 
    HP Debugger reference manual says:

    "If you get a Permission denied error message when you attach to a 
     running process, it is likely that you are running either the debugger 
     or the target process over an NFS link and that the relevant file system
     is mounted with the default intr option.  You must mount the file 
     system with the nointr option to resolve this problem.  Use a command 
     like the following to mount the file system containing the debugger:

       mount -o nointr[,other_options] \
           system:/opt/langtools /tools

     Use a command like the following to mount the file system containing 
     the target process:

       mount -o nointr[,other_options] \
           system:/test_area /test

     It is probably easier to create an auxiliary mount for the file system 
     than to unmount and remount it."
 

  Old Style Fixups
  ----------------

  Purify does not support a type of relocation information known as "old 
  style fixups".  These were generated by HP-UX system software before 
  release 3.0.  If Purify detects old style fixups the message:

      Object file has incompatible format
    (may be older than HP-UX 3.0)

  is generated.  We have seen this problem with HP's libsql.a and some of 
  Oracle's Oracle6 libraries.

  There is a simple workaround. Given a problem object module (or modules) 
  the workaround is to have /bin/ld build a new object module.  Suppose
  the old object modules are called `foo.o' and `bar.o'.  Issuing the command:

       % ld -r -o new_foo.o foo.o
       % ld -r -o new_bar.o bar.o
  or
       % ld -r -o foo_and_bar.o foo.o bar.o

  would generate a new object module where the old style fixups have been 
  removed.

  In the case of an archive file the following script will create a new 
  archive given the full pathname of the original:

      #!/bin/sh
      # Remove old fixups from an archive.
      # Supply original .a name as first argument.
      cd /tmp
      lib=new_`basename $1`
      ar x $1
      rm -f $lib
      for member in `ar t $1` ; do
          ld -r -o _$member $member
          ar q $lib _$member
          rm $member _$member
      done
      echo Created `pwd`/$lib

  Threads
  -------

  - Call chains describing when memory was malloced or freed do not always 
    include the thread id.

  - The Purify API functions purify_map_pool() and purify_map_pool_id() are 
    not MT safe.

  - Customers using unsupported threads packages should contact Rational 
    Software technical support (support@rational.com) to ensure compatibility.

  Unsupported Features
  --------------------

  - SBR and SBW errors are not reported on HP-UX.

  Copyright Notice
  ----------------

  The following copyright applies to portions of the ClearQuest
  integration and HTML based help system. 

  Copyright 1996 Netscape Communications Corporation, all rights reserved.
  Created: Jamie Zawinski (jwz@netscape.com), 24-Dec-94.  Permission to
  use, copy, modify, distribute, and sell this software and its
  documentation for any purpose is hereby granted without fee, provided
  that the above copyright notice appear in all copies and that both 
  that copyright notice and this permission notice appear in supporting
  documentation.  No representations are made about the suitability of
  this software for any purpose. It is provided "as is" without express
  or implied warranty.