- publishing free software manuals
Valgrind 3.3 - Advanced Debugging and Profiling for GNU/Linux applications
by J. Seward, N. Nethercote, J. Weidendorfer and the Valgrind Development Team
Paperback (6"x9"), 164 pages
ISBN 0954612051
RRP £12.95 ($19.95)

Get a printed copy>>>

4.2.2 Wrapping Specifications

This scheme has the advantage of being self-contained. A library of wrappers can be compiled to object code in the normal way, and does not rely on an external script telling Valgrind which wrappers pertain to which originals.

Each wrapper has a name which, in the most general case says: I am the wrapper for any function whose name matches FNPATT and whose ELF “soname” matches SOPATT. Both FNPATT and SOPATT may contain wildcards (asterisks) and other characters (spaces, dots, @, etc) which are not generally regarded as valid C identifier names.

This flexibility is needed to write robust wrappers for POSIX pthread functions, where typically we are not completely sure of either the function name or the soname, or alternatively we want to wrap a whole set of functions at once.

For example, ‘pthread_create’ in GNU libpthread is usually a versioned symbol--one whose name ends in, e.g., ‘@GLIBC_2.3’. Hence we are not sure what its real name is. We also want to cover any soname of the form ‘libpthread.so*’. So the header of the wrapper will be

int I_WRAP_SONAME_FNNAME_ZZ(libpthreadZdsoZd0,
  ( ... formals ... )
  { ... body ... }

In order to write unusual characters as valid C function names, a Z-encoding scheme is used. Names are written literally, except that a capital Z acts as an escape character, with the following encoding:

Za   encodes    *
Zp              +
Zc              :
Zd              .
Zu              _
Zh              -
Zs              (space)
ZA              @
ZZ              Z
ZL              (       # only in valgrind 3.3.0 and later
ZR              )       # only in valgrind 3.3.0 and later

Hence ‘libpthreadZdsoZd0’ is an encoding of the soname ‘libpthread.so.0’ and ‘pthreadZucreateZAZa’ is an encoding of the function name ‘pthread_create@*’.

The macro ‘I_WRAP_SONAME_FNNAME_ZZ’ constructs a wrapper name in which both the soname (first component) and function name (second component) are Z-encoded. Encoding the function name can be tiresome and is often unnecessary, so a second macro, ‘I_WRAP_SONAME_FNNAME_ZU’, can be used instead. The ‘_ZU’ variant is also useful for writing wrappers for C++ functions, in which the function name is usually already mangled using some other convention in which Z plays an important role. Having to encode a second time quickly becomes confusing.

Since the function name field may contain wildcards, it can be anything, including just ‘*’. The same is true for the soname. However, some ELF objects--specifically, main executables--do not have sonames. Any object lacking a soname is treated as if its soname was ‘NONE’, which is why the original example above had a name ‘I_WRAP_SONAME_FNNAME_ZU(NONE,foo)’.

Note that the soname of an ELF object is not the same as its file name, although it is often similar. You can find the soname of an object ‘libfoo.so’ using the command ‘readelf -a libfoo.so | grep soname’.

ISBN 0954612051Valgrind 3.3 - Advanced Debugging and Profiling for GNU/Linux applicationsSee the print edition