{"id":25949804,"url":"https://github.com/cisco-open/ruby-elf_utils","last_synced_at":"2025-06-11T10:07:56.464Z","repository":{"id":279626105,"uuid":"931151354","full_name":"cisco-open/ruby-elf_utils","owner":"cisco-open","description":"Ruby gem for parsing ELF files and DWARF debugging information","archived":false,"fork":false,"pushed_at":"2025-02-26T14:24:34.000Z","size":177,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-26T15:31:51.267Z","etag":null,"topics":["dwarf","dwarf-parser","elf","elf-parser","ruby","rubygem"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cisco-open.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-11T19:53:12.000Z","updated_at":"2025-02-26T14:24:38.000Z","dependencies_parsed_at":"2025-02-26T15:33:23.736Z","dependency_job_id":"f84e5ce6-eaed-4935-ae41-f2958b161334","html_url":"https://github.com/cisco-open/ruby-elf_utils","commit_stats":null,"previous_names":["cisco-open/ruby-elf_utils"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cisco-open%2Fruby-elf_utils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cisco-open%2Fruby-elf_utils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cisco-open%2Fruby-elf_utils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cisco-open%2Fruby-elf_utils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cisco-open","download_url":"https://codeload.github.com/cisco-open/ruby-elf_utils/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241847461,"owners_count":20030257,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dwarf","dwarf-parser","elf","elf-parser","ruby","rubygem"],"created_at":"2025-03-04T12:29:14.984Z","updated_at":"2025-03-04T12:29:15.591Z","avatar_url":"https://github.com/cisco-open.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ElfUtils\n\n[![Version](https://img.shields.io/gem/v/elf_utils.svg)](https://rubygems.org/gems/elf_utils)\n[![GitHub](https://img.shields.io/badge/github-elf__utils-blue.svg)](http://github.com/cisco-open/ruby-elf_utils)\n[![Documentation](https://img.shields.io/badge/docs-rdoc.info-blue.svg)](https://rubydoc.info/gems/elf_utils/frames)\n\n[![Contributor-Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-fbab2c.svg)](CODE_OF_CONDUCT.md)\n[![Maintainer](https://img.shields.io/badge/Maintainer-Cisco-00bceb.svg)](https://opensource.cisco.com)\n\nElfUtils is a Ruby gem for parsing ELF files and DWARF debugging information.\n\nElfUtils supports 32-bit \u0026 64-bit ELF format, both big and little endian.  It\nalso supports DWARF versions 2, 3, 4, and 5.  The handling of both ELF and\nDWARF formats **is not currently exhaustive**, but is sufficient to perform\nmany common tasks such as calculating symbol address, finding symbol source\nlocation, extracting variable data types.\n\nIf you encounter a place where the format support is incomplete, please open\nan issue.  We test against the generated binaries in [spec/data/](spec/data),\nbut need more real-world examples to ensure proper format coverage.\n\n## Installation\n\nInstall the gem and add to the application's Gemfile by executing:\n\n    $ bundle add elf_utils\n\nIf bundler is not being used to manage dependencies, install the gem by executing:\n\n    $ gem install elf_utils\n\n## Usage\nElfUtils covers a lot of ELF \u0026 DWARF functionality.  The best source for usage\nwill be the documentation.  This is a small example of using ElfUtils to\nread a complex type from the memory of a running process, given an executable\nwith DWARF debugging information to determine types.\n\n```ruby\nrequire \"elf_utils\"\n\n# open an ELF file, in this case an executable\nelf_file = ElfUtils.open(\"a.out\")\n\n# get the Symbol instance for a global variable\nsymbol = elf_file.symbol(:some_global_var)      # =\u003e #\u003cElfUtils::Symbol ...\u003e\n\n# get the address of the symbol\naddr = symbol.addr                              # =\u003e 0x40001000\n\n# relocate the load segments to account for ASLR.  Addresses for load segments\n# extracted from /proc/pid/map.\nelf_file.load_segments[0].relocate(text_addr)\nelf_file.load_segments[1].relocate(data_addr)\n\n# get the address of the symbol after relocation\naddr = symbol.addr                              # =\u003e 0x90301000\n\n# get the data type for the symbol; requires DWARF debug information\ntype = symbol.ctype                             # =\u003e #\u003cCTypes::Struct ...\u003e\n\n# open the memory for a process running this executable, and read the value of\n# the global variable.\nvalue = File.open(File.join(\"/proc\", pid, \"mem\")) do |mem|\n    # read the raw bytes for the variable\n    bytes = mem.pread(type.size, addr)          # =\u003e \"\\xef\\x99\\xde... \"\n\n    # unpack the bytes\n    type.unpack_one(bytes)                      # =\u003e { field: val, ... }\nend\n```\n\n### bin/dump_ctypes.rb\n[bin/dump_ctypes.rb] reads the `.debug_info` section of an ELF file, and\ngenerates ruby code to create each data type found in the binary.  This is\nparticularly useful for exporting types for use with foreign-function interface\n(FFI).\n\n```sh\n~/src/elf_utils\u003e bundle exec ./bin/dump_ctypes.rb spec/data/complex_64be-dwarf64-v5 \u003e types.rb\ncu[  0] 0x0        (   0kb)  spec/data/test.c\ncu[  1] 0xdb       (   1kb)  spec/data/types.c\n~/src/elf_utils\u003e head types.rb\nmodule Types\n  extend CTypes::Helpers\n\n  def self.with_bitfield\n    @with_bitfield ||= CTypes::Struct.builder()\n      .name(\"with_bitfield\")\n      .endian(:big)\n      .attribute(bitfield {\n          field :a, offset: 31, bits: 1, signed: false\n          field :b, offset: 29, bits: 2, signed: true\n```\n\n## Roadmap\n\nSee the [open issues](https://github.com/cisco-open/ruby-elf_utils/issues) for\na list of proposed features (and known issues).\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run\n`rake spec` to run the tests. You can also run `bin/console` for an interactive\nprompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To\nrelease a new version, update the version number in `version.rb`, and then run\n`bundle exec rake release`, which will create a git tag for the version, push\ngit commits and the created tag, and push the `.gem` file to\n[rubygems.org](https://rubygems.org).\n\nRunning the test suite requires a recent version of llvm be installed.  The\ntests use `llvm-readelf` and `llvm-dwarfdump` for verification.\n\n## Contributing\n\nContributions are what make the open source community such an amazing place to\nlearn, inspire, and create. Any contributions you make are **greatly\nappreciated**. For detailed contributing guidelines, please see\n[CONTRIBUTING.md](CONTRIBUTING.md)\n\n## License\n\nThe gem is available as open source under the terms of the\n[MIT License](https://opensource.org/licenses/MIT). License. See\n[LICENSE.txt](LICENSE.txt) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcisco-open%2Fruby-elf_utils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcisco-open%2Fruby-elf_utils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcisco-open%2Fruby-elf_utils/lists"}