unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



atom_description_file(5)			     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 instru-
  mentation 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 environ-
  ment 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 several 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.  Dupli-
  cate 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 .c suffix) or an
		 object	module (with an	.o suffix). No other file
		 types are allowed.
  ANAL_FILE

		 The tool's analysis file.  If this is not speci-
		 fied, 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 compil-
		 ing 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 compil-
		 ing the analysis file.	This tag is ignored if the
		 analysis 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 sys-
		 tem.
  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