## Frequently Asked Questions

## Why use GEF over PEDA?

[PEDA](https://github.com/longld/peda) is a fantastic tool that provides similar commands to make
the exploitation development process smoother.

However, PEDA suffers from a major drawbacks, which the code is too fundamentally linked to Intel
architectures (x86-32 and x86-64). On the other hand, GEF not only supports all the architecture
supported by GDB (currently x86, ARM, AARCH64, MIPS, PowerPC, SPARC) but is designed to integrate
new architectures very easily as well!

Also, PEDA development has been quite idle for a few years now, and many new interesting features a
debugger can provide simply do not exist.

## What if my GDB is < 10.0 ?

GDB was introduced with its Python support early 2011 with the release of GDB 7. A (very) long way
has gone since and the Python API has been massively improved, and GEF is taking advantage of them
to provide the coolest features with as little performance impact as possible.

Currently, GEF is optimized for running against GDB version 10.0+, and Python 3.10+. This allows for
the best performance and use of the GDB Python API. However, GEF can run on older versions too,
check out [the version compatibility matrix](compat.md). For really older versions of GDB, you can
use [`gef-legacy`](https://github.com/hugsy/gef-legacy) which supports a lot of older GDB, and a
Python 2/3 compatibility layer.

Therefore, it is highly recommended to run GEF with the latest version of GDB. However, all
functions should work on a GDB 10.0 and up. If not, send a [bug
report](https://github.com/hugsy/gef/issues) and provide as many details as possible.

If you are running an obsolete version, GEF will show a error and message and exit.

Some pre-compiled static binaries for both recent GDB and GDBServer can be downloaded from the
[`gdb-static`](https://github.com/hugsy/gdb-static) repository.

## I cannot get GEF setup

GEF will work on any GDB 10+ compiled with Python 3.10+ support. You can view that commands that
failed to load using `gef missing`, but this will not affect GEF generally.

If you experience problems setting it up on your host, first go to the [Discord
channel](https://discord.gg/HCS8Hg7) for that. You will find great people there willing to help.

Note that the GitHub issue section is to be used to **report bugs** and **GEF issues** (like
unexpected crash, improper error handling, weird edge case, etc.), not a place to ask for help.

All recent distributions ship packaged GDB that should be ready-to-go, with GDB >= 10.0 and Python
3.10+. Any version higher or equal will work just fine. So you might actually only need to run `apt
install gdb` to get the full-force of GEF.

## I get a SegFault when starting GDB with GEF

A long standing bug in the `readline` library can make `gef` crash GDB when displaying certain
characters (SOH/ETX). As a result, this would SIGSEGV GDB as `gef` is loading, a bit like this:

```text
root@debian-aarch64:~# gdb -q ./test-bin-aarch64
GEF ready, type `gef' to start, `gef config' to configure
53 commands loaded, using Python engine 3.4
[*] 5 commands could not be loaded, run `gef missing` to know why.
[+] Configuration from '/root/.gef.rc' restored
Reading symbols from ./bof-aarch64...(no debugging symbols found)...done.
Segmentation fault (core dumped)
```

If so, this can be fixed easily by setting the `gef.readline_compat` variable to `True` in the
`~/.gef.rc` file. Something like this:

```text
root@debian-aarch64:~# nano ~/.gef.rc
[...]
[gef]
readline_compat = True
```

You can now use all features of `gef` even on versions of GDB compiled against old `readline`
library.

## Does GEF prevent the use of other GDB plugins?

Definitely not! You can use any other GDB plugin on top of it for an even better debugging
experience.

Some interesting plugins highly recommended too:

-  [!exploitable](https://github.com/jfoote/exploitable/)
-  [Voltron](https://github.com/snare/voltron)

![voltron](https://raw.githubusercontent.com/hugsy/gef/refs/heads/main/docs/assets/images/voltron.png)
Src: [@rick2600: terminator + gdb + gef + voltron cc: @snare @_hugsy_](https://twitter.com/rick2600/status/775926070566490113)

## I want to contribute, where should I head first?

I would suggest thoroughly reading this documentation, just having a look to the
[CONTRIBUTE](https://github.com/hugsy/gef/blob/main/.github/CONTRIBUTING.md) file of the project to
give you pointers.

Also a good thing would be to join our [Discord channel](https://discord.gg/HCS8Hg7) to get in touch
with the people involved/using it.

## I think I've found a bug, how can I help fixing it?

`gef` is only getting better through people (like you!) using it, but most importantly reporting
unexpected behavior.

In most locations, Python exceptions will be properly intercepted. If not, `gef` wraps all commands
with a generic exception handler, to disturb as little as possible your debugging session. If it
happens, you'll only get to see a message like this:
![gef-exception](https://raw.githubusercontent.com/hugsy/gef/refs/heads/main/docs/assets/images/gef-exception.png)

By switching to debug mode, `gef` will give much more information:

```text
gef➤  gef config gef.debug 1
```

![gef-debug](https://raw.githubusercontent.com/hugsy/gef/refs/heads/main/docs/assets/images/gef-debug.png)

If you think fixing it is in your skills, then send a [Pull
Request](https://github.com/hugsy/gef/pulls) with your patched version, explaining your bug, and
what was your solution for it.

Otherwise, you can open an [issue](https://github.com/hugsy/gef/issues), give a thorough description
of your bug and copy/paste the content from above. This will greatly help for solving the issue.

## I get weird issues/characters using GDB + Python3, what's up?

Chances are you are not using UTF-8. Python3 is [highly relying on
UTF-8](https://www.diveintopython3.net/strings.html) to display correctly characters of any alphabet
and [also some cool emojis](https://unicode.org/emoji/charts/full-emoji-list.html). When GDB is
compiled with Python3, GEF will assume that your current charset is UTF-8 (for instance,
`en_US.UTF-8`). Use your `$LANG` environment variable to tweak this setting.

In addition, some unexpected results were observed when your local is not set to English. If you
aren't sure, simply run `gdb` like this:

```text
LC_ALL=en_US.UTF-8 gdb /path/to/your/binary
```

## GDB crashes on ARM memory corruption with `gdb_exception_RETURN_MASK_ERROR`

This issue is **NOT** GEF related, but GDB's, or more precisely some versions of GDB packaged with
Debian/Kali for ARM

>
> Original Issue and Mitigation
>
> gdb version 7.12, as distributed w/ Raspbian/Kali rolling (only distro's
> tested,) throws an exception while disassembling ARM binaries when using gef.
> This is not a gef problem, this is a gdb problem. gef is just the tool that
> revealed the gdb dain bramage! (The issue was not observed using vanilla
> gdb/peda/pwndbg) This issue was first noted when using si to step through a
> simple ARM assembly program (noted above) when instead of exiting cleanly,
> gdb's disassembly failed with a SIGABRT and threw an exception:
>
> `gdb_exception_RETURN_MASK_ERROR`
>
> This turns out to be a known problem (regression) with gdb, and affects
> gef users running the ARM platform (Raspberry Pi).
>
> The mitigation is for ARM users to compile gdb from source and run the latest
> version, 8.1 as of this writing.
>

**Do not file an issue**, again it is **NOT** a bug from GEF, or neither from GDB Python API.
Therefore, there is nothing GEF's developers can do about that. The correct solution as mentioned
above is to recompile your GDB with a newer (better) version.

The whole topic was already internally discussed, so please refer to the
[issue 206](https://github.com/hugsy/gef/issues/206) for the whole story.

## I still don't have my answer... Where can I go?

Discord is your answer: join and talk to us by clicking here

[![Discord](https://img.shields.io/badge/Discord-GDB--GEF-yellow)](https://discord.gg/HCS8Hg7)

If you cannot find the answer to your problem here or on the Discord, then go to the project [Issues
page](https://github.com/hugsy/gef/issues) and fill up the forms with as much information as you
can!

## How can I use GEF to debug a process in a container?

GEF can attach to a process running in a container using `gdb --pid=$PID`, where `$PID` is the ID of
the running process _on the host_. To find this, you can use `docker top <container ID> -o pid | awk
'!/PID/' | xargs -I'{}' pstree -psa {}` to view the process tree for the container.

`sudo` may be required to attach to the process, which will depend on your system's security
settings.

Please note that cross-container debugging may have unexpected issues. Installing gdb and GEF inside
the container, or using [the official GEF docker image](https://hub.docker.com/r/crazyhugsy/gef) may
improve results.
