Thomas Dorner > Parse-Readelf > Parse::Readelf::Debug::Line

Download:
Parse-Readelf-0.17.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.17   Source  

NAME ^

Parse::Readelf::Debug::Line - handle readelf's debug line section with a class

SYNOPSIS ^

  use Parse::Readelf::Debug::Line;

  my $line_info = new Parse::Readelf::Debug::Line($executable);

  my $object_id = $line_info->object_id("mocdule.c");

  my $file_name = $line_info->file($object_id, $number);
  my $directory_name = $line_info->directory($object_id, $number);
  my $path = $line_info->path($object_id, $number);

  my $object_name = $line_info->object_name($object_id);

  my $file_count = $line_info->files($object_id);
  my @files = $line_info->files($object_id);
  my $directory_count = $line_info->directories($object_id);
  my @directories = $line_info->directories($object_id);
  my $path_count = $line_info->paths($object_id);
  my @paths = $line_info->paths($object_id);

ABSTRACT ^

Parse::Readelf::Debug::Line parses the output of readelf --debug-dump=line and stores its interesting details in an object to be available. Normally it's not used directly but by other modules of Parse::Readelf.

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 line section is stored inside of the object. This information can be accessed afterwards using a bunch of getter methods, see "METHODS" for details.

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.

: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

@re_directory_table

is the version dependent regular expression that recognises the start of the directory table in line debug output of readelf.

@re_file_name_table

is the version dependent regular expression that recognises the start of the non-empty file name table in line debug output of readelf.

@re_file_name_table_header

is the version dependent regular expression that recognises the heading line of the file name table in line debug output of readelf. If this must be modified this probably means the parsing will not work correctly!

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

    $line_info = new Parse::Readelf::Debug::Line($file_name);

example:

    $line_info1 = new Parse::Readelf::Debug::Line('program');
    $line_info2 = new Parse::Readelf::Debug::Line('module.o');

parameters:

    $file_name          name of executable or object file

description:

    This method parses the output of C<readelf --debug-dump=line> and
    stores its interesting details internally to be accessed later by
    getter methods described below.

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::Line object
    or an exception in case of an error.

object_id - get object ID of (named) source file

    $object_id = $line_info->object_id($file_name);

example:

    $object_id = $line_info->object_id('module.c');

parameters:

    $file_name          name of the source file (without directory)

description:

    This method returns the internal object ID of a module when given
    the name of its source file without directory.  This is a
    non-negative number.

returns:

    The method returns the object ID or -1 if no matching object was
    found.

object_name - get name of major source file for a given object ID

    $object_name = $line_info->object_name($object_id);

example:

    $object_name = $line_info->object_name(0);

parameters:

    $object_id          internal object ID of module

description:

    This method is the opposite method of L<|C<object_id>>, it returns
    the name of the major source file for the given internal object ID
    of a module.

returns:

    The method returns the source name or an empty string if no
    matching object was found.

file - get file name of source for a given ID combination

    $file_name = $line_info->file($object_id, $source_number, $relax);

example:

    $file_name = $line_info->file(0, 0);
    $file_name = $line_info->file(0, 0, 1); # Dwarf-4

parameters:

    $object_id          internal object ID of module
    $source_number      number of the source
    $relax              optional flag to enable fallback code for object ID

description:

    This method returns the file name (without directory) of the
    source file number C<$source_number> for the given internal object
    ID of a module.  The source number is a positive integer.  1 is
    the number of the major source file, all others are usually
    include files.  Note that 0 is not used!

    Newer Dwarf versions don't seem to use different tables for
    different object IDs and put all sources into one table.  The
    optional flag C<$relax> tells the method to use this one table in
    those cases.

returns:

    The method returns the source name or an empty string if no
    matching source was found in the object.

files - list of all source file names for a given object ID

    @file_names = $line_info->files($object_id);
    $file_count = $line_info->files($object_id);

example:

    @file_names = $line_info->files(1);
    $number_of_files = $line_info->files($object_id);

parameters:

    $object_id          internal object ID of module

description:

    In list context this method returns a list of all file names
    (without directory parts) for the given internal object ID of a
    module.  In scalar context it returns how many elements this list
    would have.  As number 1 is the first source number actually used
    in the internal representation of the list the number returned in
    scalar context is also the last number you can pass to the
    L<|C<file>> method described above that returns a valid name (a
    non empty string).  Note also that the empty element 0 is not part
    of the list returned in list context.

returns:

    The method returns the list / the count as described above or an
    empty list / 0 if an unused or invalid object id was given.

directory - get directory name of source for a given ID combination

    $directory = $line_info->directory($object_id, $source_number);

example:

    $directory = $line_info->directory(0, 0);

parameters:

    $object_id          internal object ID of module
    $source_number      number of the source

description:

    This method returns the directory part of the file name of the
    source file number C<$source_number> for the given internal object
    ID of a module.  The source number is a positive integer.  1 is
    the number of the major source file, all others are usually
    include files.  Note that 0 is not used!

returns:

    The method returns the directory name or an empty string if no
    matching source was found in the object.

directories - list of all directory names for a given object ID

    @directories = $line_info->directories($object_id);
    $dir_count = $line_info->directories($object_id);

example:

    @directories = $line_info->directories(1);
    $number_of_dirs = $line_info->directories($object_id);

parameters:

    $object_id          internal object ID of module

description:

    In list context this method returns a list of the directory parts
    of all file names for the given internal object ID of a module.
    As usually several used include files are found in the same
    directory this list normally will contain duplictes.  Those are NOT
    eliminated.  In scalar context it returns how many elements this
    list would have.  As number 1 is the first source number actually
    used in the internal representation of the list the number
    returned in scalar context is also the last number you can pass to
    the L<|C<directory>> method described above that returns a valid
    name (a non empty string).  Note also that the empty element 0 is
    not part of the list returned in list context.

returns:

    The method returns the list / the count as described above or an
    empty list / 0 if an unused or invalid object id was given.

path - get path to source file for a given ID combination

    $file_path = $line_info->path($object_id, $source_number);

example:

    $file_path = $line_info->path(0, 0);

parameters:

    $object_id          internal object ID of module
    $source_number      number of the source

description:

    This method returns the path (directory plus file name) of the
    source file number C<$source_number> for the given internal object
    ID of a module.  The source number is a positive integer.  1 is
    the number of the major source file, all others are usually
    include files.  Note that 0 is not used!

returns:

    The method returns the source name or an empty string if no
    matching source was found in the object.

paths - list of paths to all sources for a given object ID

    @paths = $line_info->paths($object_id);
    $path_count = $line_info->paths($object_id);

example:

    @paths = $line_info->paths(1);
    $number_of_paths = $line_info->paths($object_id);

parameters:

    $object_id          internal object ID of module

description:

    In list context this method returns a list of all paths (directory
    plus file name) for the given internal object ID of a module.  In
    scalar context it returns how many elements this list would have.
    As number 1 is the first source number actually used in the
    internal representation of the list the number returned in scalar
    context is also the last number you can pass to the L<|C<file>>
    method described above that returns a valid name (a non empty
    string).  Note also that the empty element 0 is not part of the
    list returned in list context.

returns:

    The method returns the list / the count as described above or an
    empty list / 0 if an unused or invalid object id was given.

KNOWN BUGS ^

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 and uses Unix path syntax in some places.

SEE ALSO ^

Parse::Readelf and the readelf man page

AUTHOR ^

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

COPYRIGHT AND LICENSE ^

Copyright (C) 2007-2013 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.

syntax highlighting: