Commits

Armin Rigo committed dbe339f

Add a section about debugging with env vars (thanks sarvi)

Comments (0)

Files changed (1)

doc/source/index.rst

    structs/unions inside structs/unions.
 
 
+Debugging dlopen'ed C libraries
+-------------------------------
+
+A few C libraries are actually hard to use correctly in a ``dlopen()``
+setting.  This is because most C libraries are intented for, and tested
+with, a situation where they are *linked* with another program, using
+either static linking or dynamic linking --- but from a program written
+in C, at start-up, using the linker's capabilities instead of
+``dlopen()``.
+
+This can occasionally create issues.  You would have the same issues in
+another setting than CFFI, like with ``ctypes`` or even plain C code that
+calls ``dlopen()``.  This section contains a few generally useful
+environment variables (on Linux) that can help when debugging these
+issues.
+
+**export LD_TRACE_LOADED_OBJECTS=all**
+
+    provides a lot of information, sometimes too much depending on the
+    setting.  Output verbose debugging information about the dynamic
+    linker. If set to ``all`` prints all debugging information it has, if
+    set to ``help`` prints a help message about which categories can be
+    specified in this environment variable
+
+**export LD_VERBOSE=1**
+
+    (glibc since 2.1) If set to a nonempty string, output symbol
+    versioning information about the program if querying information
+    about the program (i.e., either ``LD_TRACE_LOADED_OBJECTS`` has been set,
+    or ``--list`` or ``--verify`` options have been given to the dynamic
+    linker).
+
+**export LD_WARN=1**
+
+    (ELF only)(glibc since 2.1.3) If set to a nonempty string, warn
+    about unresolved symbols.
+
+
 Reference: conversions
 ----------------------
 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.