Lumiera  0.pre.03
»edityourfreedom«
fileheader.h File Reference

Go to the source code of this file.

Description

Common header format to identify various kinds of files.

Lumiera creates some files on itself, caches, indexes and so on. Here we define a unified header format for identifying and handling these files.

Most of this files store binary data in host order for performance reasons and are not yet intended to be transfered between computers. While the transferability depends on the concrete implementation later and is not constrained here.

Definition in file fileheader.h.

#include "lib/error.h"
#include "backend/file.h"
#include <nobug.h>
#include <semaphore.h>

Classes

struct  lumiera_fileheader_raw
 A basic file header On-Disk representation starts with 32 bytes identifying the file. More...
 
struct  lumiera_fileheader
 A file header object encapsulates the underlying mmap object which keeps the raw header data in memory and and the dereferenced thereof. More...
 

Typedefs

typedef lumiera_fileheader * LumieraFileheader
 
typedef lumiera_fileheader_raw * LumieraFileheaderRaw
 

Macros

#define LUMIERA_FILEHEADER_ENDIANMAGIC
 
#define LUMIERA_FILEHEADER_FLAG_CLEAN
 File header flags are chars to support debugging and inspection, these add another human readable line to the header. More...
 
#define LUMIERA_FILEHEADER_FLAG_ENDIANESS
 check for host order endianess More...
 
#define LUMIERA_PACKED
 

Functions

 LUMIERA_ERROR_DECLARE (FILEHEADER_NOWRITE)
 
 LUMIERA_ERROR_DECLARE (FILEHEADER_HEADER)
 
 LUMIERA_ERROR_DECLARE (FILEHEADER_FLAGS)
 
 LUMIERA_ERROR_DECLARE (FILEHEADER_FLAGSPACE)
 
 LUMIERA_ERROR_DECLARE (FILEHEADER_ENDIANESS)
 
void lumiera_fileheader_close (LumieraFileheader self, const char *flags_add)
 Closes a previously created or opened file header. More...
 
lumiera_fileheader lumiera_fileheader_create (LumieraFile file, char *fourcc, int version, size_t size, const char *flags)
 Create a file header on a file open for writing. More...
 
LumieraFileheader lumiera_fileheader_flags_clear (LumieraFileheader self, const char *flags)
 Clear flags if present. More...
 
LumieraFileheader lumiera_fileheader_flags_set (LumieraFileheader self, const char *flags)
 Sets flags if not already set. More...
 
int lumiera_fileheader_flags_validate (LumieraFileheader self, const char *expected, const char *unexpected)
 check if all flags given from some sets are either set or not. More...
 
lumiera_fileheader lumiera_fileheader_open (LumieraFile file, char *fourcc, size_t size, const char *flags_expected, const char *flags_remove)
 Open an existing file header. More...
 
int lumiera_fileheader_version (LumieraFileheader self)
 Queries the version of a file header. More...
 

Typedef Documentation

◆ LumieraFileheader

typedef lumiera_fileheader* LumieraFileheader

Definition at line 51 of file fileheader.h.

◆ LumieraFileheaderRaw

typedef lumiera_fileheader_raw* LumieraFileheaderRaw

Definition at line 54 of file fileheader.h.

Macro Definition Documentation

◆ LUMIERA_FILEHEADER_ENDIANMAGIC

#define LUMIERA_FILEHEADER_ENDIANMAGIC

Definition at line 48 of file fileheader.h.

Referenced by lumiera_fileheader_create(), and lumiera_fileheader_open().

◆ LUMIERA_PACKED

#define LUMIERA_PACKED

Definition at line 67 of file fileheader.h.

◆ LUMIERA_FILEHEADER_FLAG_CLEAN

#define LUMIERA_FILEHEADER_FLAG_CLEAN

File header flags are chars to support debugging and inspection, these add another human readable line to the header.

file is clean

Definition at line 105 of file fileheader.h.

Referenced by TEST().

◆ LUMIERA_FILEHEADER_FLAG_ENDIANESS

#define LUMIERA_FILEHEADER_FLAG_ENDIANESS

check for host order endianess

Definition at line 108 of file fileheader.h.

Referenced by lumiera_fileheader_open(), and TEST().


Class Documentation

◆ lumiera_fileheader_raw_struct

struct lumiera_fileheader_raw_struct
Class Members
char fourcc[4] four character codes identifying this file type
char version[3] decimal digits, right bound space filled, denoting the file version, 0 is reserved for experimental things
char newline1 always '
'
char meta[15] free form string, comment or so on, initialised to spaces
char newline2 always '
'
char flags[6] Initialised to spaces, flags are single chars, unsorted.
char newline3 always '
'
char null always '\0'
uint64_t endianess_mark
+ Collaboration diagram for lumiera_fileheader_raw:

◆ lumiera_fileheader_struct

struct lumiera_fileheader_struct
Class Members
LumieraFileheaderRaw header
LumieraMMap map
+ Collaboration diagram for lumiera_fileheader:

Function Documentation

◆ LUMIERA_ERROR_DECLARE() [1/5]

LUMIERA_ERROR_DECLARE ( FILEHEADER_NOWRITE  )

◆ LUMIERA_ERROR_DECLARE() [2/5]

LUMIERA_ERROR_DECLARE ( FILEHEADER_HEADER  )

◆ LUMIERA_ERROR_DECLARE() [3/5]

LUMIERA_ERROR_DECLARE ( FILEHEADER_FLAGS  )

◆ LUMIERA_ERROR_DECLARE() [4/5]

LUMIERA_ERROR_DECLARE ( FILEHEADER_FLAGSPACE  )

◆ LUMIERA_ERROR_DECLARE() [5/5]

LUMIERA_ERROR_DECLARE ( FILEHEADER_ENDIANESS  )

◆ lumiera_fileheader_create()

lumiera_fileheader lumiera_fileheader_create ( LumieraFile  file,
char *  fourcc,
int  version,
size_t  size,
const char *  flags 
)

Create a file header on a file open for writing.

This overwrites any existing date, take care. The created file header is mmaped into memory and must be closed after use. The File should be locked for operations on the file header.

Parameters
fileThe file on which to create the header.
fourccpointer to a string of length 4
versionversion number for the header (should be incremented after changes) the value '0' is reserved for experimental versions.
sizeThe actual size of all header data, including following format specific data.
flagsinitial flags which should be set (don't include CLEAN here, should be set on close)
Returns
A lumiera_fileheader object by value, .header and .map are set to NULL on error.

Definition at line 51 of file fileheader.c.

References for(), LUMIERA_ERROR_SET_CRITICAL, lumiera_file_checkflags(), LUMIERA_FILEHEADER_ENDIANMAGIC, lumiera_fileheader_flags_set(), lumiera_mmap_address(), lumiera_mmap_new_exact(), and NULL.

Referenced by TEST().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ lumiera_fileheader_open()

lumiera_fileheader lumiera_fileheader_open ( LumieraFile  file,
char *  fourcc,
size_t  size,
const char *  flags_expected,
const char *  flags_remove 
)

Open an existing file header.

The underlying file might be readonly. The opened file header is mmaped into memory and must be closed after use. The File should be locked for operations on the file header.

Parameters
fileThe file on which to open the header.
fourccpointer to a string of length 4 with the expected identifier for the file
sizeThe actual size of all header data, including following format specific data
flags_expectedexpect this flags being set
flags_removeremove this flags when opening
Returns
A lumiera_fileheader object by value, .header and .map are set to NULL on error.

Definition at line 92 of file fileheader.c.

References LUMIERA_ERROR_SET_CRITICAL, LUMIERA_ERROR_SET_WARNING, LUMIERA_FILEHEADER_ENDIANMAGIC, LUMIERA_FILEHEADER_FLAG_ENDIANESS, lumiera_fileheader_flags_clear(), lumiera_fileheader_flags_validate(), lumiera_mmap_address(), lumiera_mmap_delete(), lumiera_mmap_new_exact(), and NULL.

Referenced by TEST().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ lumiera_fileheader_close()

void lumiera_fileheader_close ( LumieraFileheader  self,
const char *  flags_add 
)

Closes a previously created or opened file header.

Parameters
selfthe file header to close.
flags_addset this flags if not already set no errors, no nothing returned (yet)

Definition at line 141 of file fileheader.c.

References lumiera_fileheader_flags_set(), lumiera_mmap_delete(), and NULL.

Referenced by TEST().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ lumiera_fileheader_version()

int lumiera_fileheader_version ( LumieraFileheader  self)

Queries the version of a file header.

Parameters
selfthe file header to query
Returns
the version stored in the file header or -1 on error.

Definition at line 153 of file fileheader.c.

References LUMIERA_ERROR_SET_WARNING, lumiera_tmpbuf_snprintf(), and NULL.

Referenced by TEST().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ lumiera_fileheader_flags_validate()

int lumiera_fileheader_flags_validate ( LumieraFileheader  self,
const char *  expected,
const char *  unexpected 
)

check if all flags given from some sets are either set or not.

Definition at line 176 of file fileheader.c.

Referenced by lumiera_fileheader_open().

+ Here is the caller graph for this function:

◆ lumiera_fileheader_flags_set()

LumieraFileheader lumiera_fileheader_flags_set ( LumieraFileheader  self,
const char *  flags 
)

Sets flags if not already set.

Definition at line 194 of file fileheader.c.

References LUMIERA_ERROR_SET_CRITICAL, and NULL.

Referenced by lumiera_fileheader_close(), and lumiera_fileheader_create().

+ Here is the caller graph for this function:

◆ lumiera_fileheader_flags_clear()

LumieraFileheader lumiera_fileheader_flags_clear ( LumieraFileheader  self,
const char *  flags 
)

Clear flags if present.

Definition at line 216 of file fileheader.c.

Referenced by lumiera_fileheader_open().

+ Here is the caller graph for this function: