ll_hdinit, ll_dbinit, _ll_log, or ll_log Subroutine

Purpose

Reports errors to log files.

Library

ISODE Library (libisode.a)

Syntax

#include <isode/logger.h>
  
void ll_hdinit (lp, prefix)
register LLog * lp;
char * prefix;
  
void ll_dbinit (lp, prefix)
register LLog *lp;
char *prefix;
  
int _ll_log (lp, event, ap)
register LLog *lp;
int  event;
va_list  ap;
  
int ll_log ( va_alist)
va_dcl

Description

The ISODE library provides logging subroutines to put information into log files. The LLog data structure contains the log file information needed to control the associated log. The SMUX peer provides the log file information to the subroutines.

The LLog structure contains the following fields:

    typedef struct ll_struct 
    {
    char      *ll_file;    /* path name to logging file         */
    char      *ll_hdr;     /* text to put in opening line       */
    char      *ll_dhdr;    /* dynamic header - changes          */
    int       ll_events;   /* loggable events                   */
    int       ll_syslog;   /* loggable events to send to syslog */
                           /* takes same values as ll_events    */
    int       ll_msize;    /* max size for log, in Kbytes       */
                           /* If ll_msize < 0, then no checking */
    int       ll_stat;     /* assorted switches                 */
    int       ll_fd;       /* file descriptor                   */
    } LLog;

The possible values for the ll_events and ll_syslog fields are:

    LLOG_NONE         0         /*  No logging is performed       */
    LLOG_FATAL        0x01      /*  fatal errors                  */
    LLOG_EXCEPTIONS   0x02      /*  exceptional events            */
    LLOG_NOTICE       0x04      /*  informational notices         */
    LLOG_PDUS         0x08      /*  PDU printing                  */
    LLOG_TRACE        0x10      /*  program tracing               */
    LLOG_DEBUG        0x20      /*  full debugging                */
    LLOG_ALL          0xff      /*  All of the above logging      */

The possible values for the ll_stat field are:

   LLOGNIL           0x00      /* No status information           */
   LLOGCLS           0x01      /* keep log closed, except writing */
   LLOGCRT           0x02      /* create log if necessary         */
   LLOGZER           0x04      /* truncate log when limits reach  */
   LLOGERR           0x08      /* log closed due to (soft) error  */
   LLOGTTY           0x10      /* also log to stderr              */
   LLOGHDR           0x20      /* static header allocated/filled  */
   LLOGDHR           0x40      /* dynamic header allocated/filled */

The ll_hdinit subroutine fills the ll_hdr field of the LLog record. The subroutine allocates the memory of the static header and creates a string with the information specified by the prefix parameter, the current user's name, and the process ID of the SMUX peer. It also sets the static header flag in the ll_stat field. If the prefix parameter value is null, the header flag is set to the "unknown" string.

The ll_dbinit subroutine fills the ll_file field of the LLog record. If the prefix parameter is null, the ll_file field is not changed. The ll_dbinit subroutine also calls the ll_hdinit subroutine with the same lp and prefix parameters. The ll_dbinit subroutine sets the log messages to stderr and starts the logging facility at its highest level.

The _ll_log and ll_log subroutines are used to print to the log file. When the LLog structure for the log file is set up, the _ll_log or ll_log subroutine prints the contents of the string format, with all variables filled in, to the log specified in the lp parameter. The LLog structure passes the name of the target log to the subroutine.

The expected parameter format for the _ll_log and ll_log subroutines is:

The difference between the _ll_log and the ll_log subroutine is that the _ll_log uses an explicit listing of the LLog structure and the event parameter. The ll_log subroutine handles all the variables as a variable list.

The event parameter specifies the type of message being logged. This value is checked against the events field in the log record. If it is a valid event for the log, the other LLog structure variables are written to the log.

The what parameter variable is a string that explains what actions the subroutines have accomplished. The rest of the variables should be in the form of a printf statement, a string format and the variables to fill the various variable placeholders in the string format. The final output of the logging subroutine is in the following format:

mm/dd hh:mm:ss ll_hdr ll_dhdr string_format what: system_error

where:

Variable Description
mm/dd Specifies the date.
hh:mm:ss Specifies the time.
ll_hdr Specifies the value of the ll_hdr field of the LLog structure.
ll_dhdr Specifies the value of the ll_dhdr field of the LLog structure.
string_format Specifies the string format passed to the ll_log subroutine, with the extra variables filled in.
what Specifies the variable that tells what has occurred. The what variable often contains the reason for the failure. For example if the memory device, /dev/mem, fails, the what variable contains the name of the /dev/mem device.
system_error Contains the string for the errno value, if it exists.

These subroutines are part of the SNMP Application Programming Interface in the TCP/IP facility.

Parameters

Item Description
lp Contains a pointer to a structure that describes a log file. The lp parameter is used to describe things entered into the log, the file name, and headers.
prefix Contains a character string that is used to represent the name of the SMUX peer in the ll_hdinit subroutine. In the ll_dbinit subroutine, the prefix parameter represents the name of the log file to be used. The new log file name will be ./prefix.log.
event Specifies the type of message to be logged.
ap Provides a list of variables that is used to print additional information about the status of the logging process. The first argument needs to be a character string that describes what failed. The following arguments are expected in a format similar to the printf operation, which is a string format with the variables needed to fill the format variable places.
va_alist Provides a variable list of parameters that includes the lp, event, and ap variables.

Return Values

The ll_dbinit and ll_hdinit subroutines have no return values. The _ll_log and ll_log subroutines return OK on success and NOTOK on failure.