This document describes how you can debug an io-slave with gdb.

How does an io-slave get started?
=================================

Your application request 'tdelauncher' via DCOP for a slave. If 'tdelauncher' does 
not have an idle slave ready, it will ask tdeinit to start a new one.
tdeinit forks and dlopens the library that contains the io-slave.
Then it calls kdemain() or, if that is not present, main() in the library.


Attaching gdb to a io-slave
===========================

Due to the above sequence it is rather hard to get an io-slave in your
debugger. But wait there is hope. You can start tdelauncher in such a way
that slaves for a certain protocol are started in debug mode.

E.g. to start all 'http' slaves in debug mode, you type:

	TDE_SLAVE_DEBUG_WAIT=http tdeinit

This will restart 'tdeinit' and 'tdelauncher'.

When your application now requests a http slave, the slave will be started
by tdeinit, but before it calls kdemain() (cq. main()) it will suspend the
slave by sending it a SIGSTOP signal.

In the terminal from which you started tdeinit you will get the following
message:

tdeinit: Suspending process
tdeinit: 'gdb tdeinit 16779' to debug
tdeinit: 'kill -SIGCONT 16779' to continue

You can now debug your slave by typing (or pasting) 'gdb tdeinit 16779' in
a terminal. If you don't want to debug a slave you can let it continue by
sending it a SIGCONT by typing 'kill -SIGCONT 16779'.

Be aware that slaves will not be killed while they are suspended.

Once you have started gdb, you can set e.g. breakpoints and then resume the 
slave by typing 'continue'. The debugger will return immediate with a message 
that a SIGSTOP has been received so you will have to type 'continue' a second 
time.


Debugging io-slaves with valgrind
=================================

TDELauncher can be told to run certain io-slaves through valgrind. The following
command can be used to let tdelauncher run all https io-slaves via valgrind:

	TDE_SLAVE_VALGRIND=https tdeinit

The valgrind output will appear as the stderr output of the tdeinit process.
The $VALGRIND_OPTS environment variable can be used to pass options to valgrind.
If you want to use a different skin:

	TDE_SLAVE_VALGRIND_SKIN=calltree      ( for example )


How to get debug output
=======================

It is useful to redirect the debug output of your particular slave to a file 
instead of stderr. E.g. I myself use the following lines in
$TDEDIR/share/config/kdebugrc.

       [7113]
       InfoOutput=0
       InfoFilename=/tmp/http
       [7103]
       InfoOutput=0
       InfoFilename=/tmp/http 

This redirects all debug info for areas 7103 and 7113 (as used by tdeio_http) 
to the file /tmp/http.

To get debug information from the SMB slave you can add the following to
tdeioslaverc:

[SMB]
DebugLevel=100

This will print additional debug info to the stderr of your tdeinit process,
which typically ends up in ~/.X.err or ~/.xsession-errors

Happy debugging.
