cannam@128: /* gzlog.h
cannam@128:   Copyright (C) 2004, 2008, 2012 Mark Adler, all rights reserved
cannam@128:   version 2.2, 14 Aug 2012
cannam@128: 
cannam@128:   This software is provided 'as-is', without any express or implied
cannam@128:   warranty.  In no event will the author be held liable for any damages
cannam@128:   arising from the use of this software.
cannam@128: 
cannam@128:   Permission is granted to anyone to use this software for any purpose,
cannam@128:   including commercial applications, and to alter it and redistribute it
cannam@128:   freely, subject to the following restrictions:
cannam@128: 
cannam@128:   1. The origin of this software must not be misrepresented; you must not
cannam@128:      claim that you wrote the original software. If you use this software
cannam@128:      in a product, an acknowledgment in the product documentation would be
cannam@128:      appreciated but is not required.
cannam@128:   2. Altered source versions must be plainly marked as such, and must not be
cannam@128:      misrepresented as being the original software.
cannam@128:   3. This notice may not be removed or altered from any source distribution.
cannam@128: 
cannam@128:   Mark Adler    madler@alumni.caltech.edu
cannam@128:  */
cannam@128: 
cannam@128: /* Version History:
cannam@128:    1.0  26 Nov 2004  First version
cannam@128:    2.0  25 Apr 2008  Complete redesign for recovery of interrupted operations
cannam@128:                      Interface changed slightly in that now path is a prefix
cannam@128:                      Compression now occurs as needed during gzlog_write()
cannam@128:                      gzlog_write() now always leaves the log file as valid gzip
cannam@128:    2.1   8 Jul 2012  Fix argument checks in gzlog_compress() and gzlog_write()
cannam@128:    2.2  14 Aug 2012  Clean up signed comparisons
cannam@128:  */
cannam@128: 
cannam@128: /*
cannam@128:    The gzlog object allows writing short messages to a gzipped log file,
cannam@128:    opening the log file locked for small bursts, and then closing it.  The log
cannam@128:    object works by appending stored (uncompressed) data to the gzip file until
cannam@128:    1 MB has been accumulated.  At that time, the stored data is compressed, and
cannam@128:    replaces the uncompressed data in the file.  The log file is truncated to
cannam@128:    its new size at that time.  After each write operation, the log file is a
cannam@128:    valid gzip file that can decompressed to recover what was written.
cannam@128: 
cannam@128:    The gzlog operations can be interupted at any point due to an application or
cannam@128:    system crash, and the log file will be recovered the next time the log is
cannam@128:    opened with gzlog_open().
cannam@128:  */
cannam@128: 
cannam@128: #ifndef GZLOG_H
cannam@128: #define GZLOG_H
cannam@128: 
cannam@128: /* gzlog object type */
cannam@128: typedef void gzlog;
cannam@128: 
cannam@128: /* Open a gzlog object, creating the log file if it does not exist.  Return
cannam@128:    NULL on error.  Note that gzlog_open() could take a while to complete if it
cannam@128:    has to wait to verify that a lock is stale (possibly for five minutes), or
cannam@128:    if there is significant contention with other instantiations of this object
cannam@128:    when locking the resource.  path is the prefix of the file names created by
cannam@128:    this object.  If path is "foo", then the log file will be "foo.gz", and
cannam@128:    other auxiliary files will be created and destroyed during the process:
cannam@128:    "foo.dict" for a compression dictionary, "foo.temp" for a temporary (next)
cannam@128:    dictionary, "foo.add" for data being added or compressed, "foo.lock" for the
cannam@128:    lock file, and "foo.repairs" to log recovery operations performed due to
cannam@128:    interrupted gzlog operations.  A gzlog_open() followed by a gzlog_close()
cannam@128:    will recover a previously interrupted operation, if any. */
cannam@128: gzlog *gzlog_open(char *path);
cannam@128: 
cannam@128: /* Write to a gzlog object.  Return zero on success, -1 if there is a file i/o
cannam@128:    error on any of the gzlog files (this should not happen if gzlog_open()
cannam@128:    succeeded, unless the device has run out of space or leftover auxiliary
cannam@128:    files have permissions or ownership that prevent their use), -2 if there is
cannam@128:    a memory allocation failure, or -3 if the log argument is invalid (e.g. if
cannam@128:    it was not created by gzlog_open()).  This function will write data to the
cannam@128:    file uncompressed, until 1 MB has been accumulated, at which time that data
cannam@128:    will be compressed.  The log file will be a valid gzip file upon successful
cannam@128:    return. */
cannam@128: int gzlog_write(gzlog *log, void *data, size_t len);
cannam@128: 
cannam@128: /* Force compression of any uncompressed data in the log.  This should be used
cannam@128:    sparingly, if at all.  The main application would be when a log file will
cannam@128:    not be appended to again.  If this is used to compress frequently while
cannam@128:    appending, it will both significantly increase the execution time and
cannam@128:    reduce the compression ratio.  The return codes are the same as for
cannam@128:    gzlog_write(). */
cannam@128: int gzlog_compress(gzlog *log);
cannam@128: 
cannam@128: /* Close a gzlog object.  Return zero on success, -3 if the log argument is
cannam@128:    invalid.  The log object is freed, and so cannot be referenced again. */
cannam@128: int gzlog_close(gzlog *log);
cannam@128: 
cannam@128: #endif