00001 /* gzlog.h 00002 Copyright (C) 2004, 2008 Mark Adler, all rights reserved 00003 version 2.0, 25 Apr 2008 00004 00005 This software is provided 'as-is', without any express or implied 00006 warranty. In no event will the author be held liable for any damages 00007 arising from the use of this software. 00008 00009 Permission is granted to anyone to use this software for any purpose, 00010 including commercial applications, and to alter it and redistribute it 00011 freely, subject to the following restrictions: 00012 00013 1. The origin of this software must not be misrepresented; you must not 00014 claim that you wrote the original software. If you use this software 00015 in a product, an acknowledgment in the product documentation would be 00016 appreciated but is not required. 00017 2. Altered source versions must be plainly marked as such, and must not be 00018 misrepresented as being the original software. 00019 3. This notice may not be removed or altered from any source distribution. 00020 00021 Mark Adler madler@alumni.caltech.edu 00022 */ 00023 00024 /* Version History: 00025 1.0 26 Nov 2004 First version 00026 2.0 25 Apr 2008 Complete redesign for recovery of interrupted operations 00027 Interface changed slightly in that now path is a prefix 00028 Compression now occurs as needed during gzlog_write() 00029 gzlog_write() now always leaves the log file as valid gzip 00030 */ 00031 00032 /* 00033 The gzlog object allows writing short messages to a gzipped log file, 00034 opening the log file locked for small bursts, and then closing it. The log 00035 object works by appending stored (uncompressed) data to the gzip file until 00036 1 MB has been accumulated. At that time, the stored data is compressed, and 00037 replaces the uncompressed data in the file. The log file is truncated to 00038 its new size at that time. After each write operation, the log file is a 00039 valid gzip file that can decompressed to recover what was written. 00040 00041 The gzlog operations can be interupted at any point due to an application or 00042 system crash, and the log file will be recovered the next time the log is 00043 opened with gzlog_open(). 00044 */ 00045 00046 #ifndef GZLOG_H 00047 #define GZLOG_H 00048 00049 /* gzlog object type */ 00050 typedef void gzlog; 00051 00052 /* Open a gzlog object, creating the log file if it does not exist. Return 00053 NULL on error. Note that gzlog_open() could take a while to complete if it 00054 has to wait to verify that a lock is stale (possibly for five minutes), or 00055 if there is significant contention with other instantiations of this object 00056 when locking the resource. path is the prefix of the file names created by 00057 this object. If path is "foo", then the log file will be "foo.gz", and 00058 other auxiliary files will be created and destroyed during the process: 00059 "foo.dict" for a compression dictionary, "foo.temp" for a temporary (next) 00060 dictionary, "foo.add" for data being added or compressed, "foo.lock" for the 00061 lock file, and "foo.repairs" to log recovery operations performed due to 00062 interrupted gzlog operations. A gzlog_open() followed by a gzlog_close() 00063 will recover a previously interrupted operation, if any. */ 00064 gzlog *gzlog_open(char *path); 00065 00066 /* Write to a gzlog object. Return zero on success, -1 if there is a file i/o 00067 error on any of the gzlog files (this should not happen if gzlog_open() 00068 succeeded, unless the device has run out of space or leftover auxiliary 00069 files have permissions or ownership that prevent their use), -2 if there is 00070 a memory allocation failure, or -3 if the log argument is invalid (e.g. if 00071 it was not created by gzlog_open()). This function will write data to the 00072 file uncompressed, until 1 MB has been accumulated, at which time that data 00073 will be compressed. The log file will be a valid gzip file upon successful 00074 return. */ 00075 int gzlog_write(gzlog *log, void *data, size_t len); 00076 00077 /* Force compression of any uncompressed data in the log. This should be used 00078 sparingly, if at all. The main application would be when a log file will 00079 not be appended to again. If this is used to compress frequently while 00080 appending, it will both significantly increase the execution time and 00081 reduce the compression ratio. The return codes are the same as for 00082 gzlog_write(). */ 00083 int gzlog_compress(gzlog *log); 00084 00085 /* Close a gzlog object. Return zero on success, -3 if the log argument is 00086 invalid. The log object is freed, and so cannot be referenced again. */ 00087 int gzlog_close(gzlog *log); 00088 00089 #endif