|
|
|
|
|
|
|
|
Applications that need to log messages during their execution may use the syslog API. There is more than one way to use this interface, of which only one will be presented here. I urge you to consult the man pages for the openlog, syslog and closelog functions.
The openlog call takes three arguments. The first, a pointer to a null-terminated string, is the identification of the message's origin. This is usually the program name. Note: this is usually not argv[0]. The argv[0] string frequently contains path information that will merely clutter up the system logs. Keep this short and simple.
The second argument is an integer that specifies options on the logging. There are defined constants in the syslog.h file. These are LOG_CONS, LOG_NDELAY, LOG_PERROR and LOG_PID. I won't describe all of these, but I will mention they can be combined with the bitwise OR operator (|), and LOG_PID includes the process ID in the log in a standard way, which is frequently useful. Also, if your process is not a dæmon, you might want the LOG_PERROR option which will cause the syslog messages to be dumped to STDERR as well as to syslogd. This may be useful in a foreground process.
The third argument is the ``facility'', as described above. The syslog.h file defines constants to use here that correspond to the facility part of the selectors in the syslog.conf file. These are LOG_AUTHPRIV, LOG_CRON, LOG_DAEMON, LOG_LOCALn (where n is a number from 0 to 7, inclusive) and LOG_USER. This list includes only those facilities you are likely to use in an application. See the man pages for others. If you are not the administrator of your system, consult with the system administrator to find out which to use. I would recommend LOG_DAEMON if you are writing a dæmon, and LOG_USER for non-dæmon processes.
The syslog call actually sends messages. It takes an indefinite number of arguments, although you must provide at least two. The first is a priority. There are defined values that match the levels in the syslog.conf file, included in the syslog.h file. These are (in descending order of severity) LOG_EMERG, LOG_ALERT, LOG_CRIT, LOG_ERR, LOG_WARNING, LOG_NOTICE, LOG_INFO and LOG_DEBUG. Again, if you are not the administrator of your system, consult with your administrator to decide which level to use for the various messages you generate. My personal opinion (and just my opinion; it is vital that you consult with your administrator) is that messages of LOG_CRIT and above should be reserved for situations that require the system administrator to take action. Unless it is going to affect the smooth operation of the operating system and standard system components, it doesn't warrant a LOG_CRIT or higher.
At the application or business-function level, LOG_ERROR would represent a situation that requires attention to maintain the normal operation of the application. LOG_WARNING reports other exceptional conditions (ones that can wait for attention). LOG_NOTICE is for ``handled'' or ``expected'' exceptions (another judgment call). LOG_INFO is for normal system operation messages. Finally, LOG_DEBUG is reserved for ``extra'' messages designed, as the name implies, to assist in debugging the program.
The second argument is a printf style format string. Like printf, syslog can take variable arguments with the format string, specifying how subsequent arguments are to be displayed. The format flags are just like the printf ones: see the printf man page for details. Note one exception: syslog adds an additional format string not offered by printf. The %m flag will be replaced by the string message that goes with the current value of the errno variable (this is the string strerror would return).
The final function, closelog, shuts down logging for the program and should be called before program termination.