These functions provide support for circular log files.
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.
file has a fixed size and is accessed using
opens the log file with pathname
may be equal to zero,
for locking purposes
If the file is locked,
does not block, but instead returns
If the named file exists, it must be a valid
Otherwise, it is created using those parameters:
limits the total number of entries that the file may contain, and
limit the total amount of entry data (in bytes) that the file
When full, the files ultimate size will be approximately
+ (8 *
in which case the logfile is not stored in the file system and
therefore is not persistent.
closes a log file previously opened using
will be set to
is already equal to
is invoked, nothing happens.
returns the number of valid entries contained in a log file.
retrieves an entry from a log file.
must be a negative number: -1 is the most recently added entry,
-2 is the second most recently added, etc.
is not equal to
is set to the length of the entry.
Entries returned by
are contiguous and suitably aligned for any type.
The caller should not free the returned pointer.
adds a new entry to a log file.
The entry is pointed to by
and has length
discards the oldest entries in a log file as necessary to make
the total number of entries be at most
synchronously flushes any unwritten entries to permanent storage.
object maintains an internal mutex lock.
may be safely called simultaneously from different threads.