libjf API reference guide

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

jf_file.h File Reference

#include <jf/jf_config.h>
#include <jf/jf_defines.h>
#include <jf/jf_utils.h>
#include <jf_journal.h>

Go to the source code of this file.

Data Structures

struct  jf_file_open_opts_s
struct  jf_file_t

Defines

#define JF_FILE_BUFFER_PAGE_SIZE   4096
#define JF_FILE_OPEN_MODE_SIZE   4
#define JF_TRACE_MODULE   JF_TRACE_MOD_LIB_FILE

Functions

int jf_file_build_open_mode (uint32_t flags, char *mode1, char *mode2, int *repos, int *resize, int *append)
int jf_file_check_mode (const char *mode, uint32_t *flags)
LIBJF_EXPORT int jf_file_close (jf_file_t *jfile)
int jf_file_commit (jf_file_t *jfile)
int jf_file_eof (const jf_file_t *jfile)
LIBJF_EXPORT jf_offset_t jf_file_get_cache_limit (const jf_file_t *jfile)
jf_word_t jf_file_get_id (const jf_file_t *jf)
jf_journal_tjf_file_get_journal (const jf_file_t *jf)
LIBJF_EXPORT int jf_file_getc (jf_file_t *jf, int *c)
LIBJF_EXPORT int jf_file_gets (jf_file_t *jf, size_t size, char *s)
int jf_file_is_safe (const jf_file_t *jf)
LIBJF_EXPORT int jf_file_open (jf_file_t *jfile, jf_journal_t *journal, const char *path, const char *mode, const struct jf_file_open_opts_s *options)
LIBJF_EXPORT int jf_file_printf (jf_file_t *jf, size_t *write_number, const char *format,...)
LIBJF_EXPORT int jf_file_putc (jf_file_t *jf, int c)
LIBJF_EXPORT int jf_file_puts (jf_file_t *jf, const char *s)
LIBJF_EXPORT int jf_file_read (jf_file_t *jf, void *data, size_t size, size_t *read_number)
void jf_file_reset (jf_file_t *jf)
int jf_file_rewind (jf_file_t *jf)
int jf_file_rollback (jf_file_t *jfile)
LIBJF_EXPORT int jf_file_seek (jf_file_t *jf, jf_offset_t offset, int whence)
LIBJF_EXPORT int jf_file_size (jf_file_t *jf, jf_offset_t *last_size, jf_offset_t *last_uc_size)
LIBJF_EXPORT int jf_file_vprintf (jf_file_t *jf, size_t *write_number, const char *format, va_list ap)
LIBJF_EXPORT int jf_file_write (jf_file_t *jf, const void *data, size_t size, size_t *write_number)
void jf_set_default_file_open_opts (struct jf_file_open_opts_s *options)


Define Documentation

#define JF_FILE_BUFFER_PAGE_SIZE   4096
 

Size of the smallest slot used when allocating buffer for format related functions (i.e. jf_file_printf) Definition at line 60 of file jf_file.h.

Referenced by jf_file_vprintf().

#define JF_FILE_OPEN_MODE_SIZE   4
 

Number of chars used to encode an "fopen" mode string Definition at line 51 of file jf_file.h.

Referenced by jf_journal_open_attach_file().

#define JF_TRACE_MODULE   JF_TRACE_MOD_LIB_FILE
 

Definition at line 44 of file jf_file.h.


Function Documentation

int jf_file_build_open_mode uint32_t  flags,
char *  mode1,
char *  mode2,
int *  repos,
int *  resize,
int *  append
 

Build real open mode related to flag mask

Parameters:
flags IN a bitmask encoding "mode" in a confortable way
mode1 OUT a mode string can be used for a regular "fopen" function;
NOTE: buffer MUST at least JF_FILE_OPEN_MODE_SIZE bytes long

Parameters:
mode2 OUT an alternative mode string can be used for a regular "fopen" if first mode (mode1) fails; empty string "" is used if no alternative mode is available
repos OUT boolean flag: if true, file pointer must be positioned at last committed position
resize OUT boolean flag: if true, file must be resized at last committed position
append OUT boolean flag: if true, file pointer must be positioned at last committed size
Returns:
a reason code
Definition at line 273 of file jf_file.c.

References CATCH, FALSE, JF_FILE_OM_APPEND, JF_FILE_OM_MASK, JF_FILE_OM_MSDOS, JF_FILE_OM_READ, JF_FILE_OM_RESTART, JF_FILE_OM_TRUNCATE, JF_FILE_OM_WRITE, JF_RC_INTERNAL_ERROR, JF_RC_INVALID_OPTION, JF_RC_OK, JF_TRACE, THROW, and TRUE.

Referenced by jf_journal_open_attach_file().

int jf_file_check_mode const char *  mode,
uint32_t *  flags
 

Check the "open mode" and build related binary flags

Parameters:
mode IN a string containing how the journaled file should be opened; see jf_file_open for a complete description of allowed strings
flags OUT a bitmask encoding "mode" in a confortable way: the output value is valid only if return code is JF_RC_OK
Returns:
a reason code
Definition at line 179 of file jf_file.c.

References CATCH, JF_FILE_OM_APPEND, JF_FILE_OM_MSDOS, JF_FILE_OM_READ, JF_FILE_OM_RESTART, JF_FILE_OM_TRUNCATE, JF_FILE_OM_WRITE, JF_RC_INTERNAL_ERROR, JF_RC_INVALID_OPTION, JF_RC_NULL_OBJECT, JF_RC_OK, JF_TRACE, and THROW.

Referenced by jf_journal_open_attach_file().

LIBJF_EXPORT int jf_file_close jf_file_t jfile  ) 
 

PUBLIC METHOD
Close a journaled file

Parameters:
jfile IN/OUT journaled file object
Returns:
a reason code
Definition at line 384 of file jf_file.c.

References CATCH, jf_file_t::char_buffer, jf_file_t::char_buffer_size, jf_file_t::id, jf_file_is_safe(), jf_file_reset(), jf_file_rollback(), jf_journal_close(), jf_journal_close_detach_file(), JF_RC_INTERNAL_ERROR, JF_RC_INVALID_STATUS, JF_RC_OBJ_CORRUPTED, JF_RC_OK, JF_TRACE, jf_file_t::journal, jf_file_t::private_journal, and THROW.

Referenced by bench_X0_ljf_post(), and jf_journal_util_join().

int jf_file_commit jf_file_t jfile  )  [inline, static]
 

PUBLIC METHOD
Commit updates: all the changes since last jf_file_commit / jf_file_rollback / jf_journal_commit / jf_journal_rollback are committed and will be permanent

Parameters:
jfile IN/OUT journaled file object
Returns:
a reason code
Definition at line 471 of file jf_file.h.

References jf_file_get_id(), jf_file_get_journal(), and jf_journal_commit_int().

int jf_file_eof const jf_file_t jfile  )  [inline, static]
 

PUBLIC METHOD
Is the current journaled file pointer at END-OF-FILE position?

Parameters:
jfile IN journaled file object
Returns:
the method return non-zero if and only if the end-of-file indicator is set for journaled file NOTE: if some error afflicts the journaled file, you can NOT determine it invoking this method (no "reason code" is available)
Definition at line 383 of file jf_file.h.

References FALSE, jf_file_get_id(), jf_file_get_journal(), jf_file_is_safe(), jf_journal_file_get_last_uc_pos(), jf_journal_file_get_last_uc_size(), jf_journal_get_jfile(), jf_word_t, and TRUE.

LIBJF_EXPORT jf_offset_t jf_file_get_cache_limit const jf_file_t jfile  ) 
 

PUBLIC METHOD
Retrieve the real cache limit of a journaled file (useful when actual value is different than asked value)

Parameters:
jfile IN journaled file object
Returns:
max number of cache bytes will be used before journal records are flushed
Definition at line 460 of file jf_file.c.

References jf_file_t::id, jf_cache_file_get_limit(), jf_file_is_safe(), jf_journal_file_get_cache_file(), jf_journal_get_jfile(), jf_offset_t, and jf_file_t::journal.

jf_word_t jf_file_get_id const jf_file_t jf  )  [inline, static]
 

Retrieve the id associated to file in journal

Parameters:
jf IN file object
Returns:
the file identificator
Definition at line 154 of file jf_file.h.

References jf_file_t::id, and jf_word_t.

Referenced by jf_file_commit(), jf_file_eof(), jf_file_getc(), jf_file_gets(), jf_file_putc(), jf_file_puts(), jf_file_read(), jf_file_rollback(), jf_file_seek(), jf_file_size(), jf_file_write(), and jf_journal_util_join().

jf_journal_t* jf_file_get_journal const jf_file_t jf  )  [inline, static]
 

Retrieve the journal associated to a file

Parameters:
jf IN file object
Returns:
a reference to associated journal
Definition at line 143 of file jf_file.h.

References jf_file_t::journal.

Referenced by jf_file_commit(), jf_file_eof(), jf_file_getc(), jf_file_gets(), jf_file_putc(), jf_file_puts(), jf_file_read(), jf_file_rollback(), jf_file_seek(), jf_file_size(), jf_file_vprintf(), and jf_file_write().

LIBJF_EXPORT int jf_file_getc jf_file_t jf,
int *  c
 

PUBLIC METHOD
jf_file_getc reads the next character from journaled file and returns it as a byte_t cast to an int

Parameters:
jf IN/OUT journaled object file
c OUT character read from journaled file
Returns:
a reason code
Definition at line 756 of file jf_file.c.

References CATCH, jf_file_get_id(), jf_file_get_journal(), jf_file_is_safe(), jf_journal_get_c(), jf_journal_get_jfile(), JF_RC_INTERNAL_ERROR, JF_RC_OBJ_CORRUPTED, JF_RC_OK, JF_TRACE, jf_word_t, and THROW.

LIBJF_EXPORT int jf_file_gets jf_file_t jf,
size_t  size,
char *  s
 

PUBLIC METHOD
jf_file_gets reads in at most one less than size characters from journaled file and stores them into the buffer pointed to by s. Reading stops after an EOF or a newline. If a newline is read, it is stored into the buffer. A '0' is stored after the last character in the buffer.

Parameters:
jf IN/OUT journaled object file
size IN buffer size
s OUT string buffer
Returns:
a reason code
Definition at line 803 of file jf_file.c.

References CATCH, jf_file_get_id(), jf_file_get_journal(), jf_file_is_safe(), jf_journal_get_c(), jf_journal_get_jfile(), JF_RC_EOF, JF_RC_INTERNAL_ERROR, JF_RC_OBJ_CORRUPTED, JF_RC_OK, JF_TRACE, jf_word_t, and THROW.

int jf_file_is_safe const jf_file_t jf  )  [inline, static]
 

Check the safety of a "jf_file_t" object: can be it used?

Parameters:
jf IN file object
Returns:
a boolean value
Definition at line 165 of file jf_file.h.

References jf_file_t::id, JF_JOURNAL_JOURNAL_FILE_ID, and jf_file_t::journal.

Referenced by jf_file_close(), jf_file_eof(), jf_file_get_cache_limit(), jf_file_getc(), jf_file_gets(), jf_file_seek(), and jf_file_size().

LIBJF_EXPORT int jf_file_open jf_file_t jfile,
jf_journal_t journal,
const char *  path,
const char *  mode,
const struct jf_file_open_opts_s options
 

PUBLIC METHOD
Open a journaled file attaching it to a shared journal or to a private one

Parameters:
jfile OUT journaled file object
journal IN/OUT journal for this file: use NULL if a private one must be used
path IN journaled file path
mode IN how the journaled file must be opened; allowed values are:
  • "r": Open text file for reading. The stream is positioned at the beginning of the file.
  • "r+": Open for reading and writing. The stream is positioned at the beginning of the file.
  • "R": Open text file for reading. The stream is positioned at last committed pos (*** RESTART MODE ***).
  • "R+": Open for reading and writing. The stream is positioned at last committed pos (*** RESTART MODE ***).
  • "w": Truncate file to zero length or create text file for writing. The stream is positioned at the beginning of the file.
  • "w+": Open for reading and writing. The file is created if it does not exist, otherwise it is truncated. The stream is positioned at the beginning of the file.
  • "W": Truncate file to last committed pos or create text file for writing. The stream is positioned at last committed pos (*** RESTART MODE ***).
  • "W+": Open for reading and writing. The file is created if it does not exist, otherwise it is truncated to last committed pos. The stream is positioned at last committed pos (*** RESTART MODE ***).
  • "a": Open for writing. The file is created if it does not exist. The stream is positioned at the end of the file.
  • "a+": Open for reading and writing. The file is created if it does not exist. The stream is positioned at the end of the file.
The mode string can also include the letter "b" or the letter "D" either as a last character or as a character between the characters in any of the two-character strings described above; "b" flag can be used to specify BINARY (default) stream; "D" flag should be used to read/write MS-DOS TEXT stream (output "\n" is converted to "\r\n" and input "\r\n" is converted to "\n")
options IN stuff may be passed to specify some additional actions (see jf_file_open_opts_s); use NULL for default behaviour. Note: jf_journal_opts_s struct is taken in account only when journal param is NULL
Returns:
a reason code
Definition at line 66 of file jf_file.c.

References CATCH, FALSE, jf_journal_opts_s::flags, jf_file_t::id, jf_file_reset(), JF_JOURNAL_EXTENSION, jf_journal_open(), jf_journal_open_attach_file(), JF_JOURNAL_PROP_OPEN_O_CREAT, JF_RC_INTERNAL_ERROR, JF_RC_INVALID_PATH_NAME, JF_RC_MALLOC_ERROR, JF_RC_OK, jf_set_default_file_open_opts(), JF_TRACE, jf_file_open_opts_s::join_the_journal, jf_file_t::journal, jf_journal_opts_s::journal_file_opts, jf_file_open_opts_s::journal_opts, jf_file_t::private_journal, THROW, and TRUE.

Referenced by bench_X0_ljf_pre(), jf_journal_cold_recovery_patch(), jf_journal_reopen_files(), and jf_journal_util_join().

LIBJF_EXPORT int jf_file_printf jf_file_t jf,
size_t *  write_number,
const char *  format,
  ...
 

PUBLIC METHOD
NOTE: this metod is defined only on platforms with "vsnprintf" function.
Produce output to a journaled file according to a format

Parameters:
jf IN/OUT journaled file object
write_number OUT number of bytes written to journaled file (meaningful only if reason core is JF_RC_OK)
format IN specifies how subsequent arguments are converted for output
Returns:
a reason code
Definition at line 862 of file jf_file.c.

References CATCH, jf_file_vprintf(), JF_RC_INTERNAL_ERROR, JF_RC_OK, JF_TRACE, and THROW.

LIBJF_EXPORT int jf_file_putc jf_file_t jf,
int  c
 

PUBLIC METHOD
jf_file_putc writes the character c, cast to an byte_t, to journaled file

Parameters:
jf IN/OUT journaled file object
c IN character to write
Returns:
a reason code
Definition at line 683 of file jf_file.c.

References CATCH, jf_file_get_id(), jf_file_get_journal(), jf_journal_add_c(), JF_RC_INTERNAL_ERROR, JF_RC_OK, JF_TRACE, and THROW.

LIBJF_EXPORT int jf_file_puts jf_file_t jf,
const char *  s
 

PUBLIC METHOD
jf_file_puts writes string s to journaled file, without its trailing '0'

Parameters:
jf IN/OUT journaled file object
s IN string
Returns:
a reason code
Definition at line 716 of file jf_file.c.

References byte_t, CATCH, jf_file_get_id(), jf_file_get_journal(), jf_journal_add_byte_data(), JF_RC_INTERNAL_ERROR, JF_RC_OK, JF_TRACE, and THROW.

LIBJF_EXPORT int jf_file_read jf_file_t jf,
void *  data,
size_t  size,
size_t *  read_number
 

PUBLIC METHOD
Read size bytes from journaled file jf

Parameters:
jf IN/OUT journaled file object
data IN location where data must be stored
size IN number of bytes to read
read_number OUT number of bytes successfully read
Returns:
a reason code
Definition at line 648 of file jf_file.c.

References byte_t, CATCH, jf_file_get_id(), jf_file_get_journal(), jf_journal_get_byte_data(), JF_RC_INTERNAL_ERROR, JF_RC_OK, JF_TRACE, and THROW.

Referenced by bench_01_ljf_run(), and bench_03_ljf_run().

void jf_file_reset jf_file_t jf  ) 
 

Reset a file object Definition at line 54 of file jf_file.c.

References jf_file_t::char_buffer, jf_file_t::char_buffer_size, FALSE, jf_file_t::id, JF_JOURNAL_GLOBAL_FILE_ID, JF_TRACE, jf_file_t::journal, and jf_file_t::private_journal.

Referenced by jf_file_close(), and jf_file_open().

int jf_file_rewind jf_file_t jf  )  [inline, static]
 

PUBLIC METHOD
Move the file pointer of a journaled file like "rewind" move the file pointer of a standard IO C stream

Parameters:
jf IN/OUT journaled file object
Returns:
a reason code
Definition at line 445 of file jf_file.h.

References jf_file_seek(), and jf_offset_t.

int jf_file_rollback jf_file_t jfile  )  [inline, static]
 

PUBLIC METHOD
Rollback updates: all the changes since last jf_file_commit / jf_file_rollback / jf_journal_commit / jf_journal_rollback are backed-out

Parameters:
jfile IN/OUT journaled file object
Returns:
a reason code
Definition at line 486 of file jf_file.h.

References jf_file_get_id(), jf_file_get_journal(), and jf_journal_rollback_int().

Referenced by jf_file_close().

LIBJF_EXPORT int jf_file_seek jf_file_t jf,
jf_offset_t  offset,
int  whence
 

PUBLIC METHOD
Move the file pointer of a journaled file like "fseek" move the file pointer of a standard IO C stream

Parameters:
jf IN/OUT journaled file object
offset IN relative offset movement
whence IN specifies how offset must be applied: SEEK_SET: the offset is applied to the beginning of the file SEEK_CUR: the offset is applied to current file position SEEK_END: the offset is applied to end-of-file
Returns:
a reason code
Definition at line 477 of file jf_file.c.

References CATCH, jf_file_get_id(), jf_file_get_journal(), jf_file_is_safe(), JF_FILE_OM_APPEND, JF_FILE_OM_READ, jf_journal_file_get_last_uc_pos(), jf_journal_file_get_last_uc_size(), jf_journal_file_get_open_mode(), jf_journal_file_set_last_uc_pos(), jf_journal_get_jfile(), jf_offset_t, JF_RC_INTERNAL_ERROR, JF_RC_INVALID_STREAM_POSITION, JF_RC_OBJ_CORRUPTED, JF_RC_OK, JF_RC_OUT_OF_RANGE, JF_TRACE, jf_word_t, and THROW.

Referenced by bench_01_ljf_run(), bench_02_ljf_run(), bench_03_ljf_run(), and jf_file_rewind().

LIBJF_EXPORT int jf_file_size jf_file_t jf,
jf_offset_t last_size,
jf_offset_t last_uc_size
 

PUBLIC METHOD
Retrieve the current size of the journaled file

Parameters:
jf IN/OUT journaled file object
last_size OUT last COMMITTED size; pass NULL to avoid it
last_uc_size OUT last UNCOMMITTED size; it may differ from param last_size if there's an "in flyght transaction"; pass NULL to avoid it
Returns:
a reason code
Definition at line 562 of file jf_file.c.

References CATCH, jf_file_get_id(), jf_file_get_journal(), jf_file_is_safe(), jf_journal_file_get_last_size(), jf_journal_file_get_last_uc_size(), jf_journal_get_jfile(), jf_offset_t, JF_RC_INTERNAL_ERROR, JF_RC_OBJ_CORRUPTED, JF_RC_OK, JF_TRACE, jf_word_t, and THROW.

LIBJF_EXPORT int jf_file_vprintf jf_file_t jf,
size_t *  write_number,
const char *  format,
va_list  ap
 

PUBLIC METHOD
NOTE: this metod is defined only on platforms with "vsnprintf" function.
This function is equivalent to jf_file_printf except that it is called with a va_list instead of a variable number of arguments

Parameters:
jf IN/OUT journaled file object
write_number OUT number of bytes written to journaled file (meaningful only if reason core is JF_RC_OK)
format IN specifies how subsequent arguments are converted for output
ap IN specifies a variable array list (va_list)
Returns:
a reason code
Definition at line 899 of file jf_file.c.

References CATCH, jf_file_t::char_buffer, jf_file_t::char_buffer_size, JF_FILE_BUFFER_PAGE_SIZE, jf_file_get_journal(), jf_file_write(), jf_journal_get_open_opts_flags(), JF_JOURNAL_PROP_VIRTMEM_LOW, JF_JOURNAL_PROP_VIRTMEM_MEDIUM, JF_RC_INTERNAL_ERROR, JF_RC_INVALID_STATUS, JF_RC_MALLOC_ERROR, JF_RC_OK, JF_RC_VSNPRINTF_ERROR, JF_TRACE, THROW, and TRUE.

Referenced by jf_file_printf().

LIBJF_EXPORT int jf_file_write jf_file_t jf,
const void *  data,
size_t  size,
size_t *  write_number
 

PUBLIC METHOD
Write size bytes to journaled file jf

Parameters:
jf IN/OUT journaled file object
data IN pointer to data must be written
size IN number of bytes to write
write_number OUT number of bytes successfully written
Returns:
a reason code
Definition at line 607 of file jf_file.c.

References byte_t, CATCH, jf_file_get_id(), jf_file_get_journal(), jf_journal_add_byte_data(), JF_RC_INTERNAL_ERROR, JF_RC_OK, JF_TRACE, and THROW.

Referenced by bench_00_ljf_run(), bench_01_ljf_run(), bench_02_ljf_pre(), bench_02_ljf_run(), bench_03_ljf_run(), bench_X1_ljf_pre(), and jf_file_vprintf().

void jf_set_default_file_open_opts struct jf_file_open_opts_s options  )  [inline, static]
 

PUBLIC METHOD
Set default value for journaled file options

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

References FALSE, jf_set_default_journal_opts(), jf_file_open_opts_s::join_the_journal, and jf_file_open_opts_s::journal_opts.

Referenced by bench_X0_ljf_pre(), jf_file_open(), and jf_journal_util_join().


Copyright 2005 © Tiian