Changeset 21a750bb in rtems for cpukit/zlib


Ignore:
Timestamp:
Apr 25, 2008, 5:40:02 PM (12 years ago)
Author:
Ralf Corsepius <ralf.corsepius@…>
Branches:
4.10, 4.11, master
Children:
d42bd2f
Parents:
13d404a
Message:

Import from zlib-1.2.4

File:
1 edited

Legend:

Unmodified
Added
Removed
  • cpukit/zlib/examples/gzlog.h

    r13d404a r21a750bb  
    11/* gzlog.h
    2   Copyright (C) 2004 Mark Adler, all rights reserved
    3   version 1.0, 26 Nov 2004
     2  Copyright (C) 2004, 2008 Mark Adler, all rights reserved
     3  version 2.0, 25 Apr 2008
    44
    55  This software is provided 'as-is', without any express or implied
     
    2222 */
    2323
     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
    2432/*
    2533   The gzlog object allows writing short messages to a gzipped log file,
    2634   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
    28    accumulated.  At that time, the stored data is compressed, and replaces the
    29    uncompressed data in the file.  The log file is truncated to its new size at
    30    that time.  After closing, the log file is always valid gzip file that can
    31    decompressed to recover what was written.
     35   object works by appending stored (uncompressed) data to the gzip file until
     36   1 MB has been accumulated.  At that time, the stored data is compressed, and
     37   replaces the uncompressed data in the file.  The log file is truncated to
     38   its new size at that time.  After each write operation, the log file is a
     39   valid gzip file that can decompressed to recover what was written.
    3240
    33    A gzip header "extra" field contains two file offsets for appending.  The
    34    first points to just after the last compressed data.  The second points to
    35    the last stored block in the deflate stream, which is empty.  All of the
    36    data between those pointers is uncompressed.
     41   The gzlog operations can be interupted at any point due to an application or
     42   system crash, and the log file will be recovered the next time the log is
     43   opened with gzlog_open().
    3744 */
    3845
     46#ifndef GZLOG_H
     47#define GZLOG_H
     48
     49/* gzlog object type */
     50typedef void gzlog;
     51
    3952/* 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
    41    there is difficulty in locking the file. */
    42 void *gzlog_open(char *path);
     53   NULL on error.  Note that gzlog_open() could take a while to complete if it
     54   has to wait to verify that a lock is stale (possibly for five minutes), or
     55   if there is significant contention with other instantiations of this object
     56   when locking the resource.  path is the prefix of the file names created by
     57   this object.  If path is "foo", then the log file will be "foo.gz", and
     58   other auxiliary files will be created and destroyed during the process:
     59   "foo.dict" for a compression dictionary, "foo.temp" for a temporary (next)
     60   dictionary, "foo.add" for data being added or compressed, "foo.lock" for the
     61   lock file, and "foo.repairs" to log recovery operations performed due to
     62   interrupted gzlog operations.  A gzlog_open() followed by a gzlog_close()
     63   will recover a previously interrupted operation, if any. */
     64gzlog *gzlog_open(char *path);
    4365
    44 /* Write to a gzlog object.  Return non-zero on error.  This function will
    45    simply write data to the file uncompressed.  Compression of the data
    46    will not occur until gzlog_close() is called.  It is expected that
    47    gzlog_write() is used for a short message, and then gzlog_close() is
    48    called.  If a large amount of data is to be written, then the application
    49    should write no more than 1 MB at a time with gzlog_write() before
    50    calling gzlog_close() and then gzlog_open() again. */
    51 int gzlog_write(void *log, char *data, size_t len);
     66/* Write to a gzlog object.  Return zero on success, -1 if there is a file i/o
     67   error on any of the gzlog files (this should not happen if gzlog_open()
     68   succeeded, unless the device has run out of space or leftover auxiliary
     69   files have permissions or ownership that prevent their use), -2 if there is
     70   a memory allocation failure, or -3 if the log argument is invalid (e.g. if
     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);
    5276
    53 /* Close a gzlog object.  Return non-zero on error.  The log file is locked
    54    until this function is called.  This function will compress stored data
    55    at the end of the gzip file if at least 1 MB has been accumulated.  Note
    56    that the file will not be a valid gzip file until this function completes.
    57  */
    58 int gzlog_close(void *log);
     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
Note: See TracChangeset for help on using the changeset viewer.