html/suif1_104.html

   1 <HTML>
   2 <HEAD>
   3 <!-- This HTML file has been created by texi2html 1.54
   4      from suif1.texi on 28 April 1999 -->
   5
   6 <TITLE>The SUIF Version 1 Library - Initialization</TITLE>
   7 <link href="suif1_105.html" rel=Next>
   8 <link href="suif1_103.html" rel=Previous>
   9 <link href="suif1_toc.html" rel=ToC>
  10
  11 </HEAD>
  12 <BODY>
  13 <p>Go to the <A HREF="suif1_1.html">first</A>, <A HREF="suif1_103.html">previous</A>, <A HREF="suif1_105.html">next</A>, <A HREF="suif1_113.html">last</A> section, <A HREF="suif1_toc.html">table of contents</A>.
  14 <P><HR><P>
  15
  16
  17 <H2><A NAME="SEC104" HREF="suif1_toc.html#TOC104">Initialization and Finalization</A></H2>
  18 <P>
  19 <A NAME="IDX733"></A>
  20 <A NAME="IDX734"></A>
  21 <A NAME="IDX735"></A>
  22
  23 </P>
  24 <P>
  25 <A NAME="IDX736"></A>
  26 Before using any features of the SUIF library, a program must first
  27 initialize it.  The <CODE>init_suif</CODE> function, defined in the
  28 <TT>`initsuif.h'</TT> and <TT>`initsuif.cc'</TT> files, performs this
  29 initialization.  The <CODE>main</CODE> function of a SUIF program should call
  30 <CODE>init_suif</CODE> first.  The <CODE>argc</CODE> and <CODE>argv</CODE> parameters are
  31 passed to <CODE>init_suif</CODE> so that it can check for the following
  32 standard options:
  33
  34 </P>
  35 <DL COMPACT>
  36
  37 <DT><CODE>-version</CODE>
  38 <DD>
  39 Print the version numbers and compilation information for the program
  40 and for any libraries with which it is linked.  The
  41 <CODE>prog_ver_string</CODE> and <CODE>prog_who_string</CODE> strings contain the
  42 version number and compilation information for the program.  They are
  43 usually set automatically by the standard SUIF makefiles.  Similarly,
  44 the <CODE>libsuif1_ver_string</CODE> and <CODE>libsuif1_who_string</CODE> strings
  45 are used for the SUIF library.  Information for other libraries is
  46 recorded when they are registered (as described below).
  47
  48 <DT><CODE>-print-flat</CODE>
  49 <DD>
  50 Do not print structured annotations (see section <A HREF="suif1_72.html#SEC72">Structured Annotations</A>) using
  51 the user-defined printing functions.  If all annotations are printed as
  52 flat lists of immediate values, the output could be parsed and converted
  53 back to a binary SUIF file.
  54
  55 <DT><CODE>-no-types</CODE>
  56 <DD>
  57 Do not print the result types for instructions.  This is just to help
  58 make the output more readable in situations where the result types are
  59 not of interest.
  60
  61 <DT><CODE>-no-symtabs</CODE>
  62 <DD>
  63 Do not print out symbol tables.  If the symbolic information is not
  64 needed, this makes the output shorter and easier to read.
  65 </DL>
  66
  67 <P>
  68 These options are potentially applicable to all SUIF programs, so they
  69 are included in the library.
  70
  71 </P>
  72 <P>
  73 <A NAME="IDX737"></A>
  74 At the end of a SUIF program, the data structures in the SUIF library
  75 may be deallocated.  Although this is not absolutely necessary, it may
  76 simplify debugging by making it easier to read the output from Purify
  77 and other tools.  Besides deallocating the data structures, it may
  78 someday be useful to perform other actions at the end of a SUIF program.
  79 The <CODE>exit_suif</CODE> function is provided to perform this finalization.
  80 If used, it should be called at the very end of the program.
  81
  82 </P>
  83 <P>
  84 <A NAME="IDX738"></A>
  85 <A NAME="IDX739"></A>
  86 <A NAME="IDX740"></A>
  87 Besides the base SUIF library, many SUIF programs are linked with other
  88 libraries that also need to be initialized.  Rather than just
  89 initializing them directly, they are registered with the SUIF library
  90 along with initialization and finalization functions.  The
  91 initialization functions are then called automatically by
  92 <CODE>init_suif</CODE> and the finalization functions by <CODE>exit_suif</CODE>.
  93 This allows the SUIF library to record and print version numbers and
  94 other information for all of the libraries linked with a program.  The
  95 <CODE>register_library</CODE> function records the name, version, and
  96 compilation information for a library along with pointers to the
  97 functions to initialize and finalize that library.  The initialization
  98 function must match the <CODE>lib_init_f</CODE> type, which takes the
  99 <CODE>argc</CODE> and <CODE>argv</CODE> parameters for the command line and returns
 100 <CODE>void</CODE>.  Similarly, the finalization function must match the
 101 <CODE>lib_exit_f</CODE> type, which takes no arguments and returns
 102 <CODE>void</CODE>.  The parameters for the name, version, and compilation
 103 information are required, but the initialization and finalization
 104 functions are optional.  The libraries must be registered, in the order
 105 in which they should be initialized, before calling <CODE>init_suif</CODE>.
 106 The finalization functions are called in the reverse order in which the
 107 libraries were registered.
 108
 109 </P>
 110 <P>
 111 <A NAME="IDX741"></A>
 112 <A NAME="IDX742"></A>
 113 The situation is much simpler if you use the standard SUIF makefiles.
 114 These makefiles automatically generate strings holding the version and
 115 compilation information.  The <CODE>LIBRARY</CODE> macro may be used to
 116 register a library using these version strings.  You only need to
 117 specify the base name of the library and the names of the initialization
 118 and finalization functions <A NAME="DOCF7" HREF="suif1_foot.html#FOOT7">(7)</A>.  To make things even easier, the
 119 SUIF makefiles also generate a new function called <CODE>start_suif</CODE>.
 120 This function automatically registers all of the libraries linked with
 121 the program and then calls <CODE>init_suif</CODE>.  So to make a long story
 122 short, if a SUIF program begins with a call to <CODE>start_suif</CODE> all of
 123 the libraries will be automatically registered and initialized.
 124
 125 </P>
 126
 127 <P><HR><P>
 128 <p>Go to the <A HREF="suif1_1.html">first</A>, <A HREF="suif1_103.html">previous</A>, <A HREF="suif1_105.html">next</A>, <A HREF="suif1_113.html">last</A> section, <A HREF="suif1_toc.html">table of contents</A>.
 129 </BODY>
 130 </HTML>