diff options
author | Mark Adler <madler@alumni.caltech.edu> | 2011-09-09 23:26:40 -0700 |
---|---|---|
committer | Mark Adler <madler@alumni.caltech.edu> | 2011-09-09 23:26:40 -0700 |
commit | f6194ef39af5864f792412460c354cc339dde7d1 (patch) | |
tree | 5ea1e6849128e9b2194c66ee3d82afa36b4ac07c /examples/gzlog.h | |
parent | 639be997883d9016baaf46017a2802b2ce1698bd (diff) | |
download | zlib-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.h | 93 |
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 */ | ||
50 | typedef 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 |
42 | void *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. */ |
51 | int gzlog_write(void *log, char *data, size_t len); | 64 | gzlog *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 |
58 | int 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. */ | ||
75 | int 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(). */ | ||
83 | int 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. */ | ||
87 | int gzlog_close(gzlog *log); | ||
88 | |||
89 | #endif | ||