dbus_shutdown: document its effect on shared connections

In practice, the sort of applications that call dbus_shutdown()
(e.g. regression tests) will want to either use private connections,
or turn off exit-on-disconnect on the shared connection, or both.

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=16924

diff --git a/dbus/dbus-memory.c b/dbus/dbus-memory.c
index 22e80727b886583aaf97897b5697a1d24c70df7e..67d5cb0524f54734d3565dd1672162875a0bc131 100644 (file)
--- a/dbus/dbus-memory.c
+++ b/dbus/dbus-memory.c
@@ -862,6 +862,13 @@ _dbus_register_shutdown_func_unlocked (DBusShutdownFunction  func,
  * You MUST free all memory and release all reference counts
  * returned to you by libdbus prior to calling dbus_shutdown().
  *
+ * If a shared connection is open, calling dbus_shutdown() will
+ * drain its queue of messages and disconnect it. In particular,
+ * this will result in processing of the special Disconnected
+ * signal, which may result in a call to _exit(), unless you
+ * have used dbus_connection_set_exit_on_disconnect() to disable
+ * that behaviour.
+ *
  * You can't continue to use any D-Bus objects, such as connections,
  * that were allocated prior to dbus_shutdown(). You can, however,
  * start over; call dbus_threads_init() again, create new connections,