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