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

FreeBSD Manual Pages

  
 
  

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

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 ef-
     ficiency.

     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 de-
     tails).  If the file is locked, logfile_open() does not block, but	in-
     stead 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	nega-
     tive 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 contigu-
     ous 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.

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=logfile&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help