Reflow comments and clean up whitespace

Merge branch 'master' of github.com:eliben/pyelftools

ref_addr size changed between v2 and v3 - take 2 (#273)

In DWARF 2, the DW_FORM_ref_addr format matches the target address size, while in DWARF3+ it matches the bitness of the CU record. Here are the relevant fragments from the spec, part 7:

v2:

    The second type of reference is the address of any debugging information entry within the same executable or shared object; it may refer to an entry in a different compilation unit from the unit containing the reference. This type of reference (DW_FORM_ref_addr) is the size of an address on the target architecture; it is relocatable in a relocatable object file and relocated in an executable file or shared object.

v3:

    The second type of reference can identify any debugging information entry within a program; in particular, it may refer to an entry in a different compilation unit from the unit containing the reference, and may refer to an entry in a different shared object. This type of reference (DW_FORM_ref_addr) is an offset from the beginning of the .debug_info section of the target executable or shared object; it is relocatable in a relocatable object file and frequently relocated in an executable file or shared object. For references from one shared object or static executable file to another, the relocation and identification of the target object must be performed by the consumer. In the 32-bit DWARF format, this offset is a 4-byte unsigned value; in the 64-bit DWARF format, it is an 8-byte unsigned value (see Section 7.4).

If elftools encounters 32-bit DWARF v2 targeting a 64-bit architecture, it will misparse DW_FORM_ref_addr and crash downstream.

I encountered this in an iOS binary from 2017, built with Xcode several versions ago for ARM64. This probably never came up before because by the time 64 bit code became relevant, most toolchains would generate DWARF 3 or newer.

Co-authored-by: Seva Alekseyev <sevaa@nih.gov>

Fix typo in comment

examples: Add dwarf_lineprogram_filenames.py (#285)

This adds an example of the operation discussed in #283.

Usage:

   python3 ./dwarf_lineprogram_filenames.py --test x.elf y.elf z.elf

construct_utils.py: add missing import (#291)

Add a forgotten import of SizeofError.

Fixes: #278

Move test file name to be included in distribution

Fixes #260

Reformat whitespace in dwarf enums

DWARF 5 tags and attributes (#271)

Trim whitespace

Make sure ELFFile.has_dwarf_info() returns a boolean. (#266)

segments.py: fix TLS checks in section_in_segment() (#275)

While the comment in section_in_segment() suggests that the
logic follows the logic inside ELF_SECTION_IN_SEGMENT_1 with
the strict parameter set, all of the checks in the binutils
macro are written so that they must succeed for the section
to be contained in the current segment. In our implementation,
however, the checks were not properly negated.

This showed in the case of .tdata and .tbss which did not
appear in the section to segment mapping (these sections are
found in glibc, for example).

Fix it up by aligning the logic more closely to the binutils
macro by implementing the same logic and returning False only
if the checks fail. Additionally, introduce the third check
from the upstream binutils which checks the combination of
SHT_ALLOC sections and PT_LOAD-like segments.

Furthermore, in the original check, the PT_GNU_RELRO type was
misspelled with a 0 (zero) instead of an O so this check
could never have worked.

Fixes: #263

Travis: drop Python 3.4, add 3.8

Fix simple typo: wether -> whether (#259)

Closes #258

Tweak release instructions in TODO

Update release notes in TODO

Prepare for release 0.26

Lazy DIE parsing (#249)

Supersedes/closes #216.

elf/constants: Add SHN_XINDEX (#248)

Include README.rst instead of README in manifest (#247)

`setup.py bdist_wheel` warns about not finding README.

dwarf/die: Handle DW_FORM_flag_present in value translation (#246)

* dwarf/die: Handle DW_FORM_flag_present in value translation

When an attribute has form DW_FORM_flag_present it is implicitly
indicated as present, with no actual value.

Ref. DWARFv4, section 7.

* test: Add DW_FORM_flag_present value test

* test: Fix iteration

* test: Remove old assert

dwarf/constants: More DW_LANG, DW_ATE constants (#245)

Most of these were added in DWARFv5.

Realign columns for some constants

dwarf/enums: More attributes, tags, and forms (#244)

dwarf/enums Add GNU parameter tags (#242)

dwarf_expr: Add DW_OP_{lo,hi}_user (#239)

dwarf_expr: Add DWARFv5 OPs (#240)

Portable import of collections.Mapping

Tested with Python 3.8

Based on #237 by @Plailect. Closes #237

Improved handling of location information (#225)

This commit moves some of the location-handling code from the examples
to a new class (LocationParser) in order to make it more reusable.

Also adds two test files containing location information.

Fix for `CFIEntry.get_decoded()` (#232)

* test: test `CFIEntry.get_decoded()`

This test detects an error in `CFIEntry.get_decoded()`, that occurs when
decodes the `DW_CFA_def_cfa_register` instruction without some CFA
definition previously.

Signed-off-by: Koltunov Dmitry <koltunov@ispras.ru>
* add empty `cfa` for fixup decode of the `DW_CFA_def_cfa_register`

Signed-off-by: Koltunov Dmitry <koltunov@ispras.ru>

dwarf/descriptions: Remove DW_LANG_Upc (#234)

The standard defines only DW_LANG_UPC, and this
value also contained a typo.

dwarf_expr: Add DW_OP_{implicit,stack}_value (#233)

Bump minimal supported Python 3.x version to 3.4 and add testing with 3.7

Fix deprecation warning in Python 3.7 (#231)

$SITE_PYTHON/lib/python3.7/site-packages/elftools/construct/lib/container.py:5
 Using or importing the ABCs from 'collections' instead of from 'collections.abc' is deprecated, and in 3.8 it will stop working

This change is compatible with Python 3.3 and up, when the ABCs were
moved to collections.abc. Backward compatibility is retained through
the try/except block.

Add ability to parse the NT_FILE note found in core files (#220)

Improve symbol table handling in DynamicSegment (#219)

dynamic: parse DT_{GNU_}HASH for number of symbols

In ultra-stripped binaries we can find the symbol table by
parsing the dynamic segment and using the pointer in the
DT_SYMTAB tag as the base address. However, we don't know
anything about the number of symbols in the symbol table.

Earlier, this code relied on finding the closest pointer
value bigger than the base address of the symbol table. In
PIE executables and shared libraries however this method
could break as the pointer value for DT_SYMTAB is in the same
range as things like DT_RELASZ or DT_STRSZ, leading to a too
small number of symbols returned by iter_symbols().

The crashpad project has implemented a different strategy to
find the number of symbols: parsing the symbol lookup hash
tables (see [0]) as every symbol must have a corresponding
entry in the hash table. This commit implements this
behaviour for DynamicSegment, leaving the old code as a
backup if neither DT_HASH or DT_GNU_HASH tags have been
found.

For DT_HASH type tables, it is quite easy as the header
already contains the number of entries. For DT_GNU_HASH
things are a bit more complicated as we need to work forward
from the highest symbol referenced in the header (a good
explanation of the format can be found at [1]).

[0]: https://github.com/chromium/crashpad/commit/1f1657d573c789aa36b6022440e34d9ec30d894c
[1]: https://flapenguin.me/2017/05/10/elf-lookup-dt-gnu-hash/

* dynamic: provide more functions for symbol access

So far, the DynamicSegment only provided a method to iterate
over all symbols but for some use cases it might be useful to
use the recovered symbol table more like a normal
SymbolTableSection.

To this end, provide get_symbol(index) to fetch a symbol by
its index, num_symbols() to get the total number of symbols
and get_symbol_by_name(name) to look for a list of symbols
with a given name.

Enable parsing of relocations pointed to by DYNAMIC. (#135)

Fix LookupError when testing with tox (#221)

On macOS I'm getting the following error when testing with tox on py27:

```
ERROR: invocation failed (exit code 1), logfile: /devel/pyelftools/.tox/py27/log/py27-33.log
ERROR: actionid: py27
msg: installpkg
cmdargs: ['/devel/pyelftools/.tox/py27/bin/pip', 'install', '-U', '--no-deps', '/devel/pyelftools/.tox/dist/pyelftools-0.25.zip']

DEPRECATION: Python 2.7 will reach the end of its life on January 1st, 2020. Please upgrade your Python as Python 2.7 won't be maintained after that date. A future version of pip will drop support for Python 2.7.
Processing ./.tox/dist/pyelftools-0.25.zip
    Complete output from command python setup.py egg_info:
    Traceback (most recent call last):
      File "<string>", line 1, in <module>
      File "/private/var/folders/qz/XXX/T/pip-req-build-890d2p/setup.py", line 47, in <module>
        scripts=['scripts/readelf.py']
      File "/devel/pyelftools/.tox/py27/lib/python2.7/site-packages/setuptools/__init__.py", line 144, in setup
        _install_setup_requires(attrs)
      File "/devel/pyelftools/.tox/py27/lib/python2.7/site-packages/setuptools/__init__.py", line 137, in _install_setup_requires
        dist.parse_config_files(ignore_option_errors=True)
      File "/devel/pyelftools/.tox/py27/lib/python2.7/site-packages/setuptools/dist.py", line 704, in parse_config_files
        self._parse_config_files(filenames=filenames)
      File "/devel/pyelftools/.tox/py27/lib/python2.7/site-packages/setuptools/dist.py", line 600, in _parse_config_files
        reader = io.TextIOWrapper(fp, encoding=encoding)
    LookupError: unknown encoding:
```

This is due to the specification of LC_ALL as simply `en_US` without an encoding. Python 3.x seems to be fine with this, but Python 2.7 barfs. As a fix, setting `LC_ALL` to `en_US.utf-8` (including an explicit encoding spec) works.

Also decode strings in _DynamicStringTable.get_string() (#217)

StringTableSection.get_string() returns an UTF-8 decoded
string (or '' if fetching the string failed) since #182
but the code in _DynamicStringTable was never updated to
decode anything at all so it just returns a bytes sequence
in Python 3.

Let's convert the string there as well to be able to use
both string tables the same way without having to worry
about decoding. Adapt the test cases accordingly.

Remove py34 testing target

Small stylistic fixes

Fixup error on empty .debug_pubtypes section (#215)

* tox: explicitly set locale

Locale affects GNU binutils output translation which cause
run_readelf_tests.py to fail if system language is not English.

Signed-off-by: Efimov Vasily <real@ispras.ru>
* test: unittest reproducing error with empty ".debug_pubtypes" section

Signed-off-by: Efimov Vasily <real@ispras.ru>
* NameLUT: use `construct.If` to declare "name" field

This patch also fixes problem with empty first entry.

Signed-off-by: Efimov Vasily <real@ispras.ru>
* NameLUT._get_entries: remove unused `bytes_read`

Signed-off-by: Efimov Vasily <real@ispras.ru>

Support for DWARFv4 location lists in dwarf_location_lists.py (#214)

In DWARFv4 the location lists are referenced with the 'sec_offset'
attribute form instead of 'data4' or 'data8'.

More efficient AbbrevDecl handling (#212)

Create all the AbbrevDecl objects during parsing and later return
references to them - this gives a small performance gain.

Added support for decoding .debug_pubtypes and .debug_pubnames sections (#208)

* Added support for decoding .debug_pubtypes and .debug_pubnames sections

* Added reference output to dwarf_pubnames_types.py example.

* Added readelf support, fixed review comments and documentation updates

* Avoid printing the entire die in pubnames example to workaround Python2 vs 3 imcompatibilites

Simplify handling of null DIEs (#209)

The code that is intended to coalesce null DIEs into the DIE that
precedes them does not do that and is actually not needed as the
'unflattening' procedure takes care of any unexpected null DIEs.

Also added a unit test for verifying the DIE size calculation.

Bugfix: Reset prevstate if line program sequence ends (#211)

Implemented ELFFile.get_machine_arch for the remaining architectures. (#206)

* Implemented ELFFile.get_machine_arch for the remaining architectures.

Added all architectures according to the ENUM_E_MACHINE.

* Refactored if statement into dict.get.

Remove unnecessary 'preserve_stream_pos' (#204)

The stream position in the .debug_info stream can't change when
reading from the .debug_abbrev stream.

ARMAttribute: fix access to structs, stream and nul (#203)

The __init__ function of ARMAttribute has two parameters
structs and stream through which the caller can pass in the
relevant objects (ARMAttributesSubsubsection does that after
seeking to the right position in stream).

The accesses for TAG_SECTION and TAG_SYMBOL, however, were
referring to non-existing members instead of the parameters.

Additionally, one assertion tries to access an undefined
'null_byte' variable which should be 'nul' instead.

Provide enums for DT_FLAGS and DT_FLAGS_1 (#200)

* Provide enums for DT_FLAGS and DT_FLAGS_1

This change adds two enums with the name to value mappings
for the two flags fields in the dynamic section. The values
and corresponding names are taken from the elf/elf.h file
in the most recent glibc version.

The enums are also used to print the names instead of the
raw hex values for DT_FLAGS and DT_FLAGS_1 in
scripts/readelf.py.

Fixes: #189
* Add test file for DT_FLAGS/DT_FLAGS_1 parsing

The test file has the DF_BIND_NOW and DF_ORIGIN flags set
in DT_FLAGS as well as DF_1_NOW, DF_1_GLOBAL, DF_1_NOOPEN
and DF_1_ORIGIN flags in DF_FLAGS_1.

This is the source code for the dt_flags.elf file:

  #include <stdio.h>

  int function(const char *arg){
      printf("Hello, %s!", arg);
      return 0;
  }

and was compiled using the following command line:

$ gcc -shared -m32 \
  -Wl,-rpath,'$ORIGIN/lib',-z,global,-z,origin,-z,nodlopen,-z,now \
  -o testfiles_for_readelf/dt_flags.elf dt_flags.c

Fix division in calculation function for 'R_ARM_CALL' (#196)

Move arm reloc test to proper location and simplify its code a bit

Simplify arm reloc test file

Rename input files for arm relocation test to be more consistent

Redo the new arm reloc test as a proper unit test, aligned with other tests

Call relocation for ARM V3 (#194)

* Add support for 'R_ARM_CALL' relocation type

* Add test script and test files to verify support for 'R_ARM_CALL'

Signed-off-by: Koltunov Dmitry <koltunov@ispras.ru>

Add .o test files to manifest

Update version to 0.25 to prepare for release

Update CHANGES, add 3.6 testing to Travis and fixup README

Handle ARM relocations (#121)

* relocation: handle ARM binaries

* relocation: handle R_ARM_ABS32 for ARM machines

* testfiles: add reloc_arm_gcc.o.elf

Generated on Ubuntu 14.04 using: arm-linux-gnueabi-gcc-4.7 -c -g -o reloc_armhf_gcc.o.elf hello.c

* testfiles: add reloc_armhf_gcc.o.elf

Generated on Ubuntu 14.04 using: arm-linux-gnueabihf-gcc-4.7 -c -g -o reloc_armhf_gcc.o.elf hello.c

* readelf: print soft-float abi for ARM if EF_ARM_ABI_FLOAT_SOFT in flags

* readelf: print hard-float abi for ARM if EF_ARM_ABI_FLOAT_HARD in flags

* readelf: print BE8 info for armeb binaries

* testfiles: add simple_armhf_gcc.o.elf

    Generated on Ubuntu 14.04 using: arm-linux-gnueabihf-gcc-4.7  -g -o simple_armhf_gcc.o.elf hello.c

* elf: remove unwind from dicts and set ARM_EXIDX description

* testfiles: add  reloc_armsf_gcc.o.elf as soft float testcase taken from binutils 2.30

* testfiles: add reloc_armeb_gcc.o.elf as arm big endian testcase taken from binutils 2.30 testcase arm-be8

* readelf: print endian info LE8 if flag was set in header flags

Enable --parallel tests for readelf in the tox config

Merge branch 'master' of github.com:eliben/pyelftools

Add basic parallel execution capabilities to readelf tests

Add timings for steps of execution in running these tests

Update CHANGES

Switch readelf.py to using argparse instead of optparse

Switch run_readelf_tests to use argparse instead of optparse

Fix DW_CFA_remember_state (#184)

* Fix #103

* Fix description for DW_CFA_def_cfa_expression

* Add test file for issue #103

Choose members of the dynamic tag enum based on the current machine (#183)

* Only use processor/os specific dynamic tags if that processor or os is in use

* Add testcase for machine-specific dynamic tags

* Clarify layout of ENUM_D_TAG

Convert all ascii decoding to utf-8 decoding (#182)

* Convert all ascii-decoding to utf-8 decoding

* Add testcase for unicode symbols

Fix #181 for real

EM_BLAKCFIN --> EM_BLACKFIN

Merge branch 'master' of github.com:eliben/pyelftools

Fix a typo EM_BLAFKIN --> EM_BLACKFIN

Fixes #181

Update README

Do not crash if CIE doesn't define CFA (#177)

Mention recent changes in CHANGES

e_machine-dependent p_type parsing;

This should address #71 and #121, hopefully

Implement e_machine-based section type decoding

Adding a dict-merging utility

Some whitespace fixes

Don't include 'meta-tag' markers in descriptions of ENUM_D_TAG (#176)

Fixes #150

Add a local .vimrc for pyelftools

Fix merge conflicts for ABIFLAGS branch (#168)

Arm exidx (#172)

* Fix merge conflicts for ABIFLAGS branch

* Fix EXIDX output to match binutils readelf -e

Many improvements to MIPS flags handling to make output consistent with GNU binutils readelf + typo (#165)

* Add EF_MIPS_PIC for E_FLAGS for statically linked MIPS-I executable produced by MUSL

pyelftools picked up CPIC but not PIC

binutils readelf says:
  Flags:                             0x1007, noreorder, pic, cpic, o32, mips1

pyelftools said (before this change):
  Flags:                             0x1007, noreorder, cpic, o32, mips1

Reproduce with the binary available at:

https://github.com/mzpqnxow/embedded-toolkit/blob/master/prebuilt_static_bins/gdbserver/gdbserver-6.8-mips-i-rtl819x-lexra

* Fix order of fix, was "cpic, pic" needs to be "pic, cpic", reordered the if statement to address this

* - Improve reporting on MIPS flags, fix many inconsistencies with GNU binutils
- Fix `desrciption` typo that raises fatal exception when encountering an unknown ABI
- Add E_FLAGS_MASKS constants to simplify ABI logic

* Add masks for E_FLAGS to simplify ABI logic

Add TLS and PowerPC to Machine and Program Headers description tables to match binutils output (#163)

Before:
...
  Machine:                           <unknown>
...
Program Headers:
...
  <unknown>      0x0bcd0c 0x100ccd0c 0x100ccd0c 0x00000 0x00008 R   0x4
...

After:
...
  Machine:                           PowerPC
Program Headers:
...
  TLS            0x0bcd0c 0x100ccd0c 0x100ccd0c 0x00000 0x00008 R   0x4
...

Reproduced and then tested change against statically linked PPC binary produced by MUSL:

https://github.com/mzpqnxow/embedded-toolkit/blob/master/prebuilt_static_bins/gdbserver/gdbserver-7.12-ppc-sysv

ARM build attributes section parsing (#160)

DIE.__repr__ typo: s/chidren/children/ (#161)

Clean up some whitespace

Fix - ELFFile#address_offsets should consider PT_LOAD only (#159)

* fix - ELFFile#address_offsets should consider PT_LOAD only

create inital wheel support (#158)

Update the shipped `readelf` (#157)

* elftools.elf.description: re-indent describe_note according to PEP8

* Update the embedded `readelf`, update readelf.py accordingly

Clean up py3compat a bit and add some tests

Add parsing and readelf dumping for .eh_frame (#155)

* Fix the byte size for R_X86_64_PC32 relocations

* Describe the address for DW_CFA_advance_loc with only 8 columns

* Add .eh_frame section decoding and dump in readelf.py

Minor testsuite improvements (#154)

* run_readelf_tests.py: add an option to continue tests after a failure

Also add a counter to display the number of failed tests over the number
of tests run.

* run_readelf_tests.py: run tests in alphabetical order

This gives deterministic runs, which is handy to run edit/test
development cycles.

Compressed sections (#152)

* Add constants, enums and structs for compressed section

* ELFStructs: update comments for new section numbers in Oracle docs

* Make the ELFFile's stream/structs available to all Section instances

This harmonizes the signature of Section constructors. Besides, structs
will be required to read compressed sections.

* ELFFile._read_dwarf_section: use Section.data to read the section

An upcoming change will add compressed sections handling. In this
context, the DWARF must be parsed from the decompressed data, so reading
the ELFFile stream will be wrong.

* Add ELF compressed debug sections handling

Adding new OS ABI to ELF header parsing (#153)

* Add OS ABI to ELF header

* Add new OS ABI to description

Cosmetic fixups

Better support for core dumps (in particular, fix issue #93) (#147)

* Better support for core dumps (in particular, fix notes issue)

* Fix readelf.py for python3.

* Edits after code review. Introduce structure for NT_PRPSINFO. Add unittest.