libmspack

- Main Page
- Data Structures
- Files

- Data Structures
- Data Structure Index
- Data Fields

Data Fields
mspack_system Struct Reference

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

`#include <mspack.h>`

## Data Fields

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

## 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

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()

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()

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

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

Frees memory.

Parameters:

  ptr | the memory to be freed.

See also:
  alloc()

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()

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.

struct mspack_file*(* mspack_system::open)(struct mspack_system *self, const char *filename, int mode)`[read]`

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()

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.

See also:
  open(), write()

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()

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()

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

All Data Structures Files Functions Variables Defines