journal

journal — Utility functions for journal handling

Synopsis

#include <atomic-install/journal.h>

typedef             ai_journal_t;
int                 ai_journal_create                   (const char *journal_path,
                                                         const char *location);
int                 ai_journal_open                     (const char *journal_path,
                                                         ai_journal_t *ret);
int                 ai_journal_close                    (ai_journal_t j);
int                 ai_journal_get_maxpathlen           (ai_journal_t j);
const char *        ai_journal_get_filename_prefix      (ai_journal_t j);
typedef             ai_journal_file_t;
ai_journal_file_t * ai_journal_get_files                (ai_journal_t j);
ai_journal_file_t * ai_journal_file_next                (ai_journal_file_t *f);
unsigned char       ai_journal_file_flags               (ai_journal_file_t *f);
int                 ai_journal_file_set_flag            (ai_journal_file_t *f,
                                                         unsigned char new_flag);
const char *        ai_journal_file_name                (ai_journal_file_t *f);
const char *        ai_journal_file_path                (ai_journal_file_t *f);
unsigned long int   ai_journal_get_flags                (ai_journal_t j);
int                 ai_journal_set_flag                 (ai_journal_t j,
                                                         unsigned long int new_flag);

Description

libjournal provides a set of functions to create and use atomic-install journal files.

Details

ai_journal_t

typedef struct ai_journal *ai_journal_t;

The type describing an open journal. Returned by ai_journal_open(); when done with it, pass to ai_journal_close().


ai_journal_create ()

int                 ai_journal_create                   (const char *journal_path,
                                                         const char *location);

Create a new journal file and fill it with files from source tree location. This function doesn't open the newly-created journal; for that, use ai_journal_open() afterwards.

journal_path :

path for the new journal file

location :

source tree location

Returns :

0 on success, errno otherwise

ai_journal_open ()

int                 ai_journal_open                     (const char *journal_path,
                                                         ai_journal_t *ret);

Open the journal file at journal_path and put ai_journal_t for it at location pointed by ret. Note that ret may be modified even if this function fails (e.g. when journal contents are invalid).

journal_path :

path to the journal file

ret :

location to store new ai_journal_t

Returns :

0 on success, errno otherwise

ai_journal_close ()

int                 ai_journal_close                    (ai_journal_t j);

Close the journal file.

j :

an open journal

Returns :

0 on success, errno otherwise (very unlikely)

ai_journal_get_maxpathlen ()

int                 ai_journal_get_maxpathlen           (ai_journal_t j);

Get the maximum path length for files within the journal. This is the length of ai_journal_file_path() + ai_journal_file_name() for the longest path in the journal. This variable can be used to allocate buffer quickly.

j :

an open journal

Returns :

maximum path length

ai_journal_get_filename_prefix ()

const char *        ai_journal_get_filename_prefix      (ai_journal_t j);

Get the random prefix used for temporary files associated with this journal (session).

j :

an open journal

Returns :

a pointer to null-terminated prefix in the journal

ai_journal_file_t

typedef char ai_journal_file_t;

The type describing a single file in the journal. Used via a pointer.


ai_journal_get_files ()

ai_journal_file_t * ai_journal_get_files                (ai_journal_t j);

Get the pointer to the first file in journal.

j :

an open journal

Returns :

a pointer to ai_journal_file_t, or NULL if no files

ai_journal_file_next ()

ai_journal_file_t * ai_journal_file_next                (ai_journal_file_t *f);

Get the pointer to the next file in journal.

f :

the current file

Returns :

a pointer to ai_journal_file_t, or NULL if f is last

ai_journal_file_flags ()

unsigned char       ai_journal_file_flags               (ai_journal_file_t *f);

Get flags for the specified file.

f :

the file

Returns :

an 8-bit flag field contents

ai_journal_file_set_flag ()

int                 ai_journal_file_set_flag            (ai_journal_file_t *f,
                                                         unsigned char new_flag);

Set specified flag for the file.

f :

the file

new_flag :

bitfield for new flags to set

Returns :

0 on success, errno otherwise

ai_journal_file_name ()

const char *        ai_journal_file_name                (ai_journal_file_t *f);

Get the filename part of file path.

f :

the file

Returns :

a pointer to static, null-terminated filename inside journal

ai_journal_file_path ()

const char *        ai_journal_file_path                (ai_journal_file_t *f);

Get the directory part of file path. The path is guaranteed to have a trailing slash, i.e. files in root directory will return '/'.

f :

the file

Returns :

a pointer to static, null-terminated path inside journal

ai_journal_get_flags ()

unsigned long int   ai_journal_get_flags                (ai_journal_t j);

Get global journal flags.

j :

an open journal

Returns :

a 32-bit flag field contents

ai_journal_set_flag ()

int                 ai_journal_set_flag                 (ai_journal_t j,
                                                         unsigned long int new_flag);

Set specified flag for the journal. The journal will be synced to disk afterwards.

j :

an open journal

new_flag :

bitfield for new flags to set

Returns :

0 on success, errno otherwise