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