From c21511c01ab56d75f3aa4643761e9fd096a7f8be Mon Sep 17 00:00:00 2001 From: Havoc Pennington Date: Wed, 19 Feb 2003 03:53:24 +0000 Subject: 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...) --- dbus/dbus-sysdeps.c | 54 +++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 50 insertions(+), 4 deletions(-) (limited to 'dbus/dbus-sysdeps.c') 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) { -- cgit