• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1<?xml version="1.0"?> <!-- -*- sgml -*- -->
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
4[ <!ENTITY % vg-entities SYSTEM "vg-entities.xml"> %vg-entities; ]>
5
6
7<chapter id="manual-core-adv" xreflabel="Valgrind's core: advanced topics">
8<title>Using and understanding the Valgrind core: Advanced Topics</title>
9
10<para>This chapter describes advanced aspects of the Valgrind core
11services, which are mostly of interest to power users who wish to
12customise and modify Valgrind's default behaviours in certain useful
13ways.  The subjects covered are:</para>
14
15<itemizedlist>
16  <listitem><para>The "Client Request" mechanism</para></listitem>
17  <listitem><para>Debugging your program using Valgrind's gdbserver
18      and GDB</para></listitem>
19  <listitem><para>Function Wrapping</para></listitem>
20</itemizedlist>
21
22
23
24<sect1 id="manual-core-adv.clientreq"
25       xreflabel="The Client Request mechanism">
26<title>The Client Request mechanism</title>
27
28<para>Valgrind has a trapdoor mechanism via which the client
29program can pass all manner of requests and queries to Valgrind
30and the current tool.  Internally, this is used extensively
31to make various things work, although that's not visible from the
32outside.</para>
33
34<para>For your convenience, a subset of these so-called client
35requests is provided to allow you to tell Valgrind facts about
36the behaviour of your program, and also to make queries.
37In particular, your program can tell Valgrind about things that it
38otherwise would not know, leading to better results.
39</para>
40
41<para>Clients need to include a header file to make this work.
42Which header file depends on which client requests you use.  Some
43client requests are handled by the core, and are defined in the
44header file <filename>valgrind/valgrind.h</filename>.  Tool-specific
45header files are named after the tool, e.g.
46<filename>valgrind/memcheck.h</filename>.  Each tool-specific header file
47includes <filename>valgrind/valgrind.h</filename> so you don't need to
48include it in your client if you include a tool-specific header.  All header
49files can be found in the <literal>include/valgrind</literal> directory of
50wherever Valgrind was installed.</para>
51
52<para>The macros in these header files have the magical property
53that they generate code in-line which Valgrind can spot.
54However, the code does nothing when not run on Valgrind, so you
55are not forced to run your program under Valgrind just because you
56use the macros in this file.  Also, you are not required to link your
57program with any extra supporting libraries.</para>
58
59<para>The code added to your binary has negligible performance impact:
60on x86, amd64, ppc32, ppc64 and ARM, the overhead is 6 simple integer
61instructions and is probably undetectable except in tight loops.
62However, if you really wish to compile out the client requests, you
63can compile with <option>-DNVALGRIND</option> (analogous to
64<option>-DNDEBUG</option>'s effect on
65<function>assert</function>).
66</para>
67
68<para>You are encouraged to copy the <filename>valgrind/*.h</filename> headers
69into your project's include directory, so your program doesn't have a
70compile-time dependency on Valgrind being installed.  The Valgrind headers,
71unlike most of the rest of the code, are under a BSD-style license so you may
72include them without worrying about license incompatibility.</para>
73
74<para>Here is a brief description of the macros available in
75<filename>valgrind.h</filename>, which work with more than one
76tool (see the tool-specific documentation for explanations of the
77tool-specific macros).</para>
78
79 <variablelist>
80
81  <varlistentry>
82   <term><command><computeroutput>RUNNING_ON_VALGRIND</computeroutput></command>:</term>
83   <listitem>
84    <para>Returns 1 if running on Valgrind, 0 if running on the
85    real CPU.  If you are running Valgrind on itself, returns the
86    number of layers of Valgrind emulation you're running on.
87    </para>
88   </listitem>
89  </varlistentry>
90
91  <varlistentry>
92   <term><command><computeroutput>VALGRIND_DISCARD_TRANSLATIONS</computeroutput>:</command></term>
93   <listitem>
94    <para>Discards translations of code in the specified address
95    range.  Useful if you are debugging a JIT compiler or some other
96    dynamic code generation system.  After this call, attempts to
97    execute code in the invalidated address range will cause
98    Valgrind to make new translations of that code, which is
99    probably the semantics you want.  Note that code invalidations
100    are expensive because finding all the relevant translations
101    quickly is very difficult, so try not to call it often.
102    Note that you can be clever about
103    this: you only need to call it when an area which previously
104    contained code is overwritten with new code.  You can choose
105    to write code into fresh memory, and just call this
106    occasionally to discard large chunks of old code all at
107    once.</para>
108    <para>
109    Alternatively, for transparent self-modifying-code support,
110    use<option>--smc-check=all</option>, or run
111    on ppc32/Linux, ppc64/Linux or ARM/Linux.
112    </para>
113   </listitem>
114  </varlistentry>
115
116  <varlistentry>
117   <term><command><computeroutput>VALGRIND_COUNT_ERRORS</computeroutput>:</command></term>
118   <listitem>
119    <para>Returns the number of errors found so far by Valgrind.  Can be
120    useful in test harness code when combined with the
121    <option>--log-fd=-1</option> option; this runs Valgrind silently,
122    but the client program can detect when errors occur.  Only useful
123    for tools that report errors, e.g. it's useful for Memcheck, but for
124    Cachegrind it will always return zero because Cachegrind doesn't
125    report errors.</para>
126   </listitem>
127  </varlistentry>
128
129  <varlistentry>
130   <term><command><computeroutput>VALGRIND_MALLOCLIKE_BLOCK</computeroutput>:</command></term>
131   <listitem>
132    <para>If your program manages its own memory instead of using
133    the standard <function>malloc</function> /
134    <function>new</function> /
135    <function>new[]</function>, tools that track
136    information about heap blocks will not do nearly as good a
137    job.  For example, Memcheck won't detect nearly as many
138    errors, and the error messages won't be as informative.  To
139    improve this situation, use this macro just after your custom
140    allocator allocates some new memory.  See the comments in
141    <filename>valgrind.h</filename> for information on how to use
142    it.</para>
143   </listitem>
144  </varlistentry>
145
146  <varlistentry>
147   <term><command><computeroutput>VALGRIND_FREELIKE_BLOCK</computeroutput>:</command></term>
148   <listitem>
149    <para>This should be used in conjunction with
150    <computeroutput>VALGRIND_MALLOCLIKE_BLOCK</computeroutput>.
151    Again, see <filename>valgrind.h</filename> for
152    information on how to use it.</para>
153   </listitem>
154  </varlistentry>
155
156  <varlistentry>
157   <term><command><computeroutput>VALGRIND_RESIZEINPLACE_BLOCK</computeroutput>:</command></term>
158   <listitem>
159    <para>Informs a Valgrind tool that the size of an allocated block has been
160    modified but not its address. See <filename>valgrind.h</filename> for
161    more information on how to use it.</para>
162   </listitem>
163  </varlistentry>
164
165  <varlistentry>
166   <term>
167   <command><computeroutput>VALGRIND_CREATE_MEMPOOL</computeroutput></command>,
168   <command><computeroutput>VALGRIND_DESTROY_MEMPOOL</computeroutput></command>,
169   <command><computeroutput>VALGRIND_MEMPOOL_ALLOC</computeroutput></command>,
170   <command><computeroutput>VALGRIND_MEMPOOL_FREE</computeroutput></command>,
171   <command><computeroutput>VALGRIND_MOVE_MEMPOOL</computeroutput></command>,
172   <command><computeroutput>VALGRIND_MEMPOOL_CHANGE</computeroutput></command>,
173   <command><computeroutput>VALGRIND_MEMPOOL_EXISTS</computeroutput></command>:
174   </term>
175   <listitem>
176    <para>These are similar to
177    <computeroutput>VALGRIND_MALLOCLIKE_BLOCK</computeroutput> and
178    <computeroutput>VALGRIND_FREELIKE_BLOCK</computeroutput>
179    but are tailored towards code that uses memory pools.  See
180    <xref linkend="mc-manual.mempools"/> for a detailed description.</para>
181   </listitem>
182  </varlistentry>
183
184  <varlistentry>
185   <term><command><computeroutput>VALGRIND_NON_SIMD_CALL[0123]</computeroutput>:</command></term>
186   <listitem>
187    <para>Executes a function in the client program on the
188    <emphasis>real</emphasis> CPU, not the virtual CPU that Valgrind
189    normally runs code on.  The function must take an integer (holding a
190    thread ID) as the first argument and then 0, 1, 2 or 3 more arguments
191    (depending on which client request is used).  These are used in various
192    ways internally to Valgrind.  They might be useful to client
193    programs.</para>
194
195    <para><command>Warning:</command> Only use these if you
196    <emphasis>really</emphasis> know what you are doing.  They aren't
197    entirely reliable, and can cause Valgrind to crash.  See
198    <filename>valgrind.h</filename> for more details.
199    </para>
200   </listitem>
201  </varlistentry>
202
203  <varlistentry>
204   <term><command><computeroutput>VALGRIND_PRINTF(format, ...)</computeroutput>:</command></term>
205   <listitem>
206    <para>Print a printf-style message to the Valgrind log file.  The
207    message is prefixed with the PID between a pair of
208    <computeroutput>**</computeroutput> markers.  (Like all client requests,
209    nothing is output if the client program is not running under Valgrind.)
210    Output is not produced until a newline is encountered, or subsequent
211    Valgrind output is printed; this allows you to build up a single line of
212    output over multiple calls.  Returns the number of characters output,
213    excluding the PID prefix.</para>
214   </listitem>
215  </varlistentry>
216
217  <varlistentry>
218   <term><command><computeroutput>VALGRIND_PRINTF_BACKTRACE(format, ...)</computeroutput>:</command></term>
219   <listitem>
220    <para>Like <computeroutput>VALGRIND_PRINTF</computeroutput> (in
221    particular, the return value is identical), but prints a stack backtrace
222    immediately afterwards.</para>
223   </listitem>
224  </varlistentry>
225
226  <varlistentry>
227   <term><command><computeroutput>VALGRIND_MONITOR_COMMAND(command)</computeroutput>:</command></term>
228   <listitem>
229    <para>Execute the given monitor command (a string).
230    Returns 0 if command is recognised. Returns 1 if command is not recognised.
231    Note that some monitor commands provide access to a functionality
232    also accessible via a specific client request. For example,
233    memcheck leak search can be requested from the client program
234    using VALGRIND_DO_LEAK_CHECK or via the monitor command "leak_search".
235    Note that the syntax of the command string is only verified at
236    run-time. So, if it exists, it is preferrable to use a specific
237    client request to have better compile time verifications of the
238    arguments.
239    </para>
240   </listitem>
241  </varlistentry>
242
243  <varlistentry>
244   <term><command><computeroutput>VALGRIND_STACK_REGISTER(start, end)</computeroutput>:</command></term>
245   <listitem>
246    <para>Registers a new stack.  Informs Valgrind that the memory range
247    between start and end is a unique stack.  Returns a stack identifier
248    that can be used with other
249    <computeroutput>VALGRIND_STACK_*</computeroutput> calls.</para>
250    <para>Valgrind will use this information to determine if a change
251    to the stack pointer is an item pushed onto the stack or a change
252    over to a new stack.  Use this if you're using a user-level thread
253    package and are noticing crashes in stack trace recording or
254    spurious errors from Valgrind about uninitialized memory
255    reads.</para>
256
257    <para><command>Warning:</command> Unfortunately, this client request is
258    unreliable and best avoided.</para>
259   </listitem>
260  </varlistentry>
261
262  <varlistentry>
263   <term><command><computeroutput>VALGRIND_STACK_DEREGISTER(id)</computeroutput>:</command></term>
264   <listitem>
265    <para>Deregisters a previously registered stack.  Informs
266    Valgrind that previously registered memory range with stack id
267    <computeroutput>id</computeroutput> is no longer a stack.</para>
268
269    <para><command>Warning:</command> Unfortunately, this client request is
270    unreliable and best avoided.</para>
271   </listitem>
272  </varlistentry>
273
274  <varlistentry>
275   <term><command><computeroutput>VALGRIND_STACK_CHANGE(id, start, end)</computeroutput>:</command></term>
276   <listitem>
277    <para>Changes a previously registered stack.  Informs
278    Valgrind that the previously registered stack with stack id
279    <computeroutput>id</computeroutput> has changed its start and end
280    values.  Use this if your user-level thread package implements
281    stack growth.</para>
282
283    <para><command>Warning:</command> Unfortunately, this client request is
284    unreliable and best avoided.</para>
285   </listitem>
286  </varlistentry>
287
288 </variablelist>
289
290</sect1>
291
292
293
294
295
296
297<!-- Referenced from both the manual and manpage -->
298<sect1 id="&vg-gdbserver-id;"
299       xreflabel="&vg-gdbserver-label;">
300<title>Debugging your program using Valgrind gdbserver and GDB</title>
301
302<para>A program running under Valgrind is not executed directly by the
303CPU.  Instead it runs on a synthetic CPU provided by Valgrind.  This is
304why a debugger cannot debug your program when it runs on Valgrind.
305</para>
306<para>
307This section describes how GDB can interact with the
308Valgrind gdbserver to provide a fully debuggable program under
309Valgrind. Used in this way, GDB also provides an interactive usage of
310Valgrind core or tool functionalities, including incremental leak search
311under Memcheck and on-demand Massif snapshot production.
312</para>
313
314<sect2 id="manual-core-adv.gdbserver-simple"
315       xreflabel="gdbserver simple example">
316<title>Quick Start: debugging in 3 steps</title>
317
318<para>The simplest way to get started is to run Valgrind with the
319flag <option>--vgdb-error=0</option>.  Then follow the on-screen
320directions, which give you the precise commands needed to start GDB
321and connect it to your program.</para>
322
323<para>Otherwise, here's a slightly more verbose overview.</para>
324
325<para>If you want to debug a program with GDB when using the Memcheck
326tool, start Valgrind like this:
327<screen><![CDATA[
328valgrind --vgdb=yes --vgdb-error=0 prog
329]]></screen></para>
330
331<para>In another shell, start GDB:
332<screen><![CDATA[
333gdb prog
334]]></screen></para>
335
336<para>Then give the following command to GDB:
337<screen><![CDATA[
338(gdb) target remote | vgdb
339]]></screen></para>
340
341<para>You can now debug your program e.g. by inserting a breakpoint
342and then using the GDB <computeroutput>continue</computeroutput>
343command.</para>
344
345<para>This quick start information is enough for basic usage of the
346Valgrind gdbserver.  The sections below describe more advanced
347functionality provided by the combination of Valgrind and GDB. Note
348that the command line flag <option>--vgdb=yes</option> can be omitted,
349as this is the default value.
350</para>
351
352</sect2>
353
354<sect2 id="manual-core-adv.gdbserver-concept"
355       xreflabel="gdbserver">
356<title>Valgrind gdbserver overall organisation</title>
357<para>The GNU GDB debugger is typically used to debug a process
358running on the same machine.  In this mode, GDB uses system calls to
359control and query the program being debugged.  This works well, but
360only allows GDB to debug a program running on the same computer.
361</para>
362
363<para>GDB can also debug processes running on a different computer.
364To achieve this, GDB defines a protocol (that is, a set of query and
365reply packets) that facilitates fetching the value of memory or
366registers, setting breakpoints, etc.  A gdbserver is an implementation
367of this "GDB remote debugging" protocol.  To debug a process running
368on a remote computer, a gdbserver (sometimes called a GDB stub)
369must run at the remote computer side.
370</para>
371
372<para>The Valgrind core provides a built-in gdbserver implementation,
373which is activated using <option>--vgdb=yes</option>
374or <option>--vgdb=full</option>.  This gdbserver allows the process
375running on Valgrind's synthetic CPU to be debugged remotely.
376GDB sends protocol query packets (such as "get register contents") to
377the Valgrind embedded gdbserver.  The gdbserver executes the queries
378(for example, it will get the register values of the synthetic CPU)
379and gives the results back to GDB.
380</para>
381
382<para>GDB can use various kinds of channels (TCP/IP, serial line, etc)
383to communicate with the gdbserver.  In the case of Valgrind's
384gdbserver, communication is done via a pipe and a small helper program
385called <xref linkend="&vg-vgdb-id;"/>, which acts as an
386intermediary.  If no GDB is in use, vgdb can also be
387used to send monitor commands to the Valgrind gdbserver from a shell
388command line.
389</para>
390
391</sect2>
392
393<sect2 id="manual-core-adv.gdbserver-gdb"
394       xreflabel="Connecting GDB to a Valgrind gdbserver">
395<title>Connecting GDB to a Valgrind gdbserver</title>
396<para>To debug a program "<filename>prog</filename>" running under
397Valgrind, you must ensure that the Valgrind gdbserver is activated by
398specifying either <option>--vgdb=yes</option>
399or <option>--vgdb=full</option>.  A secondary command line option,
400<option>--vgdb-error=number</option>, can be used to tell the gdbserver
401only to become active once the specified number of errors have been
402shown.  A value of zero will therefore cause
403the gdbserver to become active at startup, which allows you to
404insert breakpoints before starting the run.  For example:
405<screen><![CDATA[
406valgrind --tool=memcheck --vgdb=yes --vgdb-error=0 ./prog
407]]></screen></para>
408
409<para>The Valgrind gdbserver is invoked at startup
410and indicates it is waiting for a connection from a GDB:</para>
411
412<programlisting><![CDATA[
413==2418== Memcheck, a memory error detector
414==2418== Copyright (C) 2002-2010, and GNU GPL'd, by Julian Seward et al.
415==2418== Using Valgrind-3.7.0.SVN and LibVEX; rerun with -h for copyright info
416==2418== Command: ./prog
417==2418==
418==2418== (action at startup) vgdb me ...
419]]></programlisting>
420
421
422<para>GDB (in another shell) can then be connected to the Valgrind gdbserver.
423For this, GDB must be started on the program <filename>prog</filename>:
424<screen><![CDATA[
425gdb ./prog
426]]></screen></para>
427
428
429<para>You then indicate to GDB that you want to debug a remote target:
430<screen><![CDATA[
431(gdb) target remote | vgdb
432]]></screen>
433GDB then starts a vgdb relay application to communicate with the
434Valgrind embedded gdbserver:</para>
435
436<programlisting><![CDATA[
437(gdb) target remote | vgdb
438Remote debugging using | vgdb
439relaying data between gdb and process 2418
440Reading symbols from /lib/ld-linux.so.2...done.
441Reading symbols from /usr/lib/debug/lib/ld-2.11.2.so.debug...done.
442Loaded symbols for /lib/ld-linux.so.2
443[Switching to Thread 2418]
4440x001f2850 in _start () from /lib/ld-linux.so.2
445(gdb)
446]]></programlisting>
447
448<para>Note that vgdb is provided as part of the Valgrind
449distribution.  You do not need to install it separately.</para>
450
451<para>If vgdb detects that there are multiple Valgrind gdbservers that
452can be connected to, it will list all such servers and their PIDs, and
453then exit.  You can then reissue the GDB "target" command, but
454specifying the PID of the process you want to debug:
455</para>
456
457<programlisting><![CDATA[
458(gdb) target remote | vgdb
459Remote debugging using | vgdb
460no --pid= arg given and multiple valgrind pids found:
461use --pid=2479 for valgrind --tool=memcheck --vgdb=yes --vgdb-error=0 ./prog
462use --pid=2481 for valgrind --tool=memcheck --vgdb=yes --vgdb-error=0 ./prog
463use --pid=2483 for valgrind --vgdb=yes --vgdb-error=0 ./another_prog
464Remote communication error: Resource temporarily unavailable.
465(gdb)  target remote | vgdb --pid=2479
466Remote debugging using | vgdb --pid=2479
467relaying data between gdb and process 2479
468Reading symbols from /lib/ld-linux.so.2...done.
469Reading symbols from /usr/lib/debug/lib/ld-2.11.2.so.debug...done.
470Loaded symbols for /lib/ld-linux.so.2
471[Switching to Thread 2479]
4720x001f2850 in _start () from /lib/ld-linux.so.2
473(gdb)
474]]></programlisting>
475
476<para>Once GDB is connected to the Valgrind gdbserver, it can be used
477in the same way as if you were debugging the program natively:</para>
478 <itemizedlist>
479  <listitem>
480    <para>Breakpoints can be inserted or deleted.</para>
481  </listitem>
482  <listitem>
483    <para>Variables and register values can be examined or modified.
484    </para>
485  </listitem>
486  <listitem>
487    <para>Signal handling can be configured (printing, ignoring).
488    </para>
489  </listitem>
490  <listitem>
491    <para>Execution can be controlled (continue, step, next, stepi, etc).
492    </para>
493  </listitem>
494  <listitem>
495    <para>Program execution can be interrupted using Control-C.</para>
496  </listitem>
497 </itemizedlist>
498
499<para>And so on.  Refer to the GDB user manual for a complete
500description of GDB's functionality.
501</para>
502
503</sect2>
504
505<sect2 id="manual-core-adv.gdbserver-gdb-android"
506       xreflabel="Connecting to an Android gdbserver">
507<title>Connecting to an Android gdbserver</title>
508<para> When developping applications for Android, you will typically use
509a development system (on which the Android NDK is installed) to compile your
510application. An Android target system or emulator will be used to run
511the application.
512In this setup, Valgrind and vgdb will run on the Android system,
513while GDB will run on the development system. GDB will connect
514to the vgdb running on the Android system using the Android NDK
515'adb forward' application.
516</para>
517<para> Example: on the Android system, execute the following:
518    <screen><![CDATA[
519valgrind --vgdb-error=0 --vgdb=yes prog
520# and then in another shell, run:
521vgdb --port=1234
522]]></screen>
523</para>
524
525<para> On the development system, execute the following commands:
526<screen><![CDATA[
527adb forward tcp:1234 tcp:1234
528gdb prog
529(gdb) target remote :1234
530]]></screen>
531GDB will use a local tcp/ip connection to connect to the Android adb forwarder.
532Adb will establish a relay connection between the host system and the Android
533target system.  Be sure to use the GDB delivered in the
534Android NDK system (typically, arm-linux-androideabi-gdb), as the host
535GDB is probably not able to debug Android arm applications.
536Note that the local port nr (used by GDB) must not necessarily be equal
537to the port number used by vgdb: adb can forward tcp/ip between different
538port numbers.
539</para>
540
541<para>In the current release, the GDB server is not enabled by default
542for Android, due to problems in establishing a suitable directory in
543which Valgrind can create the necessary FIFOs (named pipes) for
544communication purposes.  You can stil try to use the GDB server, but
545you will need to explicitly enable it using the flag
546<computeroutput>--vgdb=yes</computeroutput> or
547<computeroutput>--vgdb=full</computeroutput>.
548</para>
549
550<para>Additionally, you
551will need to select a temporary directory which is (a) writable
552by Valgrind, and (b) supports FIFOs.  This is the main difficult
553point.  Often, <computeroutput>/sdcard</computeroutput> satisfies
554requirement (a), but fails for (b) because it is a VFAT file system
555and VFAT does not support pipes.  Possibilities you could try are
556<computeroutput>/data/local</computeroutput>,
557<computeroutput>/data/local/Inst</computeroutput> (if you
558installed Valgrind there), or
559<computeroutput>/data/data/name.of.my.app</computeroutput>, if you
560are running a specific application and it has its own directory of
561that form.  This last possibility may have the highest probability
562of success.</para>
563
564<para>You can specify the temporary directory to use either via
565the <computeroutput>--with-tmpdir=</computeroutput> configure time
566flag, or by setting environment variable TMPDIR when running Valgrind
567(on the Android device, not on the Android NDK development host).
568Another alternative is to specify the directory for the FIFOs using
569the <computeroutput>--vgdb-prefix=</computeroutput> Valgrind command
570line option.
571</para>
572
573<para>We hope to have a better story for temporary directory handling
574on Android in the future.  The difficulty is that, unlike in standard
575Unixes, there is no single temporary file directory that reliably
576works across all devices and scenarios.
577</para>
578
579</sect2>
580
581<sect2 id="manual-core-adv.gdbserver-commandhandling"
582       xreflabel="Monitor command handling by the Valgrind gdbserver">
583<title>Monitor command handling by the Valgrind gdbserver</title>
584
585<para> The Valgrind gdbserver provides additional Valgrind-specific
586functionality via "monitor commands".  Such monitor commands can be
587sent from the GDB command line or from the shell command line or
588requested by the client program using the VALGRIND_MONITOR_COMMAND
589client request.  See
590<xref linkend="&vg-monitor-id;"/> for the
591list of the Valgrind core monitor commands available regardless of the
592Valgrind tool selected.
593</para>
594
595<para>The following tools provide tool-specific monitor commands:
596  <itemizedlist>
597    <listitem>
598      <para><xref linkend="mc-manual.monitor-commands"/></para>
599    </listitem>
600    <listitem>
601      <para><xref linkend="cl-manual.monitor-commands"/></para>
602    </listitem>
603    <listitem>
604      <para><xref linkend="ms-manual.monitor-commands"/></para>
605    </listitem>
606    <listitem>
607      <para><xref linkend="hg-manual.monitor-commands"/></para>
608    </listitem>
609  </itemizedlist>
610</para>
611
612<para>An example of a tool specific monitor command is the Memcheck monitor
613command <computeroutput>leak_check full
614reachable any</computeroutput>.  This requests a full reporting of the
615allocated memory blocks.  To have this leak check executed, use the GDB
616command:
617<screen><![CDATA[
618(gdb) monitor leak_check full reachable any
619]]></screen>
620</para>
621
622<para>GDB will send the <computeroutput>leak_check</computeroutput>
623command to the Valgrind gdbserver.  The Valgrind gdbserver will
624execute the monitor command itself, if it recognises it to be a Valgrind core
625monitor command.  If it is not recognised as such, it is assumed to
626be tool-specific and is handed to the tool for execution.  For example:
627</para>
628<programlisting><![CDATA[
629(gdb) monitor leak_check full reachable any
630==2418== 100 bytes in 1 blocks are still reachable in loss record 1 of 1
631==2418==    at 0x4006E9E: malloc (vg_replace_malloc.c:236)
632==2418==    by 0x804884F: main (prog.c:88)
633==2418==
634==2418== LEAK SUMMARY:
635==2418==    definitely lost: 0 bytes in 0 blocks
636==2418==    indirectly lost: 0 bytes in 0 blocks
637==2418==      possibly lost: 0 bytes in 0 blocks
638==2418==    still reachable: 100 bytes in 1 blocks
639==2418==         suppressed: 0 bytes in 0 blocks
640==2418==
641(gdb)
642]]></programlisting>
643
644<para>As with other GDB commands, the Valgrind gdbserver will accept
645abbreviated monitor command names and arguments, as long as the given
646abbreviation is unambiguous.  For example, the above
647<computeroutput>leak_check</computeroutput>
648command can also be typed as:
649<screen><![CDATA[
650(gdb) mo l f r a
651]]></screen>
652
653The letters <computeroutput>mo</computeroutput> are recognised by GDB as being
654an abbreviation for <computeroutput>monitor</computeroutput>.  So GDB sends the
655string <computeroutput>l f r a</computeroutput> to the Valgrind
656gdbserver.  The letters provided in this string are unambiguous for the
657Valgrind gdbserver.  This therefore gives the same output as the
658unabbreviated command and arguments.  If the provided abbreviation is
659ambiguous, the Valgrind gdbserver will report the list of commands (or
660argument values) that can match:
661<programlisting><![CDATA[
662(gdb) mo v. n
663v. can match v.set v.info v.wait v.kill v.translate v.do
664(gdb) mo v.i n
665n_errs_found 0 n_errs_shown 0 (vgdb-error 0)
666(gdb)
667]]></programlisting>
668</para>
669
670<para>Instead of sending a monitor command from GDB, you can also send
671these from a shell command line.  For example, the following command
672lines, when given in a shell, will cause the same leak search to be executed
673by the process 3145:
674<screen><![CDATA[
675vgdb --pid=3145 leak_check full reachable any
676vgdb --pid=3145 l f r a
677]]></screen></para>
678
679<para>Note that the Valgrind gdbserver automatically continues the
680execution of the program after a standalone invocation of
681vgdb.  Monitor commands sent from GDB do not cause the program to
682continue: the program execution is controlled explicitly using GDB
683commands such as "continue" or "next".</para>
684
685</sect2>
686
687<sect2 id="manual-core-adv.gdbserver-threads"
688       xreflabel="Valgrind gdbserver thread information">
689<title>Valgrind gdbserver thread information</title>
690
691<para>Valgrind's gdbserver enriches the output of the
692GDB <computeroutput>info threads</computeroutput> command
693with Valgrind-specific information.
694The operating system's thread number is followed
695by Valgrind's internal index for that thread ("tid") and by
696the Valgrind scheduler thread state:</para>
697
698<programlisting><![CDATA[
699(gdb) info threads
700  4 Thread 6239 (tid 4 VgTs_Yielding)  0x001f2832 in _dl_sysinfo_int80 () from /lib/ld-linux.so.2
701* 3 Thread 6238 (tid 3 VgTs_Runnable)  make_error (s=0x8048b76 "called from London") at prog.c:20
702  2 Thread 6237 (tid 2 VgTs_WaitSys)  0x001f2832 in _dl_sysinfo_int80 () from /lib/ld-linux.so.2
703  1 Thread 6234 (tid 1 VgTs_Yielding)  main (argc=1, argv=0xbedcc274) at prog.c:105
704(gdb)
705]]></programlisting>
706
707</sect2>
708
709<sect2 id="manual-core-adv.gdbserver-shadowregisters"
710       xreflabel="Examining and modifying Valgrind shadow registers">
711<title>Examining and modifying Valgrind shadow registers</title>
712
713<para> When the option <option>--vgdb-shadow-registers=yes</option> is
714given, the Valgrind gdbserver will let GDB examine and/or modify
715Valgrind's shadow registers.  GDB version 7.1 or later is needed for this
716to work. For x86 and amd64, GDB version 7.2 or later is needed.</para>
717
718<para>For each CPU register, the Valgrind core maintains two
719shadow register sets.  These shadow registers can be accessed from
720GDB by giving a postfix <computeroutput>s1</computeroutput>
721or <computeroutput>s2</computeroutput> for respectively the first
722and second shadow register.  For example, the x86 register
723<computeroutput>eax</computeroutput> and its two shadows
724can be examined using the following commands:</para>
725
726<programlisting><![CDATA[
727(gdb) p $eax
728$1 = 0
729(gdb) p $eaxs1
730$2 = 0
731(gdb) p $eaxs2
732$3 = 0
733(gdb)
734]]></programlisting>
735
736<para>Float shadow registers are shown by GDB as unsigned integer
737values instead of float values, as it is expected that these
738shadow values are mostly used for memcheck validity bits. </para>
739
740<para>Intel/amd64 AVX registers <computeroutput>ymm0</computeroutput>
741to <computeroutput>ymm15</computeroutput> have also their shadow
742registers. However, GDB presents the shadow values using two
743"half" registers. For example, the half shadow registers for
744<computeroutput>ymm9</computeroutput> are
745<computeroutput>xmm9s1</computeroutput> (lower half for set 1),
746<computeroutput>ymm9hs1</computeroutput> (upper half for set 1),
747<computeroutput>xmm9s2</computeroutput> (lower half for set 2),
748<computeroutput>ymm9hs2</computeroutput> (upper half for set 2).
749Note the inconsistent notation for the names of the half registers:
750the lower part starts with an <computeroutput>x</computeroutput>,
751the upper part starts with an <computeroutput>y</computeroutput>
752and has an <computeroutput>h</computeroutput> before the shadow postfix.
753</para>
754<para>The special presentation of the AVX shadow registers is due to
755the fact that GDB independently retrieves the lower and upper half of
756the <computeroutput>ymm</computeroutput> registers.  GDB does not
757however know that the shadow half registers have to be shown combined.
758</para>
759</sect2>
760
761
762<sect2 id="manual-core-adv.gdbserver-limitations"
763       xreflabel="Limitations of the Valgrind gdbserver">
764<title>Limitations of the Valgrind gdbserver</title>
765
766<para>Debugging with the Valgrind gdbserver is very similar to native
767debugging.  Valgrind's gdbserver implementation is quite
768complete, and so provides most of the GDB debugging functionality.  There
769are however some limitations and peculiarities:</para>
770 <itemizedlist>
771   <listitem>
772     <para>Precision of "stop-at" commands.</para>
773     <para>
774       GDB commands such as "step", "next", "stepi", breakpoints
775       and watchpoints, will stop the execution of the process.  With
776       the option <option>--vgdb=yes</option>, the process might not
777       stop at the exact requested instruction. Instead, it might
778       continue execution of the current basic block and stop at one
779       of the following basic blocks. This is linked to the fact that
780       Valgrind gdbserver has to instrument a block to allow stopping
781       at the exact instruction requested.  Currently,
782       re-instrumentation of the block currently being executed is not
783       supported. So, if the action requested by GDB (e.g. single
784       stepping or inserting a breakpoint) implies re-instrumentation
785       of the current block, the GDB action may not be executed
786       precisely.
787     </para>
788     <para>
789       This limitation applies when the basic block
790       currently being executed has not yet been instrumented for debugging.
791       This typically happens when the gdbserver is activated due to the
792       tool reporting an error or to a watchpoint.  If the gdbserver
793       block has been activated following a breakpoint, or if a
794       breakpoint has been inserted in the block before its execution,
795       then the block has already been instrumented for debugging.
796     </para>
797     <para>
798       If you use the option <option>--vgdb=full</option>, then GDB
799       "stop-at" commands will be obeyed precisely.  The
800       downside is that this requires each instruction to be
801       instrumented with an additional call to a gdbserver helper
802       function, which gives considerable overhead (+500% for memcheck)
803       compared to  <option>--vgdb=no</option>.
804       Option <option>--vgdb=yes</option> has neglectible overhead compared
805       to <option>--vgdb=no</option>.
806     </para>
807   </listitem>
808
809   <listitem>
810     <para>Processor registers and flags values.</para>
811     <para>When Valgrind gdbserver stops on an error, on a breakpoint
812     or when single stepping, registers and flags values might not be always
813     up to date due to the optimisations done by the Valgrind core.
814     The default value
815     <option>--vex-iropt-register-updates=unwindregs-at-mem-access</option>
816     ensures that the registers needed to make a stack trace (typically
817     PC/SP/FP) are up to date at each memory access (i.e. memory exception
818     points).
819     Disabling some optimisations using the following values will increase
820     the precision of registers and flags values (a typical performance
821     impact for memcheck is given for each option).
822       <itemizedlist>
823         <listitem>
824           <option>--vex-iropt-register-updates=allregs-at-mem-access</option> (+10%)
825           ensures that all registers and flags are up to date at each memory
826           access.
827         </listitem>
828         <listitem>
829           <option>--vex-iropt-register-updates=allregs-at-each-insn</option> (+25%)
830           ensures that all registers and flags are up to date at each instruction.
831         </listitem>
832       </itemizedlist>
833       Note that <option>--vgdb=full</option> (+500%, see above
834       Precision of "stop-at" commands) automatically
835       activates <option>--vex-iropt-register-updates=allregs-at-each-insn</option>.
836     </para>
837   </listitem>
838
839   <listitem>
840     <para>Hardware watchpoint support by the Valgrind
841     gdbserver.</para>
842
843     <para> The Valgrind gdbserver can simulate hardware watchpoints
844     if the selected tool provides support for it.  Currently,
845     only Memcheck provides hardware watchpoint simulation.  The
846     hardware watchpoint simulation provided by Memcheck is much
847     faster that GDB software watchpoints, which are implemented by
848     GDB checking the value of the watched zone(s) after each
849     instruction.  Hardware watchpoint simulation also provides read
850     watchpoints.  The hardware watchpoint simulation by Memcheck has
851     some limitations compared to real hardware
852     watchpoints. However, the number and length of simulated
853     watchpoints are not limited.
854     </para>
855     <para>Typically, the number of (real) hardware watchpoints is
856     limited.  For example, the x86 architecture supports a maximum of
857     4 hardware watchpoints, each watchpoint watching 1, 2, 4 or 8
858     bytes. The Valgrind gdbserver does not have any limitation on the
859     number of simulated hardware watchpoints. It also has no
860     limitation on the length of the memory zone being
861     watched.  Using GDB version 7.4 or later allow full use of the
862     flexibility of the Valgrind gdbserver's simulated hardware watchpoints.
863     Previous GDB versions do not understand that Valgrind gdbserver
864     watchpoints have no length limit.
865     </para>
866     <para>Memcheck implements hardware watchpoint simulation by
867     marking the watched address ranges as being unaddressable.  When
868     a hardware watchpoint is removed, the range is marked as
869     addressable and defined.  Hardware watchpoint simulation of
870     addressable-but-undefined memory zones works properly, but has
871     the undesirable side effect of marking the zone as defined when
872     the watchpoint is removed.
873     </para>
874     <para>Write watchpoints might not be reported at the
875     exact instruction that writes the monitored area,
876     unless option <option>--vgdb=full</option> is given.  Read watchpoints
877     will always be reported at the exact instruction reading the
878     watched memory.
879     </para>
880     <para>It is better to avoid using hardware watchpoint of not
881     addressable (yet) memory: in such a case, GDB will fall back to
882     extremely slow software watchpoints.  Also, if you do not quit GDB
883     between two debugging sessions, the hardware watchpoints of the
884     previous sessions will be re-inserted as software watchpoints if
885     the watched memory zone is not addressable at program startup.
886     </para>
887   </listitem>
888
889   <listitem>
890     <para>Stepping inside shared libraries on ARM.</para>
891     <para>For unknown reasons, stepping inside shared
892     libraries on ARM may fail.  A workaround is to use the
893     <computeroutput>ldd</computeroutput> command
894     to find the list of shared libraries and their loading address
895     and inform GDB of the loading address using the GDB command
896     "add-symbol-file". Example:
897     <programlisting><![CDATA[
898(gdb) shell ldd ./prog
899	libc.so.6 => /lib/libc.so.6 (0x4002c000)
900	/lib/ld-linux.so.3 (0x40000000)
901(gdb) add-symbol-file /lib/libc.so.6 0x4002c000
902add symbol table from file "/lib/libc.so.6" at
903	.text_addr = 0x4002c000
904(y or n) y
905Reading symbols from /lib/libc.so.6...(no debugging symbols found)...done.
906(gdb)
907]]></programlisting>
908     </para>
909   </listitem>
910
911   <listitem>
912     <para>GDB version needed for ARM and PPC32/64.</para>
913     <para>You must use a GDB version which is able to read XML
914     target description sent by a gdbserver.  This is the standard setup
915     if GDB was configured and built with the "expat"
916     library.  If your GDB was not configured with XML support, it
917     will report an error message when using the "target"
918     command.  Debugging will not work because GDB will then not be
919     able to fetch the registers from the Valgrind gdbserver.
920     For ARM programs using the Thumb instruction set, you must use
921     a GDB version of 7.1 or later, as earlier versions have problems
922     with next/step/breakpoints in Thumb code.
923     </para>
924   </listitem>
925
926   <listitem>
927     <para>Stack unwinding on PPC32/PPC64. </para>
928     <para>On PPC32/PPC64, stack unwinding for leaf functions
929     (functions that do not call any other functions) works properly
930     only when you give the option
931     <option>--vex-iropt-register-updates=allregs-at-mem-access</option>
932     or <option>--vex-iropt-register-updates=allregs-at-each-insn</option>.
933     You must also pass this option in order to get a precise stack when
934     a signal is trapped by GDB.
935     </para>
936   </listitem>
937
938   <listitem>
939     <para>Breakpoints encountered multiple times.</para>
940     <para>Some instructions (e.g. x86 "rep movsb")
941     are translated by Valgrind using a loop.  If a breakpoint is placed
942     on such an instruction, the breakpoint will be encountered
943     multiple times -- once for each step of the "implicit" loop
944     implementing the instruction.
945     </para>
946   </listitem>
947
948   <listitem>
949     <para>Execution of Inferior function calls by the Valgrind
950     gdbserver.</para>
951
952     <para>GDB allows the user to "call" functions inside the process
953     being debugged.  Such calls are named "inferior calls" in the GDB
954     terminology.  A typical use of an inferior call is to execute
955     a function that prints a human-readable version of a complex data
956     structure.  To make an inferior call, use the GDB "print" command
957     followed by the function to call and its arguments.  As an
958     example, the following GDB command causes an inferior call to the
959     libc "printf" function to be executed by the process
960     being debugged:
961     </para>
962     <programlisting><![CDATA[
963(gdb) p printf("process being debugged has pid %d\n", getpid())
964$5 = 36
965(gdb)
966]]></programlisting>
967
968     <para>The Valgrind gdbserver supports inferior function calls.
969     Whilst an inferior call is running, the Valgrind tool will report
970     errors as usual.  If you do not want to have such errors stop the
971     execution of the inferior call, you can
972     use <computeroutput>v.set vgdb-error</computeroutput> to set a
973     big value before the call, then manually reset it to its original
974     value when the call is complete.</para>
975
976     <para>To execute inferior calls, GDB changes registers such as
977     the program counter, and then continues the execution of the
978     program. In a multithreaded program, all threads are continued,
979     not just the thread instructed to make the inferior call.  If
980     another thread reports an error or encounters a breakpoint, the
981     evaluation of the inferior call is abandoned.</para>
982
983     <para>Note that inferior function calls are a powerful GDB
984     feature, but should be used with caution. For example, if
985     the program being debugged is stopped inside the function "printf",
986     forcing a recursive call to printf via an inferior call will
987     very probably create problems.  The Valgrind tool might also add
988     another level of complexity to inferior calls, e.g. by reporting
989     tool errors during the Inferior call or due to the
990     instrumentation done.
991     </para>
992
993   </listitem>
994
995   <listitem>
996     <para>Connecting to or interrupting a Valgrind process blocked in
997     a system call.</para>
998
999     <para>Connecting to or interrupting a Valgrind process blocked in
1000     a system call requires the "ptrace" system call to be usable.
1001     This may be disabled in your kernel for security reasons.
1002     </para>
1003
1004     <para>When running your program, Valgrind's scheduler
1005     periodically checks whether there is any work to be handled by
1006     the gdbserver.  Unfortunately this check is only done if at least
1007     one thread of the process is runnable.  If all the threads of the
1008     process are blocked in a system call, then the checks do not
1009     happen, and the Valgrind scheduler will not invoke the gdbserver.
1010     In such a case, the vgdb relay application will "force" the
1011     gdbserver to be invoked, without the intervention of the Valgrind
1012     scheduler.
1013     </para>
1014
1015     <para>Such forced invocation of the Valgrind gdbserver is
1016     implemented by vgdb using ptrace system calls.  On a properly
1017     implemented kernel, the ptrace calls done by vgdb will not
1018     influence the behaviour of the program running under Valgrind.
1019     If however they do, giving the
1020     option <option>--max-invoke-ms=0</option> to the vgdb relay
1021     application will disable the usage of ptrace calls.  The
1022     consequence of disabling ptrace usage in vgdb is that a Valgrind
1023     process blocked in a system call cannot be woken up or
1024     interrupted from GDB until it executes enough basic blocks to let
1025     the Valgrind scheduler's normal checking take effect.
1026     </para>
1027
1028     <para>When ptrace is disabled in vgdb, you can increase the
1029     responsiveness of the Valgrind gdbserver to commands or
1030     interrupts by giving a lower value to the
1031     option <option>--vgdb-poll</option>.  If your application is
1032     blocked in system calls most of the time, using a very low value
1033     for <option>--vgdb-poll</option> will cause a the gdbserver to be
1034     invoked sooner.  The gdbserver polling done by Valgrind's
1035     scheduler is very efficient, so the increased polling frequency
1036     should not cause significant performance degradation.
1037     </para>
1038
1039     <para>When ptrace is disabled in vgdb, a query packet sent by GDB
1040     may take significant time to be handled by the Valgrind
1041     gdbserver.  In such cases, GDB might encounter a protocol
1042     timeout.  To avoid this,
1043     you can increase the value of the timeout by using the GDB
1044     command "set remotetimeout".
1045     </para>
1046
1047     <para>Ubuntu versions 10.10 and later may restrict the scope of
1048     ptrace to the children of the process calling ptrace.  As the
1049     Valgrind process is not a child of vgdb, such restricted scoping
1050     causes the ptrace calls to fail.  To avoid that, Valgrind will
1051     automatically allow all processes belonging to the same userid to
1052     "ptrace" a Valgrind process, by using PR_SET_PTRACER.</para>
1053
1054     <para>Unblocking processes blocked in system calls is not
1055     currently implemented on Mac OS X and Android.  So you cannot
1056     connect to or interrupt a process blocked in a system call on Mac
1057     OS X or Android.
1058     </para>
1059
1060   </listitem>
1061
1062   <listitem>
1063     <para>Changing register values.</para>
1064     <para>The Valgrind gdbserver will only modify the values of the
1065     thread's registers when the thread is in status Runnable or
1066     Yielding.  In other states (typically, WaitSys), attempts to
1067     change register values will fail.  Amongst other things, this
1068     means that inferior calls are not executed for a thread which is
1069     in a system call, since the Valgrind gdbserver does not implement
1070     system call restart.
1071     </para>
1072   </listitem>
1073
1074   <listitem>
1075     <para>Unsupported GDB functionality.</para>
1076     <para>GDB provides a lot of debugging functionality and not all
1077     of it is supported.  Specifically, the following are not
1078     supported: reversible debugging and tracepoints.
1079     </para>
1080   </listitem>
1081
1082   <listitem>
1083     <para>Unknown limitations or problems.</para>
1084     <para>The combination of GDB, Valgrind and the Valgrind gdbserver
1085     probably has unknown other limitations and problems.  If you
1086     encounter strange or unexpected behaviour, feel free to report a
1087     bug.  But first please verify that the limitation or problem is
1088     not inherent to GDB or the GDB remote protocol.  You may be able
1089     to do so by checking the behaviour when using standard gdbserver
1090     part of the GDB package.
1091     </para>
1092   </listitem>
1093
1094 </itemizedlist>
1095
1096</sect2>
1097
1098<!-- Referenced from both the manual and manpage -->
1099<sect2 id="&vg-vgdb-id;"
1100       xreflabel="&vg-vgdb-label;">
1101<title>vgdb command line options</title>
1102<para> Usage: <computeroutput>vgdb [OPTION]... [[-c] COMMAND]...</computeroutput></para>
1103
1104<para> vgdb ("Valgrind to GDB") is a small program that is used as an
1105intermediary between Valgrind and GDB or a shell.
1106Therefore, it has two usage modes:
1107</para>
1108<!-- start of xi:include in the manpage -->
1109<orderedlist id="vgdb.desc.modes">
1110  <listitem id="manual-core-adv.vgdb-standalone" xreflabel="vgdb standalone">
1111    <para>As a standalone utility, it is used from a shell command
1112    line to send monitor commands to a process running under
1113    Valgrind. For this usage, the vgdb OPTION(s) must be followed by
1114    the monitor command to send. To send more than one command,
1115    separate them with the <option>-c</option> option.
1116    </para>
1117  </listitem>
1118
1119  <listitem id="manual-core-adv.vgdb-relay" xreflabel="vgdb relay">
1120    <para>In combination with GDB "target remote |" command, it is
1121    used as the relay application between GDB and the Valgrind
1122    gdbserver.  For this usage, only OPTION(s) can be given, but no
1123    COMMAND can be given.
1124    </para>
1125  </listitem>
1126
1127</orderedlist>
1128<!-- end of xi:include in the manpage -->
1129
1130<para><computeroutput>vgdb</computeroutput> accepts the following
1131options:</para>
1132<!-- start of xi:include in the manpage -->
1133<variablelist id="vgdb.opts.list">
1134  <varlistentry>
1135    <term><option>--pid=&lt;number&gt;</option></term>
1136    <listitem><para>Specifies the PID of
1137    the process to which vgdb must connect to.  This option is useful
1138    in case more than one Valgrind gdbserver can be connected to.  If
1139    the <option>--pid</option> argument is not given and multiple
1140    Valgrind gdbserver processes are running, vgdb will report the
1141    list of such processes and then exit.</para></listitem>
1142  </varlistentry>
1143
1144  <varlistentry>
1145    <term><option>--vgdb-prefix</option></term>
1146    <listitem><para>Must be given to both
1147    Valgrind and vgdb if you want to change the default prefix for the
1148    FIFOs (named pipes) used for communication between the Valgrind
1149    gdbserver and vgdb.</para></listitem>
1150  </varlistentry>
1151
1152  <varlistentry>
1153    <term><option>--wait=&lt;number&gt;</option></term>
1154    <listitem><para>Instructs vgdb to
1155    search for available Valgrind gdbservers for the specified number
1156    of seconds.  This makes it possible start a vgdb process
1157    before starting the Valgrind gdbserver with which you intend the
1158    vgdb to communicate.  This option is useful when used in
1159    conjunction with a <option>--vgdb-prefix</option> that is
1160    unique to the process you want to wait for.
1161    Also, if you use the <option>--wait</option> argument in the GDB
1162    "target remote" command, you must set the GDB remotetimeout to a
1163    value bigger than the --wait argument value.  See option
1164    <option>--max-invoke-ms</option> (just below)
1165    for an example of setting the remotetimeout value.</para></listitem>
1166  </varlistentry>
1167
1168  <varlistentry>
1169    <term><option>--max-invoke-ms=&lt;number&gt;</option></term>
1170    <listitem><para>Gives the
1171    number of milliseconds after which vgdb will force the invocation
1172    of gdbserver embedded in Valgrind.  The default value is 100
1173    milliseconds. A value of 0 disables forced invocation. The forced
1174    invocation is used when vgdb is connected to a Valgrind gdbserver,
1175    and the Valgrind process has all its threads blocked in a system
1176    call.
1177    </para>
1178
1179    <para>If you specify a large value, you might need to increase the
1180    GDB "remotetimeout" value from its default value of 2 seconds.
1181    You should ensure that the timeout (in seconds) is
1182    bigger than the <option>--max-invoke-ms</option> value.  For
1183    example, for <option>--max-invoke-ms=5000</option>, the following
1184    GDB command is suitable:
1185    <screen><![CDATA[
1186    (gdb) set remotetimeout 6
1187    ]]></screen>
1188    </para></listitem>
1189  </varlistentry>
1190
1191  <varlistentry>
1192    <term><option>--cmd-time-out=&lt;number&gt;</option></term>
1193    <listitem><para>Instructs a
1194    standalone vgdb to exit if the Valgrind gdbserver it is connected
1195    to does not process a command in the specified number of seconds.
1196    The default value is to never time out.</para></listitem>
1197  </varlistentry>
1198
1199  <varlistentry>
1200    <term><option>--port=&lt;portnr&gt;</option></term>
1201    <listitem><para>Instructs vgdb to
1202    use tcp/ip and listen for GDB on the specified port nr rather than
1203    to use a pipe to communicate with GDB. Using tcp/ip allows to have
1204    GDB running on one computer and debugging a Valgrind process
1205    running on another target computer.
1206    Example:
1207    <screen><![CDATA[
1208# On the target computer, start your program under valgrind using
1209valgrind --vgdb-error=0 prog
1210# and then in another shell, run:
1211vgdb --port=1234
1212]]></screen></para>
1213    <para>On the computer which hosts GDB, execute the command:
1214    <screen><![CDATA[
1215gdb prog
1216(gdb) target remote targetip:1234
1217]]></screen>
1218    where targetip is the ip address or hostname of the target computer.
1219    </para></listitem>
1220  </varlistentry>
1221
1222  <varlistentry>
1223    <term><option>-c</option></term>
1224    <listitem><para>To give more than one command to a
1225    standalone vgdb, separate the commands by an
1226    option <option>-c</option>. Example:
1227    <screen><![CDATA[
1228vgdb v.set log_output -c leak_check any
1229]]></screen></para></listitem>
1230  </varlistentry>
1231
1232  <varlistentry>
1233    <term><option>-l</option></term>
1234    <listitem><para>Instructs a standalone vgdb to report
1235    the list of the Valgrind gdbserver processes running and then
1236    exit.</para></listitem>
1237  </varlistentry>
1238
1239  <varlistentry>
1240    <term><option>-D</option></term>
1241    <listitem><para>Instructs a standalone vgdb to show the
1242    state of the shared memory used by the Valgrind gdbserver.  vgdb
1243    will exit after having shown the Valgrind gdbserver shared memory
1244    state.</para></listitem>
1245  </varlistentry>
1246
1247  <varlistentry>
1248    <term><option>-d</option></term>
1249    <listitem><para>Instructs vgdb to produce debugging
1250    output.  Give multiple <option>-d</option> args to increase the
1251    verbosity. When giving <option>-d</option> to a relay vgdb, you better
1252    redirect the standard error (stderr) of vgdb to a file to avoid
1253    interaction between GDB and vgdb debugging output.</para></listitem>
1254  </varlistentry>
1255
1256</variablelist>
1257<!-- end of xi:include in the manpage -->
1258
1259</sect2>
1260
1261
1262<!-- Referenced from both the manual and manpage -->
1263<sect2 id="&vg-monitor-id;"
1264       xreflabel="&vg-monitor-label;">
1265<title>Valgrind monitor commands</title>
1266
1267<para>This section describes the Valgrind monitor commands, available
1268regardless of the Valgrind tool selected. For the tool specific
1269commands, refer to <xref linkend="mc-manual.monitor-commands"/>,
1270<xref linkend="hg-manual.monitor-commands"/>,
1271<xref linkend="cl-manual.monitor-commands"/> and
1272<xref linkend="ms-manual.monitor-commands"/>. </para>
1273
1274<para> The monitor commands can be sent either from a shell command line, by using a
1275standalone vgdb, or from GDB, by using GDB's "monitor"
1276command (see <xref linkend="manual-core-adv.gdbserver-commandhandling"/>).
1277They can also be launched by the client program, using the VALGRIND_MONITOR_COMMAND
1278client request.
1279</para>
1280
1281<itemizedlist>
1282  <listitem>
1283    <para><varname>help [debug]</varname> instructs Valgrind's gdbserver
1284    to give the list of all monitor commands of the Valgrind core and
1285    of the tool. The optional "debug" argument tells to also give help
1286    for the monitor commands aimed at Valgrind internals debugging.
1287    </para>
1288  </listitem>
1289
1290  <listitem>
1291    <para><varname>v.info all_errors</varname> shows all errors found
1292    so far.</para>
1293  </listitem>
1294  <listitem>
1295    <para><varname>v.info last_error</varname> shows the last error
1296    found.</para>
1297  </listitem>
1298
1299  <listitem>
1300    <para><varname>v.info location &lt;addr&gt;</varname> outputs
1301    information about the location &lt;addr&gt;. Possibly, the
1302    following are described: global variables, local (stack)
1303    variables, allocated or freed blocks, ...  The information
1304    produced depends on the tool and on the options given to valgrind.
1305    Some tools (e.g. memcheck and helgrind) produce more detailed
1306    information for client heap blocks. For example, these tools show
1307    the stacktrace where the heap block was allocated. If a tool does
1308    not replace the malloc/free/... functions, then client heap blocks
1309    will not be described.  Use the
1310    option <varname>--read-var-info=yes</varname> to obtain more
1311    detailed information about global or local (stack) variables.
1312    </para>
1313<programlisting><![CDATA[
1314(gdb) monitor v.info location 0x8050b20
1315 Location 0x8050b20 is 0 bytes inside global var "mx"
1316 declared at tc19_shadowmem.c:19
1317
1318(gdb) mo v.in loc 0x582f33c
1319 Location 0x582f33c is 0 bytes inside local var "info"
1320 declared at tc19_shadowmem.c:282, in frame #1 of thread 3
1321(gdb)
1322]]></programlisting>
1323  </listitem>
1324
1325  <listitem>
1326    <para><varname>v.info n_errs_found [msg]</varname> shows the number of
1327    errors found so far, the nr of errors shown so far and the current
1328    value of the <option>--vgdb-error</option> argument. The optional
1329    <computeroutput>msg</computeroutput> (one or more words) is appended.
1330    Typically, this can be used to insert markers in a process output
1331    file between several tests executed in sequence by a process
1332    started only once. This allows to associate the errors reported
1333    by Valgrind with the specific test that produced these errors.
1334    </para>
1335  </listitem>
1336
1337  <listitem>
1338    <para><varname>v.info open_fds</varname> shows the list of open file
1339    descriptors and details related to the file descriptor.
1340    This only works if <option>--track-fds=yes</option>
1341    was given at Valgrind startup.</para>
1342  </listitem>
1343
1344  <listitem>
1345    <para><varname>v.set {gdb_output | log_output |
1346    mixed_output}</varname> allows redirection of the Valgrind output
1347    (e.g. the errors detected by the tool).  The default setting is
1348    <computeroutput>mixed_output</computeroutput>.</para>
1349
1350    <para>With <computeroutput>mixed_output</computeroutput>, the
1351    Valgrind output goes to the Valgrind log (typically stderr) while
1352    the output of the interactive GDB monitor commands (e.g.
1353    <computeroutput>v.info last_error</computeroutput>)
1354    is displayed by GDB.</para>
1355
1356    <para>With <computeroutput>gdb_output</computeroutput>, both the
1357    Valgrind output and the interactive GDB monitor commands output are
1358    displayed by GDB.</para>
1359
1360    <para>With <computeroutput>log_output</computeroutput>, both the
1361    Valgrind output and the interactive GDB monitor commands output go
1362    to the Valgrind log.</para>
1363  </listitem>
1364
1365  <listitem>
1366    <para><varname>v.wait [ms (default 0)]</varname> instructs
1367    Valgrind gdbserver to sleep "ms" milli-seconds and then
1368    continue.  When sent from a standalone vgdb, if this is the last
1369    command, the Valgrind process will continue the execution of the
1370    guest process. The typical usage of this is to use vgdb to send a
1371    "no-op" command to a Valgrind gdbserver so as to continue the
1372    execution of the guest process.
1373    </para>
1374  </listitem>
1375
1376  <listitem>
1377    <para><varname>v.kill</varname> requests the gdbserver to kill
1378    the process. This can be used from a standalone vgdb to properly
1379    kill a Valgrind process which is currently expecting a vgdb
1380    connection.</para>
1381  </listitem>
1382
1383  <listitem>
1384    <para><varname>v.set vgdb-error &lt;errornr&gt;</varname>
1385    dynamically changes the value of the
1386    <option>--vgdb-error</option> argument. A
1387    typical usage of this is to start with
1388    <option>--vgdb-error=0</option> on the
1389    command line, then set a few breakpoints, set the vgdb-error value
1390    to a huge value and continue execution.</para>
1391  </listitem>
1392
1393</itemizedlist>
1394
1395<para>The following Valgrind monitor commands are useful for
1396investigating the behaviour of Valgrind or its gdbserver in case of
1397problems or bugs.</para>
1398
1399<itemizedlist>
1400
1401  <listitem>
1402    <para><varname>v.do expensive_sanity_check_general</varname>
1403    executes various sanity checks. In particular, the sanity of the
1404    Valgrind heap is verified. This can be useful if you suspect that
1405    your program and/or Valgrind has a bug corrupting Valgrind data
1406    structure.  It can also be used when a Valgrind tool
1407    reports a client error to the connected GDB, in order to verify
1408    the sanity of Valgrind before continuing the execution.
1409    </para>
1410  </listitem>
1411
1412  <listitem>
1413    <para><varname>v.info gdbserver_status</varname> shows the
1414    gdbserver status. In case of problems (e.g. of communications),
1415    this shows the values of some relevant Valgrind gdbserver internal
1416    variables.  Note that the variables related to breakpoints and
1417    watchpoints (e.g. the number of breakpoint addresses and the number of
1418    watchpoints) will be zero, as GDB by default removes all
1419    watchpoints and breakpoints when execution stops, and re-inserts
1420    them when resuming the execution of the debugged process.  You can
1421    change this GDB behaviour by using the GDB command
1422    <computeroutput>set breakpoint always-inserted on</computeroutput>.
1423    </para>
1424  </listitem>
1425
1426  <listitem>
1427    <para><varname>v.info memory [aspacemgr]</varname> shows the statistics of
1428    Valgrind's internal heap management. If
1429    option <option>--profile-heap=yes</option> was given, detailed
1430    statistics will be output. With the optional argument
1431    <computeroutput>aspacemgr</computeroutput>. the segment list maintained
1432    by valgrind address space manager will be output. Note that
1433    this list of segments is always output on the Valgrind log.
1434    </para>
1435  </listitem>
1436
1437  <listitem>
1438    <para><varname>v.info exectxt</varname> shows informations about
1439    the "executable contexts" (i.e. the stack traces) recorded by
1440    Valgrind.  For some programs, Valgrind can record a very high
1441    number of such stack traces, causing a high memory usage.  This
1442    monitor command shows all the recorded stack traces, followed by
1443    some statistics. This can be used to analyse the reason for having
1444    a big number of stack traces. Typically, you will use this command
1445    if <varname>v.info memory</varname> has shown significant memory
1446    usage by the "exectxt" arena.
1447    </para>
1448  </listitem>
1449
1450  <listitem>
1451    <para><varname>v.info scheduler</varname> shows various
1452    information about threads. First, it outputs the host stack trace,
1453    i.e. the Valgrind code being executed. Then, for each thread, it
1454    outputs the thread state. For non terminated threads, the state is
1455    followed by the guest (client) stack trace. Finally, for each
1456    active thread or for each terminated thread slot not yet re-used,
1457    it shows the max usage of the valgrind stack.</para>
1458    <para>Showing the client stack traces allows to compare the stack
1459    traces produced by the Valgrind unwinder with the stack traces
1460    produced by GDB+Valgrind gdbserver. Pay attention that GDB and
1461    Valgrind scheduler status have their own thread numbering
1462    scheme. To make the link between the GDB thread number and the
1463    corresponding Valgrind scheduler thread number, use the GDB
1464    command <computeroutput>info threads</computeroutput>.  The output
1465    of this command shows the GDB thread number and the valgrind
1466    'tid'. The 'tid' is the thread number output
1467    by <computeroutput>v.info scheduler</computeroutput>.  When using
1468    the callgrind tool, the callgrind monitor command
1469    <computeroutput>status</computeroutput> outputs internal callgrind
1470    information about the stack/call graph it maintains.
1471    </para>
1472  </listitem>
1473
1474  <listitem>
1475    <para><varname>v.info stats</varname> shows various valgrind core and
1476    tool statistics. With this, Valgrind and tool statistics can
1477    be examined while running, even without option <option>--stats=yes</option>.
1478    </para>
1479  </listitem>
1480
1481  <listitem>
1482    <para><varname>v.info unwind  &lt;addr&gt; [&lt;len&gt;]</varname> shows
1483    the CFI unwind debug info for the address range [addr, addr+len-1].
1484    The default value of &lt;len&gt; is 1, giving the unwind information
1485    for the instruction at &lt;addr&gt;.
1486    </para>
1487  </listitem>
1488
1489  <listitem>
1490    <para><varname>v.set debuglog &lt;intvalue&gt;</varname> sets the
1491    Valgrind debug log level to &lt;intvalue&gt;.  This allows to
1492    dynamically change the log level of Valgrind e.g. when a problem
1493    is detected.</para>
1494  </listitem>
1495
1496  <listitem>
1497    <para><varname>v.set hostvisibility [yes*|no]</varname> The value
1498    "yes" indicates to gdbserver that GDB can look at the Valgrind
1499    'host' (internal) status/memory. "no" disables this access.
1500    When hostvisibility is activated, GDB can e.g. look at Valgrind
1501    global variables. As an example, to examine a Valgrind global
1502    variable of the memcheck tool on an x86, do the following setup:</para>
1503
1504<screen><![CDATA[
1505(gdb) monitor v.set hostvisibility yes
1506(gdb) add-symbol-file /path/to/tool/executable/file/memcheck-x86-linux 0x38000000
1507add symbol table from file "/path/to/tool/executable/file/memcheck-x86-linux" at
1508	.text_addr = 0x38000000
1509(y or n) y
1510Reading symbols from /path/to/tool/executable/file/memcheck-x86-linux...done.
1511(gdb)
1512]]></screen>
1513
1514  <para>After that, variables defined in memcheck-x86-linux can be accessed, e.g.</para>
1515
1516<screen><![CDATA[
1517(gdb) p /x vgPlain_threads[1].os_state
1518$3 = {lwpid = 0x4688, threadgroup = 0x4688, parent = 0x0,
1519  valgrind_stack_base = 0x62e78000, valgrind_stack_init_SP = 0x62f79fe0,
1520  exitcode = 0x0, fatalsig = 0x0}
1521(gdb) p vex_control
1522$5 = {iropt_verbosity = 0, iropt_level = 2,
1523  iropt_register_updates = VexRegUpdUnwindregsAtMemAccess,
1524  iropt_unroll_thresh = 120, guest_max_insns = 60, guest_chase_thresh = 10,
1525  guest_chase_cond = 0 '\000'}
1526(gdb)
1527]]></screen>
1528  </listitem>
1529
1530  <listitem>
1531    <para><varname>v.translate &lt;address&gt;
1532    [&lt;traceflags&gt;]</varname> shows the translation of the block
1533    containing <computeroutput>address</computeroutput> with the given
1534    trace flags. The <computeroutput>traceflags</computeroutput> value
1535    bit patterns have similar meaning to Valgrind's
1536    <option>--trace-flags</option> option.  It can be given
1537    in hexadecimal (e.g. 0x20) or decimal (e.g. 32) or in binary 1s
1538    and 0s bit (e.g. 0b00100000). The default value of the traceflags
1539    is 0b00100000, corresponding to "show after instrumentation".
1540    The output of this command always goes to the Valgrind
1541    log.</para>
1542    <para>The additional bit flag 0b100000000 (bit 8)
1543    has no equivalent in the <option>--trace-flags</option> option.
1544    It enables tracing of the gdbserver specific instrumentation.  Note
1545    that this bit 8 can only enable the addition of gdbserver
1546    instrumentation in the trace.  Setting it to 0 will not
1547    disable the tracing of the gdbserver instrumentation if it is
1548    active for some other reason, for example because there is a breakpoint at
1549    this address or because gdbserver is in single stepping
1550    mode.</para>
1551  </listitem>
1552
1553</itemizedlist>
1554
1555</sect2>
1556
1557</sect1>
1558
1559
1560
1561
1562
1563<sect1 id="manual-core-adv.wrapping" xreflabel="Function Wrapping">
1564<title>Function wrapping</title>
1565
1566<para>
1567Valgrind allows calls to some specified functions to be intercepted and
1568rerouted to a different, user-supplied function.  This can do whatever it
1569likes, typically examining the arguments, calling onwards to the original,
1570and possibly examining the result.  Any number of functions may be
1571wrapped.</para>
1572
1573<para>
1574Function wrapping is useful for instrumenting an API in some way.  For
1575example, Helgrind wraps functions in the POSIX pthreads API so it can know
1576about thread status changes, and the core is able to wrap
1577functions in the MPI (message-passing) API so it can know
1578of memory status changes associated with message arrival/departure.
1579Such information is usually passed to Valgrind by using client
1580requests in the wrapper functions, although the exact mechanism may vary.
1581</para>
1582
1583<sect2 id="manual-core-adv.wrapping.example" xreflabel="A Simple Example">
1584<title>A Simple Example</title>
1585
1586<para>Supposing we want to wrap some function</para>
1587
1588<programlisting><![CDATA[
1589int foo ( int x, int y ) { return x + y; }]]></programlisting>
1590
1591<para>A wrapper is a function of identical type, but with a special name
1592which identifies it as the wrapper for <computeroutput>foo</computeroutput>.
1593Wrappers need to include
1594supporting macros from <filename>valgrind.h</filename>.
1595Here is a simple wrapper which prints the arguments and return value:</para>
1596
1597<programlisting><![CDATA[
1598#include <stdio.h>
1599#include "valgrind.h"
1600int I_WRAP_SONAME_FNNAME_ZU(NONE,foo)( int x, int y )
1601{
1602   int    result;
1603   OrigFn fn;
1604   VALGRIND_GET_ORIG_FN(fn);
1605   printf("foo's wrapper: args %d %d\n", x, y);
1606   CALL_FN_W_WW(result, fn, x,y);
1607   printf("foo's wrapper: result %d\n", result);
1608   return result;
1609}
1610]]></programlisting>
1611
1612<para>To become active, the wrapper merely needs to be present in a text
1613section somewhere in the same process' address space as the function
1614it wraps, and for its ELF symbol name to be visible to Valgrind.  In
1615practice, this means either compiling to a
1616<computeroutput>.o</computeroutput> and linking it in, or
1617compiling to a <computeroutput>.so</computeroutput> and
1618<computeroutput>LD_PRELOAD</computeroutput>ing it in.  The latter is more
1619convenient in that it doesn't require relinking.</para>
1620
1621<para>All wrappers have approximately the above form.  There are three
1622crucial macros:</para>
1623
1624<para><computeroutput>I_WRAP_SONAME_FNNAME_ZU</computeroutput>:
1625this generates the real name of the wrapper.
1626This is an encoded name which Valgrind notices when reading symbol
1627table information.  What it says is: I am the wrapper for any function
1628named <computeroutput>foo</computeroutput> which is found in
1629an ELF shared object with an empty
1630("<computeroutput>NONE</computeroutput>") soname field.  The specification
1631mechanism is powerful in
1632that wildcards are allowed for both sonames and function names.
1633The details are discussed below.</para>
1634
1635<para><computeroutput>VALGRIND_GET_ORIG_FN</computeroutput>:
1636once in the wrapper, the first priority is
1637to get hold of the address of the original (and any other supporting
1638information needed).  This is stored in a value of opaque
1639type <computeroutput>OrigFn</computeroutput>.
1640The information is acquired using
1641<computeroutput>VALGRIND_GET_ORIG_FN</computeroutput>.  It is crucial
1642to make this macro call before calling any other wrapped function
1643in the same thread.</para>
1644
1645<para><computeroutput>CALL_FN_W_WW</computeroutput>: eventually we will
1646want to call the function being
1647wrapped.  Calling it directly does not work, since that just gets us
1648back to the wrapper and leads to an infinite loop.  Instead, the result
1649lvalue,
1650<computeroutput>OrigFn</computeroutput> and arguments are
1651handed to one of a family of macros of the form
1652<computeroutput>CALL_FN_*</computeroutput>.  These
1653cause Valgrind to call the original and avoid recursion back to the
1654wrapper.</para>
1655</sect2>
1656
1657<sect2 id="manual-core-adv.wrapping.specs" xreflabel="Wrapping Specifications">
1658<title>Wrapping Specifications</title>
1659
1660<para>This scheme has the advantage of being self-contained.  A library of
1661wrappers can be compiled to object code in the normal way, and does
1662not rely on an external script telling Valgrind which wrappers pertain
1663to which originals.</para>
1664
1665<para>Each wrapper has a name which, in the most general case says: I am the
1666wrapper for any function whose name matches FNPATT and whose ELF
1667"soname" matches SOPATT.  Both FNPATT and SOPATT may contain wildcards
1668(asterisks) and other characters (spaces, dots, @, etc) which are not
1669generally regarded as valid C identifier names.</para>
1670
1671<para>This flexibility is needed to write robust wrappers for POSIX pthread
1672functions, where typically we are not completely sure of either the
1673function name or the soname, or alternatively we want to wrap a whole
1674set of functions at once.</para>
1675
1676<para>For example, <computeroutput>pthread_create</computeroutput>
1677in GNU libpthread is usually a
1678versioned symbol - one whose name ends in, eg,
1679<computeroutput>@GLIBC_2.3</computeroutput>.  Hence we
1680are not sure what its real name is.  We also want to cover any soname
1681of the form <computeroutput>libpthread.so*</computeroutput>.
1682So the header of the wrapper will be</para>
1683
1684<programlisting><![CDATA[
1685int I_WRAP_SONAME_FNNAME_ZZ(libpthreadZdsoZd0,pthreadZucreateZAZa)
1686  ( ... formals ... )
1687  { ... body ... }
1688]]></programlisting>
1689
1690<para>In order to write unusual characters as valid C function names, a
1691Z-encoding scheme is used.  Names are written literally, except that
1692a capital Z acts as an escape character, with the following encoding:</para>
1693
1694<programlisting><![CDATA[
1695     Za   encodes    *
1696     Zp              +
1697     Zc              :
1698     Zd              .
1699     Zu              _
1700     Zh              -
1701     Zs              (space)
1702     ZA              @
1703     ZZ              Z
1704     ZL              (       # only in valgrind 3.3.0 and later
1705     ZR              )       # only in valgrind 3.3.0 and later
1706]]></programlisting>
1707
1708<para>Hence <computeroutput>libpthreadZdsoZd0</computeroutput> is an
1709encoding of the soname <computeroutput>libpthread.so.0</computeroutput>
1710and <computeroutput>pthreadZucreateZAZa</computeroutput> is an encoding
1711of the function name <computeroutput>pthread_create@*</computeroutput>.
1712</para>
1713
1714<para>The macro <computeroutput>I_WRAP_SONAME_FNNAME_ZZ</computeroutput>
1715constructs a wrapper name in which
1716both the soname (first component) and function name (second component)
1717are Z-encoded.  Encoding the function name can be tiresome and is
1718often unnecessary, so a second macro,
1719<computeroutput>I_WRAP_SONAME_FNNAME_ZU</computeroutput>, can be
1720used instead.  The <computeroutput>_ZU</computeroutput> variant is
1721also useful for writing wrappers for
1722C++ functions, in which the function name is usually already mangled
1723using some other convention in which Z plays an important role.  Having
1724to encode a second time quickly becomes confusing.</para>
1725
1726<para>Since the function name field may contain wildcards, it can be
1727anything, including just <computeroutput>*</computeroutput>.
1728The same is true for the soname.
1729However, some ELF objects - specifically, main executables - do not
1730have sonames.  Any object lacking a soname is treated as if its soname
1731was <computeroutput>NONE</computeroutput>, which is why the original
1732example above had a name
1733<computeroutput>I_WRAP_SONAME_FNNAME_ZU(NONE,foo)</computeroutput>.</para>
1734
1735<para>Note that the soname of an ELF object is not the same as its
1736file name, although it is often similar.  You can find the soname of
1737an object <computeroutput>libfoo.so</computeroutput> using the command
1738<computeroutput>readelf -a libfoo.so | grep soname</computeroutput>.</para>
1739</sect2>
1740
1741<sect2 id="manual-core-adv.wrapping.semantics" xreflabel="Wrapping Semantics">
1742<title>Wrapping Semantics</title>
1743
1744<para>The ability for a wrapper to replace an infinite family of functions
1745is powerful but brings complications in situations where ELF objects
1746appear and disappear (are dlopen'd and dlclose'd) on the fly.
1747Valgrind tries to maintain sensible behaviour in such situations.</para>
1748
1749<para>For example, suppose a process has dlopened (an ELF object with
1750soname) <filename>object1.so</filename>, which contains
1751<computeroutput>function1</computeroutput>.  It starts to use
1752<computeroutput>function1</computeroutput> immediately.</para>
1753
1754<para>After a while it dlopens <filename>wrappers.so</filename>,
1755which contains a wrapper
1756for <computeroutput>function1</computeroutput> in (soname)
1757<filename>object1.so</filename>.  All subsequent calls to
1758<computeroutput>function1</computeroutput> are rerouted to the wrapper.</para>
1759
1760<para>If <filename>wrappers.so</filename> is
1761later dlclose'd, calls to <computeroutput>function1</computeroutput> are
1762naturally routed back to the original.</para>
1763
1764<para>Alternatively, if <filename>object1.so</filename>
1765is dlclose'd but <filename>wrappers.so</filename> remains,
1766then the wrapper exported by <filename>wrappers.so</filename>
1767becomes inactive, since there
1768is no way to get to it - there is no original to call any more.  However,
1769Valgrind remembers that the wrapper is still present.  If
1770<filename>object1.so</filename> is
1771eventually dlopen'd again, the wrapper will become active again.</para>
1772
1773<para>In short, valgrind inspects all code loading/unloading events to
1774ensure that the set of currently active wrappers remains consistent.</para>
1775
1776<para>A second possible problem is that of conflicting wrappers.  It is
1777easily possible to load two or more wrappers, both of which claim
1778to be wrappers for some third function.  In such cases Valgrind will
1779complain about conflicting wrappers when the second one appears, and
1780will honour only the first one.</para>
1781</sect2>
1782
1783<sect2 id="manual-core-adv.wrapping.debugging" xreflabel="Debugging">
1784<title>Debugging</title>
1785
1786<para>Figuring out what's going on given the dynamic nature of wrapping
1787can be difficult.  The
1788<option>--trace-redir=yes</option> option makes
1789this possible
1790by showing the complete state of the redirection subsystem after
1791every
1792<function>mmap</function>/<function>munmap</function>
1793event affecting code (text).</para>
1794
1795<para>There are two central concepts:</para>
1796
1797<itemizedlist>
1798
1799  <listitem><para>A "redirection specification" is a binding of
1800  a (soname pattern, fnname pattern) pair to a code address.
1801  These bindings are created by writing functions with names
1802  made with the
1803  <computeroutput>I_WRAP_SONAME_FNNAME_{ZZ,_ZU}</computeroutput>
1804  macros.</para></listitem>
1805
1806  <listitem><para>An "active redirection" is a code-address to
1807  code-address binding currently in effect.</para></listitem>
1808
1809</itemizedlist>
1810
1811<para>The state of the wrapping-and-redirection subsystem comprises a set of
1812specifications and a set of active bindings.  The specifications are
1813acquired/discarded by watching all
1814<function>mmap</function>/<function>munmap</function>
1815events on code (text)
1816sections.  The active binding set is (conceptually) recomputed from
1817the specifications, and all known symbol names, following any change
1818to the specification set.</para>
1819
1820<para><option>--trace-redir=yes</option> shows the contents
1821of both sets following any such event.</para>
1822
1823<para><option>-v</option> prints a line of text each
1824time an active specification is used for the first time.</para>
1825
1826<para>Hence for maximum debugging effectiveness you will need to use both
1827options.</para>
1828
1829<para>One final comment.  The function-wrapping facility is closely
1830tied to Valgrind's ability to replace (redirect) specified
1831functions, for example to redirect calls to
1832<function>malloc</function> to its
1833own implementation.  Indeed, a replacement function can be
1834regarded as a wrapper function which does not call the original.
1835However, to make the implementation more robust, the two kinds
1836of interception (wrapping vs replacement) are treated differently.
1837</para>
1838
1839<para><option>--trace-redir=yes</option> shows
1840specifications and bindings for both
1841replacement and wrapper functions.  To differentiate the
1842two, replacement bindings are printed using
1843<computeroutput>R-></computeroutput> whereas
1844wraps are printed using <computeroutput>W-></computeroutput>.
1845</para>
1846</sect2>
1847
1848
1849<sect2 id="manual-core-adv.wrapping.limitations-cf"
1850       xreflabel="Limitations - control flow">
1851<title>Limitations - control flow</title>
1852
1853<para>For the most part, the function wrapping implementation is robust.
1854The only important caveat is: in a wrapper, get hold of
1855the <computeroutput>OrigFn</computeroutput> information using
1856<computeroutput>VALGRIND_GET_ORIG_FN</computeroutput> before calling any
1857other wrapped function.  Once you have the
1858<computeroutput>OrigFn</computeroutput>, arbitrary
1859calls between, recursion between, and longjumps out of wrappers
1860should work correctly.  There is never any interaction between wrapped
1861functions and merely replaced functions
1862(eg <function>malloc</function>), so you can call
1863<function>malloc</function> etc safely from within wrappers.
1864</para>
1865
1866<para>The above comments are true for {x86,amd64,ppc32,arm,mips32,s390}-linux.
1867On
1868ppc64-linux function wrapping is more fragile due to the (arguably
1869poorly designed) ppc64-linux ABI.  This mandates the use of a shadow
1870stack which tracks entries/exits of both wrapper and replacement
1871functions.  This gives two limitations: firstly, longjumping out of
1872wrappers will rapidly lead to disaster, since the shadow stack will
1873not get correctly cleared.  Secondly, since the shadow stack has
1874finite size, recursion between wrapper/replacement functions is only
1875possible to a limited depth, beyond which Valgrind has to abort the
1876run.  This depth is currently 16 calls.</para>
1877
1878<para>For all platforms ({x86,amd64,ppc32,ppc64,arm,mips32,s390}-linux)
1879all the above
1880comments apply on a per-thread basis.  In other words, wrapping is
1881thread-safe: each thread must individually observe the above
1882restrictions, but there is no need for any kind of inter-thread
1883cooperation.</para>
1884</sect2>
1885
1886
1887<sect2 id="manual-core-adv.wrapping.limitations-sigs"
1888       xreflabel="Limitations - original function signatures">
1889<title>Limitations - original function signatures</title>
1890
1891<para>As shown in the above example, to call the original you must use a
1892macro of the form <computeroutput>CALL_FN_*</computeroutput>.
1893For technical reasons it is impossible
1894to create a single macro to deal with all argument types and numbers,
1895so a family of macros covering the most common cases is supplied.  In
1896what follows, 'W' denotes a machine-word-typed value (a pointer or a
1897C <computeroutput>long</computeroutput>),
1898and 'v' denotes C's <computeroutput>void</computeroutput> type.
1899The currently available macros are:</para>
1900
1901<programlisting><![CDATA[
1902CALL_FN_v_v    -- call an original of type  void fn ( void )
1903CALL_FN_W_v    -- call an original of type  long fn ( void )
1904
1905CALL_FN_v_W    -- call an original of type  void fn ( long )
1906CALL_FN_W_W    -- call an original of type  long fn ( long )
1907
1908CALL_FN_v_WW   -- call an original of type  void fn ( long, long )
1909CALL_FN_W_WW   -- call an original of type  long fn ( long, long )
1910
1911CALL_FN_v_WWW  -- call an original of type  void fn ( long, long, long )
1912CALL_FN_W_WWW  -- call an original of type  long fn ( long, long, long )
1913
1914CALL_FN_W_WWWW -- call an original of type  long fn ( long, long, long, long )
1915CALL_FN_W_5W   -- call an original of type  long fn ( long, long, long, long, long )
1916CALL_FN_W_6W   -- call an original of type  long fn ( long, long, long, long, long, long )
1917and so on, up to
1918CALL_FN_W_12W
1919]]></programlisting>
1920
1921<para>The set of supported types can be expanded as needed.  It is
1922regrettable that this limitation exists.  Function wrapping has proven
1923difficult to implement, with a certain apparently unavoidable level of
1924ickiness.  After several implementation attempts, the present
1925arrangement appears to be the least-worst tradeoff.  At least it works
1926reliably in the presence of dynamic linking and dynamic code
1927loading/unloading.</para>
1928
1929<para>You should not attempt to wrap a function of one type signature with a
1930wrapper of a different type signature.  Such trickery will surely lead
1931to crashes or strange behaviour.  This is not a limitation
1932of the function wrapping implementation, merely a reflection of the
1933fact that it gives you sweeping powers to shoot yourself in the foot
1934if you are not careful.  Imagine the instant havoc you could wreak by
1935writing a wrapper which matched any function name in any soname - in
1936effect, one which claimed to be a wrapper for all functions in the
1937process.</para>
1938</sect2>
1939
1940<sect2 id="manual-core-adv.wrapping.examples" xreflabel="Examples">
1941<title>Examples</title>
1942
1943<para>In the source tree,
1944<filename>memcheck/tests/wrap[1-8].c</filename> provide a series of
1945examples, ranging from very simple to quite advanced.</para>
1946
1947<para><filename>mpi/libmpiwrap.c</filename> is an example
1948of wrapping a big, complex API (the MPI-2 interface).  This file defines
1949almost 300 different wrappers.</para>
1950</sect2>
1951
1952</sect1>
1953
1954
1955
1956
1957</chapter>
1958