runtime/kioslave/DEBUG.howto

   1 This document describes how you can debug an io-slave with gdb.
   2
   3 How does an io-slave get started?
   4 =================================
   5
   6 Your application request 'klauncher' via DCOP for a slave. If 'klauncher' does
   7 not have an idle slave ready, it will ask kdeinit to start a new one.
   8 kdeinit forks and dlopens the library that contains the io-slave.
   9 Then it calls kdemain() or, if that is not present, main() in the library.
  10
  11
  12 Attaching gdb to a io-slave
  13 ===========================
  14
  15 Due to the above sequence it is rather hard to get an io-slave in your
  16 debugger. But wait there is hope. You can start klauncher in such a way
  17 that slaves for a certain protocol are started in debug mode.
  18
  19 E.g. to start all 'http' slaves in debug mode, you type:
  20
  21         KDE_SLAVE_DEBUG_WAIT=http kdeinit4
  22
  23 This will restart 'kdeinit4' and 'klauncher'.
  24
  25 When your application now requests a http slave, the slave will be started
  26 by kdeinit, but before it calls kdemain() (cq. main()) it will suspend the
  27 slave by sending it a SIGSTOP signal.
  28
  29 In the terminal from which you started kdeinit you will get the following
  30 message:
  31
  32 kdeinit: Suspending process
  33 kdeinit: 'gdb kdeinit4 16779' to debug
  34 kdeinit: 'kill -SIGCONT 16779' to continue
  35
  36 You can now debug your slave by typing (or pasting) 'gdb kdeinit 16779' in
  37 a terminal. If you don't want to debug a slave you can let it continue by
  38 sending it a SIGCONT by typing 'kill -SIGCONT 16779'.
  39
  40 Be aware that slaves will not be killed while they are suspended.
  41
  42 Once you have started gdb, you can set e.g. breakpoints and then resume the
  43 slave by typing 'continue'. The debugger will return immediate with a message
  44 that a SIGSTOP has been received so you will have to type 'continue' a second
  45 time.
  46
  47
  48 Debugging io-slaves with valgrind
  49 =================================
  50
  51 KLauncher can be told to run certain io-slaves through valgrind. The following
  52 command can be used to let klauncher run all https io-slaves via valgrind:
  53
  54         KDE_SLAVE_VALGRIND=https kdeinit
  55
  56 The valgrind output will appear as the stderr output of the kdeinit process.
  57 The $VALGRIND_OPTS environment variable can be used to pass options to valgrind.
  58 If you want to use a different skin:
  59
  60         KDE_SLAVE_VALGRIND_SKIN=calltree      ( for example )
  61
  62
  63 How to get debug output
  64 =======================
  65
  66 It is useful to redirect the debug output of your particular slave to a file
  67 instead of stderr. E.g. I myself use the following lines in
  68 $KDEDIR/share/config/kdebugrc.
  69
  70        [7113]
  71        InfoOutput=0
  72        InfoFilename=/tmp/http
  73        [7103]
  74        InfoOutput=0
  75        InfoFilename=/tmp/http
  76
  77 This redirects all debug info for areas 7103 and 7113 (as used by kio_http)
  78 to the file /tmp/http.
  79
  80 To get debug information from the SMB slave you can add the following to
  81 kioslaverc:
  82
  83 [SMB]
  84 DebugLevel=100
  85
  86 This will print additional debug info to the stderr of your kdeinit process,
  87 which typically ends up in ~/.X.err or ~/.xsession-errors
  88
  89 Happy debugging.