atom_description_file(5)					File Formats Manual					  atom_description_file(5)

NAME

       atom_description_file - Description of an Atom tool's instrumentation and analysis files.

DESCRIPTION

       An  Atom  tool's description file identifies and describes the tool's instrumentation and analysis files.  It can also specify the flags to
       be used by the cc, ld, and atom commands when it is compiled, linked, and invoked.  Each Atom tool must supply  at  least  one  description
       file.  See atom(1) for additional information on Atom.

       You  must  place  a  tool's description files, along with its instrumentation and analysis files, in the tool's directory. By default, Atom
       searches for tools 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.

       Atom  has  two types of description files: A description file providing an environment for generalized use of the tool.	A tool can provide
       only one general-purpose environment.  The name of this type of description file has the format: tool.desc.  A description  file  providing
       an environment for use of the tool in specific contexts, such as in a multithreaded application or in kernel mode.  A tool can provide sev-
       eral special-purpose environments, each of which has its own description file. The name of this type of description file  has  the  format:
       tool.environment.desc.

       The  names  supplied  for  the tool and environment portions of these names correspond to values the user specifies with the -tool and -env
       flags on an atom command when invoking the tool.

       An Atom description file is a text file containing a series of tag, value pairs.  The tag and value are separated by white space and occupy
       a single line. The order of the lines in a description file are unimportant. Lines starting with a pound sign (#) are comments, blank lines
       are ignored.  A line can be continued by ending with a backslash () newline character.

       The following tag values are defined. If a tool's description file contains an unknown tag, Atom issues a warning and  ignores  that  tag's
       line.  Duplicate tags in a description file cause a fatal error.

       --------------------------------------------------------------------
       Tag	      Meaning
       --------------------------------------------------------------------
       INST_FILE      The   tool's  instrumentation  file.   This  tag	is
		      required in all description files.  The file can	be
		      either  a C source file (with a suffix) or an object
		      module (with an suffix). No  other  file	types  are
		      allowed.
       ANAL_FILE      The tool's analysis file.  If this is not specified,
		      a null analysis file  is	used.	The  file  can	be
		      either  a  C  source file (with a ".c" suffix) or an
		      object module (with a ".o" suffix).  No  other  file
		      types are allowed.
       INST_CFLAGS    Flags  to be passed to the C compiler when compiling
		      the instrumentation file.  This tag  is  ignored	if
		      the instrumentation file is not a C source file.
       ANAL_CFLAGS    Flags  to be passed to the C compiler when compiling
		      the analysis file. This tag is ignored if the analy-
		      sis  file  is  not  specified,  or is not a C source
		      file.
       INST_LDFLAGS   Flags to be passed to the linker	when  linking  the
		      instrumentation file with the Atom run-time system.
       ANAL_LDFLAGS   Flags  to  be  passed to the linker when linking the
		      analysis file to resolve all undefined symbols.
       ATOM_REQ       Required	atom  command  line  flags  for  the  tool
		      described by this description file.  These flags are
		      implicitly passed to Atom when the tool is  invoked.
		      If  the  user specifies a conflicting flag, the atom
		      command displays a warning  and  ignores	the  user-
		      specified switch.

       ATOM_DEF       Default	atom  command  line  flags  for  the  tool
		      described by this description file.  These flags are
		      implicitly  passed to Atom when the tool is invoked.
		      If the user specifies a conflicting flag,  the  atom
		      command  overrides  the corresponding flag listed in
		      this list.
       --------------------------------------------------------------------

       The following description file is for a tool named pixie that has an instrumentation file called pixie.inst.c and an analysis  file  called
       pixie.anal.c.  The  instrumentation  file links in the libmld library (using the -lmld flag) and the analysis file links in the pdf library
       (using the -lpdf flag).

       # # pixie.desc # INST_FILE	pixie.inst.c ANAL_FILE	     pixie.anal.c INST_LDFLAGS	  -lmld ANAL_LDFLAGS	-lpdf

       The following environment-specific description file supports a version of the pixie tool for the threads environment.  The threaded version
       of  pixie  uses	the same instrumentation and analysis source files as the general-purpose version.  However, the source files are compiled
       with the -DTHREADS compiler flag.

       # # pixie.threads.desc  #  INST_FILE	  pixie.inst.c	ANAL_FILE	pixie.anal.c  INST_CFLAGS     -DTHREADS  ANAL_CFLAGS	 -DTHREADS
       INST_LDFLAGS   -lmld ANAL_LDFLAGS   -lpdf

       The  following  general-purpose description file for the third Atom tool specifies default and required atom command line flags.  It forces
       the -heapbase progend flag to be passed to atom whenever the third tool is invoked.  It also passes the -A1 flag to the atom  command  line
       unless the user overrides this option by explicitly specifying -A0 when issuing the command.

       #  #  third.desc  #  INST_FILE	     third.inst.o  ANAL_FILE	    third.anal.o  ATOM_REQ	   -heapbase  progend  ATOM_DEF        -A1
       -----------------------------------------------------------------

SEE ALSO

       Commands: atom(1)

       AtomTools: hiprof(5), pixie(5), third(5)

       Functions: atom_application_instrumentation(5), atom_application_navigation(5),	atom_application_query(5),  atom_application_resolvers(5),
       atom_object_management(5), atom_instrumentation_routines(5), AnalHeapBase(5), Xlate(5), Thread(5)

       Programmer's Guide

															  atom_description_file(5)