log.h

/******************************************************************************
 * Copyright 2022 ETC Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 * 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.
 *******************************************************************************
 * This file is a part of EtcPal. For more information, go to:
 * https://github.com/ETCLabs/EtcPal
 ******************************************************************************/
 
/* etcpal/log.h: Common logging functions. */
 
#ifndef ETCPAL_LOG_H_
#define ETCPAL_LOG_H_
 
#include <limits.h>
#include <stdarg.h>
#include <stdbool.h>
#include <stddef.h>
#include "etcpal/common.h"
 
/* clang-format off */
 
#define ETCPAL_LOG_KERN (0 << 3)      
#define ETCPAL_LOG_USER (1 << 3)      
#define ETCPAL_LOG_MAIL (2 << 3)      
#define ETCPAL_LOG_DAEMON (3 << 3)    
#define ETCPAL_LOG_AUTH (4 << 3)      
#define ETCPAL_LOG_SYSLOG (5 << 3)    
#define ETCPAL_LOG_LPR (6 << 3)       
#define ETCPAL_LOG_NEWS (7 << 3)      
#define ETCPAL_LOG_UUCP (8 << 3)      
#define ETCPAL_LOG_CRON (9 << 3)      
#define ETCPAL_LOG_AUTHPRIV (10 << 3) 
#define ETCPAL_LOG_FTP (11 << 3)      
#define ETCPAL_LOG_LOCAL0 (16 << 3) 
#define ETCPAL_LOG_LOCAL1 (17 << 3) 
#define ETCPAL_LOG_LOCAL2 (18 << 3) 
#define ETCPAL_LOG_LOCAL3 (19 << 3) 
#define ETCPAL_LOG_LOCAL4 (20 << 3) 
#define ETCPAL_LOG_LOCAL5 (21 << 3) 
#define ETCPAL_LOG_LOCAL6 (22 << 3) 
#define ETCPAL_LOG_LOCAL7 (23 << 3) 
#define ETCPAL_LOG_NFACILITIES 24 
#define ETCPAL_LOG_FACMASK 0x03f8 /* Mask off the facility part of a prival */
#define ETCPAL_LOG_FAC(p) (((p) & ETCPAL_LOG_FACMASK) >> 3) 
#define ETCPAL_LOG_EMERG 0   
#define ETCPAL_LOG_ALERT 1   
#define ETCPAL_LOG_CRIT 2    
#define ETCPAL_LOG_ERR 3     
#define ETCPAL_LOG_WARNING 4 
#define ETCPAL_LOG_NOTICE 5  
#define ETCPAL_LOG_INFO 6    
#define ETCPAL_LOG_DEBUG 7   
#define ETCPAL_LOG_PRIMASK 0x07 /* mask off the priority part of a prival */
#define ETCPAL_LOG_PRI(p) ((p) & ETCPAL_LOG_PRIMASK) 
#define ETCPAL_LOG_MAKEPRI(fac, pri) (((fac) << 3) | (pri)) 
#define ETCPAL_LOG_MASK(pri) (1 << (pri)) 
#define ETCPAL_LOG_UPTO(pri) ((1 << ((pri) + 1)) - 1) 
#define ETCPAL_LOG_HOSTNAME_MAX_LEN 256u 
#define ETCPAL_LOG_APP_NAME_MAX_LEN 49u  
#define ETCPAL_LOG_PROCID_MAX_LEN 129u   
#define ETCPAL_RAW_LOG_MSG_MAX_LEN 480u
 
/* clang-format on */
 
/*
 * Timestamp length:
 * Date:       10 (1970-01-01)
 * "T" or " ":  1
 * Time:       12 (00:00:00.001)
 * UTC Offset:  6 (-05:00)
 * Nullterm:    1
 * --------------
 * Total:      30
 */
#define ETCPAL_LOG_TIMESTAMP_LEN 30u
 
/*
 * Syslog header length (from RFC 5424):
 * PRIVAL:                     5
 * VERSION:                    3
 * SP:                         1
 * TIMESTAMP:       [Referenced]
 * SP:                         1
 * HOSTNAME:        [Referenced]
 * SP:                         1
 * APP-NAME:        [Referenced]
 * SP:                         1
 * PROCID:          [Referenced]
 * SP:                         1
 * MSGID (not used):           1
 * SP:                         1
 * STRUCTURED-DATA (not used): 1
 * SP:                         1
 * -----------------------------
 * Total non-referenced:      17
 */
#define ETCPAL_SYSLOG_HEADER_MAX_LEN                                                                                 \
  (17u + (ETCPAL_LOG_TIMESTAMP_LEN - 1u) + (ETCPAL_LOG_HOSTNAME_MAX_LEN - 1u) + (ETCPAL_LOG_APP_NAME_MAX_LEN - 1u) + \
   (ETCPAL_LOG_PROCID_MAX_LEN - 1u))
 
#define ETCPAL_SYSLOG_STR_MIN_LEN ETCPAL_SYSLOG_HEADER_MAX_LEN
#define ETCPAL_LOG_STR_MIN_LEN (ETCPAL_LOG_TIMESTAMP_LEN + 1u /*SP*/ + 6u /*pri*/ + 1u /*SP*/)
 
#define ETCPAL_SYSLOG_STR_MAX_LEN (ETCPAL_SYSLOG_HEADER_MAX_LEN + ETCPAL_RAW_LOG_MSG_MAX_LEN)
 
/*
 * Human-reaadable log string max length:
 * Timestamp:      [Referenced]
 * Space:                     1
 * Priority:                  6 ([CRIT])
 * Space:                     1
 * Message length: [Referenced]
 * ----------------------------
 * Total non-referenced:      8
 */
#define ETCPAL_LOG_STR_MAX_LEN (8u + (ETCPAL_LOG_TIMESTAMP_LEN - 1u) + ETCPAL_RAW_LOG_MSG_MAX_LEN)
 
typedef struct EtcPalLogTimestamp
{
  unsigned int year;       
  unsigned int month;      
  unsigned int day;        
  unsigned int hour;       
  unsigned int minute;     
  unsigned int second;     
  unsigned int msec;       
  int          utc_offset; 
} EtcPalLogTimestamp;
 
typedef struct EtcPalLogStrings
{
  const char* syslog;
  const char* legacy_syslog;
  const char* human_readable;
  const char* raw;
  int priority;
} EtcPalLogStrings;
 
typedef void (*EtcPalLogCallback)(void* context, const EtcPalLogStrings* strings);
 
typedef void (*EtcPalLogTimeFn)(void* context, EtcPalLogTimestamp* timestamp);
 
#define ETCPAL_LOG_CREATE_HUMAN_READABLE 0x01
#define ETCPAL_LOG_CREATE_SYSLOG 0x02
#define ETCPAL_LOG_CREATE_LEGACY_SYSLOG 0x04
 
typedef struct EtcPalSyslogParams
{
  int facility;
  char hostname[ETCPAL_LOG_HOSTNAME_MAX_LEN];  // NOLINT(modernize-avoid-c-arrays,cppcoreguidelines-avoid-c-arrays)
  char app_name[ETCPAL_LOG_APP_NAME_MAX_LEN];  // NOLINT(modernize-avoid-c-arrays,cppcoreguidelines-avoid-c-arrays)
  char procid[ETCPAL_LOG_PROCID_MAX_LEN];  // NOLINT(modernize-avoid-c-arrays,cppcoreguidelines-avoid-c-arrays)
} EtcPalSyslogParams;
 
#define ETCPAL_SYSLOG_PARAMS_INIT \
  {                               \
    0, {'\0'}, {'\0'}, { '\0' }   \
  }
 
typedef struct EtcPalLogParams
{
  int action;
  EtcPalLogCallback log_fn;
  EtcPalSyslogParams syslog_params;
  int log_mask;
  EtcPalLogTimeFn time_fn;
  void* context;
} EtcPalLogParams;
 
#define ETCPAL_LOG_PARAMS_INIT                        \
  {                                                   \
    0, NULL, ETCPAL_SYSLOG_PARAMS_INIT, 0, NULL, NULL \
  }
 
#ifdef __cplusplus
extern "C" {
#endif
 
etcpal_error_t etcpal_init_log_handler(const EtcPalLogParams* log_params);
 
/*
 * The various compiler ifdefs are to use each compiler's method of checking printf-style
 * arguments.
 */
 
#ifdef __ICCARM__
#pragma __printf_args
#endif
bool etcpal_create_log_str(char*                     buf,
                           size_t                    buflen,
                           const EtcPalLogTimestamp* timestamp,
                           int                       pri,
                           const char*               format,
                           ...)
#ifdef __GNUC__
    __attribute__((__format__(__printf__, 5, 6)))
#endif
    ;
 
bool etcpal_vcreate_log_str(char*                     buf,
                            size_t                    buflen,
                            const EtcPalLogTimestamp* timestamp,
                            int                       pri,
                            const char*               format,
                            va_list                   args);
 
#ifdef __ICCARM__
#pragma __printf_args
#endif
bool etcpal_create_syslog_str(char*                     buf,
                              size_t                    buflen,
                              const EtcPalLogTimestamp* timestamp,
                              const EtcPalSyslogParams* syslog_params,
                              int                       pri,
                              const char*               format,
                              ...)
#ifdef __GNUC__
    __attribute__((__format__(__printf__, 6, 7)))
#endif
    ;
 
bool etcpal_vcreate_syslog_str(char*                     buf,
                               size_t                    buflen,
                               const EtcPalLogTimestamp* timestamp,
                               const EtcPalSyslogParams* syslog_params,
                               int                       pri,
                               const char*               format,
                               va_list                   args);
 
#ifdef __ICCARM__
#pragma __printf_args
#endif
bool etcpal_create_legacy_syslog_str(char*                     buf,
                                     size_t                    buflen,
                                     const EtcPalLogTimestamp* timestamp,
                                     const EtcPalSyslogParams* syslog_params,
                                     int                       pri,
                                     const char*               format,
                                     ...)
#ifdef __GNUC__
    __attribute__((__format__(__printf__, 6, 7)))
#endif
    ;
 
bool etcpal_vcreate_legacy_syslog_str(char*                     buf,
                                      size_t                    buflen,
                                      const EtcPalLogTimestamp* timestamp,
                                      const EtcPalSyslogParams* syslog_params,
                                      int                       pri,
                                      const char*               format,
                                      va_list                   args);
 
void etcpal_sanitize_syslog_params(EtcPalSyslogParams* params);
bool etcpal_validate_log_params(EtcPalLogParams* params);
bool etcpal_validate_log_timestamp(const EtcPalLogTimestamp* timestamp);
 
bool etcpal_can_log(const EtcPalLogParams* params, int pri);
 
#ifdef __ICCARM__
#pragma __printf_args
#endif
void etcpal_log(const EtcPalLogParams* params, int pri, const char* format, ...)
#ifdef __GNUC__
    __attribute__((__format__(__printf__, 3, 4)))
#endif
    ;
 
void etcpal_vlog(const EtcPalLogParams* params, int pri, const char* format, va_list args);
 
#ifdef __cplusplus
}
#endif
 
#endif /* ETCPAL_LOG_H_ */