log.h

Go to the documentation of this file.

/*
 * Copyright (c) 2008 - 2012, Andy Bierman, All Rights Reserved.
 * Copyright (c) 2012 - 2021, YumaWorks, Inc., All Rights Reserved.
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
#ifndef _H_log
#define _H_log
/*  FILE: log.h
*********************************************************************
*                                                                   *
*                        P U R P O S E                              *
*                                                                   *
*********************************************************************/



/********************************************************************
*                                                                   *
*                  C H A N G E   H I S T O R Y                      *
*                                                                   *
*********************************************************************

date         init     comment
----------------------------------------------------------------------
08-jan-06    abb      begun
28may12      mts      Logging feature set mods
*/




#include <stdio.h>
#include <xmlstring.h>

#include "procdefs.h"
#include "status.h"

#ifdef PTHREADS
#ifndef _H_thd
#include "thd.h"
#endif
#endif

#ifdef __cplusplus
extern "C" {
#endif

/********************************************************************
*                                                                   *
*                           M A C R O S                             *
*                                                                   *
*********************************************************************/

#if defined(_XOPEN_SOURCE) || defined(CYGWIN) || defined(MACOSX)
#define uint uint32
#endif

#if 0  // removed -- not threadsafe, may cause deadlocks

/* THESE MACROS NOW DEFINED IN platform/procdefs.f
 * ENTER_CS and EXIT_CS used instead
 */

#ifndef PTHREADS
/* NOP for non-threaded build */
#define LOG_ENTER_CS
#define LOG_EXIT_CS
#else

/*
 * Since multiple threads may call the logger at any time, access
 * is synchronized via a mutex in order to prevent garbled output.
 * In addition, a series of calls may be related (for example,
 * val_dump_value() or trace_buff()). In order to allow nested calls
 * on logger, a recursive "counting" mutex is used, allowing
 * the owner to make multiple log calls in a "critical section".
 *
 * These are exported in order to allow the aforementioned calls
 * from application code. (See val.c)
 *
 * Note that since the macros check for server vs client, these may
 * be placed in common output code with no issues.
 */

#define LOG_ENTER_CS   if (ncx_netconfd_running()) {                    \
                           if (thd_lock_recursive_log_cs_mutex())             \
                           {                                                  \
                               SET_ERROR(ERR_MUTEX_ERR);                      \
                           }                                                  \
                        }

#define LOG_EXIT_CS    if (ncx_netconfd_running()) {                    \
                           if (thd_unlock_recursive_log_cs_mutex())           \
                           {                                                  \
                               SET_ERROR(ERR_MUTEX_ERR);                      \
                           }                                                  \
                        }

#endif   // PTHREADS
#endif  // 0

/*
 * Log internal errors to stderr. We can't call logger code to
 * handle its own internal errors.
 */

/********************************************************************
* MACRO: LOG_INTERNAL_ERR
*
*    Output string to stderr reporting error, function name, and line number
*    and resulting action ...
*
* EXAMPLE:
*
*     MACRO: LOG_INTERNAL_ERR(Null buf ptr, RETURN);
*
*    OUTPUT: ERROR [log_util_init_buf@86]: Null buf ptr - RETURN
*
*
*********************************************************************/
#define LOG_INTERNAL_ERR(err_str, action)                                     \
  log_internal_err("\nERROR [%s@%d]: " #err_str " - " #action,                \
               __FUNCTION__, __LINE__)

#define LOG_INTERNAL_LOCK_ERR(name, err_str, hndl, rc, action)               \
 log_internal_lock_err(                                                      \
        "\nERROR [%s@%d]: [" #name "] " #err_str " (%p:%d) - " #action,      \
        __FUNCTION__, __LINE__, (void *)(hndl), rc)


/********************************************************************
* MACRO: LOG_INTERNAL_BUFF_ERR
*
*    Output string to stderr reporting error, function name, and line number.
*    Dump salient buffer descriptor state, and resulting action ...
*
* EXAMPLE:
*
*     MACRO: LOG_INTERNAL_BUF_ERR(Bad buf, buf, remaining, REINIT);
*
*    OUTPUT: ERROR [upd_log_buf@179]: Bad buf 'remaining' [ptr=81783a0,  \
*            id=4242, start=81783cc, end=81787cc, len=1024(0x400),       \
*            remaining=1024(0x400)]->remaining=400 - REINIT              \
*
*********************************************************************/
#define LOG_INTERNAL_BUF_ERR(err_str, ptr, action)                      \
  log_internal_err("\nERROR [%s@%d]: " #err_str                         \
                   " [ptr=%p, id=%4x, start=%p, end=%p"                 \
                   ", len=%u(0x%x), remaining=%d(0x%x)]"                \
                   " wp=%u" " - %s\n", __FUNCTION__, __LINE__,          \
                   ptr, (ptr)->idid, (ptr)->start, (ptr)->end,          \
                   (ptr)->len, (ptr)->len, (ptr)->remaining, (ptr)->remaining, \
                   (uint)(ptr)->write_pending, #action)


/********************************************************************
*                                                                   *
*                        C O N S T A N T S                          *
*                                                                   *
*********************************************************************/
#define LOG_CLEANUP_PHASE1 FALSE
#define LOG_CLEANUP_PHASE2 !LOG_CLEANUP_PHASE1


/********************************************************************
* MACRO FILTER_DEBUG_LEVEL(lvl)
*
* Filter log calls at debug_level and syslog_level.
*
* Note: For efficiency, looks first at system_debug_level which is defined
*       to be max of (debug_level, syslog_log_level, pthread_log_level).
*       If system_debug_level indicates filtering, then no need to look
*       at context specific debug levels.
*
* Note: pthread_log_level only exists in PTHREAD build
*
* INPUTS:
*    lvl == debug level to inspect
*
* RETURNS:
*    TRUE  => filter
*    FALSE => pass
*********************************************************************/
#define FILTER_DEBUG_LEVEL(lvl) \
    ((log_get_system_log_level() < (lvl)) ||    \
     ((log_get_log_level() < (lvl)) &&          \
      (log_get_syslog_log_level() < (lvl))))

#define ALLOW_DEBUG_LEVEL(lvl) !FILTER_DEBUG_LEVEL(lvl)

#ifdef PTHREADS
/********************************************************************
* MACRO FILTER_PTHREAD_DEBUG_LEVEL(lvl)
*
* Filter pthread specific log calls at pthread_debug_level
*
* Note: For efficiency, looks first at system_debug_level which is defined
*       to be max of (debug_level, syslog_log_level, pthread_log_level).
*       If system_debug_level indicates filtering, then no need to look
*       at context specific debug levels.
*
* Note: pthread_log_level only exists in PTHREAD build
*
* INPUTS:
*    lvl == debug level to inspect
*
* RETURNS:
*    TRUE  => filter
*    FALSE => pass
*********************************************************************/
#define FILTER_PTHREAD_DEBUG_LEVEL(lvl) \
    ((log_get_system_log_level() < (lvl)) || \
     (log_get_pthread_log_level() < (lvl)))

#define ALLOW_PTHREAD_DEBUG_LEVEL(lvl) !FILTER_PTHREAD_DEBUG_LEVEL(lvl)
#endif


// Header only

#define LOGDEV0    (log_get_system_log_level() >= LOG_DEBUG_DEV0)

   // BEGIN ncxlib/log/logmacros



#define LOGERROR   (log_get_system_log_level() >= LOG_DEBUG_ERROR)

#define LOGWARN    (log_get_system_log_level() >= LOG_DEBUG_WARN)

#define LOGINFO    (log_get_system_log_level() >= LOG_DEBUG_INFO)


#define LOGDEV1    (log_get_system_log_level() >= LOG_DEBUG_DEV1)

#define LOGDEBUG   (log_get_system_log_level() >= LOG_DEBUG_DEBUG)

#define LOGDEBUG2  (log_get_system_log_level() >= LOG_DEBUG_DEBUG2)

#define LOGDEBUG3  (log_get_system_log_level() >= LOG_DEBUG_DEBUG3)

#define LOGDEBUG4  (log_get_system_log_level() >= LOG_DEBUG_DEBUG4)
   // END ncxlib/log/logmacros



/* macros to check pthread debug level only ... improves performance when
   running without debugs enabled                                          */
#define LOGDEV1_THD    (log_get_pthread_log_level() >= LOG_DEBUG_DEV1)
#define LOGDBG_THD     (log_get_pthread_log_level() >= LOG_DEBUG_DEBUG)
#define LOGDBG2_THD    (log_get_pthread_log_level() >= LOG_DEBUG_DEBUG2)
#define LOGDBG3_THD    (log_get_pthread_log_level() >= LOG_DEBUG_DEBUG3)
#define LOGDBG4_THD    (log_get_pthread_log_level() >= LOG_DEBUG_DEBUG4)

  /* Ultra concise version */
#define DWRT    LOG_DEBUG_WRITE
#define DEV0    LOG_DEBUG_DEV0
#define DERR    LOG_DEBUG_ERROR
#define DWARN   LOG_DEBUG_WARN
#define DINFO   LOG_DEBUG_INFO
#define DEV1    LOG_DEBUG_DEV1
#define DBG     LOG_DEBUG_DEBUG
#define DBG1    LOG_DEBUG_DEBUG
#define DBG2    LOG_DEBUG_DEBUG2
#define DBG3    LOG_DEBUG_DEBUG3
#define DBG4    LOG_DEBUG_DEBUG4

#define LOG_DEBUG_STR_OFF     (const xmlChar *)"off"
#define LOG_DEBUG_STR_WRITE   (const xmlChar *)"write" /* "Force" output */
#define LOG_DEBUG_STR_DEV0    (const xmlChar *)"dev0"  /* Special debugging */
#define LOG_DEBUG_STR_ERROR   (const xmlChar *)"error"
#define LOG_DEBUG_STR_WARN    (const xmlChar *)"warn"
#define LOG_DEBUG_STR_INFO    (const xmlChar *)"info"
#define LOG_DEBUG_STR_DEV1    (const xmlChar *)"dev1" /* Special debugging */
#define LOG_DEBUG_STR_DEBUG   (const xmlChar *)"debug"
#define LOG_DEBUG_STR_DEBUG2  (const xmlChar *)"debug2"
#define LOG_DEBUG_STR_DEBUG3  (const xmlChar *)"debug3"
#define LOG_DEBUG_STR_DEBUG4  (const xmlChar *)"debug4"

/* syslog wants to know what app is calling ... */
#define LOG_DEBUG_APP_STR_UNKNOWN   (const char *)"?yuma?"
#define LOG_DEBUG_APP_STR_YANGCLI   (const char *)"yangcli-pro"
#define LOG_DEBUG_APP_STR_YANGDUMP  (const char *)"yangdump-pro"
#define LOG_DEBUG_APP_STR_YANGDIFF  (const char *)"yangdiff-pro"
#define LOG_DEBUG_APP_STR_NETCONFD  (const char *)"netconfd-pro"

/*
 * Count to skip backtrace frames that are within the logging code ...
 * these are usually not interesting or meaningful to the end user.
 */
#define FRAME_OVERHEAD_CNT 4

/********************************************************************
*                                                                   *
*                            T Y P E S                              *
*                                                                   *
*********************************************************************/
   // BEGIN ncxlib/log/logtypes


typedef enum log_stream_t_ {
    LOG_STREAM_NONE,           
    LOG_STREAM_STDOUT,         
    LOG_STREAM_STDERR,         
    LOG_STREAM_LOGFILE,        
    LOG_STREAM_CAPFILE         
}  log_stream_t;


typedef enum log_debug_t_ {
    LOG_DEBUG_NONE,           
    LOG_DEBUG_OFF,            
    LOG_DEBUG_WRITE,          
    LOG_DEBUG_DEV0,           
    LOG_DEBUG_ERROR,          
    LOG_DEBUG_WARN,           
    LOG_DEBUG_INFO,           
    LOG_DEBUG_DEV1,           
    LOG_DEBUG_DEBUG,          
    LOG_DEBUG_DEBUG2,         
    LOG_DEBUG_DEBUG3,         
    LOG_DEBUG_DEBUG4          
}  log_debug_t;


typedef enum log_debug_app_t_ {
    LOG_DEBUG_APP_NONE,
    LOG_DEBUG_APP_YANGCLI,        
    LOG_DEBUG_APP_YANGDUMP,       
    LOG_DEBUG_APP_YANGDIFF,       
    LOG_DEBUG_APP_NETCONFD,       
    LOG_DEBUG_APP_MAX
}  log_debug_app_t;

   // END ncxlib/log/logtypes



#define VALID_DEBUG_APP(app) \
    ((app) > LOG_DEBUG_APP_NONE) && ((app) < LOG_DEBUG_APP_MAX)

#define APP_IS_NETCONFD (log_get_debug_app() == LOG_DEBUG_APP_NETCONFD)

/* logging function template to switch between
 * log_stdout and log_write
 */
typedef void (*logfn_void_t) (void);

/*
 * Function vectors to switch between native versus syslog (or
 * vendor-specific) logging.
 */
typedef void (*logfn_t) (const char *fstr, ...)
                         __attribute__ ((format (printf, 1, 2)));


/*
 * log_common() and log_xxx_common()
 */
typedef void (*logfn_cmn_va_t) (boolean recursive,
                                log_debug_t level, log_debug_t sub_level,
                                const char *fstr, va_list args);

/*
 * log_append() and log_xxx_append()
 */
typedef void (*logfn_app_va_t) (boolean recursive,
                                log_debug_t level, log_debug_t sub_level,
                                const char *fstr, va_list args);
  /* log_flush() and log_xxx_flush() */
typedef void (*logfn_flush_t) (void);
  /* log_xxx_connect() */
typedef void (*logfn_connect_t) (void);
  /* log_xxx_send() */
typedef void (*logfn_send_t) (log_debug_app_t app, log_debug_t level,
                              const char *fstr, ...)
                              __attribute__ ((format (printf, 3, 4)));


/* Accessed by log_syslog.c and log_vendor.c */
extern logfn_connect_t logfn_connect;
extern logfn_send_t logfn_send;

/********************************************************************
*                                                                   *
*                       V A R I A B L E S                           *
*                                                                   *
*********************************************************************/



/********************************************************************
*                                                                   *
*                       F U N C T I O N S                           *
*                                                                   *
*********************************************************************/

/*
* Enforce logger critical section via logger mutex
*/
extern void log_enter_cs ( void );


/*
* Enforce logger critical section via logger mutex
*/
extern void log_exit_cs ( void );

   // BEGIN ncxlib/log/logfns


extern void disable_default_stdout(void);


extern void enable_default_stdout(void);




void
    log_cleanup ( boolean phase2, boolean debugs );


/********************************************************************
* FUNCTION log_internal_err
*
* Send internal logging error info to stderr. This function is called
* when an error is detected while in the process of trying to send
* info via the logging stream.
*
* See also  LOG_INTERNAL_ERR() and  LOG_INTERNAL_BUF_ERR macros.
*
* INPUTS:
*
*    fstr == format output string
*    ... == variable argument list
*
* RETURNS:
*    None
*********************************************************************/
void
    log_internal_err (const char *fstr, ...)
                      __attribute__ ((format (printf, 1, 2)));

void
    log_internal_lock_err (const char *fstr, ...)
                           __attribute__ ((format (printf, 1, 2)));


/********************************************************************
* FUNCTIONs log_set_xxx and log_get_xxx
*
* Read/write support for the various (binary) --log-xxx config
* options above. Additional comments inline where noteworthy.
*
* INPUTS:
*    None
*
* RETURNS:
*    if log_get_xxx(), the requested configured value
*********************************************************************/

/* Backtrace info level */
extern boolean
    log_get_backtrace_detail (void);
extern void
    log_set_backtrace_detail (void);

/* --logheader="custom" */
extern void
    log_set_custom (void);

/* --log-header="localtime" */
extern void
    log_set_localtime (void);

/* --log-mirroring */
extern void
    log_set_mirroring (void);
/* --log-mirroring */
extern boolean
    log_get_mirroring (void);

/* --log-stderr */
extern void
    log_set_stderr (void);

/* --log-suppress-ctrl */
extern void
    log_set_suppress_ctrl (void);

/* --log-syslog --log-vendor */
extern boolean
    log_get_syslog_bfr_allocated (void);

extern log_debug_t
    log_syslog_log_level (void);

/* --log-syslog --log-vendor */
extern boolean
    log_get_vendor_bfr_allocated (void);

/* --log-syslog --log-vendor */
extern void
    log_set_syslog_bfr_allocated (void);

/* --log-syslog --log-vendor */
extern void
    log_set_vendor_bfr_allocated (void);

/* --log-syslog --log-vendor */
extern void
    log_clr_syslog_bfr_allocated (void);

/* --log-syslog --log-vendor */
extern void
    log_clr_vendor_bfr_allocated (void);

/* --log-syslog */
extern void    log_set_syslog (void);
extern void    log_clr_syslog (void);
extern boolean log_get_syslog (void);

/* --log-vendor */
extern void
    log_set_vendor (void);

/* --log-backtrace-stream="logfile" */
extern void
    log_set_backtrace_logfile (void);

/* --log-backtrace-stream="stderr" */
extern void
    log_set_backtrace_stderr (void);

/* --log-backtrace-stream="stdout" */
extern void
    log_set_backtrace_stdout (void);

/* --log-backtrace-stream="syslog" */
extern boolean
    log_get_backtrace_syslog (void);
extern void
    log_set_backtrace_syslog (void);

/* --log-backtrace-stream="vendor" */
extern boolean
    log_get_backtrace_vendor (void);
extern void
    log_set_backtrace_vendor (void);


/********************************************************************
 * FUNCTION log_set_backtrace
*
*    Set the maximum frame count to report on a backtrace log entry
*    (--log-backtrace=<frame_count>)
*
* INPUTS:
*
*    frame_cnt == the requested frame count (if 0 then use internal default).
*
* RETURNS:
*    None
*
*********************************************************************/
extern void
    log_set_backtrace (uint frame_cnt);


/********************************************************************
* FUNCTIONs log_cvt_debug_level2bit
*
*    Convert a debug level to a unique bit mask
*
* INPUTS:
*
*    level == debug level enum to convert
*
* RETURNS:
*    Unique bit mask
*
*********************************************************************/
extern uint
    log_cvt_debug_level2bit (log_debug_t level);


/********************************************************************
* FUNCTIONs log_set_backtrace_level and log_clear_backtrace_level
*
*    Manage the debug level bit mask to allow or restrict
*    reporting of backtrace log entries
*
* INPUTS:
*
*    log_set_backtrace_level: level == debug level for which backtrace
*                             log entries will be reported
*
*    log_clear_backtrace_level: level == debug level for which backtrace
*                               log entries should no longer be reported
*
*
* RETURNS:
*    none
*********************************************************************/
extern void
    log_clear_backtrace_level (log_debug_t level);


extern void
    log_set_backtrace_level (log_debug_t level);


/********************************************************************
* FUNCTION log_set_backtrace_level_mask
*
*    Set the debug level bit mask to restrict reporting of backtrace info
*
* INPUTS:
*    mask == bit mask respresenting debug levels for which to append
*            backtrace info
*
* RETURNS:
*    none
*********************************************************************/
extern void
    log_set_backtrace_level_mask (uint mask);


/********************************************************************
* FUNCTIONs log_get_backtrace_level_mask
*
*    Return the debug level bit mask in current use
*
* INPUTS:
*    none
*
* RETURNS:
*     mask == bit mask respresenting debug levels for which to append
*             backtrace info
*********************************************************************/
extern uint
    log_get_backtrace_level_mask (void);

/********************************************************************
* FUNCTIONs log_test_backtrace_level
*
*    Return whether a given debug level is enabled for backtrace
*
* INPUTS:
*    level == debug level to test
*
* RETURNS:
*      TRUE == backtrace enabled for level
*     FALSE == backtrace disabled for level
*********************************************************************/
extern boolean
    log_test_backtrace_level (log_debug_t level);


/********************************************************************
* FUNCTION log_do_backtrace
*
* Return the configured status for including backtrace info on a
* given output stream (e.g., logfile, syslog, stderr, etc.) at a
* given content level (e.g., error, warn, info, etc.).
*
* NOTE: Slightly funky. To use, pass the current (boolean) value
*       of the config flag to be tested, along with the current
*       content level (sub_level).
*
* INPUTS:
*
*    sub_level == the content level for the log output
*    flag == the --log-backtrace-stream flag to test
*
* RETURNS:
*
*    TRUE  == backtrace info should be generated
*    FALSE == backtrace info should NOT be generated
*
*********************************************************************/
extern boolean
    log_do_backtrace (log_debug_t sub_level, boolean flag);


extern status_t
    log_open (const char *fname,
              boolean append,
              boolean tstamps);


extern void
    log_close (void);


extern status_t
    log_audit_open (const char *fname,
                    boolean append,
                    boolean tstamps);


extern void
    log_audit_close (void);


extern boolean
    log_audit_is_open (void);


extern status_t
    log_alt_open (const char *fname);


extern status_t
    log_alt_open_ex (const char *fname,
                     boolean overwrite);


extern void
    log_alt_close (void);


extern void
    log_init (void);


/********************************************************************
* FUNCTION log_common
*
*   Generate "new" message log output, optionally pre-pended with an
*   internal status header (date, time, level, etc). Additional info
*   may be appended (via log_append()) on the same or subsequent lines.
*
* INPUTS:
*   recursive == TRUE means this is a recursive callback from print_backtrace()
*   level == internal logger "screening" level
*   sub_level == internal logger functional (content) level
*   fstr == format string in printf format
*   args  == any additional arguments for printf
*
* KLUDGE ALERT:
*    For convenience we equate the 'recursive' param to a call from
*    print_backtrace(), passing this information unvetted on to
*    log_common_internal(). At present, this works because print_backtrace()
*    is the ONLY routine to pass recursive as TRUE. Someday this may change.
*
*********************************************************************/
extern void
    log_common (boolean recursive, log_debug_t level, log_debug_t sub_level,
                const char *fstr, va_list args);


/*
*  Append formatted string to the current logger output stream
*
* INPUTS:
*   recursive == TRUE means this is a recursive callback from print_backtrace()
*   level == internal logger "screening" level
*   sub_level == internal logger functional (content) level
*   fstr == format string in printf format
*   args == additional arguments for printf
*
*********************************************************************/
extern void
    log_append (boolean recursive, log_debug_t level, log_debug_t sub_level,
                const char *fstr, va_list args);


extern void
    log_flush (void);


/********************************************************************
* FUNCTION log_print_backtrace
*
*   Print up to (array[] size) stack frame addresses
*
* INPUT:
*
*    orig_sub_level == content level
*    localfn_flush == flush call vector function
*    max_detail == include maximum backtrace return information
*    frame_overhead == number of frames in logger code (skip)
*    preamble == prompt string to precede backtrace output
*
* RETURNS:
*    none
*********************************************************************/
extern void
    log_print_backtrace (boolean syslog_call,
                         log_debug_t orig_sub_level,
                         logfn_flush_t localfn_flush,
                         boolean max_detail,
                         uint frame_overhead,
                         const char *preamble);


/********************************************************************
* FUNCTION log_capture_backtrace
*
*   Capture backtrace context for storage and later display. Used by
*   chkheaps.c
*
* INPUT:
*    strP == ptr to a ptr to an array of printable strings describing the
*            backtrace represented by bt_arrayP. This memory MUST be
*            returned (via free()) by the caller.
*    bt_arrayP == ptr to a (pre-allocated) buffer of size sufficient
*                 to hold max_frames backtrace addresses (void * ptrs).
*    max_frames == max frames to dump, preallocated and described by bt_arrayP
*
* RETURNS:
*    none
*********************************************************************/
extern uint
    log_capture_backtrace (char ***strP, void *bt_arrayP, uint max_frames);


/********************************************************************
* FUNCTION log_backtrace
*
*    Output a string followed by backtrace detail, regardless of
*    backtrace setting.
*
* In general, use only for debugging ... should not be present in released
* software (though it might be useful for debugging in the field).
*
* INPUTS:
*   level == output level
*   fstr == format string for log message
*   ... == variable arg list for format string
*********************************************************************/
extern void
    log_backtrace (log_debug_t level, const char *fstr, ...)
    __attribute__ ((format (printf, 2, 3)));


/********************************************************************
* FUNCTION log_stderr_backtrace
*
*   Print up to (array[] size) stack frame addresses but output to STDERR.
*   This is useful for debugging within logger, e.g., when generating an
*   error internal to the logging subsystem. (See log_internal_err())
*
* INPUT:
*
*    max_detail == include maximum backtrace return information
*    preamble == prompt string to precede backtrace output
*
* RETURNS:
*    none
*********************************************************************/
void
     log_stderr_backtrace (boolean max_detail, const char *preamble);


extern void
    log_stdout (const char *fstr, ...)
    __attribute__ ((format (printf, 1, 2)));


extern void
    log_stdout_level (log_debug_t level, const char *fstr, ...)
    __attribute__ ((format (printf, 2, 3)));


extern void
    log_write (const char *fstr, ...)
    __attribute__ ((format (printf, 1, 2)));

extern void
    log_write_append (const char *fstr, ...)
    __attribute__ ((format (printf, 1, 2)));


extern void
    log_write_filtered (log_debug_t level, const char *fstr, ...)
    __attribute__ ((format (printf, 2, 3)));

extern void
    log_write_filtered_append (log_debug_t level, const char *fstr, ...)
    __attribute__ ((format (printf, 2, 3)));

extern void
    log_write_syslog_level (log_debug_t level, const char *fstr, ...)
    __attribute__ ((format (printf, 2, 3)));

extern void
    log_write_syslog_level_append (log_debug_t level, const char *fstr, ...)
    __attribute__ ((format (printf, 2, 3)));


extern void
    log_audit_write (const char *fstr, ...)
    __attribute__ ((format (printf, 1, 2)));


extern void
    log_audit_write_level (log_debug_t level, const char *fstr, ...)
    __attribute__ ((format (printf, 2, 3)));


/********************************************************************
* FUNCTION log_audit_indent
*
* Printf a newline to the audit logfile,
* then the specified number of space chars
*
* INPUTS:
*    indentcnt == number of indent chars, -1 == skip everything
*
*********************************************************************/
extern void
    log_audit_indent (int32 indentcnt);

extern void
    log_audit_indent_level (log_debug_t level, int32 indentcnt);


extern void
    log_alt_write (const char *fstr, ...)
    __attribute__ ((format (printf, 1, 2)));


extern void
    log_alt_write_level (log_debug_t level, const char *fstr, ...)
    __attribute__ ((format (printf, 2, 3)));



/********************************************************************
* FUNCTION log_alt_indent
*
* Printf a newline to the alternate logfile,
* then the specified number of space chars
*
* INPUTS:
*    indentcnt == number of indent chars, -1 == skip everything
*
*********************************************************************/
extern void
    log_alt_indent (int32 indentcnt);

extern void
    log_alt_indent_level (log_debug_t level, int32 indentcnt);


/********************************************************************
* FUNCTION vlog_error
*
*   Generate a LOG_DEBUG_ERROR log entry
*
* INPUTS:
*   fstr == format string in printf format
*   valist == any additional arguments for printf
*
*********************************************************************/
void
    vlog_error (const char *fstr, va_list args );


extern void
    log_error (const char *fstr, ...)
    __attribute__ ((format (printf, 1, 2)));


extern void
    log_error_append (const char *fstr, ...)
    __attribute__ ((format (printf, 1, 2)));


extern void
    log_warn (const char *fstr, ...)
    __attribute__ ((format (printf, 1, 2)));


extern void
    log_warn_append (const char *fstr, ...)
    __attribute__ ((format (printf, 1, 2)));


extern void
    log_info (const char *fstr, ...)
    __attribute__ ((format (printf, 1, 2)));


extern void
    log_info_append (const char *fstr, ...)
    __attribute__ ((format (printf, 1, 2)));


extern void
    log_debug (const char *fstr, ...)
    __attribute__ ((format (printf, 1, 2)));


extern void
    log_debug_append (const char *fstr, ...)
    __attribute__ ((format (printf, 1, 2)));


extern void
    log_debug2 (const char *fstr, ...)
    __attribute__ ((format (printf, 1, 2)));


extern void
    log_debug2_append (const char *fstr, ...)
    __attribute__ ((format (printf, 1, 2)));


extern void
    log_debug3 (const char *fstr, ...)
    __attribute__ ((format (printf, 1, 2)));


extern void
    log_debug3_append (const char *fstr, ...)
    __attribute__ ((format (printf, 1, 2)));


extern void
    log_debug4 (const char *fstr, ...)
    __attribute__ ((format (printf, 1, 2)));


extern void
    log_debug4_append (const char *fstr, ...)
    __attribute__ ((format (printf, 1, 2)));


/********************************************************************
* FUNCTIONs log_dev0 and log_dev0_append
*
*   Generate (append to) a LOG_DEBUG_DEV0 log entry
*
* NOTE: This level is intended primarily for debugging, where output related
*       issues at {ERROR, WARN, INFO} levels change program behavior)
*
* INPUTS:
*   fstr == format string in printf format
*   ... == any additional arguments for printf
*
*********************************************************************/
extern void
    log_dev0 (const char *fstr, ...)
    __attribute__ ((format (printf, 1, 2)));

extern void
    log_dev0_append (const char *fstr, ...)
    __attribute__ ((format (printf, 1, 2)));


/********************************************************************
* FUNCTIONs log_dev1 and log_dev1_append
*
*   Generate (append to) a LOG_DEBUG_DEV1 log entry
*
* NOTE: This level is intended primarily for debugging, where output related
*       issues at {DEBUG, DEBUG2, DEBUG3, DEBUG4} change program behavior)
*
* INPUTS:
*   fstr == format string in printf format
*   ... == any additional arguments for printf
*
*********************************************************************/
extern void
    log_dev1 (const char *fstr, ...)
    __attribute__ ((format (printf, 1, 2)));

extern void
    log_dev1_append (const char *fstr, ...)
    __attribute__ ((format (printf, 1, 2)));


/********************************************************************
* FUNCTIONs log_write_level and log_write_level_append
*
*   Generate (append to) a LOG_DEBUG_<LEVEL> log trace entry
*
* NOTE: Useful when the desired debug level is passed as a param
*
* INPUTS:
*   level == debug level
*   fstr == format string in printf format
*   ... == any additional arguments for printf
*
*********************************************************************/
extern void
    log_write_level (log_debug_t level, const char *fstr, ...)
    __attribute__ ((format (printf, 2, 3)));

extern void
    log_write_level_append (log_debug_t level, const char *fstr, ...)
    __attribute__ ((format (printf, 2, 3)));


/********************************************************************
*   FUNCTIONs log_xxx_thd and log_xxx_append_thd
*
*   Generate (or append to) a "thread" LOG_DEBUG_XXX level log entry
*
* INPUTS:
*   fstr == format string in printf format
*   ... == any additional arguments for printf
*
*********************************************************************/
#ifdef PTHREADS
extern void
    log_dev1_thd (const char *fstr, ...)
    __attribute__ ((format (printf, 1, 2)));

extern void
    log_dev1_append_thd (const char *fstr, ...)
    __attribute__ ((format (printf, 1, 2)));

extern void
    log_debug_thd (const char *fstr, ...)
    __attribute__ ((format (printf, 1, 2)));

extern void
    log_debug_append_thd (const char *fstr, ...)
    __attribute__ ((format (printf, 1, 2)));

extern void
    log_debug2_thd (const char *fstr, ...)
    __attribute__ ((format (printf, 1, 2)));

extern void
    log_debug2_append_thd (const char *fstr, ...)
    __attribute__ ((format (printf, 1, 2)));

extern void
    log_debug3_thd (const char *fstr, ...)
    __attribute__ ((format (printf, 1, 2)));

extern void
    log_debug3_append_thd (const char *fstr, ...)
    __attribute__ ((format (printf, 1, 2)));

extern void
    log_debug4_thd (const char *fstr, ...)
    __attribute__ ((format (printf, 1, 2)));

extern void
    log_debug4_append_thd (const char *fstr, ...)
    __attribute__ ((format (printf, 1, 2)));
#endif //#ifdef PTHREADS


/********************************************************************
* FUNCTION log_noop
*
*  Do not generate any log message NO-OP
*  Used to set logfn_t to no-loggging option
*
* INPUTS:
*   fstr == format string in printf format
*   ... == any additional arguments for printf
*
*********************************************************************/
extern void
    log_noop (const char *fstr, ...)
    __attribute__ ((format (printf, 1, 2)));


extern void log_set_log_level (log_debug_t dlevel);

extern void log_set_syslog_log_level (log_debug_t dlevel);


#ifdef PTHREADS

extern void log_set_pthread_log_level (log_debug_t dlevel);
#endif  // PTHREADS


/*
* FUNCTION log_get_system_log_level
*
* Get the global debug filter threshold level
*
* RETURNS:
*   the debug level
*********************************************************************/
extern log_debug_t log_get_system_log_level (void);


extern log_debug_t log_get_log_level (void);


extern log_debug_t log_get_syslog_log_level (void);


extern log_debug_t log_get_pthread_log_level (void);


/********************************************************************
* FUNCTION log_get_debug_level_enum
*
* Get the corresponding debug enum for the specified string
*
* INPUTS:
*   str == string value to convert
*
* RETURNS:
*   the corresponding enum for the specified debug level
*********************************************************************/
extern log_debug_t
    log_get_debug_level_enum (const char *str);

extern uint
    log_parse_debug_level_str (const char *str);


/********************************************************************
* FUNCTION log_get_debug_level_string
*
* Get the corresponding string for the debug enum
*
* INPUTS:
*   level ==  the enum for the specified debug level
*
* RETURNS:
*   the string value for this enum

*********************************************************************/
extern const xmlChar *
    log_get_debug_level_string (log_debug_t level);



/********************************************************************
* FUNCTION log_get_debug_level_value
*
* Get the corresponding YANG enum value for the debug enum
*
* INPUTS:
*   level ==  the enum for the specified debug level
*
* RETURNS:
*   the int32 value for this enum
*********************************************************************/
extern int32
    log_get_debug_level_value (log_debug_t level);


/********************************************************************
* FUNCTION log_get_debug_app_string
*
* Get the corresponding string for the debug app enum
*
* INPUTS:
*   app ==  the enum for the specified debug app
*
* RETURNS:
*   the string value for this enum

*********************************************************************/
extern const char *
    log_debug_get_app_string (log_debug_app_t app);

/********************************************************************
* FUNCTION log_debug_app2facility
*
* Translate from YumaPro app to syslog facility
*
* INPUTS:
*   app ==  the enum for the specified YUMA app
*
* RETURNS:
*   Appropriate syslog facility code
*
*********************************************************************/
extern int
    log_debug_app2facility (log_debug_app_t app);


/********************************************************************
* FUNCTION log_set_debug_app
*
*    Set syslog application level ... for example, yangcli will set
*    USER while netconfd will set DAEMON for use by syslog.
*
* INPUTS:
*    app ==  the enum for the specified YUMA app
*
* RETURNS:
*    None
*
*********************************************************************/
extern void
    log_set_debug_app (log_debug_app_t app);


/********************************************************************
* FUNCTION log_get_debug_app
*
*    Return syslog application level.
*
* INPUTS:
*    None
*
* RETURNS:
*    enum for the current YUMA app
*
*********************************************************************/
extern log_debug_app_t
    log_get_debug_app (void);


/********************************************************************
* FUNCTION log_debug_app_string
*
*    Return syslog application level string equivalent
*
* INPUTS:
*    None
*
* RETURNS:
*    String equivalent for the current YUMA app type
*
*********************************************************************/
extern const char *
    log_debug_app_string (void);

/********************************************************************
* FUNCTION log_is_open
*
* Check if the logfile is active
*
* RETURNS:
*   TRUE if logfile open, FALSE otherwise
*********************************************************************/
extern boolean
    log_is_open (void);


/********************************************************************
* FUNCTION log_indent
*
* Printf a newline, then the specified number of chars
*
* INPUTS:
*    indentcnt == number of indent chars, -1 == skip everything
*
*********************************************************************/
extern void
    log_indent (int32 indentcnt);
extern void
    log_indent_append (int32 indentcnt);
extern void
    log_indent_level_append (log_debug_t level, int32 indentcnt);


/********************************************************************
* FUNCTION log_stdout_indent
*
* Printf a newline to stdout, then the specified number of chars
*
* INPUTS:
*    indentcnt == number of indent chars, -1 == skip everything
*
*********************************************************************/
extern void
    log_stdout_indent (int32 indentcnt);

extern void
    log_stdout_level_indent (log_debug_t level, int32 indentcnt);


/********************************************************************
* FUNCTION log_get_logfile
*
* Get the open logfile for direct output
* Needed by libtecla to write command line history
*
* RETURNS:
*   pointer to open FILE if any
*   NULL if no open logfile
*********************************************************************/
extern FILE *
    log_get_logfile (void);


/********************************************************************
* FUNCTION log_start_capture
*
*   Open a capture logfile for writing
*
* INPUTS:
*   fname == full filespec string for capfile
*
* RETURNS:
*    status
*********************************************************************/
extern status_t
    log_start_capture (const char *fname);


/********************************************************************
* FUNCTION log_end_capture
*
*   Close a capture logfile after writing
*
*********************************************************************/
extern void
    log_end_capture (void);


/********************************************************************
* FUNCTION log_trigger_rotate
*
*  Trigger the logrotate procedure
*
* RETURNS:
*    none
*********************************************************************/
extern void
    log_trigger_rotate (void);

/********************************************************************
* FUNCTION log_rotate_requested
*
*  Check if logrotate procedure is in progress
*
* RETURNS:
*    TRUE if logrotate procedure has been started
*
*********************************************************************/
extern boolean
    log_rotate_requested (void);

   // END ncxlib/log/logfns



#ifdef __cplusplus
}  /* end extern 'C' */
#endif

#endif      /* _H_log */