git.sur5r.net Git - cc65/blob - doc/od65.sgml

   1 <!doctype linuxdoc system>
   2
   3 <article>
   4 <title>od65 Users Guide
   5 <author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
   6 <date>2010-07-30
   7
   8 <abstract>
   9 od65 is the object file dump utility. It is able to output most parts of
  10 <htmlurl url="ca65.html" name="ca65"> generated object files in readable form.
  11 </abstract>
  12
  13 <!-- Table of contents -->
  14 <toc>
  15
  16 <!-- Begin the document -->
  17
  18
  19 <sect>Overview<p>
  20
  21 od65 is an object file dump utility. It is able to output most parts of
  22 <htmlurl url="ca65.html" name="ca65"> generated object files in readable form.
  23 Since the contents and format of the object files are not documented
  24 elsewhere and may change at any time, this tool is a portable way to look at
  25 the contents.
  26
  27 Apart from curiosity, most people don't need to use this tool.
  28
  29
  30
  31 <sect>Usage<p>
  32
  33 The od65 utility dumps contents of one or more ca65 generated object file to
  34 standard output. It has no cross-version compatibility, so you have to use
  35 a version that matches the version of ca65 used to create the object files.
  36
  37
  38 <sect1>Command line option overview<p>
  39
  40 The program may be called as follows:
  41
  42 <tscreen><verb>
  43 ---------------------------------------------------------------------------
  44 Usage: od65 [options] file [options] [file]
  45 Short options:
  46   -h                    Help (this text)
  47   -H                    Dump the object file header
  48   -S                    Dump segments sizes
  49   -V                    Print the version number and exit
  50
  51 Long options:
  52   --dump-all            Dump all object file information
  53   --dump-dbgsyms        Dump debug symbols
  54   --dump-exports        Dump exported symbols
  55   --dump-files          Dump the source files
  56   --dump-header         Dump the object file header
  57   --dump-imports        Dump imported symbols
  58   --dump-lineinfo       Dump line information
  59   --dump-options        Dump object file options
  60   --dump-segments       Dump the segments in the file
  61   --dump-segsize        Dump segments sizes
  62   --help                Help (this text)
  63   --version             Print the version number and exit
  64 ---------------------------------------------------------------------------
  65 </verb></tscreen>
  66
  67
  68 <sect1>Command line options in detail<p>
  69
  70 Here is a description of all the command line options:
  71
  72 <descrip>
  73
  74   <tag><tt>--dump-all</tt></tag>
  75
  76   This will output all information, od65 is able to process. The option is a
  77   shortcut for specifying all the other <tt/--dump/ options.
  78
  79
  80   <tag><tt>--dump-dbgsyms</tt></tag>
  81
  82   Dump all debug symbols contained in the object file.
  83
  84
  85   <tag><tt>--dump-exports</tt></tag>
  86
  87   Dump all exported symbols contained in the object file.
  88
  89
  90   <tag><tt>--dump-files</tt></tag>
  91
  92   Dump the file table contained in the object file.
  93
  94
  95   <tag><tt>-H, --dump-header</tt></tag>
  96
  97   Dump the object file header.
  98
  99
 100   <tag><tt>--dump-imports</tt></tag>
 101
 102   Dump the list of imported symbols contained in the object file.
 103
 104
 105   <tag><tt>--dump-lineinfo</tt></tag>
 106
 107   Dump the line info contained in the object file.
 108
 109
 110   <tag><tt>--dump-segments</tt></tag>
 111
 112   Dump the list of segments contained in the object file.
 113
 114
 115   <tag><tt>--dump-scopes</tt></tag>
 116
 117   Dump the scope (lexical level) information contained in the object file.
 118
 119
 120   <tag><tt>-S, --dump-segsize</tt></tag>
 121
 122   Dump the sizes of all segments contained in the object file. This option is
 123   quite useful to determine the effect of measures that increase or decrease
 124   code size.
 125
 126
 127   <tag><tt>-h, --help</tt></tag>
 128
 129   Print the short option summary shown above.
 130
 131
 132   <tag><tt>-V, --version</tt></tag>
 133
 134   Print the version number of the compiler. When submitting a bug report,
 135   please include the operating system you're using, and the compiler
 136   version.
 137 </descrip>
 138
 139
 140 <sect>Input and output<p>
 141
 142 The converter will read one or more object files per invocation and write the
 143 contents in readable format to standard output. Please note that you need to
 144 specify and of the <tt/--dump/ options listed above, otherwise no useful
 145 output will be generated.
 146
 147 Example output for the command
 148 <tscreen><verb>
 149 od65 --dump-header --dump-files t.o
 150 </verb></tscreen>
 151 <tscreen><verb>
 152 t.o:
 153   Header:
 154     Magic:                 0x616E7A55
 155     Version:                       12
 156     Flags:                     0x0001  (OBJ_FLAGS_DBGINFO)
 157     Options:
 158       Offset:                      88
 159       Size:                         9
 160     Files:
 161       Offset:                      97
 162       Size:                        10
 163     Segments:
 164       Offset:                     107
 165       Size:                       101
 166     Imports:
 167       Offset:                     208
 168       Size:                         1
 169     Exports:
 170       Offset:                     209
 171       Size:                         1
 172     Debug symbols:
 173       Offset:                     210
 174       Size:                        55
 175     Line infos:
 176       Offset:                     265
 177       Size:                         1
 178     String pool:
 179       Offset:                     266
 180       Size:                        80
 181   Files:
 182     Count:                          1
 183     Index:                          0
 184       Name:                     "t.s"
 185       Size:                       402
 186       Modification time:   1280498435  (Fri Jul 30 16:00:35 2010)
 187 </verb></tscreen>
 188
 189
 190 <sect>Bugs/Feedback<p>
 191
 192 If you have problems using the converter, if you find any bugs, or if you're
 193 doing something interesting with the code, I would be glad to hear from you.
 194 Feel free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
 195 name="uz@cc65.org">).
 196
 197
 198
 199 <sect>Copyright<p>
 200
 201 od65 is (C) Copyright 2000-2009, Ullrich von Bassewitz. For usage of the
 202 binaries and/or sources the following conditions apply:
 203
 204 This software is provided 'as-is', without any expressed or implied
 205 warranty.  In no event will the authors be held liable for any damages
 206 arising from the use of this software.
 207
 208 Permission is granted to anyone to use this software for any purpose,
 209 including commercial applications, and to alter it and redistribute it
 210 freely, subject to the following restrictions:
 211
 212 <enum>
 213 <item>  The origin of this software must not be misrepresented; you must not
 214         claim that you wrote the original software. If you use this software
 215         in a product, an acknowledgment in the product documentation would be
 216         appreciated but is not required.
 217 <item>  Altered source versions must be plainly marked as such, and must not
 218         be misrepresented as being the original software.
 219 <item>  This notice may not be removed or altered from any source
 220         distribution.
 221 </enum>
 222
 223 </article>
 224