Implement setting log mask string on a destination.

Improve logging docs

include/ucore/logging.h

@@ -58,6 +58,13 @@
  *  And the resulting log line will include the short_name
  *  modules[DB].short_name
  *
+ * Log levels of the messages logged are checked first 
+ * by the log_level of the uc_log_destination, and then
+ * by the log_level of the module for that destination.
+ *
+ * Thus for a message to actually be logged the level
+ * must be above the overall log level for the destination and
+ * the log level of the module.
  */
 
 #ifdef __cplusplus
@@ -93,7 +100,11 @@ enum UC_LOG_DESTINATION {
 struct uc_log_module {
     /** The id of the log module.
      * This is the id one specifies in the various log
-     * functions/macros*/
+     * functions/macros.
+     * Within the struct uc_log_modules, this id must start
+     * at 0 and be incremented consecutively, being equal
+     * to the index within struct uc_log_modules.mods
+     */
     int id;
 
     /** A short name for the module.
@@ -103,7 +114,8 @@ struct uc_log_module {
     const char *long_name;
     /** The log level of this module. Only
      * log statements with a level >= the log_level
-     * are actually logged */
+     * are actually logged, but the log_level of a destination
+     * can restrict the logging further*/
     int log_level;
 };
 
@@ -202,6 +214,43 @@ void uc_log_destination_set_log_location(struct uc_log_destination *dest, int lo
 void uc_log_delete_destination(struct uc_log_destination *dest);
 
 
+/** Set the log level for a particular module on this destination
+ * 
+ * @param dest destination to chang
+ * @param moudle the module id to change
+ * @param log_level new log level to set for the module
+ */
+void uc_log_destination_set_module_loglevel(
+    struct uc_log_destination *dest, 
+    int module,
+    enum UC_LOG_LEVEL log_level
+);
+
+/** Set the log mask for the given destination.
+ * The log_mask is a string specifying the log levels for
+ * the modules logged by this destination.
+ * The log_level of the destination itself takes priority
+ * over the log_level of the modules.
+ * The format of the log_mask string is.
+ *
+ *  SHORT_NAME_1=LEVEL:SHORT_NAME_2=LEVEL:SHORT_NAME_N=LEVEL
+ *
+ * The SHORT_NAME_N is the .short_name within a struct uc_log_module
+ * LEVEL is one of DEBUG,INFO, WARNING or ERROR
+ * Example: 
+ *  DB=DEBUG:IO=ERROR:POLLER=INFO
+ *
+ * Modules not mentioned in the string retain their default value.
+ * No whitespaces must be specifed before/after the : or = character
+ *
+ * @param dest destination to set the log mask on
+ * @parama log_mask the log mask as described above to set.
+ */
+void uc_log_destination_set_mask(
+    struct uc_log_destination *dest, 
+    const char *log_mask
+);
+
 /** Closes and re-opens all the UC_LDEST_FILE log destinations.
  * Intended for use when a log file is rotated externally.
  *