atom man page on DigitalUNIX

Man page or keyword search:  
man Server   12896 pages
apropos Keyword Search (all sections)
Output format
DigitalUNIX logo
[printable version]

atom(1)								       atom(1)

       atom - Builds an instrumented version of an application program

       atom appl_prog instrum_file [analysis_file] [options...]

       atom appl_prog -tool tool_name [-env environ] [options...]

       The  first  format  of  the  atom command is used to create a tool that
       instruments  an	application  program.	This   format	requires   the
       instrum_file   parameter.  The  analysis_file  parameter	 is  optional,
       because Atom can be used just to examine a program statically, in which
       case no run-time analysis routines are needed.

       The  second  format  of the atom command is more convenient for regular
       use, because it locates the tool's instrumentation and  analysis	 files
       by  a  simple  tool_name.  This	format	requires  the -tool option and
       accepts the -env option.	 It allows neither the	instrum_file  nor  the
       analysis_file parameter.

       The  following  list describes those options used to invoke Atom with a
       tool_name.  Identifies the  tool	 to  be	 used  by  naming  the	tool's
       description  file  (by  default, tool_name.desc).  This text file names
       the instrumentation and analysis files for the tool, as well as options
       that the tool needs. By default, atom searches for the description file
       in  the	/usr/lib/cmplrs/atom/tools  and	 /usr/lib/cmplrs/atom/examples
       directories.  You can add directories to the search path by supplying a
       colon-separated list of	additional  directories	 to  the  ATOMTOOLPATH
       environment  variable.  You can prevent Atom from searching the default
       directories for the tool by including the keyword NODEFAULT anywhere in
       the  directory list specified by the ATOMTOOLPATH environment variable.
       Identifies any special environment (for example, threads) in which  the
       tool   is  to  operate,	by  naming  an	alternative  description  file
       (tool_name.environ.desc). Atom displays an  error  if  you  specify  an
       environment  for	 which	no  description file is found in Atom's search

       Both formats of the atom command accept	the  following	options.  Note
       that  the  listed  default values apply only to the first format.  When
       the -tool option is specified, required atom options and default	 atom,
       compiler,  and  linker  options	may be defined by the specified tool's
       description file. See the atom_description_file(5) reference  page  for
       the  syntax of the file.	 Indicates that calls to analysis routines are
       not to be optimized. This is the default.  Optimizes the calls to anal‐
       ysis  routines  by  reducing  the  number  of registers that need to be
       restored. Specifying this  switch  causes  Atom	to  generate  slightly
       larger,	but  faster  code.   Instruments  all statically loaded shared
       libraries in the shared executable.  Allows debugging  of  instrumenta‐
       tion  routines. Atom puts the control in dbx with a stop at the instru‐
       mentation routine. See the Programmer's Guide for a discussion  on  how
       to use dbx with Atom.  Specifies a string for use when reporting errors
       or warnings. By default, the string “atom:” appears  on	all  error  or
       warning	messages.   Allows  debugging of instrumentation routines with
       the optional ladebug debugger, if installed on your system.  Atom  puts
       the  control in ladebug with a stop at the instrumentation routine. Use
       ladebug if the instrumentation routines contain C++ code. See the Lade‐
       bug  Debugger Manual for more information.  Specifies that objname is a
       dynamic shared library (that is, one loaded by a	 call  to  dlopen(3)).
       You  must specify each of the application's dynamic shared libraries in
       either a -dynobj option or an -incobj option. Those libraries specified
       to  the	-dynobj	 option	 are  not instrumented; those specified to the
       -incobj option are.  Excludes the named shared library from  instrumen‐
       tation.	You  can use the -excobj option more than once to specify sev‐
       eral shared libraries. Note that when -pthread is specified  (typically
       in a tool's description file for the “threads” environment), Atom auto‐
       matically instruments parts of even if it is specified in
       the  -excobj  option.   Specifies  that	fork support is required. This
       option should be used to avoid deadlocks in multithreaded applications.
       When  this option is used, fork handling routines declared by a call to
       pthread_atfork in analysis code or libraries  are  also	activated,  to
       enable  the  tool to be thread-safe and to handle forks as desired. See
       the prof example tool.  Produces the instrumented program  with	debug‐
       ging  information.  This	 enables  debugging  of analysis routines. The
       default -A0 option (not -A1) is recommended when -ga (or -g)  is	 used.
       Produces	 the  instrumented  program  with  debugging information. This
       enables debugging of analysis  and  application	routines.  The	prefix
       “_APP_” is attached to all variable and procedure names in the applica‐
       tion (this option does not work with C++	 programs).  The  default  -A0
       option  (not  -A1)  is  recommended  when  -gap	is used.  Produces the
       instrumented program with debugging information. This enables debugging
       of application routines.	 Produces the instrumented program with debug‐
       ging information. This enables debugging of  analysis  and  application
       routines.  The prefix “_ANA_” is attached to all variable and procedure
       names in the analysis object (this option does not work with  C++  pro‐
       grams).	The  default  -A0 option (not -A1) is recommended when -gpa is
       used.  Changes the base of the analysis heap.  This  option  has	 three
       forms:  Sets  the  base	to  the given hex address.  Sets the base to a
       default 31-bit address that is safe for applications that expect analy‐
       sis addresses to fit in 31 bits.	 Sets the base to the first page after
       the end of the application's bss segment. This puts the	heap  base  in
       about the same place as the application's heap. You should only specify
       this for tools that intercept every heap allocation in the  application

	      Normally,	 Atom's default location for the analysis heap is suf‐
	      ficient, so you don't need to use the  -heapbase	option.	  How‐
	      ever,  if	 the  default location conflicts with an address range
	      used by the application program, you may have to	choose	a  new
	      location	for  the  analysis heap.  Allows reuse of a previously
	      instrumented shared library. With -ii (incremental  instrumenta‐
	      tion), the first time that a shared library is instrumented, the
	      instrumentation points will be added to the shared  library  and
	      additional  information that allows for subsequent reuse will be
	      added. If previously instrumented shared	libraries  are	found,
	      those  libraries will be updated and reused. For reuse to occur,
	      the options that are specified must be the same  for  both  Atom
	      and  the	tool  (if  specified).	 Instruments  the named shared
	      library.	You can use the -incobj option more than once to spec‐
	      ify  several  shared  libraries.	Note  that  if	the tool calls
	      ThreadExcludeObj(5) for a multithreaded program,	this  function
	      will  advise  the tool not to instrument certain threads-related
	      system libraries even if they are selected.  This	 ensures  that
	      the analysis is thread-safe.  Indicates that the temporary files
	      that Atom creates should be placed in the current working direc‐
	      tory, and not deleted when instrumentation is complete.  Changes
	      the library directory search order for shared  object  libraries
	      so  that	atom  searches	for  them  in dir before searching the
	      default library directories.  You	 can  specify  multiple	 -Ldir
	      switches	to  specify  several  directory	 names.	  Changes  the
	      library directory search order for shared	 object	 libraries  so
	      that  atom  never looks for them in the default library directo‐
	      ries.  Use this option  when  the	 default  library  directories
	      should  not  be  searched	 and only the directories specified by
	      -Ldir are to be searched.	 Updates shared libraries with instru‐
	      mented  shared library information. By default, this information
	      is only added to the instrumented application.Using this	option
	      is  not  generally recommended.  Includes LD_LIBRARY_PATH in the
	      search path for shared libraries. Paths specified	 with  -L  are
	      searched	first,	then RPATH, then LD_LIBRARY_PATH, and then the
	      default directories.  Produces a list of the starting  addresses
	      of  the sections in the instrumented executable.	Indicates that
	      the tool will be instrumenting libc to clear the uniq  register,
	      so  Atom	should	not  do it. Using this option is not generally
	      recommended.  Indicates that the tool will be instrumenting libc
	      to execute the analysis fini routines, so Atom should not do it.
	      Using this option is not generally recommended.  Names the  exe‐
	      cutable output file filename.  By default, when the first format
	      of the atom command is used, the file is	called	progname.atom.
	      When  the second format of the atom command is used, the file is
	      called progname.toolname, or  progname.toolname.environ  if  the
	      -env environ option is used.  Specifies that thread-safe support
	      is required. This	 option	 should	 be  used  when	 instrumenting
	      threaded	applications.	Specifies  an  existing	  directory to
	      which atom writes the instrumented shared libraries.  Using this
	      option  allows  you to keep all of an application's instrumented
	      shared libraries in a single place.  Specifies a filename suffix
	      that is appended to the name of each object when Atom writes the
	      instrumented version.  For instance,  specifying	-suffix	 third
	      would  cause  a  shared library such as to be written as and a main executable file such  as	 test1	to  be
	      written as test1.third.  If you do not specify the -tool option,
	      the suffix defaults to the name of the tool.   Passes  arguments
	      to  the  Atom  tool's  instrumentation  routines. Use whitespace
	      characters to separate arguments from their parameters (if  any)
	      and from other arguments.

	      If you need to represent spaces within a -toolargs argument, use
	      matching single-quotes or matching  double-quotes,  making  sure
	      that  you	 avoid	having the shell interpret those characters as
	      shell-special characters.	 For example:

	      -toolargs="-exc	 'strstreambase::strstreambase(char*,	  int,

	      -toolargs='-exc "operator -" -exc "ostream::operator <<" \
			 -exc  main  -exc  "operator new(unsigned long)"' Dis‐
	      plays each step Atom takes to create the	instrumented  program.
	      Displays	Atom's	version	 number.   Controls display of warning
	      messages.	 The value of n can be one of  the  following  values:
	      Display  all warning messages, including those that are normally
	      suppressed.   Suppress  warning  messages	 that  can  be	safely
	      ignored.	 This is the default.  Suppress warning messages emit‐
	      ted when processing analysis routines.  Suppresses warning  mes‐
	      sages  about  shared  library  processing	 errors.  Atom ignores
	      shared libraries that cannot be processed.  Passes the specified
	      options to the analysis file's link phase.  Passes the specified
	      options to the instrumentation file's link  phase.   Passes  the
	      specified	 options  to  the  analysis  file's compilation phase.
	      Passes the specified options to the instrumentation file's  com‐
	      pilation phase.

       File  name of a fully linked shared or nonshared executable. For multi‐
       threaded programs, run ld(1) and atom(1) on the same version  of	 Tru64
       UNIX.  Multithreaded  programs linked on DIGITAL UNIX V3.2 are not sup‐
       ported, because the thread support libraries are	 not  compatible  with
       atom.  Programs	that  are stripped or are optimized by spike or cc -om
       are not supported.  Name of a C source file or an  object  module  that
       contains	 the  Atom  tool's instrumentation procedures.	By convention,
       most instrumentation files have the suffix inst.c  or  inst.o,  respec‐
       tively.	If  the	 instrumentation procedures are in more than one file,
       the of each file may be linked together into one file using the ld com‐
       mand with a -r option.

	      If  you  pass an object module for this parameter, consider com‐
	      piling the module with either the -g1 or -g options.   If	 there
	      are  errors  in  your instrumentation procedures, Atom can issue
	      more complete diagnostic messages when the instrumentation  pro‐
	      cedures are thus compiled.  Name of a C source file or an object
	      module that contains the Atom tool's  analysis  procedures.   By
	      convention,  most	 analysis  files  have	the  suffix  anal.c or
	      anal.o, respectively. Analysis routines may  perform  better  if
	      they  are compiled as a single compilation unit. If the analysis
	      routines are in more than one file, the  of  each	 file  may  be
	      linked  together	into  one  file using the ld command with a -r

       Atom is a programmable instrumentation toolkit. You program it by writ‐
       ing a tool with a routine called Instrument or InstrumentAll that calls
       Atom's API, as described in the related reference pages. The API	 helps
       this  routine  to  discover  the	 shared	 libraries,  procedures, basic
       blocks, and instructions that make up  an  application.	Then  the  API
       helps the routine insert calls to the tool's own run-time analysis rou‐
       tines, so that they will be invoked before or after the application (or
       any  of	its  libraries,	 procedures, blocks, or instructions) are exe‐
       cuted. The application code's behavior is unchanged in the instrumented
       program, but the tools's analysis routines execute too, producing tool-
       specific analysis data, such as an event trace or a profile.

       Temporary instrumentation files are created in /tmp.   Set  the	TMPDIR
       environment variable to a different directory to create the files else‐
       where, for example in a disk partition with more space.

       Atom does not work on programs built with the -pg or -p option.

       Instrumented code can be substantially larger than the  original	 code.
       In  rare cases, conditional branches that fit in the 21-bit branch dis‐
       placement field may not do so in the instrumented version of the	 code,
       thus generating an error.

       The  following  is  a  list  of library routines that can and cannot be
       called by analysis  routines:  Standard	C  Library  (libc.a)  routines
       (including  system  calls)  can be called except for unwind(3) routines
       and other exception-handling routines.Also, the standard	 I/O  routines
       have  certain  differences  in behavior as described later in this sec‐
       tion.  The pthread_atfork routine can be called only if the  -fork  was
       used  during  program  instrumentation.	Math Library (libm.a) routines
       can be called.  Other routines related to multi-threading or exception-
       handling should not be called (for example, pthread(3), exc_*, and lib‐
       mach routines).	Other routines that assume  a  particular  environment
       (for  example,  X  and  Motif)  may not be useful or correct in an Atom
       analysis environment.

       The standard I/O library provided to analysis routines does  not	 auto‐
       matically  flush and close streams when the instrumented program termi‐
       nates, so the analysis code must flush or close them  explicitly,  when
       all output has been completed.

       Also  the  stdout and stderr streams that are provided to analysis rou‐
       tines will be closed when the application  calls	 exit(),  so  analysis
       code may need to duplicate one or both of these streams if they need to
       be used after application exit  (for  example,  in  a  ProgramAfter  or
       ObjAfter analysis routine -- see AddCallProto(5)).

       For  output to stderr (or a duplicate of stderr) to appear immediately,
       analysis code  should  call  setbuf(stream,NULL)	 to  make  the	stream
       unbuffered  or  call fflush after each set of fprintf calls. Similarly,
       analysis routines using C++ streams can call cerr.flush().

       Thread Local Storage (TLS) is not supported in analysis routines.

       In the degenerate case of using Thread Independent Service  (TIS)  rou‐
       tines  or  Thread  Local	 Storage  (TLS)	 in  a non-threaded or single-
       threaded call-shared program, must be instrumented. This can be
       accomplished using -all or -incobj on the atom command line. In
       nonshared programs, libc.a is always instrumented.

       If you specify either the -all or -incobj switch, Atom  instruments  an
       application  and	 the application's shared libraries.  The instrumented
       shared libraries are written to the current directory with the  suffix.
       For example, is written as

       By default, Atom searches for shared libraries in the same locations as
       the  linker:  /usr/shlib	  /usr/ccs/lib	 /usr/lib/cmplrs/cc   /usr/lib
       /usr/local/lib /var/shlib

       If  the shared library is not found in any of the above locations, then
       Atom will search the current working directory.

       If you specify the -Ldir option,	 Atom  searches	 the  given  directory
       before searching the default locations.	You can specify multiple -Ldir
       options.	 You can also supply the -L option without a  directory	 name.
       This  causes  Atom  to  avoid  searching the default directories.  Only
       those directories specified by -Ldir options are searched.

       The loader uses only the instrumented shared libraries for those appli‐
       cations	that have been instrumented.  As long you choose a unique suf‐
       fix name (using the -suffix option) for the instrumented files, you can
       even  run  an  application  instrumented with two different Atom tools.
       The loader picks up the correctly instrumented shared library for  each
       version of the instrumented application.

       The  following  example tools can be named with the -tool option. These
       tools are intended to show how new tools can be written. They  may  not
       work well on all applications:

       Tool	 Description
       branch	 Instruments  all  conditional branches to deter‐
		 mine how many are predicted correctly.
       cache	 Determines cache miss rate. Simulates	execution
		 of the application in 8KB direct-mapped cache.
       dtb	 Determines  the  number of dtb (data translation
		 buffer)  misses.  Simulates  execution	 of   the
		 application  in 8KB pages and with a fully asso‐
		 ciative translation buffer.
       dyninst	 Provides fundamental dynamic counts of	 instruc‐
		 tions, loads, stores, blocks, and procedures.
       inline	 Identifies potential candidates for inlining.
       iprof	 Prints	 the  number  of  times each procedure is
		 called as well as the number (dynamic count)  of
		 instructions executed by each procedure.
       malloc	 Records  each	call  to  the malloc function and
		 prints a summary of the application's	allocated
       prof	 Prints	 the  number  (dynamic count) of instruc‐
		 tions executed by each procedure, in  a  thread-
		 safe manner.

       ptrace	 Prints	 the  name  of	each  procedure	 as it is
       replace	 Replaces an application procedure, and calls  it
		 from the analysis routine.
       trace	 Generates  an	address trace, logs the effective
		 address of every load and store  operation,  and
		 logs  the  address  of	 the start of every basic
		 block as it is executed.
       xlate	 Demonstrates how to use XLATEs to call an appli‐
		 cation procedure from an analysis routine.

       This example invokes the iprof example tool to instrument program, pro‐
       ducing the executable output file program.iprof.	 atom -tool iprof pro‐
       gram  This  example  instruments program using the instrumentation file
       my.inst.c and analysis file my.anal.c, producing the executable	output
       file program.atom.  atom program my.inst.c my.anal.c

       Functions:  atom_application_instrumentation(5), atom_application_navi‐
       gation(5),   atom_application_query(5),	  atom_application_symbols(5),
       atom_description_file(5),	     atom_instrumentation_routines(5),
       atom_object_management(5), AnalHeapBase(5), Thread(5), Xlate(5)

       Programmer's Guide


List of man pages available for DigitalUNIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
Vote for polarhome
Free Shell Accounts :: the biggest list on the net