From c21511c01ab56d75f3aa4643761e9fd096a7f8be Mon Sep 17 00:00:00 2001 From: Havoc Pennington Date: Wed, 19 Feb 2003 03:53:24 +0000 Subject: [PATCH] 2003-02-19 Havoc Pennington 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...) --- ChangeLog | 19 ++++++++++++++++ dbus/dbus-auth-script.c | 10 +++++++++ dbus/dbus-connection.c | 25 ++++++++++++--------- dbus/dbus-internals.h | 7 ++++++ dbus/dbus-keyring.c | 4 ++-- dbus/dbus-list.c | 6 ++++- dbus/dbus-md5.c | 5 +++-- dbus/dbus-message-handler.c | 8 ++++++- dbus/dbus-message.c | 21 +++++++++++++++--- dbus/dbus-string.c | 2 +- dbus/dbus-sysdeps.c | 54 +++++++++++++++++++++++++++++++++++++++++---- dbus/dbus-threads.c | 8 ++----- 12 files changed, 138 insertions(+), 31 deletions(-) diff --git a/ChangeLog b/ChangeLog index b7a0fc8..196e8f8 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,22 @@ +2003-02-19 Havoc Pennington + + 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 * dbus/dbus-string.c (_dbus_string_zero): new function diff --git a/dbus/dbus-auth-script.c b/dbus/dbus-auth-script.c index 21a9f99..4dccfe9 100644 --- a/dbus/dbus-auth-script.c +++ b/dbus/dbus-auth-script.c @@ -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) { diff --git a/dbus/dbus-connection.c b/dbus/dbus-connection.c index 64aa586..7da89bd 100644 --- a/dbus/dbus-connection.c +++ b/dbus/dbus-connection.c @@ -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) { diff --git a/dbus/dbus-internals.h b/dbus/dbus-internals.h index 2666156..9f9cba8 100644 --- a/dbus/dbus-internals.h +++ b/dbus/dbus-internals.h @@ -33,6 +33,7 @@ #include #include #include +#include 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 */ diff --git a/dbus/dbus-keyring.c b/dbus/dbus-keyring.c index a0e6f73..da66da9 100644 --- a/dbus/dbus-keyring.c +++ b/dbus/dbus-keyring.c @@ -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 */ }; diff --git a/dbus/dbus-list.c b/dbus/dbus-list.c index 72357d5..7b30692 100644 --- a/dbus/dbus-list.c +++ b/dbus/dbus-list.c @@ -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) { diff --git a/dbus/dbus-md5.c b/dbus/dbus-md5.c index 44b92af..dce18f8 100644 --- a/dbus/dbus-md5.c +++ b/dbus/dbus-md5.c @@ -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 -/* 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]*/) diff --git a/dbus/dbus-message-handler.c b/dbus/dbus-message-handler.c index 0f71d2e..143d7b0 100644 --- a/dbus/dbus-message-handler.c +++ b/dbus/dbus-message-handler.c @@ -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) { diff --git a/dbus/dbus-message.c b/dbus/dbus-message.c index e6c5178..203f0a6 100644 --- a/dbus/dbus-message.c +++ b/dbus/dbus-message.c @@ -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; diff --git a/dbus/dbus-string.c b/dbus/dbus-string.c index 52ab24a..7d8cfb8 100644 --- a/dbus/dbus-string.c +++ b/dbus/dbus-string.c @@ -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) diff --git a/dbus/dbus-sysdeps.c b/dbus/dbus-sysdeps.c index f76c6bd..316d278 100644 --- a/dbus/dbus-sysdeps.c +++ b/dbus/dbus-sysdeps.c @@ -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) { diff --git a/dbus/dbus-threads.c b/dbus/dbus-threads.c index 0b39224..a883057 100644 --- a/dbus/dbus-threads.c +++ b/dbus/dbus-threads.c @@ -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) { -- 2.7.4