# gdb
--------------------------------------------------------------------------------

# toc
------
  |gdb|
    |opts|
    |prompt|
    |user_commands|
    |hooks|
    |flows|

# gdb(1)                                                                   *gdb*
=========
  gdb [opts] [exe [coredump | pid]]
  gdb [opts] --args exe <exe-args>
    opts:                                                                 *opts*
      -p <pid>        attach to pid
      -x <file>       execute script <file> before prompt
      -ex <cmd>       execute command <cmd> before prompt
      --tty <tty>     set I/O tty for debugee (see *prompt* for details)


    prompt:                                                             *prompt*
      tty <tty>             set <tty> as tty for debugee.  make sure nobody
                            reads from target tty, easiest is to spawn a shell
                            and run
                            > while true; do sleep 1024; done

      set follow-fork-mode <child | parent>
                            specify which process to follow on fork(2)

      sharedlibrary [regex]
                            load symbols of shared lib, if REGEX then only symbols
                            for matching libs

      break [-qualified] <sym> thread <tnum>
                            set a breakpoint only on a specific thread
                            -qualified: sym must be fully qualified (quiet handy
                            to set breakpoints on C symbols in C++ contexts)

      rbreak <regex>        set breakpoints based on symbols matching regex
                            <regex> is internally expanded to .*<regex>.*
                            so 'rbreak foo' matches barfoobar()

      command [bp_list]     define commands to run after breakpoint hit if
                            BP_LIST not supplied attach command to last
                            created bp

                            BP_LIST: space separates list, eg 'command 2 5-8'
                            to run command for bp 2,5,6,7,8

      info functions [regex]
                            list functions according to REGEX, if REGEX empty,
                            list all

      info variables [regex]
                            list variables according to REGEX, if REGEX empty,
                            list all

      info handle [signal]
                            list bevahior for SIGNAL, if SIGNAL empty list all signals

      handle signal <action>
                            configure how gdb handles SIGNAL which is ment for the debugee
                            <action>:
                              stop/nostop       catch signal in gdb and break
                              print/noprint     print message when gdb catches signal
                              pass/nopass       pass signal down to debugee
                              noignore/ignore   synonyms for

      catch signal <signal>
                            create a catchpoint for SIGNAL


    user commands:                                               *user_commands*
      define <cmd>                  defines user command <cmd> to be run
        # cmds                      in prompt or script
      end

      document <cmd>                define documentation for cmd <cmd>
        # docu
      end

      help user-defined             list user defined commands
      help <cmd>                    list documentation for command <cmd>


    hooks:                                                               *hooks*
      define hook-<cmd>             run commands defined in hook before
        # cmds                      executing <cmd>
      end

      define hookpost-<cmd>         run commands defined in hookpost after
        # cmds                      executing <cmd>
      end


    flows:                                                               *flows*
      # catch SIGSEGV and execute some actions once it happends
      - script:
        catch signal SIGSEGV
        command
          bt
          c
        end

      # quickly execute gdb command on running process, eg get backtrace from
      # thread 1
      - cmd:
        $> gdb -ex 'thread 1' -ex 'bt' -p <PID>

      # script gdb for automating debugging sessions
      - script: run.gdb
        set pagination off

        break mmap
        command
        info reg rdi rsi rdx
        bt
        c
        end

        #initial drop
        c

      - cmd:
        $> gdb -p <PID> -x ./run.gdb  --batch &> run.log

    # workaround command + finish bug
    # issue: when using finish in a command block, actions after finish will not
    # be executed
    - script:
      define handler
      bt
      finish
      info reg rax
      end

      command
      handler
      end

--------------------------------------------------------------------------------
vim:ft=help:sts=2:et:tw=80:cc=80:fo+=t