00001 /* Part of the culibs project, <http://www.eideticdew.org/culibs/>. 00002 * Copyright (C) 2008--2010 Petter Urkedal <paurkedal@eideticdew.org> 00003 * 00004 * This program is free software: you can redistribute it and/or modify 00005 * it under the terms of the GNU General Public License as published by 00006 * the Free Software Foundation, either version 3 of the License, or 00007 * (at your option) any later version. 00008 * 00009 * This program is distributed in the hope that it will be useful, 00010 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00012 * GNU General Public License for more details. 00013 * 00014 * You should have received a copy of the GNU General Public License 00015 * along with this program. If not, see <http://www.gnu.org/licenses/>. 00016 */ 00017 00018 #ifndef CU_LOGGING_H 00019 #define CU_LOGGING_H 00020 00021 #include <cu/clos.h> 00022 #include <stdarg.h> 00023 00024 CU_BEGIN_DECLARATIONS 00025 /** \defgroup cu_logging_h cu/logging.h: Logging 00026 ** @{ \ingroup cu_base_mod */ 00027 00028 /** A type whose values indicate the importance or severity of log messages. */ 00029 typedef enum { 00030 CU_LOG_DEBUG, 00031 CU_LOG_INFO, 00032 CU_LOG_NOTICE, 00033 CU_LOG_WARNING, 00034 CU_LOG_ERROR, 00035 CU_LOG_FAILURE, 00036 } cu_log_severity_t; 00037 00038 /** A type which holds a hint about the origin of log messages. */ 00039 typedef enum { 00040 CU_LOG_LOGIC, 00041 CU_LOG_SYSTEM, 00042 CU_LOG_USER, 00043 } cu_log_origin_t; 00044 00045 typedef cu_clop(cu_vlogf_t, void, 00046 cu_log_facility_t facility, cu_location_t loc, 00047 char const *fmt, va_list va); 00048 00049 typedef cu_clop(cu_log_binder_t, cu_bool_t, cu_log_facility_t new_facility); 00050 00051 /** Facility flag to indicate process-long lifetime. */ 00052 #define CU_LOG_FLAG_PERMANENT 1 00053 00054 /** Facility flag to indicate transient lifetime. */ 00055 #define CU_LOG_FLAG_TRANSIENT 2 00056 00057 /** Indicates a logging facility used for debugging. */ 00058 #define CU_LOG_FLAG_DEBUG_FACILITY 4 00059 00060 /** A logging facility, which combines a printf-style format callback with 00061 ** various meta information which said function can use to determine whether, 00062 ** where, and how to log. */ 00063 struct cu_log_facility 00064 { 00065 unsigned int severity : 8; /* Actual type is cu_log_severity_t. */ 00066 unsigned int origin : 8; /* Actual type is cu_log_origin_t. */ 00067 unsigned int flags : 16; 00068 char const **keys; 00069 cu_log_facility_t next; 00070 cu_vlogf_t vlogf; 00071 }; 00072 00073 /** Expands to an initialiser for \ref cu_log_facility. */ 00074 #define CU_LOG_FACILITY_INITIALISER(severity, origin, keys, flags) \ 00075 { severity, origin, flags, keys, NULL, NULL } 00076 00077 /** The severity or importance of messages logged to this facility. This can 00078 ** be used by log binders to select the right channel and formatting, or to 00079 ** disable output. */ 00080 CU_SINLINE cu_log_severity_t 00081 cu_log_facility_severity(cu_log_facility_t facility) 00082 { return (cu_log_severity_t)facility->severity; } 00083 00084 /** A hit of the origin of messages logged to this facility. This can be used 00085 ** by log binders to select the right channel and formatting, or to disable 00086 ** output. */ 00087 CU_SINLINE cu_log_origin_t 00088 cu_log_facility_origin(cu_log_facility_t facility) 00089 { return (cu_log_origin_t)facility->origin; } 00090 00091 /** Various boolean properties of the logger in the form of an bitwise or of 00092 ** the \c CU_LOG_FLAG_* constants. */ 00093 CU_SINLINE unsigned int 00094 cu_log_facility_flags(cu_log_facility_t facility) 00095 { return facility->flags; } 00096 00097 /** Register a new log-binder. A log-binder will be called with all existing 00098 ** logs and logs created in the future. It's purpose is to assign a suitable 00099 ** vlogf implementation to log facilities based on the various 00100 ** meta-information stored in the facility. E.g. it may decide to direct 00101 ** error messages to a system log and to mail critical errors to an email 00102 ** account. 00103 ** 00104 ** The vlogf function assigned by \a binder must be thread-safe. */ 00105 cu_log_binder_t cu_register_log_binder(cu_log_binder_t binder); 00106 00107 /** Register a log facility which will persist throughout the life-time of the 00108 ** process. If \ref cu_register_log_binder is called later, the new binder 00109 ** will process \a facility, allowing it to change the vlogf implementation. */ 00110 void cu_register_permanent_log(cu_log_facility_t facility); 00111 00112 /** Register a transient logging facility. As opposed to \ref 00113 ** cu_register_permanent_log, this facility will be passed only to the current 00114 ** log-binder, and not any future ones. */ 00115 void cu_register_transient_log(cu_log_facility_t facility); 00116 00117 /** Run the vlogf implementation of \a facility. */ 00118 void cu_vlogf(cu_log_facility_t facility, char const *fmt, va_list va); 00119 00120 /** Run the vlogf implementation of \a facility. */ 00121 void cu_logf(cu_log_facility_t facility, char const *fmt, ...); 00122 00123 /** Run the vlogf implementation of \a facility with a source location. */ 00124 void cu_vlogf_at(cu_log_facility_t facility, cu_location_t loc, 00125 char const *fmt, va_list va); 00126 00127 /** @} */ 00128 CU_END_DECLARATIONS 00129 00130 #endif