NAME

logfile — circular log files

LIBRARY

PDEL Library (libpdel, -lpdel)

SYNOPSIS

#include <sys/types.h>
#include <pdel/sys/logfile.h>

struct logfile *
logfile_open(const char *path, int flags, u_int32_t maxent, u_int32_t maxdata);

void
logfile_close(struct logfile **lfp);

u_int32_t
logfile_num_entries(struct logfile *lf);

const void *
logfile_get(struct logfile *lf, int which, int *lenp);

int
logfile_put(struct logfile *lf, const void *data, int len);

void
logfile_trim(struct logfile *lf, int num);

void
logfile_sync(struct logfile *lf);

DESCRIPTION

These functions provide support for circular log files. A logfile file contains the most recently added entries, where an entry is any opaque chunk of data supplied by the application. When the file becomes full, new entries overwrite the oldest entries in a circular fashion.

Each logfile file has a fixed size and is accessed using mmap(2) for efficiency.

logfile_open() opens the log file with pathname path. flags may be equal to zero, O_SHLOCK, or O_EXLOCK for locking purposes (see open(2) for details). If the file is locked, logfile_open() does not block, but instead returns NULL immediately with errno set to EWOULDBLOCK.

If the named file exists, it must be a valid logfile file and maxent and maxdata are ignored. Otherwise, it is created using those parameters: maxent limits the total number of entries that the file may contain, and maxdata limit the total amount of entry data (in bytes) that the file may contain. When full, the file's ultimate size will be approximately maxdata + (8 * maxent) + 20.

The path may be NULL, in which case the logfile is not stored in the file system and therefore is not persistent.

logfile_close() closes a log file previously opened using logfile_open(). Upon return, *lfp will be set to NULL. If *lfp is already equal to NULL when logfile_close() is invoked, nothing happens.

logfile_num_entries() returns the number of valid entries contained in a log file.

logfile_get() retrieves an entry from a log file. which must be a negative number: -1 is the most recently added entry, -2 is the second most recently added, etc. If lenp is not equal to NULL, then *lenp is set to the length of the entry. Entries returned by logfile_get() are contiguous and suitably aligned for any type. The caller should not free the returned pointer.

logfile_put() adds a new entry to a log file. The entry is pointed to by data and has length len.

logfile_trim() discards the oldest entries in a log file as necessary to make the total number of entries be at most num.

logfile_sync() synchronously flushes any unwritten entries to permanent storage.

Each logfile object maintains an internal mutex lock. The functions logfile_num_entries(), logfile_get(), logfile_put(), logfile_trim(), and logfile_sync() may be safely called simultaneously from different threads.

RETURN VALUES

logfile_open() and logfile_get() return NULL to indicate an error. logfile_put() returns -1 to indicate an error. In all error cases, errno is set accordingly.

SEE ALSO

open(2), alog(3), libpdel(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

Meta information is stored in the logfile in host order. Therefore, logfile files are not portable.