.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "Devel::GDB 3pm" .TH Devel::GDB 3pm "2016-10-01" "perl v5.24.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Devel::GDB \- Open and communicate a gdb session .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Devel::GDB; \& \& $gdb = new Devel::GDB(); \& print $gdb\->send_cmd(\*(Aq\-environment\-path\*(Aq); \& print $gdb\->get(\*(Aqinfo functions\*(Aq); .Ve .PP The old \f(CW\*(C`get\*(C'\fR syntax (of \f(CW\*(C`Devel::GDB\-1.23\*(C'\fR) has been deprecated and will not be supported in future versions. See the documentation of the \f(CW\*(C`get\*(C'\fR function for an explanation of why. .PP If you really want to use the old syntax, set \f(CW$Devel::GDB::DEPRECATED\fR to true: .PP .Vb 1 \& use Devel::GDB ; \& \& $Devel::GDB::DEPRECATED = 1; \& $gdb = new Devel::GDB(); \& print $gdb\->get(\*(Aqinfo functions\*(Aq, $timeout, $prompt, $notyet, $alldone); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \f(CW\*(C`Devel::GDB\*(C'\fR package provides an interface for communicating with \s-1GDB.\s0 Internally, it uses the \fI\s-1GDB/MI\s0\fR interpreter (see ), 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, \s-1GDB\s0's \fIconsole\fR interpreter returns all responses on \&\f(CW\*(C`STDOUT\*(C'\fR, and thus there is no way to ensure that a particular response corresponds to a particular request. .PP Therefore, it is obviously preferable to use \s-1GDB/MI\s0 when programmatically interacting with \s-1GDB. \s0 This can be done via the \f(CW\*(C`send_cmd\*(C'\fR family of functions (\f(CW\*(C`send_cmd\*(C'\fR, \f(CW\*(C`send_cmd_excl\*(C'\fR, and \f(CW\*(C`send_cmd_async\*(C'\fR). There are, however, some cases when there is no \s-1GDB/MI\s0 command corresponding to a particular console command, or it has not yet been implemented (for example, \f(CW\*(C`\-symbol\-type\*(C'\fR, corresponding to the console command \f(CW\*(C`ptype\*(C'\fR, is not yet implemented as of \s-1GDB 6.6\s0). In this case, the \f(CW\*(C`get\*(C'\fR function provides a workaround by capturing all output sent to the console stream. .SH "CONSTRUCTOR" .IX Header "CONSTRUCTOR" .SS "new" .IX Subsection "new" .Vb 2 \& $gdb = new Devel::GDB( \*(Aq\-use\-threads\*(Aq => 1 ); \& \*(Aq\-params\*(Aq => $extra_gdb_params ); .Ve .PP Spawns a new \s-1GDB\s0 process. In \fIthreaded\fR mode, this also spawns a listening thread that asynchronously processes responses from \s-1GDB\s0; in \fInon-threaded\fR mode, the caller is responsible for handling asynchronous output (that is, output from \s-1GDB\s0 that is not directly solicited by a request). See \f(CW\*(C`demux\*(C'\fR, \&\f(CW\*(C`get_reader\*(C'\fR, and the \*(L"Non-threaded Usage\*(R" example for further discussion. .PP The parameters to the constructor are passed in hash form. The following parameters control how \s-1GDB\s0 is invoked: .ie n .IP """\-execfile""" 4 .el .IP "\f(CW\-execfile\fR" 4 .IX Item "-execfile" The \s-1GDB\s0 binary to execute; defaults to \f(CW"gdb"\fR. .ie n .IP """\-params""" 4 .el .IP "\f(CW\-params\fR" 4 .IX Item "-params" Pass additional parameters to \s-1GDB. \s0 The value can be an array reference (preferred) or a string. .PP The following parameters control how to handle interaction with the \fIinferior process\fR, 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 \f(CW\*(C`STDIN\*(C'\fR is associated with a tty. Two other (mutually exclusive) options are available: .ie n .IP """\-use\-tty""" 4 .el .IP "\f(CW\-use\-tty\fR" 4 .IX Item "-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. \f(CW"/dev/pts/123"\fR) and not an \&\f(CW\*(C`IO::Pty\*(C'\fR object. See the example \*(L"Debugging Inside an XTerm\*(R". .ie n .IP """\-create\-expect""" 4 .el .IP "\f(CW\-create\-expect\fR" 4 .IX Item "-create-expect" If this value is non-zero, create an \f(CW\*(C`Expect\*(C'\fR object (which can be subsequently retrieved by calling \f(CW\*(C`get_expect_obj\*(C'\fR); this is useful if you want to programmatically interact with the inferior process. See the example \&\*(L"Programmatically Interacting with the Inferior Process\*(R". .PP Miscellaneous parameters: .ie n .IP """\-use\-threads""" 4 .el .IP "\f(CW\-use\-threads\fR" 4 .IX Item "-use-threads" Operate in threaded (1) or non-threaded (0) mode. The default behavior is to enable threaded mode if the \f(CW\*(C`threads\*(C'\fR module has been loaded and disable it otherwise. Note that if \f(CW\*(C`\-use\-threads\*(C'\fR is enabled, the caller \fBmust\fR call \&\f(CW\*(C`use threads\*(C'\fR, but \f(CW\*(C`\-use\-threads\*(C'\fR can be disabled whether or not \f(CW\*(C`threads\*(C'\fR has been loaded. .Sp Threaded mode is the easiest to deal with, as it does not require the caller to interact with the \s-1GDB\s0 filehandles directly; for a simple non-threaded example, see the \*(L"Non-threaded Usage\*(R" example. .ie n .IP """\-readline\-fn""" 4 .el .IP "\f(CW\-readline\-fn\fR" 4 .IX Item "-readline-fn" Probably only useful in non-threaded mode, this lets the user specify a callback function \f(CW$fn\fR to be called when waiting for a response from \s-1GDB. \s0 It is invoked with one parameter, the \f(CW\*(C`Devel::GDB\*(C'\fR instance, and is expected to return one full line of output (or \f(CW\*(C`undef\*(C'\fR if \s-1EOF\s0 was reached). The default implementation uses buffered I/O: .Sp .Vb 1 \& $fn = sub { return readline($_[0]\->get_reader); } .Ve .Sp Typically, in non-threaded mode, the caller will be using \f(CW\*(C`select\*(C'\fR to multiplex multiple file streams (e.g. \f(CW\*(C`STDIN\*(C'\fR and \f(CW\*(C`get_reader\*(C'\fR); in this case, you will likely want to specify a value for \f(CW\*(C`\-readline\-fn\*(C'\fR which, at a minimum, uses \&\f(CW\*(C`sysread\*(C'\fR rather than \f(CW\*(C`readline\*(C'\fR. .SH "METHODS" .IX Header "METHODS" .IP "send_cmd" 4 .IX Item "send_cmd" .Vb 1 \& $response = $gdb\->send_cmd($command) .Ve .Sp Send \f(CW$command\fR to \s-1GDB,\s0 and block until a response is received. In threaded mode, this does not prevent other threads from simultaneously sending requests. .Sp The \f(CW$command\fR can be a \s-1GDB/MI\s0 command, prefixed with a hyphen (e.g. \&\f(CW"\-exec\-run"\fR) or a console command (\f(CW"run"\fR). However, the response returned will always be a \s-1GDB/MI\s0 response, so \f(CW\*(C`$gdb\->send_cmd("info variables")\*(C'\fR will only return \f(CW"done"\fR; 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 \f(CW\*(C`get\*(C'\fR. .IP "send_cmd_excl" 4 .IX Item "send_cmd_excl" .Vb 1 \& $gdb\->send_cmd_excl($cmd, $before_fn, $after_fn) .Ve .Sp Send \f(CW$cmd\fR to \s-1GDB\s0 in \fIexclusive mode\fR. In threaded mode, this means that other \&\f(CW\*(C`send_cmd\*(C'\fR and \f(CW\*(C`send_cmd_excl\*(C'\fR calls will not coincide with this call. In non-threaded mode, this ensures that any pending \f(CW\*(C`send_cmd_async\*(C'\fR calls are processed before proceeding. .Sp If provided, the \f(CW$before_fn\fR and \f(CW$after_fn\fR functions will, respectively, be called before the command is sent (after the exclusive lock is acquired) and after the result has been received (before the exclusive lock is released). .IP "send_cmd_async" 4 .IX Item "send_cmd_async" .Vb 1 \& $gdb\->send_cmd_excl($cmd, $callback_fn) .Ve .Sp \&\fBNot yet implemented.\fR .Sp Send \f(CW$cmd\fR to \s-1GDB\s0 in \fIasync mode\fR. This returns immediately, rather than blocking until a response is received; instead, the \f(CW$callback_fn\fR callback function is called, with the response as the first argument. .Sp This will likely only be supported in non-threaded mode. .IP "get" 4 .IX Item "get" .Vb 1 \& $gdb\->get($command) .Ve .Sp Issues the \f(CW$command\fR to \s-1GDB,\s0 and returns all output sent to the console output stream. Note that there is no way to ensure that the output \*(L"belongs\*(R" to a particular command, so it is possible that spurious output will be included! In particular, if you call \f(CW\*(C`$gdb\->get($command)\*(C'\fR immediately after creating the \&\f(CW\*(C`Devel::GDB\*(C'\fR object, and don't suppress \s-1GDB\s0's initialization messages (by passing \f(CW\*(C`\-q\*(C'\fR to \f(CW\*(C`\-params\*(C'\fR), some of these messages may end up in the response to \&\f(CW\*(C`get\*(C'\fR. .Sp In list context, returns \f(CW\*(C`($buffer, $error)\*(C'\fR, with exactly one of the two defined; \f(CW$buffer\fR is the text captured from the console stream and \f(CW$error\fR is the \s-1GDB/MI\s0 error message. In scalar context, only \f(CW$buffer\fR is returned (\f(CW\*(C`undef\*(C'\fR if there was an error). .IP "get (\s-1DEPRECATED\s0)" 4 .IX Item "get (DEPRECATED)" .Vb 1 \& $gdb\->get($command, $timeout, $prompt, $notyet, $alldone) .Ve .Sp This version of \f(CW\*(C`get\*(C'\fR is used when \f(CW$Devel::GDB::DEPRECATED\fR is true, and provides backwards compatibility with older versions of \f(CW\*(C`Devel::GDB\*(C'\fR. It is not compatible with any of the new features (e.g. \f(CW\*(C`send_cmd\*(C'\fR, threaded mode) and will be removed in future versions. .Sp This method is flawed in a number of ways: the semantics of when \f(CW$notyet\fR is called are unclear, the handling of \f(CW$timeout\fR is broken, and most importantly, the fact that it allows execution to be interrupted can put the module into an inconsistent state. .Sp No new code should use this function. .IP "get_expect_obj" 4 .IX Item "get_expect_obj" Returns the \f(CW\*(C`Expect\*(C'\fR object created by \f(CW\*(C`\-create\-expect\*(C'\fR. .IP "get_reader" 4 .IX Item "get_reader" Returns the filehandle from which to read \s-1GDB\s0 responses. .Sp In non-threaded mode, the caller will need this filehandle in its \&\f(CW\*(C`\-readline\-fn\*(C'\fR; in addition, to support asynchronous \s-1GDB\s0 responses, the caller should pass lines read from this filehandle to \f(CW\*(C`demux\*(C'\fR. .IP "demux" 4 .IX Item "demux" .Vb 1 \& $gdb\->demux($line) .Ve .Sp Process a line read from the \s-1GDB\s0 stream (see \f(CW\*(C`get_reader\*(C'\fR). This should only be called in non-threaded mode. (See example: \*(L"Non-threaded Usage\*(R") .IP "interrupt" 4 .IX Item "interrupt" Send \s-1SIGINT\s0 to the \s-1GDB\s0 session, interrupting the inferior process (if any). .IP "end" 4 .IX Item "end" Kills the \s-1GDB\s0 connection. You \fBmust\fR call this to ensure that the \s-1GDB\s0 process is killed gracefully. .SH "EXAMPLES" .IX Header "EXAMPLES" .SS "Non-threaded Usage" .IX Subsection "Non-threaded Usage" .Vb 2 \& use Devel::GDB; \& use IO::BufferedSelect; \& \& my $gdb = new Devel::GDB( \*(Aq\-use\-threads\*(Aq => 0, \& \*(Aq\-readline\-fn\*(Aq => \e&message_loop ); \& \& my $gdb_fh = $gdb\->get_reader; \& \& my $bs = new IO::BufferedSelect(\e*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 == \e*STDIN) \& { \& print STDERR "RECEIVED: $line\en"; \& my $result = $gdb\->get($line); \& last unless defined($result); \& print STDERR $result; \& } \& else \& { \& $gdb\->demux($line); \& } \& } \& } .Ve .SS "Programmatically Interacting with the Inferior Process" .IX Subsection "Programmatically Interacting with the Inferior Process" Here's a simple example that communicates with an inferior process (in this case, \f(CW\*(C`tr\*(C'\fR) using the \f(CW\*(C`Expect\*(C'\fR module. .PP .Vb 4 \& use strict; \& use warnings; \& use threads; \& use Devel::GDB; \& \& my $gdb = new Devel::GDB( \*(Aq\-create\-expect\*(Aq => 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\en"); \& $e\->send("ONE two\en"); \& \& $e\->expect(undef, \*(Aq\-re\*(Aq, \*(Aq^.+$\*(Aq) \& and $e\->match =~ /^ONE two/ \& and print "ok 1\en" \& or die; \& \& $e\->expect(undef, \*(Aq\-re\*(Aq, \*(Aq^.+$\*(Aq) \& and $e\->match =~ /^one TWO/ \& and print "ok 2\en" \& or die; \& \& $gdb\->end; \& \& $e\->slave\->close; \& $e\->expect(undef); \& printf "EXPECT(EOF): %s\en", $e\->before; .Ve .SS "Debugging Inside an XTerm" .IX Subsection "Debugging Inside an XTerm" Here's an example that spawns an xterm and runs the inferior process inside it. Commands are read from \s-1STDIN,\s0 and responses written to \s-1STDERR.\s0 .PP .Vb 6 \& 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(\e*MASTER) \& or die "Failed reopening pty handle"; \& \& my $cmd = "xterm \-Sxx$fd"; \& \& print "calling exec($cmd)\en"; \& 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\*(Aqt 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\*(Aqt close the slave!) \& close $pty; \& \& # Create the GDB object, telling the inferior process to use the new xterm\*(Aqs pty \& my $gdb = new Devel::GDB( \*(Aq\-use\-tty\*(Aq => $pty\->ttyname ); \& \& while() \& { \& chomp; \& \& if(/^Z/) \& { \& $gdb\->interrupt; \& next; \& } \& \& my $result = $gdb\->send_cmd($_); \& last unless defined($result); \& print STDERR "[GDB] $result\en"; \& } \& \& $gdb\->end; .Ve .SH "TODO" .IX Header "TODO" There are a number of features that will be made available in future versions of \&\f(CW\*(C`Devel::GDB\*(C'\fR. Among them: .IP "\(bu" 4 Finish implementing \f(CW\*(C`send_cmd_async\*(C'\fR. .IP "\(bu" 4 Add an interface for redirecting \s-1GDB/MI\s0 output. Currently, all \f(CW\*(C`out\-of\-band\-records\*(C'\fR (see ) are redirected to \f(CW\*(C`STDERR\*(C'\fR; there should be a facility for callers to specify what to do with each stream. .IP "\(bu" 4 In order to allow full-fledged \s-1GDB\s0 front-ends to be implemented with this module, we need a more \*(L"intelligent\*(R" layer above \f(CW\*(C`Devel::GDB\*(C'\fR: rather than simply sending commands and receiving their results, the hypothetical \&\f(CW\*(C`Devel::GDB::HighLevel\*(C'\fR 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. .SH "SEE ALSO" .IX Header "SEE ALSO" Devel::GDB::LowLevel .SH "AUTHORS" .IX Header "AUTHORS" Antal Novak , Josef Ezra .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright (C) 2007 by Antal Novak & Josef Ezra .PP 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.