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 https://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 anIO::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 callingget_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 calluse threads
, but-use-threads
can be disabled whether or notthreads
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 (orundef
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
andget_reader
); in this case, you will likely want to specify a value for-readline-fn
which, at a minimum, usessysread
rather thanreadline
.
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, useget
. - 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 othersend_cmd
andsend_cmd_excl
calls will not coincide with this call. In non-threaded mode, this ensures that any pendingsend_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 theDevel::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 toget
.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 ofDevel::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 todemux
. - 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 https://sourceware.org/gdb/current/onlinedocs/gdb_25.html#SEC246) are redirected toSTDERR
; 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 hypotheticalDevel::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
AUTHORS
Antal Novak <[email protected]>, Josef Ezra <[email protected]>
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.