LOGFILE(3) 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 effi- ciency. 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 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 suit- ably 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 log- file_num_entries(), logfile_get(), logfile_put(), logfile_trim(), and log- file_sync() may be safely called simultaneously from different threads. RETURN VALUES logfile_open() and logfile_get() return NULL to indicate an error. log- file_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 ports 15.quarterly April 22, 2002 LOGFILE(3)
NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | SEE ALSO | HISTORY | AUTHORS | BUGS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=logfile_num_entries&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>