From fe535d25e58d75397ddefeb796bf60e897360f35 Mon Sep 17 00:00:00 2001 From: Klaus Schmidinger Date: Sun, 2 Apr 2017 13:01:34 +0200 Subject: [PATCH] Added some guidelines and recommendations to the 'Logging' section of PLUGINS.html --- HISTORY | 4 ++++ PLUGINS.html | 24 ++++++++++++++++++++++++ 2 files changed, 28 insertions(+) diff --git a/HISTORY b/HISTORY index fc10b912..e2dfbf89 100644 --- a/HISTORY +++ b/HISTORY @@ -8944,3 +8944,7 @@ Video Disk Recorder Revision History store auxiliary information with an event (thanks to Jörg Wendel). This string has no meaning whatsoever to VDR itself, and it will not be written into the info file of a recording that is made for such an event. +- Added some guidelines and recommendations to the 'Logging' section of PLUGINS.html. + The most important being: implement a command line option to control the level + of logging (in particular allow turning off logging completely!) and never print + anything to stdout or stderr (unless one of the listed exceptions applies). diff --git a/PLUGINS.html b/PLUGINS.html index dd7a154f..92a4d313 100644 --- a/PLUGINS.html +++ b/PLUGINS.html @@ -583,6 +583,30 @@ esyslog("pluginname: error #%d has occurred", ErrorNumber); Note that the log messages will be given as provided, the plugin's name will not automatically be added, so make sure your log messages are obvious enough. +

+ +Only use the above logging functions for occasional log messages. Do not use +them unconditionally for frequent messages that produce long sequences of lines +in the log file every few seconds. That might make it hard to work on other plugins +or the core VDR code, watching their log entries while they are permanently +interspersed with unrelated stuff.
+
+The recommended behavior for a plugin that does logging is to implement a command +line option that controls the level of log messages, preferably '-l N, --log=N', +where 'N' is in the range 0...3, with 0 meaning no logging whatsoever, 1 log only +errors, 2 log errors and informational messages, and 3 also log debug information.
+
+If a plugin can output extensive data for special debugging purposes (either to +the log file or stdout/stderr), this should be enabled by setting proper switches +in one of its source files (see for example how the communication between VDR and +CAMs can be monitored in VDR/ci.c).
+
+Under no circumstances must a plugin print anything to stdout or stderr during +normal operation! The only exceptions being special debug information as described +above, fatal error messages that will cause VDR to abort, or if it is the sole +purpose of the plugin to display something on stdout, like for instance the +skincurses plugin, which displays the OSD at the console. +

Main menu entry