summaryrefslogtreecommitdiff
path: root/examples/gzlog.h
diff options
context:
space:
mode:
authorMark Adler <madler@alumni.caltech.edu>2011-09-09 23:26:40 -0700
committerMark Adler <madler@alumni.caltech.edu>2011-09-09 23:26:40 -0700
commitf6194ef39af5864f792412460c354cc339dde7d1 (patch)
tree5ea1e6849128e9b2194c66ee3d82afa36b4ac07c /examples/gzlog.h
parent639be997883d9016baaf46017a2802b2ce1698bd (diff)
downloadzlib-1.2.3.4.tar.gz
zlib-1.2.3.4.tar.bz2
zlib-1.2.3.4.zip
zlib 1.2.3.4v1.2.3.4
Diffstat (limited to 'examples/gzlog.h')
-rw-r--r--examples/gzlog.h93
1 files changed, 62 insertions, 31 deletions
diff --git a/examples/gzlog.h b/examples/gzlog.h
index a800bd5..c461426 100644
--- a/examples/gzlog.h
+++ b/examples/gzlog.h
@@ -1,6 +1,6 @@
1/* gzlog.h 1/* gzlog.h
2 Copyright (C) 2004 Mark Adler, all rights reserved 2 Copyright (C) 2004, 2008 Mark Adler, all rights reserved
3 version 1.0, 26 Nov 2004 3 version 2.0, 25 Apr 2008
4 4
5 This software is provided 'as-is', without any express or implied 5 This software is provided 'as-is', without any express or implied
6 warranty. In no event will the author be held liable for any damages 6 warranty. In no event will the author be held liable for any damages
@@ -21,38 +21,69 @@
21 Mark Adler madler@alumni.caltech.edu 21 Mark Adler madler@alumni.caltech.edu
22 */ 22 */
23 23
24/* Version History:
25 1.0 26 Nov 2004 First version
26 2.0 25 Apr 2008 Complete redesign for recovery of interrupted operations
27 Interface changed slightly in that now path is a prefix
28 Compression now occurs as needed during gzlog_write()
29 gzlog_write() now always leaves the log file as valid gzip
30 */
31
24/* 32/*
25 The gzlog object allows writing short messages to a gzipped log file, 33 The gzlog object allows writing short messages to a gzipped log file,
26 opening the log file locked for small bursts, and then closing it. The log 34 opening the log file locked for small bursts, and then closing it. The log
27 object works by appending stored data to the gzip file until 1 MB has been 35 object works by appending stored (uncompressed) data to the gzip file until
28 accumulated. At that time, the stored data is compressed, and replaces the 36 1 MB has been accumulated. At that time, the stored data is compressed, and
29 uncompressed data in the file. The log file is truncated to its new size at 37 replaces the uncompressed data in the file. The log file is truncated to
30 that time. After closing, the log file is always valid gzip file that can 38 its new size at that time. After each write operation, the log file is a
31 decompressed to recover what was written. 39 valid gzip file that can decompressed to recover what was written.
32 40
33 A gzip header "extra" field contains two file offsets for appending. The 41 The gzlog operations can be interupted at any point due to an application or
34 first points to just after the last compressed data. The second points to 42 system crash, and the log file will be recovered the next time the log is
35 the last stored block in the deflate stream, which is empty. All of the 43 opened with gzlog_open().
36 data between those pointers is uncompressed.
37 */ 44 */
38 45
46#ifndef GZLOG_H
47#define GZLOG_H
48
49/* gzlog object type */
50typedef void gzlog;
51
39/* Open a gzlog object, creating the log file if it does not exist. Return 52/* Open a gzlog object, creating the log file if it does not exist. Return
40 NULL on error. Note that gzlog_open() could take a long time to return if 53 NULL on error. Note that gzlog_open() could take a while to complete if it
41 there is difficulty in locking the file. */ 54 has to wait to verify that a lock is stale (possibly for five minutes), or
42void *gzlog_open(char *path); 55 if there is significant contention with other instantiations of this object
43 56 when locking the resource. path is the prefix of the file names created by
44/* Write to a gzlog object. Return non-zero on error. This function will 57 this object. If path is "foo", then the log file will be "foo.gz", and
45 simply write data to the file uncompressed. Compression of the data 58 other auxiliary files will be created and destroyed during the process:
46 will not occur until gzlog_close() is called. It is expected that 59 "foo.dict" for a compression dictionary, "foo.temp" for a temporary (next)
47 gzlog_write() is used for a short message, and then gzlog_close() is 60 dictionary, "foo.add" for data being added or compressed, "foo.lock" for the
48 called. If a large amount of data is to be written, then the application 61 lock file, and "foo.repairs" to log recovery operations performed due to
49 should write no more than 1 MB at a time with gzlog_write() before 62 interrupted gzlog operations. A gzlog_open() followed by a gzlog_close()
50 calling gzlog_close() and then gzlog_open() again. */ 63 will recover a previously interrupted operation, if any. */
51int gzlog_write(void *log, char *data, size_t len); 64gzlog *gzlog_open(char *path);
52 65
53/* Close a gzlog object. Return non-zero on error. The log file is locked 66/* Write to a gzlog object. Return zero on success, -1 if there is a file i/o
54 until this function is called. This function will compress stored data 67 error on any of the gzlog files (this should not happen if gzlog_open()
55 at the end of the gzip file if at least 1 MB has been accumulated. Note 68 succeeded, unless the device has run out of space or leftover auxiliary
56 that the file will not be a valid gzip file until this function completes. 69 files have permissions or ownership that prevent their use), -2 if there is
57 */ 70 a memory allocation failure, or -3 if the log argument is invalid (e.g. if
58int gzlog_close(void *log); 71 it was not created by gzlog_open()). This function will write data to the
72 file uncompressed, until 1 MB has been accumulated, at which time that data
73 will be compressed. The log file will be a valid gzip file upon successful
74 return. */
75int gzlog_write(gzlog *log, void *data, size_t len);
76
77/* Force compression of any uncompressed data in the log. This should be used
78 sparingly, if at all. The main application would be when a log file will
79 not be appended to again. If this is used to compress frequently while
80 appending, it will both significantly increase the execution time and
81 reduce the compression ratio. The return codes are the same as for
82 gzlog_write(). */
83int gzlog_compress(gzlog *log);
84
85/* Close a gzlog object. Return zero on success, -3 if the log argument is
86 invalid. The log object is freed, and so cannot be referenced again. */
87int gzlog_close(gzlog *log);
88
89#endif