• Main Page
  • Related Pages
  • Modules
  • Namespaces
  • Data Structures
  • Files
  • File List
  • Globals

contrib/zlib/examples/gzlog.h

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

Generated on Wed Oct 20 2010 11:12:17 for APBS by  doxygen 1.7.2