man/logsys_overview.8

   1 .\"/*
   2 .\" * Copyright (c) 2007 Red Hat, Inc.
   3 .\" *
   4 .\" * All rights reserved.
   5 .\" *
   6 .\" * Author: Steven Dake (sdake@redhat.com)
   7 .\" *
   8 .\" * This software licensed under BSD license, the text of which follows:
   9 .\" *
  10 .\" * Redistribution and use in source and binary forms, with or without
  11 .\" * modification, are permitted provided that the following conditions are met:
  12 .\" *
  13 .\" * - Redistributions of source code must retain the above copyright notice,
  14 .\" *   this list of conditions and the following disclaimer.
  15 .\" * - Redistributions in binary form must reproduce the above copyright notice,
  16 .\" *   this list of conditions and the following disclaimer in the documentation
  17 .\" *   and/or other materials provided with the distribution.
  18 .\" * - Neither the name of the MontaVista Software, Inc. nor the names of its
  19 .\" *   contributors may be used to endorse or promote products derived from this
  20 .\" *   software without specific prior written permission.
  21 .\" *
  22 .\" * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  23 .\" * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
  26 .\" * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  27 .\" * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  28 .\" * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  29 .\" * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  30 .\" * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  31 .\" * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
  32 .\" * THE POSSIBILITY OF SUCH DAMAGE.
  33 .\" */
  34 .TH LOGSYS_OVERVIEW 8 2007-05-15 "openais Man Page" "Openais Programmer's Manual"
  35 .SH OVERVIEW
  36 The logsys library provides a generically usable logging and tracing system for
  37 use by applications.  It supports many features including:
  38 .PP
  39 Configurable subsystem logging or single system logging
  40 .PP
  41 Threaded non-blocking logging of log output data for better non-blocking performance
  42 .PP
  43 Support for 8 tracing levels and tracing the entering and leaving of functions
  44 .PP
  45 Declartion of logging system or subsystem without calling any functions
  46 .PP
  47 Dynamic reconfiguration of the logging system parameters
  48 .PP
  49 Logging to syslog, file, stderr.
  50
  51 .SH Declartion of the System logger
  52 The logsys library is initially configured by including logsys.h and declaring
  53 a logger.  Once the logger is declared either a subsystem logger or nosubsystem
  54 logger is declared in every file.
  55
  56 The definition LOGSYS_DECLARE_SYSTEM is placed after the include section of one
  57 C file in the application.  This declartion creates a constructor function
  58 which will be called automatically.  This technique avoids the need for calling
  59 any setup functions in short applications that don't require it.
  60
  61 #define LOGSYS_DECLARE_SYSTEM(name,mode,file,facility)
  62 The name parameter is the name of the application.
  63 The mode parameter is the logging mode of the system.  The following modes
  64 can be configured by logically ORing these flags:
  65 LOG_MODE_OUTPUT_FILE: Output all log data to the file parameter of this declartion
  66 LOG_MODE_OUTPUT_STDERR: Output all log data to the stderr descriptor
  67 LOG_MODE_OUTPUT_SYSLOG_THREADED: Output all log data to syslog using a non-blocking thread
  68 LOG_MODE_OUTPUT_SYSLOG_LOSSY: Output all log data without using a thread but potentially losing data.  This mode is not yet implemented.
  69 LOG_MODE_OUTPUT_SYSLOG_BLOCKING: Output all log data without using a thread and potentially blocking at each syslog call.
  70 LOG_MODE_DISPLAY_PRIORITY: Output the priority of the log entry in the message contents.  This mode is currently not implemented.
  71 LOG_MODE_DISPLAY_FILELINE: Output the file and line at which the log message was created.
  72 LOG_MODE_DISPLAY_TIMESTAMP: Output the timestamp of the message.
  73 LOG_MODE_DISPLAY_DEBUG: Display debug level messages
  74 LOG_MODE_BUFFER_BEFORE_CONFIG: This mode is used to buffer log messages before logsys_mode_config is called.  This is useful in applications in which the logging file isn't known before the application is compiled and must be set dynamically.  It is also useful when an application calls fork to disconnect the local tty and should hold logging of messages until after the fork.
  75 LOG_MODE_FLUSH_AFTER_CONFIG: This mode is used to flush any buffered messages when the LOG_MODE_BUFFER_BEFORE_CONFIG declartion is specified in the declartion of the logger.
  76 The file parameter specifies the filename that should be used to log messages.  This parameter may be NULL if LOG_MODE_OUTPUT_FILE is not specified.
  77 The facility parameter is the syslog facility that should be used when logging
  78 messages.
  79
  80
  81 An example declartion would be:
  82
  83 #include <openais/logsys.h>
  84
  85 ... (other #includes)
  86
  87 LOGSYS_DECLARE_SYSTEM ("my_example_app",
  88         LOG_MODE_OUTPUT_STDERR | LOG_MODE_OUTPUT_SYSLOG_THREADED | LOG_MODE_OUTPUT_FILE,
  89         "/tmp/log",
  90         LOG_DAEMON);
  91
  92 This would output any logging messages to stderr, syslog, and the file /tmp/log.
  93
  94 .SH Declartion of subsystems or no subsystems
  95 The logsys library supports the logging of information to one main system or
  96 subsystem.  This is specified in each individual object file in the system.
  97
  98 if no subsystems are desired, The define LOGSYS_DECLARE_NOSUBSYS should be
  99 declared for every object file in the system.  These object files are usually C
 100 files.
 101
 102 An example of using this would be
 103
 104 LOGSYS_DECLARE_NOSUBSYS (LOG_LEVEL_INFO);
 105
 106 Any messages of LOG_LEVEL_INFO priority or higher would be logged.
 107
 108 If subsystems are desired, the define LOGSYS_DECLARE_SUBSYS should be declared
 109 for every object file in the system.  It is possible to use the same subsystem
 110 name in separate object files.  In this case, the individual logging parameters
 111 for those subsystem identifier will be used.
 112
 113 An example of using this would be
 114 LOGSYS_DECLARE_SUBSYS ("SYS1", LOG_LEVEL_INFO);
 115
 116 Any message of LOG_LEVEL_INFO priority or higher would be logged and any
 117 logging within the object file this declartion is specified within will be
 118 logged to the SYS1 subsystem identifier.
 119
 120 .SH Logging Messages
 121 The definition log_printf is used to log information to the log.  It works
 122 in a similiar fashion to printf, except it has a first parameter of level
 123 which may be the following:
 124 LOG_EMERG
 125 LOG_ALERT
 126 LOG_CRIT
 127 LOG_ERR
 128 LOG_WARNING
 129 LOG_NOTICE
 130 LOG_INFO
 131 LOG_DEBUG
 132
 133 An example of using log_printf would be
 134
 135 log_printf (LOG_EMERG, "This is an emergency %s value %d\n", string, value);
 136
 137 Tracing of functions can be done using ENTER_VOID() or ENTER (format, args) LEAVE_VOID() or LEAVE (format, args);
 138
 139 An exmaple of using ENTER_VOID is
 140 void funtion (void) {
 141 ENTER_VOID();
 142 ... function contents ...
 143 LEAVE_VOID();
 144 }
 145
 146 An example of using ENTER is
 147 void function (char *name) {
 148 ENTER ("The name is %s\n", name);
 149 ... function contents ...
 150 LEAVE ("Bye\n");
 151 }
 152
 153 Individual tracing levels are supported through the macros
 154 TRACE1(format, args)
 155 TRACE2(format, args)
 156 ..
 157 TRACE8(format, args)
 158
 159 An example of using TRACE is
 160
 161 char *name = "test";
 162 TRACE7 ("This is a trace 7 log with name %s\n", name);
 163
 164 .SH "SEE ALSO"
 165 .BR logsys_config_mode_set (3),
 166 .BR logsys_config_file_set (3),
 167 .BR logsys_config_facility_set (3),
 168 .BR logsys_config_facility_set (3),
 169 .BR logsys_config_priority_set (3),
 170 .BR logsys_config_subsys_set (3),
 171 .BR logsys_config_subsys_get (3),
 172 .BR logsys_facility_id_get (3),
 173 .BR logsys_priority_id_get (3),
 174 .BR logsys_flush (3),
 175 .BR logsys_atsegv (3),
 176 .PP