Main Page | Modules | Data Structures | File List | Data Fields | Globals

mar_c.h File Reference

The MAR API header file. More...

#include "mar_storage_c.h"
#include "mar_types_c.h"

Go to the source code of this file.

Typedefs

typedef mar_ * mar_t
 The meta archive handle type.


Functions

MAR_API int mar_copy (mar_t dst, mar_t src)
 Copy an existing meta archive.

MAR_API mar_t mar_create (void)
 Create an in-memory meta archive.

MAR_API mar_t mar_open (const char *path, int flags,...)
 Create or open a file-based meta archive.

MAR_API int mar_release (mar_t mar)
 Release meta archive handle.

MAR_API int mar_retain (mar_t mar)
 Retain additional reference to meta archive handle.

MAR_API int mar_removepairs (mar_t mar)
 Remove all pairs contained within meta archive.

MAR_API int mar_setpair (mar_t mar, const mar_pair_t *pair, size_t *ord)
 Set meta pair within meta archive.

MAR_API int mar_setmeta (mar_t mar, size_t ord, const void *data, size_t size)
 Set meta data within meta archive.

MAR_API int mar_unsetbykey (mar_t mar, const char *key, size_t *ord)
 Unset meta pair (by key) within meta archive.

MAR_API int mar_unsetbyord (mar_t mar, size_t ord)
 Unset meta pair (by ordinal) within meta archive.

MAR_API const void * mar_metabykey (mar_t mar, const char *key, size_t *size)
 Obtain meta data (by key) from meta archive.

MAR_API const void * mar_metabyord (mar_t mar, size_t ord, size_t *size)
 Obtain meta data (by ordinal) from meta archive.

MAR_API int mar_metapair (mar_t mar, mar_pair_t *pair, size_t ord)
 Obtain meta pair from meta archive.

MAR_API int mar_metapairs (mar_t mar, size_t *size)
 Obtain the number of pairs contained within meta archive.

MAR_API int mar_tokey (mar_t mar, mar_key_t key, size_t ord)
 Obtain key based on ordinal in meta archive.

MAR_API int mar_toord (mar_t mar, size_t *ord, const char *key)
 Obtain ordinal based on key in meta archive.

MAR_API int mar_insert (mar_t mar, const char *path)
 Insert user data from file into meta archive.

MAR_API ssize_t mar_read (mar_t mar, void *buf, size_t size)
 Read user data from meta archive.

MAR_API off_t mar_seek (mar_t mar, off_t offset, int whence)
 Reposition user data offset within meta archive.

MAR_API int mar_setuser (mar_t mar, const void *data, size_t size)
 Set user data within meta archive.

MAR_API int mar_sync (mar_t mar)
 Flush meta archive buffers.

MAR_API int mar_truncate (mar_t mar, size_t size)
 Truncate user data within meta archive.

MAR_API ssize_t mar_write (mar_t mar, const void *buf, size_t size)
 Write user data to meta archive.

MAR_API int mar_extract (mar_t mar, const char *path)
 Extract user data from meta archive into file.

MAR_API const void * mar_user (mar_t mar, size_t *size)
 Obtain user data from meta archive.

MAR_API int mar_usersize (mar_t mar, size_t *size)
 Obtain size of user data within meta archive.

MAR_API int mar_errno (void)
 Obtain last error number.


Detailed Description

The MAR API header file.

Definition in file mar_c.h.


Function Documentation

MAR_API int mar_copy mar_t  dst,
mar_t  src
 

Copy an existing meta archive.

Parameters:
dst A handle to the destination meta archive.
src A handle to the source meta archive.
Returns:
zero on success or -1 on failure, in which case mar_errno can be used to determine the error.
See also:
mar_retain.

MAR_API mar_t mar_create void   ) 
 

Create an in-memory meta archive.

Returns:
A handle to the newly created meta archive or NULL on failure, in which case mar_errno can be used to determine the error.
See also:
mar_open and mar_release.

MAR_API mar_t mar_open const char *  path,
int  flags,
... 
 

Create or open a file-based meta archive.

Parameters:
path A path to the file to be created or opened.
flags The flags used to create or open the file.
... The permissions used to create a new file. Required when the MAR_CREAT flag has been specified, otherwise ignored.
Returns:
A handle to the newly created meta archive or NULL on failure, in which case mar_errno can be used to determine the error.
See also:
mar_create and mar_release.

MAR_API int mar_release mar_t  mar  ) 
 

Release meta archive handle.

This function must be used to release handles allocated by either the mar_create or mar_open functions.

Parameters:
mar A handle to the meta archive to be released.
Returns:
zero on success or -1 on failure, in which case mar_errno can be used to determine the error.
See also:
mar_create, mar_open and mar_retain.

MAR_API int mar_retain mar_t  mar  ) 
 

Retain additional reference to meta archive handle.

Parameters:
mar A handle to the meta archive.
Returns:
zero on success or -1 on failure, in which case mar_errno can be used to determine the error.
See also:
mar_copy and mar_release.

MAR_API int mar_removepairs mar_t  mar  ) 
 

Remove all pairs contained within meta archive.

Parameters:
mar A handle to the meta archive.
Returns:
zero on success or -1 on failure, in which case mar_errno can be used to determine the error.
See also:
mar_unsetbykey and mar_unsetbyord.

MAR_API int mar_setpair mar_t  mar,
const mar_pair_t pair,
size_t *  ord
 

Set meta pair within meta archive.

Parameters:
mar A handle to the meta archive.
pair A pair specifying the key and a pointer to and size of the meta data.
ord An optional output parameter in which the ordinal of the meta pair would be returned.
Returns:
zero on success or -1 on failure, in which case mar_errno can be used to determine the error.
See also:
mar_setmeta.

MAR_API int mar_setmeta mar_t  mar,
size_t  ord,
const void *  data,
size_t  size
 

Set meta data within meta archive.

Parameters:
mar A handle to the meta archive.
ord The ordinal of an existing meta pair.
data A pointer to the meta data to be copied.
size The size of the meta data to be copied.
Returns:
zero on success or -1 on failure, in which case mar_errno can be used to determine the error.
See also:
mar_setpair.

MAR_API int mar_unsetbykey mar_t  mar,
const char *  key,
size_t *  ord
 

Unset meta pair (by key) within meta archive.

Parameters:
mar A handle to the meta archive.
key The key of the meta pair.
ord An optional output parameter in which the ordinal of the meta pair would be returned.
Returns:
zero on success, MAR_NOMATCH if no matching pair exists, or -1 on failure, in which case mar_errno can be used to determine the error.
See also:
mar_removepairs, mar_unsetbyord and mar_tokey.

MAR_API int mar_unsetbyord mar_t  mar,
size_t  ord
 

Unset meta pair (by ordinal) within meta archive.

Parameters:
mar A handle to the meta archive.
ord The ordinal of the meta pair.
Returns:
zero on success, MAR_NOMATCH if no matching pair exists, or -1 on failure, in which case mar_errno can be used to determine the error.
See also:
mar_removepairs, mar_unsetbykey and mar_toord.

MAR_API const void* mar_metabykey mar_t  mar,
const char *  key,
size_t *  size
 

Obtain meta data (by key) from meta archive.

Parameters:
mar A handle to the meta archive.
key The key of the meta pair.
size An optional output parameter in which the size of the meta data would be returned.
Returns:
A pointer to the meta data or NULL on failure, in which case mar_errno can be used to determine the error.
See also:
mar_metabyord, mar_metapair and mar_tokey.

MAR_API const void* mar_metabyord mar_t  mar,
size_t  ord,
size_t *  size
 

Obtain meta data (by ordinal) from meta archive.

Parameters:
mar A handle to the meta archive.
ord The zero-based ordinal of the meta pair.
size An optional output parameter in which the size of the meta data would be returned.
Returns:
A pointer to the meta data or NULL on failure, in which case mar_errno can be used to determine the error.
See also:
mar_metabykey, mar_metapair and mar_toord.

MAR_API int mar_metapair mar_t  mar,
mar_pair_t pair,
size_t  ord
 

Obtain meta pair from meta archive.

Parameters:
mar A handle to the meta archive.
pair The output parameter in which the pair will be returned.
ord The zero-based ordinal of the meta pair.
Returns:
zero on success, MAR_NOMATCH if no matching pair exists, or -1 on failure, in which case mar_errno can be used to determine the error.
See also:
mar_metabykey, mar_metabyord and mar_metapairs.

MAR_API int mar_metapairs mar_t  mar,
size_t *  size
 

Obtain the number of pairs contained within meta archive.

Parameters:
mar A handle to the meta archive.
size The output parameter in which the number of pairs will be returned.
Returns:
zero on success or -1 on failure, in which case mar_errno can be used to determine the error.
See also:
mar_metapair.

MAR_API int mar_tokey mar_t  mar,
mar_key_t  key,
size_t  ord
 

Obtain key based on ordinal in meta archive.

Parameters:
mar A handle to the meta archive.
key The output parameter in which the key will be returned.
ord The zero-based ordinal of the key to be returned.
Returns:
zero on success, MAR_NOMATCH if no matching pair exists, or -1 on failure, in which case mar_errno can be used to determine the error.
See also:
mar_unsetbykey, mar_metabykey and mar_toord.

MAR_API int mar_toord mar_t  mar,
size_t *  ord,
const char *  key
 

Obtain ordinal based on key in meta archive.

Parameters:
mar A handle to the meta archive.
ord The output parameter in which the ordinal will be returned.
key The key of the meta pair.
Returns:
zero on success, MAR_NOMATCH if no matching pair exists, or -1 on failure, in which case mar_errno can be used to determine the error.
See also:
mar_unsetbyord, mar_metabyord and mar_tokey.

MAR_API int mar_insert mar_t  mar,
const char *  path
 

Insert user data from file into meta archive.

Parameters:
mar A handle to the meta archive.
path A path to the file from which the user data is read.
Returns:
zero on success or -1 on failure, in which case mar_errno can be used to determine the error.
See also:
mar_setuser and mar_write.

MAR_API ssize_t mar_read mar_t  mar,
void *  buf,
size_t  size
 

Read user data from meta archive.

Parameters:
mar A handle to the meta archive.
buf The output buffer to which the user data will be copied.
size The number of bytes to be read.
Returns:
The number of bytes actually read or zero to signal end-of-file. -1 is returned on failure, in which case mar_errno can be used to determine the error.
See also:
mar_seek, mar_extract and mar_user.

MAR_API off_t mar_seek mar_t  mar,
off_t  offset,
int  whence
 

Reposition user data offset within meta archive.

Parameters:
mar A handle to the meta archive.
offset The offset calculated according to the Seek Whence "whence" directive.
whence The whence directive.
Returns:
The resulting offset location in bytes from the beginning of the user data or -1 on failure, in which case mar_errno can be used to determine the error.
See also:
mar_read and mar_write.

MAR_API int mar_setuser mar_t  mar,
const void *  data,
size_t  size
 

Set user data within meta archive.

Parameters:
mar A handle to the meta archive.
data A pointer to the user data to be copied.
size The size of the user data to be copied.
Returns:
zero on success or -1 on failure, in which case mar_errno can be used to determine the error.
See also:
mar_insert and mar_write.

MAR_API int mar_sync mar_t  mar  ) 
 

Flush meta archive buffers.

Parameters:
mar A handle to the meta archive.
Returns:
zero on success or -1 on failure, in which case mar_errno can be used to determine the error.

MAR_API int mar_truncate mar_t  mar,
size_t  size
 

Truncate user data within meta archive.

Parameters:
mar A handle to the meta archive.
size The size to which the user data will be truncated.
Returns:
zero on success or -1 on failure, in which case mar_errno can be used to determine the error.

MAR_API ssize_t mar_write mar_t  mar,
const void *  buf,
size_t  size
 

Write user data to meta archive.

Parameters:
mar A handle to the meta archive.
buf The buffer from which the user data will be copied.
size The number of bytes to be written.
Returns:
The number of bytes actually written or -1 on failure, in which case mar_errno can be used to determine the error.
See also:
mar_insert, mar_seek and mar_setuser.

MAR_API int mar_extract mar_t  mar,
const char *  path
 

Extract user data from meta archive into file.

Parameters:
mar A handle to the meta archive.
path A path to the file to which the user data will be written.
Returns:
zero on success or -1 on failure, in which case mar_errno can be used to determine the error.
See also:
mar_read and mar_user.

MAR_API const void* mar_user mar_t  mar,
size_t *  size
 

Obtain user data from meta archive.

Parameters:
mar A handle to the meta archive.
size An optional output parameter in which the size of the user data would be returned.
Returns:
A pointer to the user data or NULL on failure, in which case mar_errno can be used to determine the error.
See also:
mar_read, mar_extract and mar_usersize.

MAR_API int mar_usersize mar_t  mar,
size_t *  size
 

Obtain size of user data within meta archive.

Parameters:
mar A handle to the meta archive.
size The output parameter in which the size of the user data will be returned.
Returns:
zero on success or -1 on failure, in which case mar_errno can be used to determine the error.
See also:
mar_user.

MAR_API int mar_errno void   ) 
 

Obtain last error number.

Returns:
the last error number or zero if no error has occurred.


Generated on Tue Dec 14 16:10:54 2004 for mar by doxygen 1.3.6