1VGDB(1) vgdb VGDB(1)
2
6 vgdb - intermediary between Valgrind and GDB or a shell
7
9 vgdb [options]
10
12 vgdb ("Valgrind to GDB") is used as an intermediary between Valgrind
13 and GDB or a shell. It has three usage modes:
14 1. As a standalone utility, it is used from a shell command line to
16 send monitor commands to a process running under Valgrind. For this
17 usage, the vgdb OPTION(s) must be followed by the monitor command
18 to send. To send more than one command, separate them with the -c
19 option.
20 2. In combination with GDB "target remote |" command, it is used as
22 the relay application between GDB and the Valgrind gdbserver. For
23 this usage, only OPTION(s) can be given, but no COMMAND can be
24 given.
25 3. In the --multi mode, vgdb uses the extended remote protocol to
27 communicate with GDB. This allows you to view output from both
28 valgrind and GDB in the GDB session. This is accomplished via the
29 "target extended-remote | vgdb --multi". In this mode you no longer
30 need to start valgrind yourself. vgdb will start up valgrind when
31 gdb tells it to run a new program. For this usage, the vgdb
32 OPTIONS(s) can also include --valgrind and --vargs to describe how
33 valgrind should be started.
34
36 --pid=<number>
37 Specifies the PID of the process to which vgdb must connect to.
38 This option is useful in case more than one Valgrind gdbserver can
39 be connected to. If the --pid argument is not given and multiple
40 Valgrind gdbserver processes are running, vgdb will report the list
41 of such processes and then exit.
42 --vgdb-prefix
44 Must be given to both Valgrind and vgdb if you want to change the
45 default prefix for the FIFOs (named pipes) used for communication
46 between the Valgrind gdbserver and vgdb.
47 --wait=<number>
49 Instructs vgdb to search for available Valgrind gdbservers for the
50 specified number of seconds. This makes it possible start a vgdb
51 process before starting the Valgrind gdbserver with which you
52 intend the vgdb to communicate. This option is useful when used in
53 conjunction with a --vgdb-prefix that is unique to the process you
54 want to wait for. Also, if you use the --wait argument in the GDB
55 "target remote" command, you must set the GDB remotetimeout to a
56 value bigger than the --wait argument value. See option
57 --max-invoke-ms (just below) for an example of setting the
58 remotetimeout value.
59 --max-invoke-ms=<number>
61 Gives the number of milliseconds after which vgdb will force the
62 invocation of gdbserver embedded in Valgrind. The default value is
63 100 milliseconds. A value of 0 disables forced invocation. The
64 forced invocation is used when vgdb is connected to a Valgrind
65 gdbserver, and the Valgrind process has all its threads blocked in
66 a system call.
67 If you specify a large value, you might need to increase the GDB
69 "remotetimeout" value from its default value of 2 seconds. You
70 should ensure that the timeout (in seconds) is bigger than the
71 --max-invoke-ms value. For example, for --max-invoke-ms=5000, the
72 following GDB command is suitable:
73 (gdb) set remotetimeout 6
75 --cmd-time-out=<number>
79 Instructs a standalone vgdb to exit if the Valgrind gdbserver it is
80 connected to does not process a command in the specified number of
81 seconds. The default value is to never time out.
82 --port=<portnr>
84 Instructs vgdb to use tcp/ip and listen for GDB on the specified
85 port nr rather than to use a pipe to communicate with GDB. Using
86 tcp/ip allows to have GDB running on one computer and debugging a
87 Valgrind process running on another target computer. Example:
88 # On the target computer, start your program under valgrind using
90 valgrind --vgdb-error=0 prog
91 # and then in another shell, run:
92 vgdb --port=1234
93 On the computer which hosts GDB, execute the command:
95 gdb prog
97 (gdb) target remote targetip:1234
98 where targetip is the ip address or hostname of the target
100 computer.
101 --vgdb-multi
103 Makes vgdb start in extended-remote mode and to wait for gdb to
104 tell us what to run.
105 --valgrind
107 The path to valgrind to use, in extended-remote mode. If not
108 specified, the system valgrind will be launched.
109 --vargs
111 Options to run valgrind with, in extended-remote mode. For example
112 -q. Everything following --vargs will be provided as arguments to
113 valgrind as is.
114 -c
116 To give more than one command to a standalone vgdb, separate the
117 commands by an option -c. Example:
118 vgdb v.set log_output -c leak_check any
120 -l
122 Instructs a standalone vgdb to report the list of the Valgrind
123 gdbserver processes running and then exit.
124 -T
126 Instructs vgdb to add timestamps to vgdb information messages.
127 -D
129 Instructs a standalone vgdb to show the state of the shared memory
130 used by the Valgrind gdbserver. vgdb will exit after having shown
131 the Valgrind gdbserver shared memory state.
132 -d
134 Instructs vgdb to produce debugging output. Give multiple -d args
135 to increase the verbosity. When giving -d to a relay vgdb, you
136 better redirect the standard error (stderr) of vgdb to a file to
137 avoid interaction between GDB and vgdb debugging output.
138
140 valgrind(1), $INSTALL/share/doc/valgrind/html/index.html or
141 http://www.valgrind.org/docs/manual/index.html,
142 Debugging your program using Valgrind's gdbserver and GDB[1] vgdb[2],
144 Valgrind monitor commands[3].
145
147 Philippe Waroquiers.
148
150 1. Debugging your program using Valgrind's gdbserver and GDB
151 http://www.valgrind.org/docs/manual/manual-core-adv.html#manual-core-adv.gdbserver
152 2. vgdb
154 http://www.valgrind.org/docs/manual/manual-core-adv.html#manual-core-adv.vgdb
155 3. Valgrind monitor commands
157 http://www.valgrind.org/docs/manual/manual-core-adv.html#manual-core-adv.valgrind-monitor-commands
158Release 3.22.0 10/31/2023 VGDB(1)