Provided by: libdevel-gdb-perl_2.02-1_all bug

NAME

       Devel::GDB - Open and communicate a gdb session

SYNOPSIS

           use Devel::GDB;

           $gdb = new Devel::GDB();
           print $gdb->send_cmd('-environment-path');
           print $gdb->get('info functions');

       The old "get" syntax (of "Devel::GDB-1.23") has been deprecated and will not be supported
       in future versions.  See the documentation of the "get" function for an explanation of
       why.

       If you really want to use the old syntax, set $Devel::GDB::DEPRECATED to true:

           use Devel::GDB ;

           $Devel::GDB::DEPRECATED = 1;
           $gdb = new Devel::GDB();
           print $gdb->get('info functions', $timeout, $prompt, $notyet, $alldone);

DESCRIPTION

       The "Devel::GDB" package provides an interface for communicating with GDB.  Internally, it
       uses the GDB/MI interpreter (see
       <http://sourceware.org/gdb/current/onlinedocs/gdb_25.html>), which accurately informs the
       caller of the program state and, through the use of tokens, guarantees that the results
       returned actually correspond to the request sent.  By contrast, GDB's console interpreter
       returns all responses on "STDOUT", and thus there is no way to ensure that a particular
       response corresponds to a particular request.

       Therefore, it is obviously preferable to use GDB/MI when programmatically interacting with
       GDB.  This can be done via the "send_cmd" family of functions ("send_cmd",
       "send_cmd_excl", and "send_cmd_async").  There are, however, some cases when there is no
       GDB/MI command corresponding to a particular console command, or it has not yet been
       implemented (for example, "-symbol-type", corresponding to the console command "ptype", is
       not yet implemented as of GDB 6.6).  In this case, the "get" function provides a
       workaround by capturing all output sent to the console stream.

CONSTRUCTOR

       new

           $gdb = new Devel::GDB( '-use-threads' => 1 );
                                  '-params'      => $extra_gdb_params );

       Spawns a new GDB process.  In threaded mode, this also spawns a listening thread that
       asynchronously processes responses from GDB; in non-threaded mode, the caller is
       responsible for handling asynchronous output (that is, output from GDB that is not
       directly solicited by a request).  See "demux", "get_reader", and the "Non-threaded Usage"
       example for further discussion.

       The parameters to the constructor are passed in hash form.  The following parameters
       control how GDB is invoked:

       "-execfile"
           The GDB binary to execute; defaults to "gdb".

       "-params"
           Pass additional parameters to GDB.  The value can be an array reference (preferred) or
           a string.

       The following parameters control how to handle interaction with the inferior process, the
       program being debugged.  The default behavior is to give the inferior process control of
       the terminal while it is running, returning control to perl when the program is suspended
       or stopped (emulating the behavior of gdb).  However, this only works when "STDIN" is
       associated with a tty.  Two other (mutually exclusive) options are available:

       "-use-tty"
           Specify the name of the tty that the inferior process should use for its I/O.  Note
           that this is the path to a tty (e.g. "/dev/pts/123") and not an "IO::Pty" object.  See
           the example "Debugging Inside an XTerm".

       "-create-expect"
           If this value is non-zero, create an "Expect" object (which can be subsequently
           retrieved by calling "get_expect_obj"); this is useful if you want to programmatically
           interact with the inferior process.  See the example "Programmatically Interacting
           with the Inferior Process".

       Miscellaneous parameters:

       "-use-threads"
           Operate in threaded (1) or non-threaded (0) mode.  The default behavior is to enable
           threaded mode if the "threads" module has been loaded and disable it otherwise.  Note
           that if "-use-threads" is enabled, the caller must call "use threads", but
           "-use-threads" can be disabled whether or not "threads" has been loaded.

           Threaded mode is the easiest to deal with, as it does not require the caller to
           interact with the GDB filehandles directly; for a simple non-threaded example, see the
           "Non-threaded Usage" example.

       "-readline-fn"
           Probably only useful in non-threaded mode, this lets the user specify a callback
           function $fn to be called when waiting for a response from GDB.  It is invoked with
           one parameter, the "Devel::GDB" instance, and is expected to return one full line of
           output (or "undef" if EOF was reached).  The default implementation uses buffered I/O:

               $fn = sub { return readline($_[0]->get_reader); }

           Typically, in non-threaded mode, the caller will be using "select" to multiplex
           multiple file streams (e.g. "STDIN" and "get_reader"); in this case, you will likely
           want to specify a value for "-readline-fn" which, at a minimum, uses "sysread" rather
           than "readline".

METHODS

       send_cmd
               $response = $gdb->send_cmd($command)

           Send $command to GDB, and block until a response is received.  In threaded mode, this
           does not prevent other threads from simultaneously sending requests.

           The $command can be a GDB/MI command, prefixed with a hyphen (e.g.  "-exec-run") or a
           console command ("run").  However, the response returned will always be a GDB/MI
           response, so "$gdb->send_cmd("info variables")" will only return "done"; the actual
           output you probably wanted will be dumped into the console stream.  To execute console
           commands and capture the output sent back to the console, use "get".

       send_cmd_excl
               $gdb->send_cmd_excl($cmd, $before_fn, $after_fn)

           Send $cmd to GDB in exclusive mode.  In threaded mode, this means that other
           "send_cmd" and "send_cmd_excl" calls will not coincide with this call.  In non-
           threaded mode, this ensures that any pending "send_cmd_async" calls are processed
           before proceeding.

           If provided, the $before_fn and $after_fn functions will, respectively, be called
           before the command is sent (after the exclusive lock is aquired) and after the result
           has been received (before the exclusive lock is released).

       send_cmd_async
               $gdb->send_cmd_excl($cmd, $callback_fn)

           Not yet implemented.

           Send $cmd to GDB in async mode.  This returns immediately, rather than blocking until
           a response is received; instead, the $callback_fn callback function is called, with
           the response as the first argument.

           This will likely only be supported in non-threaded mode.

       get
               $gdb->get($command)

           Issues the $command to GDB, and returns all output sent to the console output stream.
           Note that there is no way to ensure that the output "belongs" to a particular command,
           so it is possible that spurious output will be included!  In particular, if you call
           "$gdb->get($command)" immediately after creating the "Devel::GDB" object, and don't
           suppress GDB's initialization messages (by passing "-q" to "-params"), some of these
           messages may end up in the response to "get".

           In list context, returns "($buffer, $error)", with exactly one of the two defined;
           $buffer is the text captured from the console stream and $error is the GDB/MI error
           message.  In scalar context, only $buffer is returned ("undef" if there was an error).

       get (DEPRECATED)
               $gdb->get($command, $timeout, $prompt, $notyet, $alldone)

           This version of "get" is used when $Devel::GDB::DEPRECATED is true, and provides
           backwards compatibility with older versions of "Devel::GDB".  It is not compatible
           with any of the new features (e.g. "send_cmd", threaded mode) and will be removed in
           future versions.

           This method is flawed in a number of ways: the semantics of when $notyet is called are
           unclear, the handling of $timeout is broken, and most importantly, the fact that it
           allows execution to be interrupted can put the module into an inconsistent state.

           No new code should use this function.

       get_expect_obj
           Returns the "Expect" object created by "-create-expect".

       get_reader
           Returns the filehandle from which to read GDB responses.

           In non-threaded mode, the caller will need this filehandle in its "-readline-fn"; in
           addition, to support asynchronous GDB responses, the caller should pass lines read
           from this filehandle to "demux".

       demux
               $gdb->demux($line)

           Process a line read from the GDB stream (see "get_reader").  This should only be
           called in non-threaded mode.  (See example: "Non-threaded Usage")

       interrupt
           Send SIGINT to the GDB session, interrupting the inferior process (if any).

       end Kills the GDB connection.  You must call this to ensure that the GDB process is killed
           gracefully.

EXAMPLES

       Non-threaded Usage

           use Devel::GDB;
           use IO::BufferedSelect;

           my $gdb = new Devel::GDB( '-use-threads' => 0,
                                     '-readline-fn' => \&message_loop );

           my $gdb_fh = $gdb->get_reader;

           my $bs = new IO::BufferedSelect(\*STDIN, $gdb_fh);

           sub message_loop
           {
               my @result = $bs->read_line($gdb_fh);
               return @result ? $result[0][1] : undef;
           }

           OUTER:
           while(1)
           {
               my @ready = $bs->read_line();
               foreach( @ready )
               {
                   my ($fh, $line) = @$_;
                   defined($line) or last OUTER;
                   chomp $line;

                   if($fh == \*STDIN)
                   {
                       print STDERR "RECEIVED: $line\n";
                       my $result = $gdb->get($line);
                       last unless defined($result);
                       print STDERR $result;
                   }
                   else
                   {
                       $gdb->demux($line);
                   }
               }
           }

       Programmatically Interacting with the Inferior Process

       Here's a simple example that communicates with an inferior process (in this case, "tr")
       using the "Expect" module.

           use strict;
           use warnings;
           use threads;
           use Devel::GDB;

           my $gdb = new Devel::GDB( '-create-expect' => 1 );
           my $e = $gdb->get_expect_obj;

           $gdb->send_cmd("file tr");
           $gdb->send_cmd("set args a-zA-Z A-Za-z");
           $gdb->send_cmd("-exec-run");

           $e->send("one TWO\n");
           $e->send("ONE two\n");

           $e->expect(undef, '-re', '^.+$')
               and $e->match =~ /^ONE two/
               and print "ok 1\n"
               or die;

           $e->expect(undef, '-re', '^.+$')
               and $e->match =~ /^one TWO/
               and print "ok 2\n"
               or die;

           $gdb->end;

           $e->slave->close;
           $e->expect(undef);
           printf "EXPECT(EOF): %s\n", $e->before;

       Debugging Inside an XTerm

       Here's an example that spawns an xterm and runs the inferior process inside it.  Commands
       are read from STDIN, and responses written to STDERR.

           use strict;
           use warnings;
           use threads;
           use Devel::GDB;
           use IO::Pty;
           use POSIX;

           sub set_termios_lflag($$$)
           {
               my($fd, $flag, $value) = @_;
               my $termios = new POSIX::Termios;
               $termios->getattr($fd);
               $termios->setlflag($value ? ($termios->getlflag | $flag) : ($termios->getlflag & ~$flag));
               $termios->setattr($fd);
               undef $termios;
           }

           my $pty = new IO::Pty;

           # Disable echo temporarily
           set_termios_lflag(fileno($pty), &POSIX::ECHO, 0);

           # Fork an xterm
           unless(my $xterm_pid = fork)
           {
               die "Fork failed" unless defined($xterm_pid);

               # Reopen $fd with close-on-exec disabled
               my $fd  = fileno($pty);
               $^F = $fd > $^F ? $fd : $^F;
               local *MASTER;
               open(MASTER, "<&=$fd") and $fd == fileno(\*MASTER)
                   or die "Failed reopening pty handle";

               my $cmd = "xterm -Sxx$fd";

               print "calling exec($cmd)\n";
               exec($cmd);
               die "exec() failed: $!";
           }

           # xterm likes to write its window id to the pty; eat it up
           # (echo is disabled so the inferior process doesn't see this output)
           my $window_id = readline($pty->slave);

           # Now turn echo back on
           set_termios_lflag(fileno($pty), &POSIX::ECHO, 1);

           # No longer need the master (but don't close the slave!)
           close $pty;

           # Create the GDB object, telling the inferior process to use the new xterm's pty
           my $gdb = new Devel::GDB( '-use-tty' => $pty->ttyname );

           while(<STDIN>)
           {
               chomp;

               if(/^Z/)
               {
                   $gdb->interrupt;
                   next;
               }

               my $result = $gdb->send_cmd($_);
               last unless defined($result);
               print STDERR "[GDB] $result\n";
           }

           $gdb->end;

TODO

       There are a number of features that will be made available in future versions of
       "Devel::GDB".  Among them:

       •   Finish implementing "send_cmd_async".

       •   Add an interface for redirecting GDB/MI output.  Currently, all "out-of-band-records"
           (see <http://sourceware.org/gdb/current/onlinedocs/gdb_25.html#SEC246>) are redirected
           to "STDERR"; there should be a facility for callers to specify what to do with each
           stream.

       •   In order to allow full-fledged GDB front-ends to be implemented with this module, we
           need a more "intelligent" layer above "Devel::GDB": rather than simply sending
           commands and receiving their results, the hypothetical "Devel::GDB::HighLevel" module
           would be aware of the program state; it would know whether or not the inferior process
           is running, what breakpoints are set, and so forth.

SEE ALSO

       Devel::GDB::LowLevel

AUTHORS

       Antal Novak <afn@cpan.org>, Josef Ezra <jezra@cpan.org>

COPYRIGHT AND LICENSE

       Copyright (C) 2007 by Antal Novak & Josef Ezra

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of
       Perl 5 you may have available.