Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ALOG(3)		       FreeBSD Library Functions Manual		       ALOG(3)

NAME
     alog -- logging library

LIBRARY
     PDEL Library (libpdel, -lpdel)

SYNOPSIS
     #include <sys/types.h>
     #include <netinet/in.h>
     #include <pdel/structs/structs.h>
     #include <pdel/structs/type/array.h>
     #include <pdel/sys/alog.h>

     int
     alog_configure(int	channel, const struct alog_config *conf);

     int
     alog_shutdown(int channel);

     int
     alog_set_channel(int channel);

     void
     alog(int sev, const char *fmt, ...);

     void
     valog(int sev, const char *fmt, va_list args);

     int
     alog_get_history(int channel, int min_severity, int max_entries,
	 time_t	max_age, const regex_t *preg, struct alog_history *list);

     int
     alog_clear_history(int channel);

     int
     alog_facility(const char *name);

     const char	*
     alog_facility_name(int facility);

     int
     alog_severity(const char *name);

     const char	*
     alog_severity_name(int severity);

     void
     alog_set_debug(int	channel, int enabled);

     void
     alog_expand(const char *fmt, int errnum, char *buf, size_t	bufsize);

     extern const struct structs_type alog_facility_type;
     extern const struct structs_type alog_severity_type;
     extern const struct structs_type alog_config_type;
     extern const struct structs_type alog_history_type;

DESCRIPTION
     These functions provide support for storing and retrieving	log messages.
     Up	to ALOG_MAX_CHANNELS independent log channels are supported.  Log en-
     tries may be printed to standard error, stored in a searchable circular
     log history file, and sent	to a local or remote syslog(3) server.

     alog_configure() configures a log channel;	channel	must be	between	zero
     and ALOG_MAX_CHANNELS - 1,	inclusive.  The	channel's configuration	is
     pointed to	by conf, which is a pointer to a struct	alog_config:

	struct alog_config {
	    const char	   *path;	  /* logfile filename, or NULL */
	    const char	   *name;	  /* syslog id,	or NULL	to disable */
	    const char	   *facility;	  /* syslog facility, NULL=stderr */
	    struct in_addr remote_server; /* remote server, or 0.0.0.0 local */
	    int		   min_severity;  /* min severity to actually log */
	    int		   histlen;	  /* how much history to save */
	};

     If	path is	not NULL it specifies the pathname of a	circular logfile(3)
     used to store log entries,	and histlen specifies the maximum number of
     entries to	store in the file.

     If	facility is NULL, log messages will be sent to standard	error.	Other-
     wise, if name is not NULL,	syslog(3) logging is performed:	name is	the
     syslog(3) identifier, remote_server specifies the IP address of a remote
     syslog(3) server to send log entries to (or 0.0.0.0 for the local
     syslogd(8)	listening on /var/run/log), and	facility specifies a syslog(3)
     facility, which must be a valid facility name as returned by
     alog_facility_name() (see below), e.g., "daemon".	If name	is NULL, log
     messages are not output at	all (but will still be stored in the log
     file).

     min_severity specifies a minimum syslog(3)	severity level (actually a
     maximum, numerically speaking) for	logged entries;	less severe entries
     are filtered out.

     After a channel has been configured successfully via alog_configure(),
     access to that channel via	alog(),	valog(), alog_get_history(), and
     alog_clear_history() by multiple threads is safe.

     alog_shutdown() shuts down	an alog	channel, returning it to its unini-
     tialized, thread-unsafe state.  Logging to	an uninitialized channel is
     permitted;	the output is written to standard error.  This allows applica-
     tions to log errors before	they've	configured alog.

     alog_set_channel()	sets the log channel for newly logged messages.	 This
     setting persists until another call to alog_set_channel().	 A separate
     "current channel" variable	is kept	for each thread.

     alog() and	valog()	log a message.	sev is a syslog(3) severity level such
     as	LOG_ERROR.  The	message	is formatted using fmt as a printf(3) like
     format string.  As	a special case,	"%m" is	replaced with strerror(errno).
     The value of errno	is not modified	by these functions.  Note that when a
     channel is	configured to log to syslog or standard	error, these functions
     become thread cancellation	points.

     alog_get_history()	retrieves previously logged entries from the circular
     log file associated with channel channel.	Only entries with severity
     greater than min_severity are returned; only entries logged no earlier
     than max_age seconds ago are returned; if preg is not NULL, log entries
     not matching the regular expression are filtered out; and finally,	at
     most max_entries total entries are	returned.

     The returned entries are described	by an array of pointers	to struct
     alog_entry:

	struct alog_entry {
	    time_t  when;	    /* when event was logged */
	    int	    sev;	    /* entry log severity */
	    char    msg[0];	    /* entry contents (including '\0') */
	};

	DEFINE_STRUCTS_ARRAY(alog_history, struct alog_entry *);

     This array	is stored in *list, which will then contain a data structure
     with structs(3) type alog_history_type and	which must eventually be freed
     by	the caller via structs_free(3).

     alog_clear_history() resets a log history file to empty.

     alog_facility() takes a syslog(3) facility	name and returns its numeric
     value.

     alog_facility_name() returns the syslog(3)	facility name for facility.

     alog_severity() takes a syslog(3) severity	name and returns its numeric
     value.

     alog_severity_name() returns the syslog(3)	severity name for severity.

     alog_expand() expands the last occurence of "%m" (if any) in the string
     fmt into strerror(errnum) and writes the result into the buffer pointed
     to	by buf,	which has size bufsize.

     alog_set_debug() causes the next call to alog_configure() to act as if
     facility were equal to NULL.

     The following structs(3) types are	pre-defined:

	alog_facility_type

	    Same as structs_type_string(3) but may only	take values that are
	    valid syslog(3) facility names.  The default value is "daemon."

	alog_severity_type

	    Same as structs_type_int(3)	but the	ASCII representation is	the
	    severity name from alog_severity_name() instead of a number.

	alog_config_type

	    Describes a	struct alog_config.

	alog_history_type

	    Describes a	struct alog_history, which is a	structs(3) array of
	    struct alog_entry *	pointers.  This	type is	used for accessing and
	    freeing the	log history returned by	alog_get_history().

RETURN VALUES
     The above functions return	-1 or NULL to indicate an error, setting errno
     accordingly.

SEE ALSO
     libpdel(3), regex(3), structs(3), structs_type_array(3), syslog(3),
     typed_mem(3)

HISTORY
     The PDEL library was developed at Packet Design, LLC.
     http://www.packetdesign.com/

AUTHORS
     Archie Cobbs <archie@freebsd.org>

BUGS
     If	multiple channels are configured to write to local syslog, messages
     can get written with the wrong identifier or facility.  This is an	un-
     avoidable consequence of the implementation of openlog(3) and syslog(3),
     which doesn't support threading.

FreeBSD	13.0			April 22, 2002			  FreeBSD 13.0

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | SEE ALSO | HISTORY | AUTHORS | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=alog&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help