[mirror_frr.git] / lib / zlog.h

/*
 * Copyright (c) 2015-19  David Lamparter, for NetDEF, Inc.
 *
 * Permission to use, copy, modify, and distribute this software for any
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
 *
 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 */

#ifndef _FRR_ZLOG_H
#define _FRR_ZLOG_H

#include <stdarg.h>
#include <stdbool.h>
#include <stdint.h>
#include <string.h>
#include <syslog.h>
#include <unistd.h>
#include <sys/uio.h>

#include "atomlist.h"
#include "frrcu.h"
#include "memory.h"
#include "hook.h"

extern char zlog_prefix[];
extern size_t zlog_prefixsz;
extern int zlog_tmpdirfd;

/* These functions are set up to write to stdout/stderr without explicit
 * initialization and/or before config load.  There is no need to call e.g.
 * fprintf(stderr, ...) just because it's "too early" at startup.  Depending
 * on context, it may still be the right thing to use fprintf though -- try to
 * determine wether something is a log message or something else.
 */

extern void vzlog(int prio, const char *fmt, va_list ap);

__attribute__ ((format (printf, 2, 3)))
static inline void zlog(int prio, const char *fmt, ...)
{
	va_list ap;

	va_start(ap, fmt);
	vzlog(prio, fmt, ap);
	va_end(ap);
}

#define zlog_err(...)    zlog(LOG_ERR, __VA_ARGS__)
#define zlog_warn(...)   zlog(LOG_WARNING, __VA_ARGS__)
#define zlog_info(...)   zlog(LOG_INFO, __VA_ARGS__)
#define zlog_notice(...) zlog(LOG_NOTICE, __VA_ARGS__)
#define zlog_debug(...)  zlog(LOG_DEBUG, __VA_ARGS__)

extern void zlog_sigsafe(const char *text, size_t len);

/* extra priority value to disable a target without deleting it */
#define ZLOG_DISABLED	(LOG_EMERG-1)

/* zlog_msg encapsulates a particular logging call from somewhere in the code.
 * The same struct is passed around to all zlog_targets.
 *
 * This is used to defer formatting the log message until it is actually
 * requested by one of the targets.  If none of the targets needs the message
 * formatted, the formatting call is avoided entirely.
 *
 * This struct is opaque / private to the core zlog code.  Logging targets
 * should use zlog_msg_* functions to get text / timestamps / ... for a
 * message.
 */

struct zlog_msg;

extern int zlog_msg_prio(struct zlog_msg *msg);

/* pass NULL as textlen if you don't need it. */
extern const char *zlog_msg_text(struct zlog_msg *msg, size_t *textlen);

/* timestamp formatting control flags */

/* sub-second digit count */
#define ZLOG_TS_PREC		0xfU

/* 8601:   0000-00-00T00:00:00Z      (if used with ZLOG_TS_UTC)
 *         0000-00-00T00:00:00+00:00 (otherwise)
 * Legacy: 0000/00/00 00:00:00       (no TZ indicated!)
 */
#define ZLOG_TS_ISO8601		(1 << 8)
#define ZLOG_TS_LEGACY		(1 << 9)

/* default is local time zone */
#define ZLOG_TS_UTC		(1 << 10)

extern size_t zlog_msg_ts(struct zlog_msg *msg, char *out, size_t outsz,
			  uint32_t flags);

/* This list & struct implements the actual logging targets.  It is accessed
 * lock-free from all threads, and thus MUST only be changed atomically, i.e.
 * RCU.
 *
 * Since there's no atomic replace, the replacement action is an add followed
 * by a delete.  This means that during logging config changes, log messages
 * may be duplicated in the log target that is being changed.  The old entry
 * being changed MUST also at the very least not crash or do other stupid
 * things.
 *
 * This list and struct are NOT related to config.  Logging config is kept
 * separately, and results in creating appropriate zlog_target(s) to realize
 * the config.  Log targets may also be created from varying sources, e.g.
 * command line options, or VTY commands ("log monitor").
 *
 * struct zlog_target is intended to be embedded into a larger structure that
 * contains additional field for the specific logging target, e.g. an fd or
 * additional options.  It MUST be the first field in that larger struct.
 */

PREDECL_ATOMLIST(zlog_targets)
struct zlog_target {
	struct zlog_targets_item head;

	int prio_min;

	void (*logfn)(struct zlog_target *zt, struct zlog_msg *msg[],
		      size_t nmsgs);

	/* for crash handlers, set to NULL if log target can't write crash logs
	 * without possibly deadlocking (AS-Safe)
	 *
	 * text is not \0 terminated & split up into lines (e.g. no \n)
	 */
	void (*logfn_sigsafe)(struct zlog_target *zt, const char *text,
			      size_t len);

	struct rcu_head rcu_head;
};

/* make a copy for RCUpdating.  oldzt may be NULL to allocate a fresh one. */
extern struct zlog_target *zlog_target_clone(struct memtype *mt,
					     struct zlog_target *oldzt,
					     size_t size);

/* update the zlog_targets list;  both oldzt and newzt may be NULL.  You
 * still need to zlog_target_free() the old target afterwards if it wasn't
 * NULL.
 *
 * Returns oldzt so you can zlog_target_free(zlog_target_replace(old, new));
 * (Some log targets may need extra cleanup inbetween, but remember the old
 * target MUST remain functional until the end of the current RCU cycle.)
 */
extern struct zlog_target *zlog_target_replace(struct zlog_target *oldzt,
					       struct zlog_target *newzt);

/* Mostly for symmetry for zlog_target_clone(), just rcu_free() internally. */
#define zlog_target_free(mt, zt) \
	rcu_free(mt, zt, rcu_head)

extern void zlog_init(const char *progname, const char *protoname,
		      unsigned short instance, uid_t uid, gid_t gid);
DECLARE_HOOK(zlog_init, (const char *progname, const char *protoname,
			 unsigned short instance, uid_t uid, gid_t gid),
			(progname, protoname, instance, uid, gid))

extern void zlog_fini(void);
DECLARE_KOOH(zlog_fini, (), ())

/* for tools & test programs, i.e. anything not a daemon.
 * (no cleanup needed at exit)
 */
extern void zlog_aux_init(const char *prefix, int prio_min);
DECLARE_HOOK(zlog_aux_init, (const char *prefix, int prio_min),
			    (prefix, prio_min))

extern void zlog_startup_end(void);

extern void zlog_tls_buffer_init(void);
extern void zlog_tls_buffer_flush(void);
extern void zlog_tls_buffer_fini(void);

#endif /* _FRR_ZLOG_H */
Commit	Line	Data
0bdeb5e5 DL	1	/*
	2	* Copyright (c) 2015-19 David Lamparter, for NetDEF, Inc.
	3	*
	4	* Permission to use, copy, modify, and distribute this software for any
	5	* purpose with or without fee is hereby granted, provided that the above
	6	* copyright notice and this permission notice appear in all copies.
	7	*
	8	* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
	9	* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
	10	* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
	11	* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
	12	* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
	13	* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
	14	* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
	15	*/
	16
	17	#ifndef _FRR_ZLOG_H
	18	#define _FRR_ZLOG_H
	19
	20	#include <stdarg.h>
	21	#include <stdbool.h>
	22	#include <stdint.h>
	23	#include <string.h>
	24	#include <syslog.h>
	25	#include <unistd.h>
	26	#include <sys/uio.h>
	27
	28	#include "atomlist.h"
	29	#include "frrcu.h"
	30	#include "memory.h"
	31	#include "hook.h"
	32
	33	extern char zlog_prefix[];
	34	extern size_t zlog_prefixsz;
	35	extern int zlog_tmpdirfd;
	36
	37	/* These functions are set up to write to stdout/stderr without explicit
	38	* initialization and/or before config load. There is no need to call e.g.
	39	* fprintf(stderr, ...) just because it's "too early" at startup. Depending
	40	* on context, it may still be the right thing to use fprintf though -- try to
	41	* determine wether something is a log message or something else.
	42	*/
	43
	44	extern void vzlog(int prio, const char *fmt, va_list ap);
	45
	46	__attribute__ ((format (printf, 2, 3)))
	47	static inline void zlog(int prio, const char *fmt, ...)
	48	{
	49	va_list ap;
	50
	51	va_start(ap, fmt);
	52	vzlog(prio, fmt, ap);
	53	va_end(ap);
	54	}
	55
	56	#define zlog_err(...) zlog(LOG_ERR, __VA_ARGS__)
	57	#define zlog_warn(...) zlog(LOG_WARNING, __VA_ARGS__)
	58	#define zlog_info(...) zlog(LOG_INFO, __VA_ARGS__)
	59	#define zlog_notice(...) zlog(LOG_NOTICE, __VA_ARGS__)
	60	#define zlog_debug(...) zlog(LOG_DEBUG, __VA_ARGS__)
	61
	62	extern void zlog_sigsafe(const char *text, size_t len);
	63
	64	/* extra priority value to disable a target without deleting it */
65	#define ZLOG_DISABLED (LOG_EMERG-1)
66
67	/* zlog_msg encapsulates a particular logging call from somewhere in the code.
68	* The same struct is passed around to all zlog_targets.
69	*
70	* This is used to defer formatting the log message until it is actually
71	* requested by one of the targets. If none of the targets needs the message
72	* formatted, the formatting call is avoided entirely.
73	*
74	* This struct is opaque / private to the core zlog code. Logging targets
75	* should use zlog_msg_* functions to get text / timestamps / ... for a
76	* message.
77	*/
78
79	struct zlog_msg;
80
81	extern int zlog_msg_prio(struct zlog_msg *msg);
82
83	/* pass NULL as textlen if you don't need it. */
84	extern const char zlog_msg_text(struct zlog_msg msg, size_t *textlen);
85
86	/* timestamp formatting control flags */
87
88	/* sub-second digit count */
89	#define ZLOG_TS_PREC 0xfU
90
91	/* 8601: 0000-00-00T00:00:00Z (if used with ZLOG_TS_UTC)
92	* 0000-00-00T00:00:00+00:00 (otherwise)
93	* Legacy: 0000/00/00 00:00:00 (no TZ indicated!)
94	*/
95	#define ZLOG_TS_ISO8601 (1 << 8)
96	#define ZLOG_TS_LEGACY (1 << 9)
97
98	/* default is local time zone */
99	#define ZLOG_TS_UTC (1 << 10)
100
101	extern size_t zlog_msg_ts(struct zlog_msg msg, char out, size_t outsz,
102	uint32_t flags);
103
104	/* This list & struct implements the actual logging targets. It is accessed
105	* lock-free from all threads, and thus MUST only be changed atomically, i.e.
106	* RCU.
107	*
108	* Since there's no atomic replace, the replacement action is an add followed
109	* by a delete. This means that during logging config changes, log messages
110	* may be duplicated in the log target that is being changed. The old entry
111	* being changed MUST also at the very least not crash or do other stupid
112	* things.
113	*
114	* This list and struct are NOT related to config. Logging config is kept
115	* separately, and results in creating appropriate zlog_target(s) to realize
116	* the config. Log targets may also be created from varying sources, e.g.
117	* command line options, or VTY commands ("log monitor").
118	*
119	* struct zlog_target is intended to be embedded into a larger structure that
120	* contains additional field for the specific logging target, e.g. an fd or
121	* additional options. It MUST be the first field in that larger struct.
122	*/
123
124	PREDECL_ATOMLIST(zlog_targets)
125	struct zlog_target {
126	struct zlog_targets_item head;
127
128	int prio_min;
129
130	void (logfn)(struct zlog_target zt, struct zlog_msg *msg[],
131	size_t nmsgs);
132
133	/* for crash handlers, set to NULL if log target can't write crash logs
134	* without possibly deadlocking (AS-Safe)
135	*
136	* text is not \0 terminated & split up into lines (e.g. no \n)
137	*/
138	void (logfn_sigsafe)(struct zlog_target zt, const char *text,
139	size_t len);
140
141	struct rcu_head rcu_head;
142	};
143
144	/* make a copy for RCUpdating. oldzt may be NULL to allocate a fresh one. */
145	extern struct zlog_target zlog_target_clone(struct memtype mt,
146	struct zlog_target *oldzt,
147	size_t size);
148
149	/* update the zlog_targets list; both oldzt and newzt may be NULL. You
150	* still need to zlog_target_free() the old target afterwards if it wasn't
151	* NULL.
152	*
153	* Returns oldzt so you can zlog_target_free(zlog_target_replace(old, new));
154	* (Some log targets may need extra cleanup inbetween, but remember the old
155	* target MUST remain functional until the end of the current RCU cycle.)
156	*/
157	extern struct zlog_target zlog_target_replace(struct zlog_target oldzt,
158	struct zlog_target *newzt);
159
160	/* Mostly for symmetry for zlog_target_clone(), just rcu_free() internally. */
161	#define zlog_target_free(mt, zt) \
162	rcu_free(mt, zt, rcu_head)
163
164	extern void zlog_init(const char progname, const char protoname,
165	unsigned short instance, uid_t uid, gid_t gid);
166	DECLARE_HOOK(zlog_init, (const char progname, const char protoname,
167	unsigned short instance, uid_t uid, gid_t gid),
168	(progname, protoname, instance, uid, gid))
169
170	extern void zlog_fini(void);
171	DECLARE_KOOH(zlog_fini, (), ())
172
173	/* for tools & test programs, i.e. anything not a daemon.
174	* (no cleanup needed at exit)
175	*/
176	extern void zlog_aux_init(const char *prefix, int prio_min);
177	DECLARE_HOOK(zlog_aux_init, (const char *prefix, int prio_min),
178	(prefix, prio_min))
179
180	extern void zlog_startup_end(void);
181
182	extern void zlog_tls_buffer_init(void);
183	extern void zlog_tls_buffer_flush(void);
184	extern void zlog_tls_buffer_fini(void);
185
186	#endif /* _FRR_ZLOG_H */