home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / flower.zip / flower.doc < prev    next >
Text File  |  1997-02-27  |  6KB  |  188 lines
  1. /* Copyright (c) 1996, 1997 Craig Schneiderwent */
  2. Program: flower
  3. Author:  Craig Schneiderwent
  4.          74631.165@compuserve.com
  5. Date:    27-Feb-1997
  6.  
  7. Purpose: 
  8.  
  9. I found a reference to cflow in the comp.lang.c
  10. FAQ and it sounded like what I needed: write each
  11. function name in a .c source file and the names of
  12. the functions it calls to stdout.  But since I 
  13. couldn't find a working version of cflow, I wrote 
  14. my own.  It's far from perfect, but it suits my
  15. needs - and perhaps yours.  Run without arguments
  16. for execution syntax.
  17.  
  18. Multiple source code files can be specified on
  19. the command line, thus
  20.  
  21.     flower main.c mniplist.c printrpt.c updtlist.c memfunc.c
  22.  
  23. or, if you prefer
  24.  
  25.     flower @filelist.txt
  26.  
  27. where filelist.txt is a text file containing names
  28. of files, one per line.  This is useful for specifying
  29. large numbers of source code files.
  30.  
  31. Flower prints any or all of three reports: a call tree,
  32. functions and the functions they call, and functions and
  33. which functions call them.
  34.  
  35. -a all reports
  36. -b functions and which functions call them
  37. -c functions and which functions they call
  38. -t call tree
  39. -x exclude these functions
  40.  
  41. The default is to output all three reports.  The
  42. reports are written to stdout.  Progress and error
  43. messages are written to stderr.
  44.  
  45. If you want to exclude functions (maybe they're only
  46. for debugging and are #ifdef'd) add -x func1 func2 [...]
  47. after your list of files.  If you have many of these
  48. functions, add -x @exFileNm where exFileNm contains one
  49. function (to be excluded) per line.
  50.  
  51. This version was written for OS/2.  Unless I screwed up,
  52. it _should_ compile pretty much anywhere.  HA! I hear
  53. you say.  Try it.  You'll probably have to change the
  54. makefile to invoke your compiler (unless it's called
  55. ICC), and your linker (unless it's called LINK386).  There
  56. should be a file included in the original zip called
  57. cmplopt.txt that details the compile and link options I used
  58. (nothing fancy, mostly just checking for bugs).
  59.  
  60. Don't worry about the .cmd files, they're just OS/2's version
  61. of DOS .bat files in this case.
  62.  
  63. The basic algorithm:
  64.  
  65.   1. Find a token (a parenthesis, a curly
  66.      brace, a space or a line end)
  67.   2. If the token is an opening curly brace
  68.      2a. Increment a counter
  69.      2b. If the counter is 1, we're at the
  70.          beginning of a function definition
  71.          2b1. Back up to the outermost previous
  72.               opening parenthesis.
  73.          2b2. Back up to the previous token
  74.          2b3. From present position to the position
  75.               in 3a is the name of a function
  76.          2b4. Print it
  77.   3. If the token is a closing curly brace
  78.      3a. If the counter is > 0 decrement the counter
  79.   4. If the token is an opening parenthesis
  80.      4a. If the counter is > 0 we're potentially at
  81.          the beginning of a called function
  82.          4a1. Back up to the previous token
  83.          4a2. From present position to the position in
  84.               4a is potentially a called function -
  85.               copy it
  86.          4a3. Match the potentially called function
  87.               against a list of reserved words - if
  88.               it doesn't match, print it
  89.  
  90. NOTE:
  91.  
  92. I do check for circular references - recursion and
  93. the Function A calls Function B which calls Function C
  94. which calls Function A situation.  A notation is made
  95. in the call tree report if such situations are 
  96. encountered.
  97.  
  98. NOTE:
  99.  
  100. Be advised, I ran flower with the -t option on one
  101. of my projects comprising about 3K of source lines
  102. and the output was over 17K lines.  Be careful when
  103. routing this report to a printer - my advice is to
  104. route all output to a file first.
  105.  
  106. NOTE:
  107.  
  108. Feel free to make use of the -x option.  By adding
  109. two debugging functions to be ignored, I reduced the 
  110. above-mentioned 17K print lines to 4.5K lines.
  111.  
  112. Other Limitations:
  113.  
  114. If you do things like
  115.  
  116. #define BEGIN_STRUCT {
  117. #define END_STRUCT   }
  118.  
  119. flower will not work properly.
  120.  
  121. flower does not understand C++ style comments (single
  122. line beginning with // (slash slash).  Giving source
  123. code containing this comment style to flower is a good
  124. way to force a register dump.
  125.  
  126. I would suggest you exclude (-x) any macros or pragmas
  127. that take arguments.  These, combined with struct 
  128. declarations mixed in with your source, tend to 
  129. confuse flower:
  130.  
  131. #pragma alloc_text( codeseg1, myVeryCoolFunction );
  132. struct a {
  133.     short w;
  134.     char  x[ sizeof( w ) ];
  135.     struct b {
  136.         long y;
  137.         long z;
  138.     };
  139. };
  140.  
  141. The functions are stored in linked lists, if you give 
  142. flower enough source to process, you will run out of 
  143. RAM.
  144.  
  145. Each source code file is read in completely before its
  146. processing begins.  If your source code files are large
  147. enough you will run out of RAM.
  148.  
  149. The makefile declares a stack of 20K.  If you have a very
  150. deep call tree, you may have to re-link with a larger stack.
  151.  
  152. Root entries for the call tree report are any function
  153. that is not (apparently) called.  If a function is only
  154. called by passing its address to another function, it
  155. will look to flower as if it is not called.
  156.  
  157. Return Codes:
  158.  
  159.  0 Processing ended normally
  160.  1 Unable to open or close file
  161.  2 Error attempting to locate beginning or end of file
  162.  3 Error attempting to allocate memory
  163.  4 fseek position < 0
  164.  
  165.  
  166. Licensing:
  167.  
  168. On the off-chance anyone cares, this program is free.
  169. Use it, abuse it, just don't charge for it.  Take a 
  170. look at the code - who'd pay for it?
  171.  
  172. If you recompile, redistribute this stuff, please keep
  173. keep all the original source and documentation files together.
  174.  
  175. Given our litigious society:
  176.  
  177. DISCLAIMER
  178. Users of this program must accept this disclaimer of warranty:
  179.  
  180. "This program is supplied as is.  The original author disclaims all
  181. warranties, expressed or implied, including, without limitation,
  182. the warranties of merchantability and of fitness for any purpose.
  183. The original author assumes no liability for damages, direct or
  184. consequential, which may result from the use of this program."
  185.  
  186. This program was written because _I_ needed it.  I hope you find
  187. it useful, but please don't expect ANYTHING in the way of support.
  188.