*** UNIX MANUAL PAGE BROWSER ***

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 in- strumentation 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 instrumenta- tion and analysis files, in the tool's directory. By default, Atom searches for tools in the /usr/lib/cmplrs/atom/tools and /usr/lib/cm- plrs/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 de- scription 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 descrip- tion 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 unim- portant. 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 con- tains an unknown tag, Atom issues a warning and ignores that tag's line. Duplicate tags in a description file cause a fatal error. l lw(5.2i). _ Tag Meaning _ INST_FILE T{ 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. T} ANAL_FILE T{ 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 ob- ject module (with a ".o" suffix). No other file types are allowed. T} INST_CFLAGS T{ 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. T} ANAL_CFLAGS T{ Flags to be passed to the C compiler when compiling the analysis file. This tag is ignored if the analysis file is not specified, or is not a C source file. T} INST_LDFLAGS T{ Flags to be passed to the linker when linking the in- strumentation file with the Atom run-time system. T} ANAL_LDFLAGS T{ Flags to be passed to the linker when linking the analysis file to re- solve all undefined symbols. T} ATOM_REQ T{ 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. T} ATOM_DEF T{ 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. T} _ 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 (us- ing the -lmld flag) and the analysis file links in the pdf library (us- ing 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_LD- FLAGS -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 issu- ing 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_navi- gation(5), atom_application_query(5), atom_application_resolvers(5), atom_object_management(5), atom_instrumentation_routines(5), AnalHeap- Base(5), Xlate(5), Thread(5) Programmer's Guide atom_description_file(5)