This document describes libpnet6's logging functionality. See pnet6(3) for an introduction to libpnet6 itself.
- make use of libpnet6's logging functionality.
A lot of libpnet6 can fail in more than one way, and in more than one place.
To accommodate for that, libpnet6 has a highly configurable logging mechanism.
Logging happens at two levels: error logging, and application logging, the latter generally being used for debugging.
To keep things simple, and flexible (at least in my opinion), logging, both error and application, is enabled through environment variables. The idea behind this is that recompilation won't be necessary in order to enable the logging, which can be switched on ``outside'' of the given application.
Application logging is enabled by setting the variable PNET6_LOG_FILE to the name of the file you want all application logging to go to. Similarly, error logging is directed to the file pointed to by the variable PNET6_ERR_FILE.
Setting PNET6_LOG_FILE or PNET6_ERR_FILE to one of the values ``stdout'' or ``stderr'' will tell libpnet6 to use the standard error or standard output instead of a file for logging. Also, if the given file cannot be opened for whatever reason, libpnet6 will resort to stdout for logging, and stderr for error reporting.
libpnet6 tries to be as safe as possible in opening the files. In particular, it will not overwrite a file that is already present on the file system: on systems that support it, libpnet6 will also try to acquire an exclusive lock on the file prior to opening it. This means that you need to manually remove any left over log file prior to being able to reuse them again. This can be a nuisance, especially during development and testing; also, note that this behavior essentially prevents you from using the same file for both logging and error reporting. We chose to favor security above comfort (as you always should).
Logging can happen at a number of different levels. Essentially, this means that you can regulate the amout of logging that libpnet6 generates. In addition, you can tell libpnet6 to log the time, PID and thread ID of the current thread that is performing the logging. (the last one is only useful on systems that have thread support). You might have guessed it, but regulating what libpnet6 logs is also done through an environment variable, this one called PNET6_LOG_FLAGS. The syntax of this variable consists of keywords, separated by commas. Recognized keywords are ``time'', ``pid'', ``tid'', and integers from 0 to 8. The keyword ``time'' tells libpnet6 to log the time, in hh:mm:ss.msec format, ``pid'' and ``tid'' to log the PID and TID (thread id) respectively. The single digit indicates the level of logging desired. In the current version the levels are:
1 Nothing is logged
2 Warning messages---non-fatal errors
3 Normal messages
4 Informational messages---such as system information
5 Log events of minor importance
6 Log information on sockets and interfaces
7 Low intensity debug logging
8 High volume of debug logging for internal use
Error conditions are always reported to standard error if a value for PNET6_ERR_FILE has not been specified. If you don't want to see any error messages, then you have to set PNET6_ERR_FILE to point to a file. Error messages cannot be disabled, at least in the current version.
The current version of libpnet6 is highly experimental.
You can always get the most recent version from http://pnet6.sourceforge.net.
Peter Bozarov. Send mail to kingofgib (at) users.sourceforge.net