home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / dosdisas.zip / parsehdr.zip / PARSEHDR.TXT < prev    next >
Text File  |  1994-03-31  |  8KB  |  218 lines
  1.                 PARSEHDR
  2.  
  3. 1 What is ParseHdr?
  4.  
  5. 2 What is dcclibs.dat?
  6.  
  7. 3 How do I use ParseHdr?
  8.  
  9. 4 What about languages other than C?
  10.  
  11. 5 What is the structure of the dcclibs.dat file?
  12.  
  13. 6 What are all these errors, and why do they happen?
  14.  
  15.  
  16. 1 What is ParseHdr?
  17. -------------------
  18.  
  19. ParseHdr is a program that creates a special prototype file for DCC
  20. from a set of include files (.h files). This allows DCC to be aware
  21. of the type of library function arguments, and return types. The file
  22. produced is called dcclibs.dat. ParseHdr is designed specifically for
  23. C header files.
  24.  
  25. As an example, this is what allows DCC to recognise that printf has
  26. (at least) a string argument, and so converts the first argument from
  27. a numeric constant to a string. So you get
  28. printf("Hello world")
  29. instead of
  30. printf(0x42).
  31.  
  32.  
  33. 2 What is dcclibs.dat?
  34. ----------------------
  35.  
  36. dcclibs.dat is the file created by the ParseHdr program. It contains
  37. a list of function names and parameter and return types. See section
  38. 5 for details of the contents of the file.
  39.  
  40.  
  41. 3 How do I use ParseHdr?
  42. ------------------------
  43.  
  44. To use ParseHdr you need a file containing a list of header files,
  45. like this:
  46. \tc\include\alloc.h   
  47. \tc\include\assert.h  
  48. \tc\include\bios.h    
  49. ...
  50. \tc\include\time.h    
  51.  
  52. There must be one file per line, no blank lines, and unless the
  53. header files are in the current directory, a full path must be given.
  54. The easiest way to create such a file is to redirect the output of a
  55. dir command to a file, like this:
  56. c>dir \tc\include\*.h > tcfiles.lst
  57. and then edit the resultant file. Note that the path will not be
  58. included in this, so you will have to add that manually. Remove
  59. everything after the .h, such as file size, date, etc.
  60.  
  61. Once you have this file, you can run parsehdr:
  62.  
  63. parsehdr <listfile>
  64.  
  65. For example,
  66.  
  67. parsehdr tcfiles.lst
  68.  
  69. You will get some messages indicating which files are being
  70. processed, but also some error messages. Just ignore the error
  71. messages, see section 6 for why they occur.
  72.  
  73.  
  74.  
  75. 4 What about languages other than C?
  76. -----------------------------------------
  77.  
  78. ParseHdr will only work on C header files. It would be possible to
  79. process files for other languages that contained type information, to
  80. produce a dcclibs.dat file specific to that language. Ideally, DCC
  81. should look for a different file for each language, but since only a
  82. C version of dcclibs.dat has so far been created, this has not been
  83. done.
  84.  
  85. Prototype information for Turbo Pascal exists in the file turbo.tpl,
  86. at least for things like the graphics library, so it would be
  87. possible for MakeDsTp to produce a dcclibs.dat file as well as the
  88. signature file. However, the format of the turbo.tpl file is not
  89. documented by Borland; for details see 
  90.  
  91. W. L. Peavy, "Inside Turbo Pascal 6.0 Units", Public domain software
  92. file tpu6doc.txt in tpu6.zip. Anonymous ftp from garbo.uwasa.fi and
  93. mirrors, directory /pc/turbopas, 1991.
  94.  
  95.  
  96.  
  97.  
  98. 5 What is the structure of the dcclibs.dat file?
  99. ------------------------------------------------
  100.  
  101. The first 4 bytes are "dccp", identifying it as a DCC prototype file.
  102. After this, there are two sections.
  103.  
  104. The first section begins with "FN", for Function Names. It is
  105. followed by a two byte integer giving the number of function names
  106. stored. The remainder of this section is an array of structures, one
  107. per function name. Each has this structure:
  108. char Name[SYMLEN];    /* Name of the function, NULL terminated */
  109. int  type;        /* A 2 byte integer describing the return type */
  110. int  numArg;        /* The number of arguments */
  111. int  firstArg;        /* The index of the first arg, see below */
  112. char bVarArg;        /* 1 if variable arguments, 0 otherwise */
  113.  
  114. SYMLEN is 16, alowing 15 chars before the NULL. Therefore, the length
  115. of this structure is 23 bytes.
  116.  
  117. The types are as defined in locident.h (actually a part of dcc), and
  118. at present are as follows:
  119. typedef enum {
  120.     TYPE_UNKNOWN = 0,   /* unknown so far               00    */
  121.     TYPE_BYTE_SIGN,    /* signed byte (8 bits)      01    */
  122.     TYPE_BYTE_UNSIGN,    /* unsigned byte          02    */
  123.     TYPE_WORD_SIGN,     /* signed word (16 bits)     03    */
  124.     TYPE_WORD_UNSIGN,    /* unsigned word (16 bits)   04    */
  125.     TYPE_LONG_SIGN,    /* signed long (32 bits)     05    */
  126.     TYPE_LONG_UNSIGN,    /* unsigned long (32 bits)   06    */
  127.     TYPE_RECORD,    /* record structure         07    */
  128.     TYPE_PTR,            /* pointer (32 bit ptr)      08    */
  129.     TYPE_STR,            /* string                    09    */
  130.     TYPE_CONST,        /* constant (any type)         0A    */
  131.     TYPE_FLOAT,        /* floating point         0B    */
  132.     TYPE_DOUBLE,    /* double precision float    0C    */
  133. } hlType;
  134.  
  135. firstArg is an index into the array in the second section.
  136.  
  137. The second section begins with "PM" (for Parameters). It is followed
  138. by a 2 byte integer giving the number of parameter records. After
  139. this is the array of parameter structures. Initially, the names of the
  140. parameters were being stored, but this has been removed at present. 
  141. The parameter structure is therefore now just a single 2 byte
  142. integer, representing the type of that argument.
  143.  
  144. The way it all fits together is perhaps best described by an example.
  145. Lets consider this entry in dcclibs.dat:
  146.  
  147. 73 74 72 63 6D 70 00            ; "strcmp"
  148. 00 00 00 00 00 00 00 00 00    ; Padding to 16 bytes
  149. 03 00                ; Return type 3, TYPE_WORD_UNSIGN
  150. 02 00                ; 2 arguments
  151. 15 02                ; First arg is 0215
  152. 00                              ; Not var args
  153.  
  154. If we now skip to the "PM" part of the file, skip the number of
  155. arguments word, then skip 215*2 = 42A bytes, we find this:
  156. 09 00 09 00 09 00 ...
  157.  
  158. The first 09 00 (TYPE_STR) refers to the type of the first parameter,
  159. and the second to the second parameter. There are only 2 arguments,
  160. so the third 09 00 refers to the first parameter of the next
  161. function. So both parameters are strings, as is expected.
  162.  
  163. For functions with variable parameters, bVarArg is set to 01, and the
  164. number of parameters reported is the number of fixed parameters. Here
  165. is another example:
  166.  
  167. 66 70 72 69 6E 74 66 00        ; "fprintf"
  168. 00 00 00 00 00 00 00 00        ; padding
  169. 03 00                ; return type 3, TYPE_WORD_UNSIGN
  170. 02 00                ; 2 fixed args
  171. 81 01                ; First arg at index 0181
  172. 01                ; Var args
  173.  
  174. and in the "PM" section at offset 181*2 = 0302, we find 08 00 09 00
  175. 03 00 meaning that the first parameter is a pointer (in fact, we know
  176. it's a FILE *), and the second parameter is a string.
  177.  
  178.  
  179.  
  180.  
  181. 6 What are all these errors, and why do they happen?
  182. ----------------------------------------------------
  183.  
  184. When you run ParseHdr, as well as the progress statements like 
  185.   Processing \tc\include\alloc.h   ...
  186.  
  187. you can get error messages. Basically, ignore these errors. They occur
  188. for a variety of reasons, most of which are detailed below.
  189.  
  190. 1)
  191.   Expected type: got ) (29)
  192.   void          __emit__()
  193.                          ^
  194. This include file contained a non ansi prototype. This is rare, and
  195. __emit__ is not a standard function anyway. If it really bothers you,
  196. you could add the word "void" to the empty parentheses in your
  197. include file.
  198.  
  199. 2) 
  200.   Expected ',' between parameter defs: got ( (28)
  201.   void  _Cdecl ctrlbrk (int _Cdecl (*handler)(void))
  202.  
  203. Here "handler" is a pointer to a function. Being a basically simple
  204. program, ParseHdr does not expand all typedef and #define statements,
  205. so it cannot distinguish between types and user defined function
  206. names. Therefore, it is not possible in general to parse any
  207. prototypes containing pointers to functions, so at this stage, any
  208. such prototypes will produce an error of some sort. DCC cannot
  209. currently make use of this type information anyway, so this is no
  210. real loss. There are typically half a dozen such errors.
  211.  
  212. 3)
  213.   Unknown type time_t
  214.  
  215. Types (such as time_t) that are structures or pointers to structures
  216. are not handled by ParseHdr, since typedef and #define statements are
  217. ignored. Again, there are typically only about a dozen of these.
  218.