#include "sf3.h"

Include dependency graph for sf3_lib.h:

Macros
#define	SF3_EXPORT

Typedefs
typedef void *	sf3_handle
	Opaque representation of a file handle.

Enumerations
enum	sf3_open_mode { SF3_OPEN_READ_ONLY = 0 , SF3_OPEN_READ_WRITE = 1 }

enum	sf3_error { SF3_OK = 0 , SF3_OPEN_FAILED , SF3_OUT_OF_MEMORY , SF3_MMAP_FAILED , SF3_INVALID_HANDLE , SF3_WRITE_FAILED , SF3_INVALID_FILE }

Functions
SF3_EXPORT const char *	sf3_strerror (enum sf3_error error)
	Return a string representation of the error code.

SF3_EXPORT int	sf3_tell (const char *path)

SF3_EXPORT int	sf3_open (const char path, enum sf3_open_mode mode, sf3_handle handle)

SF3_EXPORT void	sf3_close (sf3_handle handle)

SF3_EXPORT void *	sf3_data (sf3_handle handle, size_t *size)

SF3_EXPORT int	sf3_create (void addr, size_t size, sf3_handle handle)

SF3_EXPORT int	sf3_write (const char *path, sf3_handle handle)

Variables
SF3_EXPORT void (	sf3_calloc )(size_t num, size_t size)

SF3_EXPORT void(*	sf3_free )(void *ptr)

Macro Definition Documentation

◆ SF3_EXPORT

#define SF3_EXPORT

Definition at line 27 of file sf3_lib.h.

Typedef Documentation

◆ sf3_handle

typedef void* sf3_handle

Opaque representation of a file handle.

Definition at line 60 of file sf3_lib.h.

Enumeration Type Documentation

◆ sf3_error

enum SF3_EXPORT enum sf3_error sf3_error ( )

Return the error code. This is thread local.

Enumerator
SF3_OK	No error has occurred.
SF3_OPEN_FAILED	The call to open failed. The file may not exist or you may lack the necessary permissions.
SF3_OUT_OF_MEMORY	A memory allocation failed.
SF3_MMAP_FAILED	The file failed to map into memory.
SF3_INVALID_HANDLE	An invalid sf3_handle was passed.
SF3_WRITE_FAILED	The file write operation failed.
SF3_INVALID_FILE	The file is not a valid SF3 file.

Definition at line 41 of file sf3_lib.h.

◆ sf3_open_mode

enum sf3_open_mode

Enumerator
SF3_OPEN_READ_ONLY	Open the file for reading only.
SF3_OPEN_READ_WRITE	Open the file for reading and writing. Note however that if you write into the memory of the file, it is not guaranteed that other applications will be able to see the changes until after sf3_write has returned successfully.

Definition at line 31 of file sf3_lib.h.

Function Documentation

◆ sf3_close()

SF3_EXPORT void sf3_close ( sf3_handle handle )

Closes the file handle.

After closing the handle is discarded and calling any function with it leads to undefined behaviour.

◆ sf3_create()

SF3_EXPORT int sf3_create	(	void *	addr,
		size_t	size,
		sf3_handle *	handle
	)

Create a handle from a given SF3 file payload in memory.

This may be useful if you want to call sf3_write to serialize the SF3 file back out to a file. Note that the SIZE here should be the size of the memory block at ADDR, and does not necessarily have to correspond to the size of the file contents (meaning you can over-allocate). The size of the file contents are computed automatically when sf3_write is called.

◆ sf3_data()

SF3_EXPORT void * sf3_data	(	sf3_handle	handle,
		size_t *	size
	)

Returns the address of the SF3 file payload and its size.

The size parameter may be a null pointer, in which case the size is not returned.

This may fail if the handle is invalid, in which case a null pointer is returned.

◆ sf3_open()

SF3_EXPORT int sf3_open	(	const char *	path,
		enum sf3_open_mode	mode,
		sf3_handle *	handle
	)

Opens the SF3 file at the given path.

If successful returns the format ID and stores the handle in the handle argument. You can then use sf3_data to retrieve the actual sf3 file address and size. This will also already call sf3_check for you, though not sf3_verify.

If the file open fails, the application is out of memory, or the file is not a valid SF3 file, zero is returned instead.

◆ sf3_strerror()

SF3_EXPORT const char * sf3_strerror ( enum sf3_error error )

Return a string representation of the error code.

◆ sf3_tell()

SF3_EXPORT int sf3_tell ( const char * path )

Returns the sf3_format_id of the file or 0 on failure.

The failure can occur because the path is inaccessible, there is no more memory available, or the file is not an actual SF3 file. Note that this will not perform a CRC32 checksum verification of the file.

◆ sf3_write()

SF3_EXPORT int sf3_write	(	const char *	path,
		sf3_handle	handle
	)

Write the SF3 file back out to a file.

PATH may be a null pointer if the handle was obtained through sf3_open with mode set to SF3_OPEN_READ_WRITE. In that case this will write the file header back into memory with a freshly computed CRC32 checksum, and then call msync to flush the file.

If the PATH is not a null pointer, the SF3 file is written out to the file at that path. As part of this the SF3 header is written fresh, including computing a fresh CRC32 checksum. The memory of the file is not modified, however. If the file at PATH already exists, it is truncated to the size of the SF3 file after writing.

Variable Documentation

◆ sf3_calloc

SF3_EXPORT void ( sf3_calloc) (size_t num, size_t size)	(	size_t	num,
		size_t	size
	)

extern

Allocates a new block of memory.

sf3_calloc must return either 0 or a pointer to a memory region that is num*size octets large. It may only return 0 if the allocation failed for some reason, such as an out of memory condition. The returned memory region must be cleared, meaning all addressable octets within the region must be 0. The memory region also must not overlap with any other allocated memory regions.

◆ sf3_free

SF3_EXPORT void(* sf3_free) (void *ptr) ( void * ptr )