+2003-02-19 Havoc Pennington <hp@pobox.com>
+
+ Throughout: mop up all the Doxygen warnings and undocumented
+ stuff.
+
+ * dbus/dbus-sysdeps.c (do_exec): do not use execvp, we don't want
+ to search any paths.
+
+ * dbus/dbus-threads.c: move global mutex initializers to
+ dbus-internals.h, multiple prototypes was confusing doxygen
+ besides being kind of ugly
+
+ * Doxyfile (PREDEFINED): have Doxygen define
+ DOXYGEN_SHOULD_SKIP_THIS so we can exclude things from
+ docs with #ifndef DOXYGEN_SHOULD_SKIP_THIS
+ (do not abuse the feature! it's for stuff like the autogenerated
+ macros in dbus-md5.c, not just for things you don't feel like
+ documenting...)
+
2003-02-18 Havoc Pennington <hp@pobox.com>
* dbus/dbus-string.c (_dbus_string_zero): new function
return "unknown";
}
+/**
+ * Runs an "auth script" which is a script for testing the
+ * authentication protocol. Scripts send and receive data, and then
+ * include assertions about the state of both ends of the connection
+ * after processing the data. A script succeeds if these assertions
+ * hold.
+ *
+ * @param filename the file containing the script to run
+ * @returns #TRUE if the script succeeds, #FALSE otherwise
+ */
dbus_bool_t
_dbus_auth_script_run (const DBusString *filename)
{
{
int refcount; /**< Reference count. */
- DBusMutex *mutex;
+ DBusMutex *mutex; /**< Lock on the entire DBusConnection */
- /* Protects dispatch_message */
- dbus_bool_t dispatch_acquired;
- DBusCondVar *dispatch_cond;
-
- /* Protects transport io path */
- dbus_bool_t io_path_acquired;
- DBusCondVar *io_path_cond;
+ dbus_bool_t dispatch_acquired; /**< Protects dispatch_message */
+ DBusCondVar *dispatch_cond; /**< Protects dispatch_message */
+
+ dbus_bool_t io_path_acquired; /**< Protects transport io path */
+ DBusCondVar *io_path_cond; /**< Protects transport io path */
DBusList *outgoing_messages; /**< Queue of messages we need to send, send the end of the list first. */
DBusList *incoming_messages; /**< Queue of messages we have received, end of the list received most recently. */
DBusMessage *message_borrowed; /**< True if the first incoming message has been borrowed */
- DBusCondVar *message_returned_cond;
+ DBusCondVar *message_returned_cond; /**< Used with dbus_connection_borrow_message() */
int n_outgoing; /**< Length of outgoing queue. */
int n_incoming; /**< Length of incoming queue. */
DBusCounter *connection_counter; /**< Counter that we decrement when finalized */
int client_serial; /**< Client serial. Increments each time a message is sent */
- DBusList *disconnect_message_link;
+ DBusList *disconnect_message_link; /**< Preallocated list node for queueing the disconnection message */
};
typedef struct
static int n_used_slots = 0;
static DBusMutex *allocated_slots_lock = NULL;
-DBusMutex *_dbus_allocated_slots_init_lock (void);
+/**
+ * Initialize the mutex used for #DBusConnecton data
+ * slot reservations.
+ *
+ * @returns the mutex
+ */
DBusMutex *
_dbus_allocated_slots_init_lock (void)
{
#include <dbus/dbus-types.h>
#include <dbus/dbus-errors.h>
#include <dbus/dbus-sysdeps.h>
+#include <dbus/dbus-threads.h>
DBUS_BEGIN_DECLS;
#define _dbus_decrement_fail_alloc_counter() FALSE
#endif /* !DBUS_BUILD_TESTS */
+/* Thread initializers */
+DBusMutex *_dbus_list_init_lock (void);
+DBusMutex *_dbus_allocated_slots_init_lock (void);
+DBusMutex *_dbus_atomic_init_lock (void);
+DBusMutex *_dbus_message_handler_init_lock (void);
+
DBUS_END_DECLS;
#endif /* DBUS_INTERNALS_H */
*/
struct DBusKeyring
{
- DBusString filename;
- DBusString lock_filename;
+ DBusString filename; /**< File containing keyring */
+ DBusString lock_filename; /**< Lock file for changing keyring */
};
static DBusMemPool *list_pool;
static DBusMutex *list_pool_lock = NULL;
-DBusMutex *_dbus_list_init_lock (void);
+/**
+ * Initializes the global mutex used for allocating list nodes.
+ *
+ * @returns the mutex
+ */
DBusMutex *
_dbus_list_init_lock (void)
{
*
* @{
*/
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
/*
* For reference, here is the program that computed the T values.
*/
#ifdef COMPUTE_T_VALUES
#include <math.h>
-/* static main is a hack so doxygen won't pick it up */
-static int
+int
main(int argc, char **argv)
{
int i;
#define T62 /* 0xbd3af235 */ (T_MASK ^ 0x42c50dca)
#define T63 0x2ad7d2bb
#define T64 /* 0xeb86d391 */ (T_MASK ^ 0x14792c6e)
+#endif /* DOXYGEN_SHOULD_SKIP_THIS */
static void
md5_process(DBusMD5Context *context, const unsigned char *data /*[64]*/)
*/
static DBusMutex *message_handler_lock = NULL;
-DBusMutex *_dbus_message_handler_init_lock (void);
+
+/**
+ * Initializes the mutex used for threadsafe access to
+ * #DBusMessageHandler objects.
+ *
+ * @returns the mutex
+ */
DBusMutex *
_dbus_message_handler_init_lock (void)
{
* with 0.
*
* @param message the message
- * @param first_argument_type type of the first argument
+ * @param first_arg_type type of the first argument
* @param ... value of first argument, list of additional type-value pairs
* @returns #TRUE on success
*/
return get_string_field (message, FIELD_SENDER, NULL);
}
+/**
+ * Checks whether the message has the given name.
+ * If the message has no name or has a different
+ * name, returns #FALSE.
+ *
+ * @param message the message
+ * @param name the name to check (must not be #NULL)
+ *
+ * @returns #TRUE if the message has the given name
+ */
dbus_bool_t
dbus_message_name_is (DBusMessage *message,
const char *name)
{
- if (dbus_message_get_name (message) &&
- strcmp (dbus_message_get_name (message), name) == 0)
+ const char *n;
+
+ _dbus_assert (name != NULL);
+
+ n = dbus_message_get_name (message);
+
+ if (n && strcmp (n, name) == 0)
return TRUE;
else
return FALSE;
/**
* Clears all allocated bytes in the string to zero.
*
- * @param the string
+ * @param str the string
*/
void
_dbus_string_zero (DBusString *str)
return TRUE;
}
+/** @} */ /* DBusString group */
+
+/**
+ * @addtogroup DBusInternalsUtils
+ * @{
+ */
+
/**
* Gets the credentials corresponding to the given username.
*
static DBusMutex *atomic_lock = NULL;
-DBusMutex *_dbus_atomic_init_lock (void);
+/**
+ * Initializes the global mutex for the fallback implementation
+ * of atomic integers.
+ *
+ * @returns the mutex
+ */
DBusMutex *
_dbus_atomic_init_lock (void)
{
return FALSE;
}
+/**
+ * A wrapper around strerror()
+ *
+ * @param errnum the errno
+ * @returns an error message (never #NULL)
+ */
const char *
_dbus_errno_to_string (int errnum)
{
- return strerror (errnum);
+ const char *msg;
+
+ msg = strerror (errnum);
+ if (msg == NULL)
+ msg = "unknown";
+
+ return msg;
}
/* Avoids a danger in threaded situations (calling close()
if (child_setup)
(* child_setup) (user_data);
+
#ifdef DBUS_BUILD_TESTS
max_open = sysconf (_SC_OPEN_MAX);
-
for (i = 3; i < max_open; i++)
{
}
#endif
- execvp (argv[0], argv);
+ execv (argv[0], argv);
/* Exec failed */
write_err_and_exit (child_err_report_fd,
}
+/**
+ * Spawns a new process. The executable name and argv[0]
+ * are the same, both are provided in argv[0]. The child_setup
+ * function is passed the given user_data and is run in the child
+ * just before calling exec().
+ *
+ * @todo this code should be reviewed/double-checked as it's fairly
+ * complex and no one has reviewed it yet.
+ *
+ * @param argv the executable and arguments
+ * @param child_setup function to call in child pre-exec()
+ * @param user_data user data for setup function
+ * @param error error object to be filled in if function fails
+ * @returns #TRUE on success, #FALSE if error is filled in
+ */
dbus_bool_t
_dbus_spawn_async (char **argv,
DBusSpawnChildSetupFunc child_setup,
signal (SIGPIPE, SIG_IGN);
}
+/**
+ * Sets the file descriptor to be close
+ * on exec. Should be called for all file
+ * descriptors in D-BUS code.
+ *
+ * @param fd the file descriptor
+ */
void
_dbus_fd_set_close_on_exec (int fd)
{
* mutex again before returning.
* Does nothing if passed a #NULL pointer.
*
+ * @param cond the condition variable
+ * @param mutex the mutex
* @param timeout_milliseconds the maximum time to wait
* @returns TRUE if the condition was reached, or FALSE if the
* timeout was reached.
(* thread_functions.condvar_wake_all) (cond);
}
-
-DBusMutex * _dbus_list_init_lock (void);
-DBusMutex * _dbus_allocated_slots_init_lock (void);
-DBusMutex *_dbus_atomic_init_lock (void);
-DBusMutex *_dbus_message_handler_init_lock (void);
-
static dbus_bool_t
init_static_locks(void)
{
projects / platform / upstream / dbus.git / commitdiff