Parse::Readelf::Debug::Info - handle readelf's debug info section with a class

NAME

Parse::Readelf::Debug::Info - handle readelf's debug info section with a class

SYNOPSIS

  use Parse::Readelf::Debug::Info;
  my $debug_info = new Parse::Readelf::Debug::Info($executable);
  my @item_ids = $debug_info->item_ids('l_object2a');
  my @structure_layout1 = $debug_info->structure_layout($item_ids[0]);
  my @some_item_ids = $debug_info->item_ids_matching('^var', 'variable');
  my @all_item_ids = $debug_info->item_ids_matching('');
  my @all_struct_ids = $debug_info->item_ids_matching('', '.*structure.*');

ABSTRACT

Parse::Readelf::Debug::Info parses the output of readelf --debug-dump=info and stores its interesting details in an object to ease access.

DESCRIPTION

Normally an object of this class is constructed with the file name of an object file to be parsed. Upon construction the file is analysed and all relevant information about its debug info section is stored inside of the object. This information can be accessed afterwards using a bunch of getter methods, see METHODS for details.

AT THE MOMENT ONLY INFORMATION REGARDING THE BINARY ARRANGEMENT OF VARIABLES (STRUCTURE LAYOUT) IS SUPPORTED. Other data is ignored for now.

Currently only output for Dwarf version 2 is supported. Please contact the author for other versions and provide some example readelf outputs.

EXPORT

Nothing is exported by default as it's normally not needed to modify any of the variables declared in the following export groups:

:all

all of the following groups

:command

$command
is the variable holding the command to run readelf to get the information relevant for this module, normally readelf --debug-dump=line.

:config

$display_nested_items
is a variable which controls if nested items (e.g. sub-structures) are not displayed unless actually used (e.g. as data type of members of their parent) or if they are always displayed - which might confuse the reader. The default is 0, any other value switches on the unconditional display.

$re_substructure_filter
is a regular expression that allows you to cut away the details of all substructures whose type names match the filter. This is useful if you have a bunch of types that you consider so basic that you like to blend out their details, e.g. the internal representation of a complex number datatype. The filter has the value ^string$ for C++ standard strings as default.

:fixed_regexps

$re_section_start
is the regular expression that recognises the start of the line debug output of readelf.

$re_dwarf_version
is the regular expression that recognises the Dwarf version line in a line debug output of readelf. The version number must be an integer number which will (must) be stored in $1.

:versioned_regexps

These regular expressions are those that recognise the (yet) supported tags of the item nodes of a readelf debug info output. Each of them is actually a list using the Dwarf version as index:

@re_item_start
recognises the start of a new item in the debug info list. $1 is the level, $2 the internal (unique) item ID, $3 the numeric type ID and $4 the type tag.

@re_bit_offset
recognises the bit offset tag of an item. $1 will contain the offset.

@re_bit_size
recognises the bit size tag of an item. $1 will contain the size.

@re_byte_size
recognises the byte size tag of an item. $1 will contain the size.

@re_comp_dir
recognises the compilation directory tag of an item. $1 will contain the compilation directory as string.

@re_const_value
recognises the const value tag of an item. $1 will contain the value.

@re_decl_file
recognises the declaration file tag of an item. $1 will contain the number of the file name (see the Parse::Readelf::Debug::Line manpage).

@re_decl_line
recognises the declaration line tag of an item. $1 will contain the line number.

@re_declaration
recognises the declaration tag of an item. $1 will usually contain a 1 indicating that it is set.

@re_encoding
recognises the encoding tag of an item. $1 will contain the encoding as text.

@re_external
recognises the external tag of an item. $1 will usually contain a 1 indicating that it is set.

@re_language
recognises the language tag of an item. $1 will contain the language as text.

@re_location
recognises the data member location tag of an item. $1 will contain the offset.

@re_member_location
recognises the data location tag of an item. $1 will contain the hex value (with spaces between each byte).

@re_name_tag
recognises the name tag of an item. $1 will contain the name.

@re_producer
recognises the producer tag of an item. $1 will contain the producer as string.

@re_specification
recognises the specification tag of an item. $1 will contain the internal item ID of the specification.

@re_type
recognises the type tag of an item. $1 will contain the internal item ID of the type.

@re_upper_bound
recognises the upper bound tag of a subrange item. $1 will contain the upper bound.

@re_ignored_attributes
recognises all attributes that are simply ignored (yet).

The last two lists are a bit different, they control what is parsed by this module. They are also arrays using the Dwarf version as index. What is inside each of this arrays is described below:

@tag_needs_attributes
holds hashes of the type tags that are processed. Each element points to a list of the absolutely needed attributes for that type of item.

@ignored_tags
is a list of the type tags (see @re_item_start above) that are currently ignored.

new - get readelf's debug info section into an object

    $debug_info = new Parse::Readelf::Debug::Info($file_name,
                                                 [$line_info]);

example:

    $debug_info1 = new Parse::Readelf::Debug::Info('program');
    $line_info = new Parse::Readelf::Debug::Line('module.o');
    $debug_info2 = new Parse::Readelf::Debug::Info('module.o',
                                                   $line_info);

parameters:

    $file_name          name of executable or object file
    $line_info          a L<Parse::Readelf::Debug::Line> object

description:

    This method parses the output of C<readelf --debug-dump=info> and
    stores its interesting details internally to be accessed later by
    getter methods described below.
    If no L<Parse::Readelf::Debug::Line> object is passed as second
    parameter the method creates one internally at it is needed to
    locate the source files.

global variables used:

    The method uses all of the variables described above in the
    L</"EXPORT"> section.

returns:

    The method returns the blessed Parse::Readelf::Debug::Info object
    or an exception in case of an error.

item_ids - get object ID(s) of (named) item

    @item_ids = $debug_info->item_ids($identifier);

example:

    @item_ids = $debug_info->item_ids('my_variable');

parameters:

    $identifier         name of item (e.g. variable name)

description:

    This method returns the internal item ID of all identifiers with
    the given name as array.

returns:

    If a name is unique, the method returns an array with exactly one
    element, if a name does not exist it returns an empty array and
    otherwise an array containing the IDs of all matching itmes is
    returned.

item_ids_matching - get object IDs of items matching constraints

    @item_ids = $debug_info->item_ids_matching($re_name, [$re_type_tag]);

example:

    @some_item_ids = $debug_info->item_ids_matching('^var', 'variable');
    @all_item_ids = $debug_info->item_ids_matching('');
    @all_structure_ids = $debug_info->item_ids_matching('', '.*structure.*');

parameters:

    $re_name            regular expression matching name of items
    $re_type_tag        regular expression matching type tag of items

description:

    This method returns an array containing the internal item ID of
    all identifiers that match both the regular expression for their
    name and their type tags.  Note that an empty string will match
    any name or type tag, even missing ones.  Also note that type tags
    in Dwarf 2 always begin with C<DW_TAG_>.

returns:

    If a name is unique, the method returns an array with exactly one
    element, if a name does not exist it returns an empty array and
    otherwise an array containing the IDs of all matching itmes is
    returned.  The IDs are sorted alphabetically according to their
    names.

structure_layout - get structure layout of variable or data type

    @structure_layout =
        $debug_info->structure_layout($id, [$initial_offset]);

example:

    @structure_layout1 =
        $debug_info->structure_layout('1a8');
    @structure_layout2 =
        $debug_info->structure_layout('2f0', 4);

parameters:

    $id                 internal ID of item
    $initial_offset     offset to be used for the beginning of the layout

description:

    This method returns the structure layout of a variable or data
    type with the given item ID (which can be found with the method
    L<"item_ids"> or L<"item_ids_matching">).  For each element of a
    structure it returns a quintuple containing (in that order)
    I<relative level>, I<name>, I<data type>, I<size> and I<offset>
    allthough some of the information might be missing (which is
    indicated by an empty string).  For bit fields two additional
    fields are added: I<bit-size> and I<bit-offset> (either both are
    defined or none at all).

returns:

    The method returns an array of the quintuples described above.

KNOWN BUGS

For references the size of the referenced data is shown, not the internal size of the reference self. This is a feature.

Only Dwarf version 2 is supported. Please contact the author for other versions and provide some example readelf outputs.

This has only be tested in a Unix like environment, namely Linux and Solaris.

SEE ALSO

the Parse::Readelf manpage, the Parse::Readelf::Debug::Line manpage and the readelf man page

AUTHOR

Thomas Dorner, <dorner (AT) pause.org>

COPYRIGHT AND LICENSE

Copyright (C) 2007 by Thomas Dorner

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.6.1 or, at your option, any later version of Perl 5 you may have available.

 Parse::Readelf::Debug::Info - handle readelf's debug info section with a class