Commit c21511c0 authored by Havoc Pennington's avatar Havoc Pennington

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...)
parent 78e16e99
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
......
......@@ -170,6 +170,16 @@ auth_state_to_string (DBusAuthState state)
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)
{
......
......@@ -82,21 +82,19 @@ struct DBusConnection
{
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. */
......@@ -114,7 +112,7 @@ struct DBusConnection
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
......@@ -1955,7 +1953,12 @@ static int n_allocated_slots = 0;
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)
{
......
......@@ -33,6 +33,7 @@
#include <dbus/dbus-types.h>
#include <dbus/dbus-errors.h>
#include <dbus/dbus-sysdeps.h>
#include <dbus/dbus-threads.h>
DBUS_BEGIN_DECLS;
......@@ -153,6 +154,12 @@ dbus_bool_t _dbus_decrement_fail_alloc_counter (void);
#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 */
......@@ -77,8 +77,8 @@ typedef struct
*/
struct DBusKeyring
{
DBusString filename;
DBusString lock_filename;
DBusString filename; /**< File containing keyring */
DBusString lock_filename; /**< Lock file for changing keyring */
};
......
......@@ -37,7 +37,11 @@
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)
{
......
......@@ -59,13 +59,13 @@
*
* @{
*/
#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;
......@@ -157,6 +157,7 @@ main(int argc, char **argv)
#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]*/)
......
......@@ -38,7 +38,13 @@
*/
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)
{
......
......@@ -1001,7 +1001,7 @@ dbus_message_get_service (DBusMessage *message)
* 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
*/
......@@ -1735,12 +1735,27 @@ dbus_message_get_sender (DBusMessage *message)
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;
......
......@@ -2166,7 +2166,7 @@ _dbus_string_validate_nul (const DBusString *str,
/**
* Clears all allocated bytes in the string to zero.
*
* @param the string
* @param str the string
*/
void
_dbus_string_zero (DBusString *str)
......
......@@ -790,6 +790,13 @@ _dbus_string_parse_double (const DBusString *str,
return TRUE;
}
/** @} */ /* DBusString group */
/**
* @addtogroup DBusInternalsUtils
* @{
*/
/**
* Gets the credentials corresponding to the given username.
*
......@@ -956,7 +963,12 @@ _dbus_string_append_our_uid (DBusString *str)
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)
{
......@@ -1512,10 +1524,22 @@ _dbus_generate_random_bytes (DBusString *str,
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()
......@@ -1636,9 +1660,9 @@ do_exec (int child_err_report_fd,
if (child_setup)
(* child_setup) (user_data);
#ifdef DBUS_BUILD_TESTS
max_open = sysconf (_SC_OPEN_MAX);
for (i = 3; i < max_open; i++)
{
......@@ -1651,7 +1675,7 @@ do_exec (int child_err_report_fd,
}
#endif
execvp (argv[0], argv);
execv (argv[0], argv);
/* Exec failed */
write_err_and_exit (child_err_report_fd,
......@@ -1659,6 +1683,21 @@ do_exec (int 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,
......@@ -1805,6 +1844,13 @@ _dbus_disable_sigpipe (void)
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)
{
......
......@@ -154,6 +154,8 @@ dbus_condvar_wait (DBusCondVar *cond,
* 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.
......@@ -193,12 +195,6 @@ dbus_condvar_wake_all (DBusCondVar *cond)
(* 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)
{
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment