gdb_helper.c

//                                                                          //
//                 _  _          _            _                             //
//       __ _   __| || |__      | |__    ___ | | _ __    ___  _ __  ___     //
//      / _` | / _` || '_ \     | '_ \  / _ \| || '_ \  / _ \| '__|/ __|    //
//     | (_| || (_| || |_) |    | | | ||  __/| || |_) ||  __/| | _| (__     //
//      \__, | \__,_||_.__/_____|_| |_| \___||_|| .__/  \___||_|(_)\___|    //
//      |___/             |_____|               |_|                         //
//                                                                          //

/*****************************************************************************

    X11workbench - X11 programmer's 'work bench' application and toolkit
    Copyright (c) 2010-2019 by Bob Frazier (aka 'Big Bad Bombastic Bob')
                           all rights reserved

  DISCLAIMER:  The X11workbench application and toolkit software are supplied
               'as-is', with no warranties, either implied or explicit.

  BSD-like license:

  There is no restriction as to what you can do with this software, so long
  as you include the above copyright notice and DISCLAIMER for any distributed
  work that is linked with, equivalent to, or derived from any portion of this
  software, along with this paragraph that explains the terms of the license if
  the source is also being made available.  "Linked with" includes the use of a
  portion of any of the source and/or header files, or their compiled binary
  output, as a part of your application or library.   A "derived work"
  describes a work that uses a significant portion of the source files or the
  algorithms that are included with this software.

  EXCLUSIONS

  Specifically excluded from this requirement are files that were generated by
  the software, or anything that is included with the software that is part of
  another package (such as files that were created or added during the
  'configure' process).

  DISTRIBUTION

  The license also covers the use of part or all of any of the X11 workbench
  toolkit source or header files in your distributed application, in source or
  binary form.  If you do not ship the source, the above copyright statement
  and DISCLAIMER is still required to be placed in a reasonably prominent
  place, such as documentation, splash screens, and/or 'about the application'
  dialog boxes.

  Use and distribution are in accordance with GPL, LGPL, and/or the above
  BSD-like license.  See COPYING and README.md files for more information.

  Additionally, this software, in source or binary form, and in whole or in
  part, may be used by explicit permission from the author, without the need
  of a license.

  Additional information at http://sourceforge.net/projects/X11workbench
  and http://bombasticbob.github.io/X11workbench/

******************************************************************************/



#include "X11workbench.h"
#include "gdb_helper.h"

#include "platform_helper.h"


// NOTES:
//
// command line gdb {executable} where '{executable}' is the binary executable file
//
// (NOTE:  output of 'gdb' typically ends with the text "(gdb)" which then waits for input)
//
// commands from within gdb that should be useful:
//
// set height 0
//   this will eliminate the "Type <return> to continue, or q <return> to quit" prompting
//
//
// list ,main
//   this will set the 'main()' source file as "current source" and allow 'info source' to work
//
// info source
//   information on the 'current' source file being displayed.  output similar to this:
//     Current source file is X11workbench.c
//     Compilation directory is /d-drive/SecureStorage/root/source/X11workbench
//     Located in /d-drive/SecureStorage/root/source/X11workbench/X11workbench.c
//     Contains 2306 lines.
//     Source language is c.
//     Compiled with DWARF 2 debugging format.
//     Does not include preprocessor macro info.
//
//
// To get a list of all files/functions, use 'info function' and then pick a function to load via 'list ,function'
//
//
// **NOTE** - the debugger source path is the canonical one, not necessarily the one for the file(s) being edited,
//            so use WBGetCanonicalPath() to make sure that I compare the path names correctly for open files.
//
//
// info sources
//   information on ALL source files.  output similar to this:
//     Source files for which symbols have been read in:
//
//     X11workbench.c, file_help.h, window_helper.h
//
//     Source files for which symbols will be read in on demand:
//
//     dialog_controls.c, dialog_window.c, clipboard_helper.c, text_object.c, platform_helper.c, window_dressing.c, draw_text.c,
//     file_help.c, conf_help.c, menu_popup.c, menu_bar.c, menu.c, dialog_support.c, dialog_impl.c, frame_window.c, child_frame.c,
//     edit_window.c, font_helper.c, window_helper.c, pixmap_helper.c, gizzard.c
//
//
// info function:
//
//   command:  info function WBInit\b   <-- the '\b' causes an exact match
//
//   output:
//
//     All functions matching regular expression "WBInit\b":
//
//     File window_helper.c:
//     Display *WBInit(const char *);
//
//
// info functions
//   this gives you a list of ALL functions and the source files that define them. example:
//
//     All defined functions:
//
//     File pixmap_helper.c:
//     Pixmap PXM_GetIconPixmap(int, XPM_ATTRIBUTES *, Pixmap *);
//     Pixmap PXM_GetIconPixmapFromAtom(Atom, XPM_ATTRIBUTES *, Pixmap *);
//       ...
//     static int clip255(int);
//
//     File font_helper.c:
//     XFontStruct *WBCopyFont(XFontStruct *);
//     XFontSet WBCopyModifyFontSet(Display *, XFontSet, int, int);
//     void WBDumpFontInfo(const char *);
//     int WBFontAvgCharWidth(Display *, const XFontStruct *);
//     ...
//
//     etc.
//
//   the list will include static functions appropriate to each source file, and ends with
//   a bunch of addresses labeled 'non-debugging symbols':
//
//     Non-debugging symbols:
//     0x0000000000404248  _init
//     0x000000000040426c  XSetInputFocus
//     0x000000000040427c  XFreePixmap
//     ...
//     0x0000000000405070  _start
//     0x0000000000405110  __do_global_dtors_aux
//     0x0000000000405150  frame_dummy
//     0x0000000000453f80  __do_global_ctors_aux
//     0x0000000000453fb4  _fini
//
//   Apparently, none of these have source available (typically contained in a linked-to library)
//
//
//
// other commands like list, backtrace, breakpoint, etc. can be applied as needed.
//
//
//
// ------------------------------
// Server/mouse/keyboard grabbing
// ------------------------------
//
// If XGrabServer() has been called, then everything will appear to freeze up during breakpoint handling.
// If XGrabKeyoard() or XGrabPointer() have been called, the kb/mouse will appear to freeze up.
//
// Additionally, calling XGrabKeyoard() or XGrabPointer() on the application window (for example) would
// return 'AlreadyGrabbed' if a grab is already in effect.  it might be prudent to grab the keyboard/mouse
// this way whenever a breakpoint is reached, in order to avoid deadlocking the system.
//
// Alternately, a watchdog timer could call XUngrabServer() after a time period, using event handling (in general)
// to detect that no events are being received.  A watchdog COULD post a client event to the main window via a
// timer, and then detect whether the event has arrived.
//
// Without additional info, the grab won't be "restorable" on return from the breakpoint.  An
// appropriate warning message should appear if the debugger has to 'Ungrab' something.
//