GDB - Documentation

Constructor

new GDB(childProcess)

Source:

index.js, line 85

Create a GDB wrapper.

Parameters:

Name	Type	Description
`childProcess`	object	A Node.js child process or just an object with `stdin`, `stdout`, `stderr` properties that are Node.js streams. If you're using GDB all-stop mode, then it should also have implementation of `kill` method that is able to send signals (such as `SIGINT`).

Extends

EventEmitter

Members

consoleStream :Readable.<string>

Source:

index.js, line 201

Raw output of GDB/MI console records.

Type:

Readable.<string>

logStream :Readable.<string>

Source:

index.js, line 211

Raw output of GDB/MI log records. The log stream contains debugging messages being produced by gdb's internals.

Type:

Readable.<string>

targetStream :Readable.<string>

Source:

index.js, line 224

Raw output of GDB/MI target records. The target output stream contains any textual output from the running target. Please, note that it's currently impossible to distinguish the target and the MI output correctly due to a bug in GDB/MI. Thus, it's recommended to use --tty option with your GDB process.

Type:

Readable.<string>

(readonly) process :object

Source:

index.js, line 361

Get the child process object.

Type:

object

Methods

init() → {Promise.<undefined, GDBError>}

Source:

index.js, line 374

Extend GDB CLI interface with some useful commands that are necessary for executing some methods of this GDB wrapper (e.g. context, execCLI). It also enables custom actions (like new-objfile event).

Returns:

A promise that resolves/rejects after completion of a GDB command.

Type: Promise.<undefined, GDBError>

set(param, value) → {Promise.<undefined, GDBError>}

Source:

index.js, line 394

Set internal GDB variable.

Parameters:

Name	Type	Description
`param`	string	The name of a GDB variable.
`value`	string	The value of a GDB variable.

Returns:

A promise that resolves/rejects after completion of a GDB command.

Type: Promise.<undefined, GDBError>

attachOnFork() → {Promise.<undefined, GDBError>}

Source:

index.js, line 407

Enable the detach-on-fork option which will automatically attach GDB to any of forked processes. Please, note that it makes sense only for systems that support fork and vfork calls. It won't work for Windows, for example.

Returns:

A promise that resolves/rejects after completion of a GDB command.

Type: Promise.<undefined, GDBError>

enableAsync() → {Promise.<undefined, GDBError>}

Source:

index.js, line 417

Enable async and non-stop modes in GDB. This mode is highly recommended!

Returns:

A promise that resolves/rejects after completion of a GDB command.

Type: Promise.<undefined, GDBError>

attach(pid) → {Promise.<ThreadGroup, GDBError>}

Source:

index.js, line 438

Attach a new target (inferior) to GDB.

Parameters:

Name	Type	Description
`pid`	number	The process id or to attach.

Returns:

A promise that resolves/rejects with the added thread group.

Type: Promise.<ThreadGroup, GDBError>

detach(process) → {Promise.<undefined, GDBError>}

Source:

index.js, line 456

Detache a target (inferior) from GDB.

Parameters:

Name	Type	Description
`process`	ThreadGroup \| number	The process id or the thread group to detach.

Returns:

A promise that resolves/rejects after completion of a GDB command.

Type: Promise.<undefined, GDBError>

interrupt(scopeopt) → {Promise.<undefined, GDBError>}

Source:

index.js, line 472

Interrupt the target. In all-stop mode and in non-stop mode without arguments it interrupts all threads. In non-stop mode it can interrupt only specific thread or a thread group.

Parameters:

Name	Type	Attributes	Description
`scope`	Thread \| ThreadGroup	<optional>	The thread or thread-group to interrupt. If this parameter is omitted, it will interrupt all threads.

Returns:

A promise that resolves/rejects after completion of a GDB command.

Type: Promise.<undefined, GDBError>

threads(scopeopt) → {Promise.<(Array.<Thread>|Thread), GDBError>}

Source:

index.js, line 494

Get the information about all the threads or about specific threads.

Parameters:

Name	Type	Attributes	Description
`scope`	Thread \| ThreadGroup	<optional>	Get information about threads of the specific thread group or even about the specific thread (if it doesn't have enough information or it's outdated). If this parameter is absent, then information about all threads is returned.

Returns:

A promise that resolves with an array of threads or a single thread.

Type: Promise.<(Array.<Thread>|Thread), GDBError>

currentThread() → {Promise.<Thread, GDBError>}

Source:

index.js, line 528

Get the current thread.

Returns:

A promise that resolves with a thread.

Type: Promise.<Thread, GDBError>

selectThread(thread) → {Promise.<undefined, GDBError>}

Source:

index.js, line 541

Although you can pass scope to commands, you can also explicitly change the context of command execution. Sometimes it might be slightly faster.

Parameters:

Name	Type	Description
`thread`	Thread	The thread that should be selected.

Returns:

A promise that resolves/rejects after completion of a GDB command.

Type: Promise.<undefined, GDBError>

threadGroups() → {Promise.<Array.<ThreadGroup>, GDBError>}

Source:

index.js, line 551

Get thread groups.

Returns:

A promise that resolves with an array thread groups.

Type: Promise.<Array.<ThreadGroup>, GDBError>

currentThreadGroup() → {Promise.<ThreadGroup, GDBError>}

Source:

index.js, line 560

Get the current thread group.

Returns:

A promise that resolves with the thread group.

Type: Promise.<ThreadGroup, GDBError>

selectThreadGroup(group) → {Promise.<undefined, GDBError>}

Source:

index.js, line 573

Although you can pass scope to commands, you can also explicitly change the context of command execution. Sometimes it might be slightly faster.

Parameters:

Name	Type	Description
`group`	ThreadGroup	The thread group that should be selected.

Returns:

A promise that resolves/rejects after completion of a GDB command.

Type: Promise.<undefined, GDBError>

addBreak(file, pos, threadopt) → {Promise.<Breakpoint, GDBError>}

Source:

index.js, line 587

Insert a breakpoint at the specified position.

Parameters:

Name	Type	Attributes	Description
`file`	string		The full name or just a file name.
`pos`	number \| string		The function name or a line number.
`thread`	Thread	<optional>	The thread where breakpoint should be set. If this field is absent, breakpoint applies to all threads.

Returns:

A promise that resolves with a breakpoint.

Type: Promise.<Breakpoint, GDBError>

removeBreak(bpopt) → {Promise.<undefined, GDBError>}

Source:

index.js, line 617

Removes a specific breakpoint.

Parameters:

Name	Type	Attributes	Description
`bp`	Breakpoint	<optional>	The breakpoint.

Returns:

A promise that resolves/rejects after completion of a GDB command.

Type: Promise.<undefined, GDBError>

stepIn(scopeopt) → {Promise.<undefined, GDBError>}

Source:

index.js, line 630

Step in.

Parameters:

Name	Type	Attributes	Description
`scope`	Thread \| ThreadGroup	<optional>	The thread or thread group where the stepping should be done.

Returns:

A promise that resolves/rejects after completion of a GDB command.

Type: Promise.<undefined, GDBError>

reverseStepIn(scopeopt) → {Promise.<undefined, GDBError>}

Source:

index.js, line 643

Step back in.

Parameters:

Name	Type	Attributes	Description
`scope`	Thread \| ThreadGroup	<optional>	The thread or thread group where the stepping should be done.

Returns:

A promise that resolves/rejects after completion of a GDB command.

Type: Promise.<undefined, GDBError>

stepOut(scopeopt) → {Promise.<undefined, GDBError>}

Source:

index.js, line 656

Step out.

Parameters:

Name	Type	Attributes	Description
`scope`	Thread \| ThreadGroup	<optional>	The thread or thread group where the stepping should be done.

Returns:

A promise that resolves/rejects after completion of a GDB command.

Type: Promise.<undefined, GDBError>

next(scopeopt) → {Promise.<undefined, GDBError>}

Source:

index.js, line 669

Execute to the next line.

Parameters:

Name	Type	Attributes	Description
`scope`	Thread \| ThreadGroup	<optional>	The thread or thread group where the stepping should be done.

Returns:

A promise that resolves/rejects after completion of a GDB command.

Type: Promise.<undefined, GDBError>

reverseNext(scopeopt) → {Promise.<undefined, GDBError>}

Source:

index.js, line 682

Execute to the previous line.

Parameters:

Name	Type	Attributes	Description
`scope`	Thread \| ThreadGroup	<optional>	The thread or thread group where the stepping should be done.

Returns:

A promise that resolves/rejects after completion of a GDB command.

Type: Promise.<undefined, GDBError>

run(groupopt) → {Promise.<undefined, GDBError>}

Source:

index.js, line 695

Run the current target.

Parameters:

Name	Type	Attributes	Description
`group`	ThreadGroup	<optional>	The thread group to run. If this parameter is omitted, current thread group will be run.

Returns:

A promise that resolves/rejects after completion of a GDB command.

Type: Promise.<undefined, GDBError>

proceed(scopeopt) → {Promise.<undefined, GDBError>}

Source:

index.js, line 712

Continue execution.

Parameters:

Name	Type	Attributes	Description
`scope`	Thread \| ThreadGroup	<optional>	The thread or thread group that should be continued. If this parameter is omitted, all threads are continued.

Returns:

A promise that resolves/rejects after completion of a GDB command.

Type: Promise.<undefined, GDBError>

reverseProceed(scopeopt) → {Promise.<undefined, GDBError>}

Source:

index.js, line 726

Continue reverse execution.

Parameters:

Name	Type	Attributes	Description
`scope`	Thread \| ThreadGroup	<optional>	The thread or thread group that should be continued. If this parameter is omitted, all threads are continued.

Returns:

A promise that resolves/rejects after completion of a GDB command.

Type: Promise.<undefined, GDBError>

context(threadopt) → {Promise.<Array.<Variable>, GDBError>}

Source:

index.js, line 740

List all symbols in the current context (i.e. all global, static, local variables and constants in the current file).

Parameters:

Name	Type	Attributes	Description
`thread`	Thread	<optional>	The thread from which the context should be taken.

Returns:

A promise that resolves with an array of variables.

Type: Promise.<Array.<Variable>, GDBError>

callstack(threadopt) → {Promise.<Array.<Frame>, GDBError>}

Source:

index.js, line 754

Get the callstack.

Parameters:

Name	Type	Attributes	Description
`thread`	Thread	<optional>	The thread from which the callstack should be taken.

Returns:

A promise that resolves with an array of frames.

Type: Promise.<Array.<Frame>, GDBError>

sourceFiles(optionsopt) → {Promise.<Array.<string>, GDBError>}

Source:

index.js, line 785

Get list of source files or a subset of source files that match the regular expression. Please, note that it doesn't return sources.

Example

let headers = await gdb.sourceFiles({ pattern: '\.h$' })

Parameters:

Name Type Attributes Description

options

object

The options object.

Properties

Name	Type	Attributes	Description
`group`	ThreadGroup	<optional>	The thread group (i.e. target) for which source files are needed. If this parameter is absent, then source files are returned for all targets.
`pattern`	string	<optional>	The regular expression (see Python regex syntax). This option is useful when the project has a lot of files so that it's not desirable to send them all in one chunk along the wire.

Returns:

A promise that resolves with an array of source files.

Type: Promise.<Array.<string>, GDBError>

evaluate(expr, scopeopt) → {Promise.<string, GDBError>}

Source:

index.js, line 815

Evaluate a GDB expression.

Parameters:

Name	Type	Attributes	Description
`expr`	string		The expression to evaluate.
`scope`	Thread \| ThreadGroup	<optional>	The thread or thread group where the expression should be evaluated.

Returns:

A promise that resolves with the result of expression.

Type: Promise.<string, GDBError>

exit() → {Promise.<undefined, GDBError>}

Source:

index.js, line 828

Exit GDB.

Returns:

A promise that resolves/rejects after completion of a GDB command.

Type: Promise.<undefined, GDBError>

execPy(src, threadopt) → {Promise.<string, GDBError>}

Source:

index.js, line 868

Execute a custom python script and get the results of its excecution. If your python script is asynchronous and you're interested in its output, you should either define a new event (refer to the Extending section in the main page) or read the console stream. Here's the example below.

By the way, with this method you can define your own CLI commands and then call them via execCLI method. For more examples, refer to the Extending section on the main page and read official GDB Python API and PythonGdbTutorial.

Example

let script = `
import gdb
import threading


def foo():
    sys.stdout.write('bar')
    sys.stdout.flush()

timer = threading.Timer(5.0, foo)
timer.start()
`
gdb.consoleStream.on('data', (str) => {
  if (str === 'bar') console.log('yep')
})
await gdb.execPy(script)

Parameters:

Name	Type	Attributes	Description
`src`	string		The python script.
`thread`	Thread	<optional>	The thread where the script should be executed.

Returns:

A promise that resolves with the output of python script execution.

Type: Promise.<string, GDBError>

execCLI(cmd, scopeopt) → {Promise.<string, GDBError>}

Source:

index.js, line 881

Execute a CLI command.

Parameters:

Name	Type	Attributes	Description
`cmd`	string		The CLI command.
`scope`	Thread \| ThreadGroup	<optional>	The thread where the command should be executed.

Returns:

A promise that resolves with the result of command execution.

Type: Promise.<string, GDBError>

execCMD(cmd, scopeopt) → {Promise.<object, GDBError>}

Source:

index.js, line 897

Execute a custom defined command. Refer to the Extending section on the main page of the documentation.

Parameters:

Name	Type	Attributes	Description
`cmd`	string		The name of the command.
`scope`	Thread \| ThreadGroup	<optional>	The thread or thread-group where the command should be executed. If this parameter is omitted, it executes in the current thread.

Returns:

A promise that resolves with the JSON representation of the result of command execution.

Type: Promise.<object, GDBError>

execMI(cmd, scopeopt) → {Promise.<object, GDBError>}

Source:

index.js, line 912

Execute a MI command.

Parameters:

Name	Type	Attributes	Description
`cmd`	string		The MI command.
`scope`	Thread \| ThreadGroup	<optional>	The thread or thread-group where the command should be executed. If this parameter is omitted, it executes in the current thread.

Returns:

A promise that resolves with the JSON representation of the result of command execution.

Type: Promise.<object, GDBError>

Events

notify

Source:

index.js, line 159

Properties:

Name	Type	Description
`state`	string	The class of the notify record (e.g. `thread-created`).
`data`	object	JSON representation of GDB/MI message.

Raw output of GDB/MI notify records. Contains supplementary information that the client should handle. Please, see the official GDB/MI documentation.

Type:

object

status

Source:

index.js, line 171

Properties:

Name	Type	Description
`state`	string	The class of the status record.
`data`	object	JSON representation of GDB/MI message.

Raw output of GDB/MI status records. Contains on-going status information about the progress of a slow operation.

Type:

object

exec

Source:

index.js, line 181

Properties:

Name	Type	Description
`state`	string	The class of the exec record (e.g. `stopped`).
`data`	object	JSON representation of GDB/MI message.

Raw output of GDB/MI exec records. Contains asynchronous state change on the target.

Type:

object

stopped

Source:

index.js, line 230

Properties:

Name	Type	Attributes	Description
`reason`	string		The reason of why target has stopped (see the official GDB/MI documentation) for more information.
`thread`	Thread	<optional>	The thread that caused the stop.
`breakpoint`	Breakpoint	<optional>	Breakpoint is provided if the reason is `breakpoint-hit`.

This event is emitted when target or one of its threads has stopped due to some reason. Note that thread property indicates the thread that caused the stop. In an all-stop mode all threads will be stopped.