#include "../misc/ErrObj.h"
#include <errno.h>
#include <pthread.h>
#include <stdarg.h>
#include <stdbool.h>
#include <stdlib.h>
#include <syslog.h>
#include "log_private.h"

Macros
#define	LOG_LOCALTIME 0x100u
	Use local time. Default is UTC. More...

#define	LOG_NOTIME 0x200u
	Don't add a timestamp.

#define	LOG_IDENT 0x400u
	Add the facility identifier.

#define	log_fini()

#define	log_free()

#define	log_is_enabled_warning log_is_level_enabled(LOG_LEVEL_WARNING)

#define	log_is_enabled_notice log_is_level_enabled(LOG_LEVEL_NOTICE)

#define	log_is_enabled_info log_is_level_enabled(LOG_LEVEL_INFO)

#define	log_is_enabled_debug log_is_level_enabled(LOG_LEVEL_DEBUG)

#define	log_debug(...)

#define	log_info(...)

#define	log_notice(...)

#define	log_warning(...)

#define	log_error(...)

#define	log_fatal(...)

#define	log_syserr(...) log_errno(errno, __VA_ARGS__)

#define	log_add_syserr(...) log_add_errno(errno, __VA_ARGS__)

#define	log_error_q(...) LOG_LOG(LOG_LEVEL_ERROR, __VA_ARGS__)

#define	log_warning_q(...) LOG_LOG(LOG_LEVEL_WARNING, __VA_ARGS__)

#define	log_notice_q(...) LOG_LOG(LOG_LEVEL_NOTICE, __VA_ARGS__)

#define	log_info_q(...) LOG_LOG(LOG_LEVEL_INFO, __VA_ARGS__)

#define	log_debug_q(...)

#define	log_log_q(level, ...) LOG_LOG(level, __VA_ARGS__)

#define	log_flush_fatal() log_flush(LOG_LEVEL_FATAL)

#define	log_flush_error() log_flush(LOG_LEVEL_ERROR)

#define	log_flush_warning() log_flush(LOG_LEVEL_WARNING)

#define	log_flush_notice() log_flush(LOG_LEVEL_NOTICE)

#define	log_flush_info() log_flush(LOG_LEVEL_INFO)

#define	log_flush_debug() log_flush(LOG_LEVEL_DEBUG)

#define	log_realloc(buf, nbytes, msg)

#define	log_abort(...)

#define	log_assert(expr)

Enumerations
enum	log_level_t { LOG_LEVEL_DEBUG = 0 , LOG_LEVEL_INFO , LOG_LEVEL_NOTICE , LOG_LEVEL_WARNING , LOG_LEVEL_ERROR , LOG_LEVEL_FATAL , LOG_LEVEL_COUNT }
	Logging levels. More...

Functions
const char *	log_get_default_daemon_destination (void)

const char *	log_get_default_destination (void)

bool	log_stderr_is_open (void)

bool	log_amDaemon (void)

int	log_init (const char *const id)

void	log_avoid_stderr (void)

void	log_refresh (void)

int	log_set_level (const log_level_t level)

log_level_t	log_get_level (void)

void	log_roll_level (void)

int	log_set_id (const char *const id)

int	log_set_upstream_id (const char *const hostId, const bool isFeeder)

const char *	log_get_id (void)

int	log_set_options (const unsigned options)

unsigned	log_get_options (void)

int	log_set_facility (const int facility)

int	log_get_facility (void)

int	log_set_destination (const char *const dest)

const char *	log_get_destination (void)

void	log_clear (void)

int	log_dispose (const log_level_t level, ErrObj *errObj)

int	log_flush (const log_level_t level)

Detailed Description

Author: Steven R. Emmerson

This file defines the API for LDM logging.

Macro Definition Documentation

◆ log_abort

#define log_abort ( ... )

Value:

    do { \
    log_add(__VA_ARGS__); \
    log_flush(LOG_LEVEL_ERROR); \
    abort(); \
} while (false)

Logs an error message and then aborts the current process.

Parameters

[in] ... Optional arguments of the message – starting with the format of the message.

◆ log_add_syserr

#define log_add_syserr ( ... ) log_add_errno(errno, __VA_ARGS__)

Adds a message based on the system error code (i.e., errno) to the current thread's queue of error messages:

Parameters

[in] ... Optional arguments of the message.

◆ log_assert

#define log_assert ( expr )

Value:

        do { \
        int prevState; \
        (void)pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, &prevState); \
        if (!(expr)) \
            log_abort("Assertion failure: %s", #expr); \
        (void)pthread_setcancelstate(prevState, &prevState); \
    } while (false)

Tests an assertion. Logs an error-message and then aborts the process if the assertion is false.

This is not a thread cancellation point.

Parameters

[in] expr The assertion to be tested.

◆ log_debug

#define log_debug ( ... )

Value:

    do {\
    if (LOG_LEVEL_DEBUG >= log_level) {\
        LOG_LOC_DECL(loc);\
        logl_log(&loc, LOG_LEVEL_DEBUG, __VA_ARGS__);\
    }\
} while (0)

Logs a single message at the DEBUG level, bypassing the message-queue.

Parameters

[in] ... Optional arguments of the message – starting with the format of the message.

Async-signal Safety:: Unsafe

◆ log_debug_q

#define log_debug_q ( ... )

Value:

    do {\
    LOG_LOC_DECL(loc);\
    logl_log_q(&loc, LOG_LEVEL_DEBUG, __VA_ARGS__);\
} while (0)

Adds a message to the current thread's queue of messages, logs the queue at the DEBUG level, and then clears the queue.

Parameters

[in] ... Optional arguments of the message – starting with the format of the message.

◆ log_error

#define log_error ( ... )

Value:

    do {\
    if (LOG_LEVEL_ERROR >= log_level) {\
        LOG_LOC_DECL(loc);\
        logl_log(&loc, LOG_LEVEL_ERROR, __VA_ARGS__);\
    }\
} while (0)

Logs a single message at the ERROR level, bypassing the message-queue.

Parameters

[in] ... Optional arguments of the message – starting with the format of the message.

Async-signal Safety:: Unsafe

◆ log_error_q

#define log_error_q ( ... ) LOG_LOG(LOG_LEVEL_ERROR, __VA_ARGS__)

The following macros add a message to the current thread's queue of messages, log the queue, and then clear the queue:

The argument-list of the variadic macros must comprise at least a NULL argument in order to avoid a syntax error. Adds a message to the current thread's queue of messages, logs the queue at the ERROR level, and then clears the queue.

Parameters

[in] ... Optional arguments of the message – starting with the format of the message.

◆ log_fatal

#define log_fatal ( ... )

Value:

    do {\
    if (LOG_LEVEL_FATAL >= log_level) {\
        LOG_LOC_DECL(loc);\
        logl_log(&loc, LOG_LEVEL_FATAL, __VA_ARGS__);\
    }\
} while (0)

Logs a single message at the FATAL level, bypassing the message-queue.

Parameters

[in] ... Optional arguments of the message – starting with the format of the message.

Async-signal Safety:: Unsafe

◆ log_fini

#define log_fini ( )

Value:

    do {\
    LOG_LOC_DECL(loc);\
    (void)log_fini_located(&loc);\
} while (false)

Finalizes the logging module. Should be called eventually after log_init(), after which no more logging should occur.

◆ log_flush_debug

#define log_flush_debug ( ) log_flush(LOG_LEVEL_DEBUG)

Logs the message-queue of the current thread at the DEBUG level and then clears the queue.

◆ log_flush_error

#define log_flush_error ( ) log_flush(LOG_LEVEL_ERROR)

Logs the message-queue of the current thread at the ERROR level and then clears the queue.

◆ log_flush_fatal

#define log_flush_fatal ( ) log_flush(LOG_LEVEL_FATAL)

Logs the message-queue of the current thread at the FATAL level and then clears the queue.

◆ log_flush_info

#define log_flush_info ( ) log_flush(LOG_LEVEL_INFO)

Logs the message-queue of the current thread at the INFO level and then clears the queue.

◆ log_flush_notice

#define log_flush_notice ( ) log_flush(LOG_LEVEL_NOTICE)

Logs the message-queue of the current thread at the NOTICE level and then clears the queue.

◆ log_flush_warning

#define log_flush_warning ( ) log_flush(LOG_LEVEL_WARNING)

Logs the message-queue of the current thread at the WARNING level and then clears the queue.

◆ log_free

#define log_free ( )

Value:

    do {\
    int prevState; \
    (void)pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, &prevState); \
    LOG_LOC_DECL(loc);\
    log_free_located(&loc);\
    (void)pthread_setcancelstate(prevState, &prevState); \
} while (false)

DEPRECATED. No longer necessary.

Frees the log-message resources of the current thread. Should only be called when no more logging by the current thread will occur.

This is not a thread-cancellation point.

◆ log_info

#define log_info ( ... )

Value:

    do {\
    if (LOG_LEVEL_INFO >= log_level) {\
        LOG_LOC_DECL(loc);\
        logl_log(&loc, LOG_LEVEL_INFO, __VA_ARGS__);\
    }\
} while (0)

Logs a single message at the INFO level, bypassing the message-queue.

Parameters

[in] ... Optional arguments of the message – starting with the format of the message.

Async-signal Safety:: Unsafe

◆ log_info_q

#define log_info_q ( ... ) LOG_LOG(LOG_LEVEL_INFO, __VA_ARGS__)

Adds a message to the current thread's queue of messages, logs the queue at the INFO level, and then clears the queue.

Parameters

[in] ... Optional arguments of the message – starting with the format of the message.

◆ log_is_enabled_debug

#define log_is_enabled_debug log_is_level_enabled(LOG_LEVEL_DEBUG)

Indicates if a log message of DEBUG level will be written. Useful if a format argument of a message is expensive to evaluate.

◆ log_is_enabled_info

#define log_is_enabled_info log_is_level_enabled(LOG_LEVEL_INFO)

Indicates if a log message of INFO level will be written. Useful if a format argument of a message is expensive to evaluate.

◆ log_is_enabled_notice

#define log_is_enabled_notice log_is_level_enabled(LOG_LEVEL_NOTICE)

Indicates if a log message of NOTICE level will be written. Useful if a format argument of a message is expensive to evaluate.

◆ log_is_enabled_warning

#define log_is_enabled_warning log_is_level_enabled(LOG_LEVEL_WARNING)

Indicates if a log message of WARNING level will be written. Useful if a format argument of a message is expensive to evaluate.

◆ LOG_LOCALTIME

#define LOG_LOCALTIME 0x100u

Use local time. Default is UTC.

Macros for the ulog backend reproduced here with the "LOG_" prefix:

◆ log_log_q

#define log_log_q	(	level,
		...
	)	LOG_LOG(level, __VA_ARGS__)

Adds a message to the current thread's queue of messages, logs the queue at the given level, and then clears the queue.

Parameters

[in]	level	`log_level_t` logging level.
[in]	...	Optional arguments of the message – starting with the format of the message.

◆ log_notice

#define log_notice ( ... )

Value:

    do {\
    if (LOG_LEVEL_NOTICE >= log_level) {\
        LOG_LOC_DECL(loc);\
        logl_log(&loc, LOG_LEVEL_NOTICE, __VA_ARGS__);\
    }\
} while (0)

Logs a single message at the NOTICE level, bypassing the message-queue.

Parameters

[in] ... Optional arguments of the message – starting with the format of the message.

Async-signal Safety:: Unsafe

◆ log_notice_q

#define log_notice_q ( ... ) LOG_LOG(LOG_LEVEL_NOTICE, __VA_ARGS__)

Adds a message to the current thread's queue of messages, logs the queue at the NOTICE level, and then clears the queue.

Parameters

[in] ... Optional arguments of the message – starting with the format of the message.

◆ log_realloc

#define log_realloc	(	buf,
		nbytes,
		msg
	)

Value:

logl_realloc(__FILE__, __func__, __LINE__, \

buf, nbytes, msg)

Re-allocates memory. Adds an message the current thread's queue of messages if an error occurs.

Parameters

[in]	buf	Previously-allocated buffer
[in]	nbytes	Number of bytes to allocate.
[in]	msg	Message to print on error. Should complete the sentence "Couldn't allocate <n> bytes for ...".

Return values

NULL	Out of memory. Log message added.

Returns: Pointer to the allocated memory.

◆ log_syserr

#define log_syserr ( ... ) log_errno(errno, __VA_ARGS__)

Logs a single message at the ERROR level based on errno, bypassing the message queue.

Parameters

[in] ... Optional arguments of the message.

Async-signal Safety:: Unsafe

◆ log_warning

#define log_warning ( ... )

Value:

    do {\
    if (LOG_LEVEL_WARNING >= log_level) {\
        LOG_LOC_DECL(loc);\
        logl_log(&loc, LOG_LEVEL_WARNING, __VA_ARGS__);\
    }\
} while (0)

Logs a single message at the WARNING level, bypassing the message-queue.

Parameters

[in] ... Optional arguments of the message – starting with the format of the message.

Async-signal Safety:: Unsafe

◆ log_warning_q

#define log_warning_q ( ... ) LOG_LOG(LOG_LEVEL_WARNING, __VA_ARGS__)

Adds a message to the current thread's queue of messages, logs the queue at the WARNING level, and then clears the queue.

Parameters

[in] ... Optional arguments of the message – starting with the format of the message.

Enumeration Type Documentation

◆ log_level_t

enum log_level_t

Logging levels.

Enumerator
LOG_LEVEL_DEBUG	Debug messages.
LOG_LEVEL_INFO	Informational messages.
LOG_LEVEL_NOTICE	Notices.
LOG_LEVEL_WARNING	Warnings.
LOG_LEVEL_ERROR	Error messages.
LOG_LEVEL_FATAL	Fatal messages.
LOG_LEVEL_COUNT	Number of levels.

Function Documentation

◆ log_amDaemon()

bool log_amDaemon ( void )

Indicates if the current process is a daemon (i.e., has no controlling terminal).

Return values

<tt>true</tt>	Current process is a daemon
<tt>false</tt>	Current process is not a daemon

◆ log_avoid_stderr()

void log_avoid_stderr ( void )

Tells this module to avoid using the standard error stream (because the process has become a daemon, for example).

Thread Safety:: Safe

Async-signal Safety:: Safe

◆ log_clear()

void log_clear ( void )

Clears the message-queue of the current thread.

Thread Safety:: Safe

Async-signal Safety:: Unsafe

◆ log_flush()

int log_flush ( const log_level_t level )

Logs the currently-accumulated log-messages of the current thread and resets the message-queue for the current thread.

This is not a thread-cancellation point.

Parameters

[in] level The level at which to log the messages. One of LOG_LEVEL_ERROR, LOG_LEVEL_WARNING, LOG_LEVEL_NOTICE, LOG_LEVEL_INFO, or LOG_LEVEL_DEBUG; otherwise, the behavior is undefined.

Return values

0	Success
-1	Failure

◆ log_get_default_daemon_destination()

const char* log_get_default_daemon_destination ( void )

Returns the default destination for log messages if the process is a daemon (i.e., doesn't have a controlling terminal).

Return values

""	The system logging daemon

Returns: The pathname of the standard LDM log file

Thread Safety:: Safe

Async-signal Safety:: Unsafe

◆ log_get_default_destination()

const char* log_get_default_destination ( void )

Returns the default destination for log messages, which depends on whether or not log_avoid_stderr() has been called. If it hasn't been called, then the default destination will be the standard error stream; otherwise, the default destination will be that given by log_get_default_daemon_destination().

Return values

""	The system logging daemon
-	The standard error stream

Returns: The pathname of the log file

Thread Safety:: Safe

Async-signal Safety:: Unsafe

◆ log_get_destination()

const char* log_get_destination ( void )

Returns the logging destination. Should be called between log_init() and log_fini().

Returns

The logging destination. One of

"": The system logging daemon.
"-": The standard error stream.
else: The pathname of the log file.

Thread Safety:: Safe

Async-signal Safety:: Unsafe

◆ log_get_facility()

int log_get_facility ( void )

Returns the facility that will be used (e.g., LOG_LOCAL0) when logging to the system logging daemon. Should be called between log_init() and log_fini().

Returns: The logging facility

Thread Safety:: Safe

Async-signal Safety:: Unsafe

◆ log_get_id()

const char* log_get_id ( void )

Returns the logging identifier. Should be called between log_init() and log_fini().

Returns: The logging identifier.

Thread Safety:: Safe

Async-signal Safety:: Unsafe

◆ log_get_level()

log_level_t log_get_level ( void )

Returns the current logging level. Should be called between log_init() and log_fini().

Returns: The lowest level through which logging will occur. The levels are ordered: LOG_LEVEL_ERROR > LOG_LEVEL_WARNING > LOG_LEVEL_NOTICE > LOG_LEVEL_INFO > LOG_LEVEL_DEBUG.

Thread Safety:: Safe

Async-signal Safety:: Unsafe

◆ log_get_options()

unsigned log_get_options ( void )

Returns the implementation-defined logging options. Should be called between log_init() and log_fini().

Returns: The logging options. Bitwise or of LOG_PID Log the pid with each message (default) LOG_CONS Log on the console if errors in sending LOG_ODELAY Delay open until first syslog() LOG_NDELAY Don't delay open (default) LOG_NOWAIT Don't wait for console forks: DEPRECATED LOG_PERROR Log to stderr as well

Thread Safety:: Safe

Async-signal Safety:: Unsafe

◆ log_init()

int log_init ( const char *const id )

Initializes the logging module. Should be called before most other functions.

log_get_facility(): will return LOG_LDM.
log_get_level(): will return LOG_LEVEL_NOTICE.

Parameters

[in] id The pathname of the program (e.g., argv[0]). Caller may free.

Return values

0	Success.
-1	Error.

Thread Safety:: Safe

Async-signal Safety:: Unsafe

◆ log_refresh()

void log_refresh ( void )

Refreshes the logging module. If logging is to the system logging daemon, then it will continue to be. If logging is to a file, then the file will be closed and re-opened when the next message is logged; thus enabling log file rotation. If logging is to the standard error stream, then it will continue to be if log_avoid_stderr() hasn't been called; otherwise, logging will be to the provider default.

Thread Safety:: Safe

Async-signal Safety:: Safe

◆ log_roll_level()

void log_roll_level ( void )

Lowers the logging threshold by one. Wraps at the bottom. Should be called between log_init() and log_fini().

Thread Safety:: Safe

Async-signal Safety:: Safe

◆ log_set_destination()

int log_set_destination ( const char *const dest )

Sets the logging destination. Should be called between log_init() and log_fini().

Parameters

[in]

dest

The logging destination. Caller may free. One of

"": The system logging daemon.
"-": The standard error stream.
else: The file whose pathname is dest.

Return values

0	Success.
-1	Failure.

Thread Safety:: Safe

Async-signal Safety:: Unsafe

◆ log_set_facility()

int log_set_facility ( const int facility )

Sets the facility that might be used (e.g., LOG_LOCAL0) when logging to the system logging daemon. Should be called between log_init() and log_fini(). May do nothing.

Parameters

[in] facility The facility that will be used when logging to the system logging daemon.

Return values

0	Success.
-1	Error.

Thread Safety:: Unsafe

Async-signal Safety:: Unsafe

◆ log_set_id()

int log_set_id ( const char *const id )

Sets the logging identifier. Should be called between log_init() and log_fini().

Parameters

[in] id The new identifier. Caller may free.

Return values

0	Success.
-1	Failure.

Thread Safety:: Safe

Async-signal Safety:: Unsafe

◆ log_set_level()

int log_set_level ( const log_level_t level )

Enables logging down to a given level. Should be called between log_init() and log_fini().

Parameters

[in] level The lowest level through which logging should occur. The levels are ordered: LOG_LEVEL_DEBUG < LOG_LEVEL_INFO < LOG_LEVEL_NOTICE < LOG_LEVEL_WARNING < LOG_LEVEL_ERROR.

Return values

0	Success.
-1	Failure.

Thread Safety:: Safe

Async-signal Safety:: Unsafe

◆ log_set_options()

int log_set_options ( const unsigned options )

Sets the implementation-defined logging options. Should be called between log_init() and log_fini().

Parameters

[in] options The logging options. Bitwise or of LOG_PID Log the pid with each message (default) LOG_CONS Log on the console if errors in sending LOG_ODELAY Delay open until first syslog() LOG_NDELAY Don't delay open (default) LOG_NOWAIT Don't wait for console forks: DEPRECATED LOG_PERROR Log to stderr as well

Return values

0	Success
-1	Failure

Thread Safety:: Safe

Async-signal Safety:: Unsafe

◆ log_set_upstream_id()

int log_set_upstream_id	(	const char *const	hostId,
		const bool	isFeeder
	)

Modifies the logging identifier. Should be called between log_init() and log_fini().

Parameters

[in]	hostId	The identifier of the remote host. Caller may free.
[in]	isFeeder	Whether or not the process is sending data-products or just notifications.

Return values

0 Success.

Thread Safety:: Safe

Async-signal Safety:: Unsafe

◆ log_stderr_is_open()

bool log_stderr_is_open ( void )

Indicates if the standard error file descriptor is open. This function may be called at any time.

Return values

true	Standard error file descriptor is open
false	Standard error file descriptor is closed

Thread Safety:: Safe

Async-signal Safety:: Safe

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ log_abort

◆ log_add_syserr

◆ log_assert

◆ log_debug

◆ log_debug_q

◆ log_error

◆ log_error_q

◆ log_fatal

◆ log_fini

◆ log_flush_debug

◆ log_flush_error

◆ log_flush_fatal

◆ log_flush_info

◆ log_flush_notice

◆ log_flush_warning

◆ log_free

◆ log_info

◆ log_info_q

◆ log_is_enabled_debug

◆ log_is_enabled_info

◆ log_is_enabled_notice

◆ log_is_enabled_warning

◆ LOG_LOCALTIME

◆ log_log_q

◆ log_notice

◆ log_notice_q

◆ log_realloc

◆ log_syserr

◆ log_warning

◆ log_warning_q

Enumeration Type Documentation

◆ log_level_t

Function Documentation

◆ log_amDaemon()

◆ log_avoid_stderr()

◆ log_clear()

◆ log_flush()

◆ log_get_default_daemon_destination()

◆ log_get_default_destination()

◆ log_get_destination()

◆ log_get_facility()

◆ log_get_id()

◆ log_get_level()

◆ log_get_options()

◆ log_init()

◆ log_refresh()

◆ log_roll_level()

◆ log_set_destination()

◆ log_set_facility()

◆ log_set_id()

◆ log_set_level()

◆ log_set_options()

◆ log_set_upstream_id()

◆ log_stderr_is_open()