libjf API reference guide

Main Page | Alphabetical List | Data Structures | File List | Data Fields | Globals | Related Pages

jf_journal_file.h File Reference

#include <jf/jf_config.h>
#include <jf/jf_defines.h>
#include <jf/jf_errors.h>
#include <jf/jf_cache_file.h>
#include <jf/jf_trace.h>

Go to the source code of this file.

Data Structures

struct  jf_journal_file_opts_s
struct  jf_journal_file_t

Defines

#define JF_FILE_OM_APPEND   0x20000000
#define JF_FILE_OM_MASK   (JF_FILE_OM_READ | JF_FILE_OM_WRITE | JF_FILE_OM_APPEND | JF_FILE_OM_RESTART | JF_FILE_OM_TRUNCATE | JF_FILE_OM_MSDOS)
#define JF_FILE_OM_MSDOS   0x04000000
#define JF_FILE_OM_READ   0x80000000
#define JF_FILE_OM_RESTART   0x10000000
#define JF_FILE_OM_TRUNCATE   0x08000000
#define JF_FILE_OM_WRITE   0x40000000
#define JF_JOURNAL_FILE_CACHE_SIZE_ENV_VAR   "JF_JOURNALED_FILE_CACHE_SIZE"
#define JF_JOURNAL_FILE_MAX_PATH_SIZE   (PATH_MAX + 1)
#define JF_JOURNAL_FILE_ST_OPEN   0x1
#define JF_JOURNAL_FILE_ST_RESET   0x0
#define JF_JOURNAL_FILE_ST_SYNC   0x2
#define JF_TRACE_MODULE   JF_TRACE_MOD_LIB_JOURNAL_FILE

Functions

void jf_journal_file_create (jf_journal_file_t *jf)
void jf_journal_file_destroy (jf_journal_file_t *jf)
int jf_journal_file_get_all_in_cache (const jf_journal_file_t *jf)
jf_cache_file_tjf_journal_file_get_cache_file (jf_journal_file_t *jf)
jf_offset_t jf_journal_file_get_last_pos (const jf_journal_file_t *jf)
jf_offset_t jf_journal_file_get_last_size (const jf_journal_file_t *jf)
jf_offset_t jf_journal_file_get_last_uc_pos (const jf_journal_file_t *jf)
jf_offset_t jf_journal_file_get_last_uc_size (const jf_journal_file_t *jf)
uint32_t jf_journal_file_get_open_mode (const jf_journal_file_t *jf)
const char * jf_journal_file_get_path (const jf_journal_file_t *jf)
uint32_t jf_journal_file_get_status (const jf_journal_file_t *jf)
FILE * jf_journal_file_get_stream (const jf_journal_file_t *jf)
int jf_journal_file_init (jf_journal_file_t *jf, const char *path, FILE *stream, uint32_t open_mode, const struct jf_journal_file_opts_s *options)
void jf_journal_file_reset (jf_journal_file_t *jf)
int jf_journal_file_set_all_in_cache (jf_journal_file_t *jf, int new_value)
int jf_journal_file_set_cache_file (jf_journal_file_t *jf, const jf_cache_file_t *cf)
int jf_journal_file_set_last_pos (jf_journal_file_t *jf, jf_offset_t new_pos)
int jf_journal_file_set_last_size (jf_journal_file_t *jf, jf_offset_t new_size)
int jf_journal_file_set_last_uc_pos (jf_journal_file_t *jf, jf_offset_t new_pos)
int jf_journal_file_set_last_uc_size (jf_journal_file_t *jf, jf_offset_t new_size)
int jf_journal_file_set_open_mode (jf_journal_file_t *jf, uint32_t new_open_mode)
int jf_journal_file_set_options (jf_journal_file_t *jf, const struct jf_journal_file_opts_s *options)
int jf_journal_file_set_path (jf_journal_file_t *jf, const char *new_path)
int jf_journal_file_set_status (jf_journal_file_t *jf, uint32_t status)
int jf_journal_file_set_stream (jf_journal_file_t *jf, FILE *stream)
void jf_set_default_journal_file_opts (struct jf_journal_file_opts_s *options)


Define Documentation

#define JF_FILE_OM_APPEND   0x20000000
 

The stream must be positioned at end of file Definition at line 75 of file jf_journal_file.h.

Referenced by jf_file_build_open_mode(), jf_file_check_mode(), jf_file_seek(), and jf_journal_add_byte_data().

#define JF_FILE_OM_MASK   (JF_FILE_OM_READ | JF_FILE_OM_WRITE | JF_FILE_OM_APPEND | JF_FILE_OM_RESTART | JF_FILE_OM_TRUNCATE | JF_FILE_OM_MSDOS)
 

Mask used to keep only the "open mode" interesting bits Definition at line 91 of file jf_journal_file.h.

Referenced by jf_file_build_open_mode().

#define JF_FILE_OM_MSDOS   0x04000000
 

The file must be opened as a MS-DOS TEXT stream (default is binary stream) Definition at line 87 of file jf_journal_file.h.

Referenced by jf_file_build_open_mode(), jf_file_check_mode(), jf_journal_add_byte_data(), and jf_journal_get_byte_data().

#define JF_FILE_OM_READ   0x80000000
 

The file can be read Definition at line 67 of file jf_journal_file.h.

Referenced by jf_file_build_open_mode(), jf_file_check_mode(), and jf_file_seek().

#define JF_FILE_OM_RESTART   0x10000000
 

The stream must be positioned at last committed file pos (RESTART MODE) Definition at line 79 of file jf_journal_file.h.

Referenced by jf_file_build_open_mode(), and jf_file_check_mode().

#define JF_FILE_OM_TRUNCATE   0x08000000
 

The stream must be truncated (at beginning or last committed pos) Definition at line 83 of file jf_journal_file.h.

Referenced by jf_file_build_open_mode(), and jf_file_check_mode().

#define JF_FILE_OM_WRITE   0x40000000
 

The file can be written Definition at line 71 of file jf_journal_file.h.

Referenced by jf_file_build_open_mode(), and jf_file_check_mode().

#define JF_JOURNAL_FILE_CACHE_SIZE_ENV_VAR   "JF_JOURNALED_FILE_CACHE_SIZE"
 

Name of the environment variable can be used to change journaled file cache if program does NOT specify a custom value when journaled file is opened: environment var is polled by function jf_set_default_journal_file_opts Definition at line 60 of file jf_journal_file.h.

Referenced by jf_set_default_journal_file_opts().

#define JF_JOURNAL_FILE_MAX_PATH_SIZE   (PATH_MAX + 1)
 

(Max) space allocated to store a file path (it's system dependent) Definition at line 112 of file jf_journal_file.h.

Referenced by jf_journal_file_set_path(), jf_journal_file_tab_dump(), and jf_journal_file_tab_restore().

#define JF_JOURNAL_FILE_ST_OPEN   0x1
 

The journaled file is in "open" status: some bytes have been written Definition at line 102 of file jf_journal_file.h.

Referenced by jf_journal_apply_changes(), jf_journal_close_detach_file(), jf_journal_new_unit_of_work(), jf_journal_remove_changes(), and jf_journal_reopen_files().

#define JF_JOURNAL_FILE_ST_RESET   0x0
 

Journaled file reset status Definition at line 98 of file jf_journal_file.h.

Referenced by jf_journal_file_init().

#define JF_JOURNAL_FILE_ST_SYNC   0x2
 

The journaled file is in "synchronized" status: NO rollback/commit operation must be performed until next change Definition at line 107 of file jf_journal_file.h.

Referenced by jf_journal_commit_int(), jf_journal_is_all_sync(), jf_journal_is_sync(), jf_journal_new_unit_of_work(), jf_journal_remove_changes(), jf_journal_scan_undo(), and jf_journal_set_all_sync().

#define JF_TRACE_MODULE   JF_TRACE_MOD_LIB_JOURNAL_FILE
 

Definition at line 50 of file jf_journal_file.h.


Function Documentation

void jf_journal_file_create jf_journal_file_t jf  ) 
 

Create a journaled file object: this is the FIRST method should be invoked before using a journaled file object Definition at line 57 of file jf_journal_file.c.

References jf_journal_file_t::cache_file, and jf_cache_file_create().

Referenced by jf_journal_create(), and jf_journal_open_attach_file().

void jf_journal_file_destroy jf_journal_file_t jf  ) 
 

Destroy a journaled file object: this is the LAST method should be invoked on a journaled file object; memory leak may happen if destruction is not performed Definition at line 64 of file jf_journal_file.c.

References jf_journal_file_t::cache_file, jf_journal_file_t::file_path, and jf_cache_file_destroy().

Referenced by jf_journal_file_tab_destroy().

int jf_journal_file_get_all_in_cache const jf_journal_file_t jf  )  [inline, static]
 

Retrieve the value of "all_in_cache" boolean flag

Parameters:
jf IN journaled file object
Returns:
TRUE if no record has be written since last commit/rollback; FALSE if it has
Definition at line 440 of file jf_journal_file.h.

References jf_journal_file_t::all_in_cache.

Referenced by jf_journal_rollback_int().

jf_cache_file_t* jf_journal_file_get_cache_file jf_journal_file_t jf  )  [inline, static]
 

Retrieve the cache file associated to a journaled file

Parameters:
jf IN journaled file object
Returns:
a read/write reference to cache file associated to journaled file
Definition at line 415 of file jf_journal_file.h.

References jf_journal_file_t::cache_file.

Referenced by jf_file_get_cache_limit(), jf_journal_add_byte_data(), jf_journal_attach_file(), jf_journal_get_byte_data(), jf_journal_open_attach_file(), jf_journal_rollback_int(), jf_journal_write_record(), and jf_journal_write_records().

jf_offset_t jf_journal_file_get_last_pos const jf_journal_file_t jf  )  [inline, static]
 

Retrieve last file pos

Parameters:
jf IN journaled file object
Returns:
the last pos of the journaled file file pointer
Definition at line 259 of file jf_journal_file.h.

References jf_offset_t, and jf_journal_file_t::last_pos.

Referenced by jf_journal_analyze(), jf_journal_cold_recovery_analyze(), jf_journal_cold_recovery_patch(), jf_journal_open(), jf_journal_open_attach_file(), and jf_journal_rollback_int().

jf_offset_t jf_journal_file_get_last_size const jf_journal_file_t jf  )  [inline, static]
 

Retrieve last file size

Parameters:
jf IN journaled file object
Returns:
the last size of the journaled file
Definition at line 283 of file jf_journal_file.h.

References jf_offset_t, and jf_journal_file_t::last_size.

Referenced by jf_file_size(), jf_journal_cold_recovery_patch(), jf_journal_cold_recovery_patch_seq(), jf_journal_open_attach_file(), jf_journal_rollback_int(), and jf_journal_write_record().

jf_offset_t jf_journal_file_get_last_uc_pos const jf_journal_file_t jf  )  [inline, static]
 

Retrieve last uncommitted file position

Parameters:
jf IN journaled file object
Returns:
the last uncommitted position of the journaled file
Definition at line 390 of file jf_journal_file.h.

References jf_offset_t, and jf_journal_file_t::last_uc_pos.

Referenced by jf_file_eof(), jf_file_seek(), jf_journal_add_byte_data(), jf_journal_commit_int(), and jf_journal_get_byte_data().

jf_offset_t jf_journal_file_get_last_uc_size const jf_journal_file_t jf  )  [inline, static]
 

Retrieve last uncommitted file size

Parameters:
jf IN journaled file object
Returns:
the last uncommitted size of the journaled file
Definition at line 331 of file jf_journal_file.h.

References jf_offset_t, and jf_journal_file_t::last_uc_size.

Referenced by jf_file_eof(), jf_file_seek(), jf_file_size(), jf_journal_add_byte_data(), jf_journal_apply_changes(), jf_journal_cold_recovery_patch_seq(), jf_journal_commit_int(), jf_journal_get_byte_data(), jf_journal_rollback_int(), jf_journal_write_record(), and jf_journal_write_records().

uint32_t jf_journal_file_get_open_mode const jf_journal_file_t jf  )  [inline, static]
 

Retrieve flags indicating how the journaled file has been opened (see JF_FILE_OM_READ, JF_FILE_OM_WRITE, JF_FILE_OM_APPEND...)

Parameters:
jf IN journaled file object
Returns:
journaled file open mode
Definition at line 358 of file jf_journal_file.h.

References JF_TRACE, and jf_journal_file_t::open_mode.

Referenced by jf_file_seek(), jf_journal_add_byte_data(), jf_journal_attach_file(), and jf_journal_get_byte_data().

const char* jf_journal_file_get_path const jf_journal_file_t jf  )  [inline, static]
 

Retrieve the path associated to a journaled file

Parameters:
jf IN journaled file object
Returns:
the path file name
Definition at line 238 of file jf_journal_file.h.

References jf_journal_file_t::file_path.

Referenced by jf_journal_cold_recovery_patch(), jf_journal_file_tab_trace(), jf_journal_reopen_files(), jf_journal_rotate(), and jf_journal_shift_files().

uint32_t jf_journal_file_get_status const jf_journal_file_t jf  )  [inline, static]
 

Retrieve file status

Parameters:
jf IN journaled file object
Returns:
the file status of the journaled file
Definition at line 307 of file jf_journal_file.h.

References jf_journal_file_t::status.

Referenced by jf_journal_apply_changes(), jf_journal_close_detach_file(), jf_journal_commit_int(), jf_journal_is_all_sync(), jf_journal_is_sync(), jf_journal_new_unit_of_work(), jf_journal_remove_changes(), jf_journal_reopen_files(), jf_journal_rollback_int(), jf_journal_scan_undo(), jf_journal_set_all_sync(), and jf_journal_write_records().

FILE* jf_journal_file_get_stream const jf_journal_file_t jf  )  [inline, static]
 

Retrieve the stream associated to a file

Parameters:
jf IN journaled file object
Returns:
the current standard I/O stream
Definition at line 214 of file jf_journal_file.h.

References jf_journal_file_t::stream.

Referenced by jf_journal_add_byte_data(), jf_journal_apply_changes(), jf_journal_attach_file(), jf_journal_close(), jf_journal_close_detach_file(), jf_journal_cold_recovery(), jf_journal_cold_recovery_patch(), jf_journal_get_byte_data(), jf_journal_get_stream(), jf_journal_open(), jf_journal_open_attach_file(), jf_journal_remove_changes(), jf_journal_reopen_files(), jf_journal_rollback_int(), jf_journal_rotate(), jf_journal_sync(), jf_journal_write_record(), and jf_journal_write_records().

int jf_journal_file_init jf_journal_file_t jf,
const char *  path,
FILE *  stream,
uint32_t  open_mode,
const struct jf_journal_file_opts_s options
 

Initialize a journaled file object

Parameters:
jf OUT journaled file object
path IN journaled file path name
stream IN standard I/O stream associated to journaled file "path"
open_mode IN open mode stream flags
options IN stuff may be passed to tune specific values; it can be a NULL pointer (default options used)
Returns:
a reason code
Definition at line 73 of file jf_journal_file.c.

References jf_journal_file_t::all_in_cache, jf_journal_file_t::cache_file, jf_journal_file_opts_s::cache_size_limit, CATCH, jf_journal_file_t::file_path, jf_cache_file_init(), jf_journal_file_set_path(), JF_JOURNAL_FILE_ST_RESET, jf_offset_t, JF_RC_INTERNAL_ERROR, JF_RC_OK, JF_TRACE, jf_journal_file_t::last_pos, jf_journal_file_t::last_size, jf_journal_file_t::last_uc_pos, jf_journal_file_t::last_uc_size, jf_journal_file_t::open_mode, jf_journal_file_t::status, jf_journal_file_t::stream, THROW, and TRUE.

Referenced by jf_journal_create(), and jf_journal_open_attach_file().

void jf_journal_file_reset jf_journal_file_t jf  ) 
 

Reset a journaled file object; NOTE: this is a PRIVATE method must NOT be used by end user application

Parameters:
jf OUT journaled file object
Definition at line 47 of file jf_journal_file.c.

References jf_journal_file_t::all_in_cache, jf_journal_file_t::cache_file, jf_journal_file_t::file_path, jf_cache_file_reset(), and TRUE.

int jf_journal_file_set_all_in_cache jf_journal_file_t jf,
int  new_value
[inline, static]
 

Set the new value for "all_in_cache" boolean flag

Parameters:
jf IN/OUT journaled file object
new_value IN TRUE if no record has be written since last commit/rollback; FALSE if it has
Returns:
a reason code
Definition at line 454 of file jf_journal_file.h.

References jf_journal_file_t::all_in_cache, and JF_RC_OK.

Referenced by jf_journal_add_byte_data(), jf_journal_commit_int(), jf_journal_open_attach_file(), and jf_journal_rollback_int().

int jf_journal_file_set_cache_file jf_journal_file_t jf,
const jf_cache_file_t cf
 

Set the cache file associated to a journaled file object

Parameters:
jf IN/OUT journaled file object
cf IN cache file object must be associated to journaled file; NOTE: the cache file object (cf) must NOT be destroyed after this method because a bit oriented copy is performed (no reallocation)
Returns:
a reason code
Definition at line 225 of file jf_journal_file.c.

References jf_journal_file_t::cache_file, CATCH, JF_RC_INTERNAL_ERROR, JF_RC_NULL_OBJECT, JF_RC_OK, JF_TRACE, and THROW.

Referenced by jf_journal_attach_file().

int jf_journal_file_set_last_pos jf_journal_file_t jf,
jf_offset_t  new_pos
[inline, static]
 

Set the logical file pointer of a journaled file

Parameters:
jf IN/OUT journaled file object
new_pos IN new logical file pointer of the journaled file
Returns:
a reason code
Definition at line 270 of file jf_journal_file.h.

References jf_offset_t, JF_RC_OK, and jf_journal_file_t::last_pos.

Referenced by jf_journal_close(), jf_journal_cold_recovery(), jf_journal_cold_recovery_patch(), jf_journal_commit_int(), jf_journal_create(), jf_journal_open_attach_file(), jf_journal_rotate(), and jf_journal_util_join().

int jf_journal_file_set_last_size jf_journal_file_t jf,
jf_offset_t  new_size
[inline, static]
 

Set the logical size of a journaled file

Parameters:
jf IN/OUT journaled file object
new_size IN new logical size of the journaled file
Returns:
a reason code
Definition at line 294 of file jf_journal_file.h.

References jf_offset_t, JF_RC_OK, and jf_journal_file_t::last_size.

Referenced by jf_journal_cold_recovery_patch_seq(), jf_journal_commit_int(), jf_journal_open_attach_file(), and jf_journal_util_join().

int jf_journal_file_set_last_uc_pos jf_journal_file_t jf,
jf_offset_t  new_pos
[inline, static]
 

Set the logical uncommitted position of a journaled file

Parameters:
jf IN/OUT journaled file object
new_pos IN new logical uncommitted pos of the journaled file
Returns:
a reason code
Definition at line 401 of file jf_journal_file.h.

References jf_offset_t, JF_RC_OK, and jf_journal_file_t::last_uc_pos.

Referenced by jf_file_seek(), jf_journal_add_byte_data(), jf_journal_get_byte_data(), jf_journal_open_attach_file(), and jf_journal_rollback_int().

int jf_journal_file_set_last_uc_size jf_journal_file_t jf,
jf_offset_t  new_size
[inline, static]
 

Set the logical uncommitted size of a journaled file

Parameters:
jf IN/OUT journaled file object
new_size IN new logical uncommitted size of the journaled file
Returns:
a reason code
Definition at line 343 of file jf_journal_file.h.

References jf_offset_t, JF_RC_OK, and jf_journal_file_t::last_uc_size.

Referenced by jf_journal_add_byte_data(), jf_journal_apply_changes(), jf_journal_commit_int(), jf_journal_create(), jf_journal_load(), jf_journal_open_attach_file(), jf_journal_rollback_int(), jf_journal_rotate(), jf_journal_write_record(), and jf_journal_write_records().

int jf_journal_file_set_open_mode jf_journal_file_t jf,
uint32_t  new_open_mode
[inline, static]
 

Set how the journaled file has been opened (see JF_FILE_OM_READ, JF_FILE_OM_WRITE, JF_FILE_OM_APPEND...)

Parameters:
jf IN/OUT journaled file object
new_open_mode IN new value
Returns:
a reason code
Definition at line 375 of file jf_journal_file.h.

References JF_RC_OK, JF_TRACE, and jf_journal_file_t::open_mode.

Referenced by jf_journal_attach_file().

int jf_journal_file_set_options jf_journal_file_t jf,
const struct jf_journal_file_opts_s options
 

Set the options of a journaled file object

Parameters:
jf IN/OUT journaled file object
options IN new options for journaled file
Returns:
a reason code
Definition at line 190 of file jf_journal_file.c.

References jf_journal_file_t::cache_file, jf_journal_file_opts_s::cache_size_limit, CATCH, jf_cache_file_set_limit(), JF_RC_INTERNAL_ERROR, JF_RC_NULL_OBJECT, JF_RC_OK, JF_TRACE, and THROW.

int jf_journal_file_set_path jf_journal_file_t jf,
const char *  new_path
 

Set (new) path for a journaled file object

Parameters:
jf IN/OUT journaled file object
new_path IN (new) path must be assigned to journaled file
Returns:
a reason code
Definition at line 142 of file jf_journal_file.c.

References CATCH, jf_journal_file_t::file_path, JF_JOURNAL_FILE_MAX_PATH_SIZE, JF_RC_INTERNAL_ERROR, JF_RC_NULL_OBJECT, JF_RC_OK, JF_RC_REALLOC_ERROR, JF_TRACE, and THROW.

Referenced by jf_journal_file_init(), and jf_journal_util_rename().

int jf_journal_file_set_status jf_journal_file_t jf,
uint32_t  status
[inline, static]
 

Set the file status of a journaled file

Parameters:
jf IN/OUT journaled file object
status IN new status of the journaled file
Returns:
a reason code
Definition at line 318 of file jf_journal_file.h.

References JF_RC_OK, and jf_journal_file_t::status.

Referenced by jf_journal_close_detach_file(), jf_journal_commit_int(), jf_journal_new_unit_of_work(), jf_journal_scan_undo(), and jf_journal_set_all_sync().

int jf_journal_file_set_stream jf_journal_file_t jf,
FILE *  stream
[inline, static]
 

Set the value of the stream associated to journaled file object

Parameters:
jf IN/OUT journaled file object
stream IN stream associated to journaled file
Returns:
a reason code
Definition at line 225 of file jf_journal_file.h.

References JF_RC_OK, and jf_journal_file_t::stream.

Referenced by jf_journal_attach_file(), jf_journal_close_detach_file(), jf_journal_file_tab_restore(), and jf_journal_rotate().

void jf_set_default_journal_file_opts struct jf_journal_file_opts_s options  )  [inline, static]
 

Set default value for journal file options

Parameters:
options IN/OUT pointer to struct must be set
Definition at line 140 of file jf_journal_file.h.

References jf_journal_file_opts_s::cache_size_limit, JF_CACHE_FILE_DEFAULT_LIMIT, and JF_JOURNAL_FILE_CACHE_SIZE_ENV_VAR.

Referenced by jf_set_default_journal_opts().


Copyright 2005 © Tiian