diff options
author | Havoc Pennington <hp@redhat.com> | 2003-02-19 03:53:24 +0000 |
---|---|---|
committer | Havoc Pennington <hp@redhat.com> | 2003-02-19 03:53:24 +0000 |
commit | c21511c01ab56d75f3aa4643761e9fd096a7f8be (patch) | |
tree | 7a0542dd8d02b8fd8e98e42409b1bf42564d32c0 | |
parent | 78e16e99e753175fa49e787eab256932eefaa03f (diff) |
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...)
-rw-r--r-- | ChangeLog | 19 | ||||
-rw-r--r-- | dbus/dbus-auth-script.c | 10 | ||||
-rw-r--r-- | dbus/dbus-connection.c | 25 | ||||
-rw-r--r-- | dbus/dbus-internals.h | 7 | ||||
-rw-r--r-- | dbus/dbus-keyring.c | 4 | ||||
-rw-r--r-- | dbus/dbus-list.c | 6 | ||||
-rw-r--r-- | dbus/dbus-md5.c | 5 | ||||
-rw-r--r-- | dbus/dbus-message-handler.c | 8 | ||||
-rw-r--r-- | dbus/dbus-message.c | 21 | ||||
-rw-r--r-- | dbus/dbus-string.c | 2 | ||||
-rw-r--r-- | dbus/dbus-sysdeps.c | 54 | ||||
-rw-r--r-- | dbus/dbus-threads.c | 8 |
12 files changed, 138 insertions, 31 deletions
@@ -1,3 +1,22 @@ +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 diff --git a/dbus/dbus-auth-script.c b/dbus/dbus-auth-script.c index 21a9f996..4dccfe9f 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 64aa5863..7da89bdc 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 26661564..9f9cba85 100644 --- a/dbus/dbus-internals.h +++ b/dbus/dbus-internals.h @@ -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 */ diff --git a/dbus/dbus-keyring.c b/dbus/dbus-keyring.c index a0e6f739..da66da98 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 72357d53..7b306924 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 44b92af4..dce18f89 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 <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]*/) diff --git a/dbus/dbus-message-handler.c b/dbus/dbus-message-handler.c index 0f71d2ea..143d7b03 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 e6c51784..203f0a6c 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 52ab24a6..7d8cfb8c 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 f76c6bd0..316d278c 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 0b392240..a883057d 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) { |