Ubuntu Manpage: vgdb - intermediary between Valgrind and GDB or a shell

Provided by: valgrind_3.24.0-0ubuntu2_amd64

NAME

       vgdb - intermediary between Valgrind and GDB or a shell

SYNOPSIS


       vgdb [options]

DESCRIPTION

       vgdb ("Valgrind to GDB") is used as an intermediary between Valgrind and GDB or a shell. It has three
       usage modes:

        1. As a standalone utility, it is used from a shell command line to send monitor commands to a process
           running under Valgrind. For this usage, the vgdb OPTION(s) must be followed by the monitor command to
           send. To send more than one command, separate them with the -c option.

        2. In combination with GDB "target remote |" command, it is used as the relay application between GDB
           and the Valgrind gdbserver. For this usage, only OPTION(s) can be given, but no COMMAND can be given.

        3. In the --multi mode, vgdb uses the extended remote protocol to communicate with GDB. This allows you
           to view output from both valgrind and GDB in the GDB session. This is accomplished via the "target
           extended-remote | vgdb --multi". In this mode you no longer need to start valgrind yourself. vgdb
           will start up valgrind when gdb tells it to run a new program. For this usage, the vgdb OPTIONS(s)
           can also include --valgrind and --vargs to describe how valgrind should be started.

OPTIONS

--pid=<number>
Specifies the PID of the process to which vgdb must connect to. This option is useful in case more
than one Valgrind gdbserver can be connected to. If the --pid argument is not given and multiple
Valgrind gdbserver processes are running, vgdb will report the list of such processes and then exit.

--vgdb-prefix
Must be given to both Valgrind and vgdb if you want to change the default prefix for the FIFOs (named
pipes) used for communication between the Valgrind gdbserver and vgdb.

--wait=<number>
Instructs vgdb to search for available Valgrind gdbservers for the specified number of seconds. This
makes it possible start a vgdb process before starting the Valgrind gdbserver with which you intend
the vgdb to communicate. This option is useful when used in conjunction with a --vgdb-prefix that is
unique to the process you want to wait for. Also, if you use the --wait argument in the GDB "target
remote" command, you must set the GDB remotetimeout to a value bigger than the --wait argument value.
See option --max-invoke-ms (just below) for an example of setting the remotetimeout value.

--max-invoke-ms=<number>
Gives the number of milliseconds after which vgdb will force the invocation of gdbserver embedded in
Valgrind. The default value is 100 milliseconds. A value of 0 disables forced invocation. The forced
invocation is used when vgdb is connected to a Valgrind gdbserver, and the Valgrind process has all
its threads blocked in a system call.

If you specify a large value, you might need to increase the GDB "remotetimeout" value from its
default value of 2 seconds. You should ensure that the timeout (in seconds) is bigger than the
--max-invoke-ms value. For example, for --max-invoke-ms=5000, the following GDB command is suitable:

(gdb) set remotetimeout 6

--cmd-time-out=<number>
Instructs a standalone vgdb to exit if the Valgrind gdbserver it is connected to does not process a
command in the specified number of seconds. The default value is to never time out.

--port=<portnr>
Instructs vgdb to use tcp/ip and listen for GDB on the specified port nr rather than to use a pipe to
communicate with GDB. Using tcp/ip allows one to have GDB running on one computer and debugging a
Valgrind process running on another target computer. Example:

# On the target computer, start your program under valgrind using
valgrind --vgdb-error=0 prog
# and then in another shell, run:
vgdb --port=1234

On the computer which hosts GDB, execute the command:

gdb prog
(gdb) target remote targetip:1234

where targetip is the ip address or hostname of the target computer.

--vgdb-multi
Makes vgdb start in extended-remote mode and to wait for gdb to tell us what to run.

--valgrind
The path to valgrind to use, in extended-remote mode. If not specified, the system valgrind will be
launched.

--vargs
Options to run valgrind with, in extended-remote mode. For example -q. Everything following --vargs
will be provided as arguments to valgrind as is.

-c
To give more than one command to a standalone vgdb, separate the commands by an option -c. Example:

vgdb v.set log_output -c leak_check any

-l
Instructs a standalone vgdb to report the list of the Valgrind gdbserver processes running and then
exit.

-T
Instructs vgdb to add timestamps to vgdb information messages.

-D
Instructs a standalone vgdb to show the state of the shared memory used by the Valgrind gdbserver.
vgdb will exit after having shown the Valgrind gdbserver shared memory state.

-d
Instructs vgdb to produce debugging output. Give multiple -d args to increase the verbosity. When
giving -d to a relay vgdb, you better redirect the standard error (stderr) of vgdb to a file to avoid
interaction between GDB and vgdb debugging output.

AUTHOR

       Philippe Waroquiers.

NOTES