NAME(S)

     Chunk_OpenFile,
     Chunk_CloseFile,
     Chunk_WriteHeader,
     Chunk_ReadHeader,
     Chunk_ReadString,
     Chunk_ReadRewind,
     Chunk_FindIndex,
     Chunk_FindType,


SYNOPSIS

     tChunkFileState* Chunk_OpenFile (char* name, char* options)

     int Chunk_CloseFile (tChunkFileState* cf)

     int Chunk_WriteHeader(tChunkFileState* cf, int32 type, char*
     tagStr)

     int  Chunk_ReadHeader  (tChunkFileState*  cf,  tChunkHeader*
     hdr)

     char* Chunk_ReadString (tChunkFileState* cf, char* outBuf)

     int Chunk_ReadRewind (tChunkFileState* cf)

     int Chunk_FindIndex (tChunkFileState* cf, int  idx,  tChunk-
     Header* hdr)

     int Chunk_FindType (tChunkFileState* cf, int32 type, tChunk-
     Header* hdr)


DESCRIPTION

           Provides a simple IFF (an existing chunkfile standard)
           like chunk-file abstraction.  Chunk files consist of a
     short
           header and a sequence of chunks.

           Each chunk  consists  of  a  twelve  byte  header,  an
     optional
           variable length string and a data  section.   A  chunk
     header
           contains the string and data size and the type  ID  of
     the chunk.
           The type ID is a simple 32bit unsigned int (but it  is
     usually
           viewed as a sequence of  four  characters.   The  data
     section is
           simply binary data encapsilated within the chunk.  The
     string
           can be used to store chunk naming information (or any-
     thing
           else).  The hope is that it will  prove  usefull  when

     building Tcl
           interfaces to chunk files.



  tChunkFileState*
  Chunk_OpenFile (char* name, char* options)
     Opens the given file and returns a  ChunkFileState  used  by
     other  ChunkFile operations.  The options string may contain
     any of the following characters in any order:
            r or R - file opened for reading (true by default)
            w or W - file opened for writing
            c or C - file created if not found.

  int
  Chunk_CloseFile (tChunkFileState* cf)
     Closes the given chunk file.  This function MUST  be  called
     if chunks have been added to the file.

  int
  Chunk_WriteHeader(tChunkFileState*  cf,   int32   type,   char*
     tagStr)
     Appends a new header to the end  of  the  chunk  file.   The
     write  head  is  left  positioned after the header, to allow
     chunk data writes, using "write(cf->fd,buf,bufSz)".

     Note: When a new header is writen to the chunk file  or  the
     file is
            closed, the size of the previous chunk can be  deter-
     mined
            automatically.  This data is computed and writen into
     the
            previous header.  This allows very  free  form  chunk
     data
            definition, using any number of write calls.

  int
  Chunk_ReadHeader (tChunkFileState* cf, tChunkHeader* hdr)
     Advances to the next chunk in  the  file.   Hdr  is  set  to
     header  info  for  the chunk.  This function leaves the read
     head at the beginning of the chunk data.  To read this  data
     call:
             read(cf->fd,&buffer,hdr->chunkSize)

     Returns:  0 iff success
                    kChunk_EndOfFile if EOF reached.

  char*
  Chunk_ReadString (tChunkFileState* cf, char* outBuf)
     Reads the current chunk's string.   Assumes  that  you  have
     already  called a header reading function.  outBuf is filled
     with the string.  It is assumed  to  be  large  enough!!  It
     should  be (header->stringSize +1) bytes or larger!  If out-
     Buf == NULL, then a new buffer is malloc()ed for the string.

     Returns:  NULL if error
                    theString

  int
  Chunk_ReadRewind (tChunkFileState* cf)
     Causes the next read header operation to  return  the  first
     header in the file.  Also effects Chunk_FindType().

     Returns:  0    iff success

  int
  Chunk_FindIndex (tChunkFileState* cf, int idx, tChunkHeader*
     Finds the idx's chunk in the file,  numbered  from  0.   The
     header  is  stored  in hdr.  Leaves read head at chunk data.
     See Chunk_ReadHeader().

     Returns:  0 iff success
                    kChunk_ErrIndexRange     if idx is too small
               kChunk_EndOfFile    if idx too large

  int
  Chunk_FindType (tChunkFileState* cf, int32 type, tChunkHeader*
     Finds the 1st chunk of the given type in the file,  starting
     from  the current start position.  Leaves read head at chunk
     data.  See Chunk_ReadHeader() and Chunk_FindIndex()

     Returns:  0 iff success
               kChunk_EndOfFile    if idx too large


AUTHOR

     Eric14@cs.berkeley.edu