mspack_system Struct Reference

A structure which abstracts file I/O and memory management. More...

#include <mspack.h>

Collaboration diagram for mspack_system:

Data Fields
struct mspack_file *(*	open )(struct mspack_system *self, const char *filename, int mode)
	Opens a file for reading, writing, appending or updating. More...
void(*	close )(struct mspack_file *file)
	Closes a previously opened file. More...
int(*	read )(struct mspack_file *file, void *buffer, int bytes)
	Reads a given number of bytes from an open file. More...
int(*	write )(struct mspack_file *file, void *buffer, int bytes)
	Writes a given number of bytes to an open file. More...
int(*	seek )(struct mspack_file *file, off_t offset, int mode)
	Seeks to a specific file offset within an open file. More...
off_t(*	tell )(struct mspack_file *file)
	Returns the current file position (in bytes) of the given file. More...
void(*	message )(struct mspack_file *file, const char *format,...)
	Used to send messages from the library to the user. More...
void *(*	alloc )(struct mspack_system *self, size_t bytes)
	Allocates memory. More...
void(*	free )(void *ptr)
	Frees memory. More...
void(*	copy )(void *src, void *dest, size_t bytes)
	Copies from one region of memory to another. More...
void *	null_ptr
	A null pointer to mark the end of mspack_system. More...

Detailed Description

A structure which abstracts file I/O and memory management.

The library always uses the mspack_system structure for interaction with the file system and to allocate, free and copy all memory. It also uses it to send literal messages to the library user.

When the library is compiled normally, passing NULL to a compressor or decompressor constructor will result in a default mspack_system being used, where all methods are implemented with the standard C library. However, all constructors support being given a custom created mspack_system structure, with the library user's own methods. This allows for more abstract interaction, such as reading and writing files directly to memory, or from a network socket or pipe.

Implementors of an mspack_system structure should read all documentation entries for every structure member, and write methods which conform to those standards.

Field Documentation

alloc

void*(* mspack_system::alloc) (struct mspack_system *self, size_t bytes)

Allocates memory.

Parameters

self	a self-referential pointer to the mspack_system structure whose alloc() method is being called.
bytes	the number of bytes to allocate

Returns

a pointer to the requested number of bytes, or NULL if not enough memory is available

See also

free()

close

void(* mspack_system::close) (struct mspack_file *file)

Closes a previously opened file.

If any memory was allocated for this particular file handle, it should be freed at this time.

Parameters

file	the file to close

See also

open()

copy

void(* mspack_system::copy) (void *src, void *dest, size_t bytes)

Copies from one region of memory to another.

The regions of memory are guaranteed not to overlap, are usually less than 256 bytes, and may not be aligned. Please note that the source parameter comes before the destination parameter, unlike the standard C function memcpy().

Parameters

src	the region of memory to copy from
dest	the region of memory to copy to
bytes	the size of the memory region, in bytes

free

void(* mspack_system::free) (void *ptr)

Frees memory.

Parameters

ptr	the memory to be freed. NULL is accepted and ignored.

See also

alloc()

message

void(* mspack_system::message) (struct mspack_file *file, const char *format,...)

Used to send messages from the library to the user.

Occasionally, the library generates warnings or other messages in plain english to inform the human user. These are informational only and can be ignored if not wanted.

Parameters

file	may be a file handle returned from open() if this message pertains to a specific open file, or NULL if not related to a specific file.
format	a printf() style format string. It does NOT include a trailing newline.

See also

open()

null_ptr

void* mspack_system::null_ptr

A null pointer to mark the end of mspack_system.

It must equal NULL.

Should the mspack_system structure extend in the future, this NULL will be seen, rather than have an invalid method pointer called.

open

struct mspack_file*(* mspack_system::open) (struct mspack_system *self, const char *filename, int mode)

Opens a file for reading, writing, appending or updating.

Parameters

self	a self-referential pointer to the mspack_system structure whose open() method is being called. If this pointer is required by close(), read(), write(), seek() or tell(), it should be stored in the result structure at this time.
filename	the file to be opened. It is passed directly from the library caller without being modified, so it is up to the caller what this parameter actually represents.
mode	one of MSPACK_SYS_OPEN_READ (open an existing file for reading), MSPACK_SYS_OPEN_WRITE (open a new file for writing), MSPACK_SYS_OPEN_UPDATE (open an existing file for reading/writing from the start of the file) or MSPACK_SYS_OPEN_APPEND (open an existing file for reading/writing from the end of the file)

Returns

a pointer to a mspack_file structure. This structure officially contains no members, its true contents are up to the mspack_system implementor. It should contain whatever is needed for other mspack_system methods to operate. Returning the NULL pointer indicates an error condition.

See also

close(), read(), write(), seek(), tell(), message()

read

int(* mspack_system::read) (struct mspack_file *file, void *buffer, int bytes)

Reads a given number of bytes from an open file.

Parameters

file	the file to read from
buffer	the location where the read bytes should be stored
bytes	the number of bytes to read from the file.

Returns

the number of bytes successfully read (this can be less than the number requested), zero to mark the end of file, or less than zero to indicate an error. The library does not "retry" reads and assumes short reads are due to EOF, so you should avoid returning short reads because of transient errors.

See also

open(), write()

seek

int(* mspack_system::seek) (struct mspack_file *file, off_t offset, int mode)

Seeks to a specific file offset within an open file.

Sometimes the library needs to know the length of a file. It does this by seeking to the end of the file with seek(file, 0, MSPACK_SYS_SEEK_END), then calling tell(). Implementations may want to make a special case for this.

Due to the potentially varying 32/64 bit datatype off_t on some architectures, the MSPACK_SYS_SELFTEST macro MUST be used before using the library. If not, the error caused by the library passing an inappropriate stackframe to seek() is subtle and hard to trace.

Parameters

file	the file to be seeked
offset	an offset to seek, measured in bytes
mode	one of MSPACK_SYS_SEEK_START (the offset should be measured from the start of the file), MSPACK_SYS_SEEK_CUR (the offset should be measured from the current file offset) or MSPACK_SYS_SEEK_END (the offset should be measured from the end of the file)

Returns

zero for success, non-zero for an error

See also

open(), tell()

tell

off_t(* mspack_system::tell) (struct mspack_file *file)

Returns the current file position (in bytes) of the given file.

Parameters

file	the file whose file position is wanted

Returns

the current file position of the file

See also

open(), seek()

write

int(* mspack_system::write) (struct mspack_file *file, void *buffer, int bytes)

Writes a given number of bytes to an open file.

Parameters

file	the file to write to
buffer	the location where the written bytes should be read from
bytes	the number of bytes to write to the file.

Returns

the number of bytes successfully written, this can be less than the number requested. Zero or less can indicate an error where no bytes at all could be written. All cases where less bytes were written than requested are considered by the library to be an error.

See also

open(), read()

---

The documentation for this struct was generated from the following file:

• mspack.h