.\" Copyright (c) 2001-2002 Packet Design, LLC. .\" All rights reserved. .\" .\" Subject to the following obligations and disclaimer of warranty, .\" use and redistribution of this software, in source or object code .\" forms, with or without modifications are expressly permitted by .\" Packet Design; provided, however, that: .\" .\" (i) Any and all reproductions of the source or object code .\" must include the copyright notice above and the following .\" disclaimer of warranties; and .\" (ii) No rights are granted, in any manner or form, to use .\" Packet Design trademarks, including the mark "PACKET DESIGN" .\" on advertising, endorsements, or otherwise except as such .\" appears in the above copyright notice or in the software. .\" .\" THIS SOFTWARE IS BEING PROVIDED BY PACKET DESIGN "AS IS", AND .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, PACKET DESIGN MAKES NO .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING .\" THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED .\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, .\" OR NON-INFRINGEMENT. PACKET DESIGN DOES NOT WARRANT, GUARANTEE, .\" OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS .\" OF THE USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, .\" RELIABILITY OR OTHERWISE. IN NO EVENT SHALL PACKET DESIGN BE .\" LIABLE FOR ANY DAMAGES RESULTING FROM OR ARISING OUT OF ANY USE .\" OF THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY DIRECT, .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL .\" DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF .\" USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY THEORY OF .\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF .\" THE USE OF THIS SOFTWARE, EVEN IF PACKET DESIGN IS ADVISED OF .\" THE POSSIBILITY OF SUCH DAMAGE. .\" .\" Author: Archie Cobbs .\" .\" $Id: alog.3,v 1.1.1.1 2012/02/21 23:25:53 misho Exp $ .\" .Dd April 22, 2002 .Dt ALOG 3 .Os .Sh NAME .Nm alog .Nd logging library .Sh LIBRARY PDEL Library (libpdel, \-lpdel) .Sh SYNOPSIS .In sys/types.h .In netinet/in.h .In pdel/structs/structs.h .In pdel/structs/type/array.h .In pdel/sys/alog.h .Ft int .Fn alog_configure "int channel" "const struct alog_config *conf" .Ft int .Fn alog_shutdown "int channel" .Ft int .Fn alog_set_channel "int channel" .Ft void .Fn alog "int sev" "const char *fmt" "..." .Ft void .Fn valog "int sev" "const char *fmt" "va_list args" .Ft int .Fn alog_get_history "int channel" "int min_severity" "int max_entries" "time_t max_age" "const regex_t *preg" "struct alog_history *list" .Ft int .Fn alog_clear_history "int channel" .Ft int .Fn alog_facility "const char *name" .Ft "const char *" .Fn alog_facility_name "int facility" .Ft int .Fn alog_severity "const char *name" .Ft "const char *" .Fn alog_severity_name "int severity" .Ft void .Fn alog_set_debug "int channel" "int enabled" .Ft void .Fn alog_expand "const char *fmt" "int errnum" "char *buf" "size_t bufsize" .Vt extern const struct structs_type alog_facility_type ; .Vt extern const struct structs_type alog_severity_type ; .Vt extern const struct structs_type alog_config_type ; .Vt extern const struct structs_type alog_history_type ; .Sh DESCRIPTION These functions provide support for storing and retrieving log messages. Up to .Dv ALOG_MAX_CHANNELS independent log channels are supported. Log entries may be printed to standard error, stored in a searchable circular log history file, and sent to a local or remote .Xr syslog 3 server. .Pp .Fn alog_configure configures a log channel; .Fa channel must be between zero and .Dv "ALOG_MAX_CHANNELS - 1" , inclusive. The channel's configuration is pointed to by .Fa conf , which is a pointer to a .Li "struct alog_config" : .Pp .Bd -literal -compact -offset 3n 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 */ }; .Ed .Pp If .Fa path is not .Dv NULL it specifies the pathname of a circular .Xr logfile 3 used to store log entries, and .Fa histlen specifies the maximum number of entries to store in the file. .Pp If .Fa facility is .Dv NULL , log messages will be sent to standard error. Otherwise, if .Fa name is not .Dv NULL , .Xr syslog 3 logging is performed: .Fa name is the .Xr syslog 3 identifier, .Fa remote_server specifies the IP address of a remote .Xr syslog 3 server to send log entries to (or .Li "0.0.0.0" for the local .Xr syslogd 8 listening on .Pa "/var/run/log)" , and .Fa facility specifies a .Xr syslog 3 facility, which must be a valid facility name as returned by .Fn alog_facility_name (see below), e.g., "daemon". If .Fa name is .Dv NULL , log messages are not output at all (but will still be stored in the log file). .Pp .Fa min_severity specifies a minimum .Xr syslog 3 severity level (actually a maximum, numerically speaking) for logged entries; less severe entries are filtered out. .Pp After a channel has been configured successfully via .Fn alog_configure , access to that channel via .Fn alog , .Fn valog , .Fn alog_get_history , and .Fn alog_clear_history by multiple threads is safe. .Pp .Fn alog_shutdown shuts down an .Fa alog channel, returning it to its uninitialized, thread-unsafe state. Logging to an uninitialized channel is permitted; the output is written to standard error. This allows applications to log errors before they've configured .Nm alog . .Pp .Fn alog_set_channel sets the log channel for newly logged messages. This setting persists until another call to .Fn alog_set_channel . A separate "current channel" variable is kept for each thread. .Pp .Fn alog and .Fn valog log a message. .Fa sev is a .Xr syslog 3 severity level such as .Dv LOG_ERROR . The message is formatted using .Fa fmt as a .Xr printf 3 like format string. As a special case, "%m" is replaced with .Fn strerror errno . The value of .Va 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. .Pp .Fn alog_get_history retrieves previously logged entries from the circular log file associated with channel .Fa channel . Only entries with severity greater than .Fa min_severity are returned; only entries logged no earlier than .Fa max_age seconds ago are returned; if .Fa preg is not .Dv NULL , log entries not matching the regular expression are filtered out; and finally, at most .Fa max_entries total entries are returned. .Pp The returned entries are described by an array of pointers to .Li "struct alog_entry" : .Pp .Bd -literal -compact -offset 3n 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 *); .Ed .Pp This array is stored in .Fa "*list" , which will then contain a data structure with .Xr structs 3 type .Fa alog_history_type and which must eventually be freed by the caller via .Xr structs_free 3 . .Pp .Fn alog_clear_history resets a log history file to empty. .Pp .Fn alog_facility takes a .Xr syslog 3 facility name and returns its numeric value. .Pp .Fn alog_facility_name returns the .Xr syslog 3 facility name for .Fa facility . .Pp .Fn alog_severity takes a .Xr syslog 3 severity name and returns its numeric value. .Pp .Fn alog_severity_name returns the .Xr syslog 3 severity name for .Fa severity . .Pp .Fn alog_expand expands the last occurence of "%m" (if any) in the string .Fa fmt into .Fn strerror errnum and writes the result into the buffer pointed to by .Fa buf , which has size .Fa bufsize . .Pp .Fn alog_set_debug causes the next call to .Fn alog_configure to act as if .Fa facility were equal to .Dv NULL . .Pp The following .Xr structs 3 types are pre-defined: .Pp .Bl -hang -width 2n -offset 3n .It Va alog_facility_type .Pp Same as .Xr structs_type_string 3 but may only take values that are valid .Xr syslog 3 facility names. The default value is .Dq daemon. .It Va alog_severity_type .Pp Same as .Xr structs_type_int 3 but the ASCII representation is the severity name from .Fn alog_severity_name instead of a number. .It Va alog_config_type .Pp Describes a .Li "struct alog_config" . .It Va alog_history_type .Pp Describes a .Li "struct alog_history" , which is a .Xr structs 3 array of .Li "struct alog_entry *" pointers. This type is used for accessing and freeing the log history returned by .Fn alog_get_history . .El .Sh RETURN VALUES The above functions return -1 or .Dv NULL to indicate an error, setting .Va errno accordingly. .Sh SEE ALSO .Xr libpdel 3 , .Xr regex 3 , .Xr structs 3 , .Xr structs_type_array 3 , .Xr syslog 3 , .Xr typed_mem 3 .Sh HISTORY The PDEL library was developed at Packet Design, LLC. .Dv "http://www.packetdesign.com/" .Sh AUTHORS .An Archie Cobbs Aq archie@freebsd.org .Sh BUGS If multiple channels are configured to write to local syslog, messages can get written with the wrong identifier or facility. This is an unavoidable consequence of the implementation of .Xr openlog 3 and .Xr syslog 3 , which doesn't support threading.