Basic API

This is the basic, lower-level API. More...


Defines

#define J_NOLOCK   1
 Don't lock the file before operating on it.
#define J_NOROLLBACK   2
 No need to read rollback information.
#define J_LINGER   4
 Use lingering transactions.

Functions

jfs_tjopen (const char *name, int flags, int mode, unsigned int jflags)
 Open a file.
int jclose (jfs_t *fs)
 Close a file opened with jopen().
int jsync (jfs_t *fs)
 Sync a file.
jtrans_tjtrans_new (jfs_t *fs, unsigned int flags)
 Create a new transaction.
int jtrans_add_w (jtrans_t *ts, const void *buf, size_t count, off_t offset)
 Add a write operation to a transaction.
int jtrans_add_r (jtrans_t *ts, void *buf, size_t count, off_t offset)
 Add a read operation to a transaction.
ssize_t jtrans_commit (jtrans_t *ts)
 Commit a transaction.
ssize_t jtrans_rollback (jtrans_t *ts)
 Rollback a transaction.
void jtrans_free (jtrans_t *ts)
 Free a transaction structure.
int jmove_journal (jfs_t *fs, const char *newpath)
 Change the location of the journal directory.
int jfs_autosync_start (jfs_t *fs, time_t max_sec, size_t max_bytes)
 Start an autosync thread.
int jfs_autosync_stop (jfs_t *fs)
 Stop an autosync thread that was started using jfs_autosync_start(fs).


Detailed Description

This is the basic, lower-level API.

Define Documentation

#define J_NOLOCK   1

Don't lock the file before operating on it.

See also:
jopen()

Definition at line 449 of file libjio.h.

Referenced by jtrans_commit(), and lock_file_ranges().

#define J_NOROLLBACK   2

No need to read rollback information.

See also:
jopen()

Definition at line 455 of file libjio.h.

Referenced by jtrans_add_common(), jtrans_commit(), and jtrans_rollback().

#define J_LINGER   4

Use lingering transactions.

See also:
jopen()

Definition at line 461 of file libjio.h.

Referenced by jtrans_commit().


Function Documentation

jfs_t* jopen ( const char *  name,
int  flags,
int  mode,
unsigned int  jflags 
) [read]

Open a file.

Takes the same parameters as the UNIX open(2), with an additional one for internal flags.

The only supported internal flag is J_LINGER, which enables lingering transactions.

Parameters:
name path to the file to open
flags flags to pass to open(2)
mode mode to pass to open(2)
jflags journal flags
Returns:
a new jfs_t that identifies the open file on success, or NULL on error
See also:
jclose(), open()

Definition at line 545 of file trans.c.

Referenced by jfopen().

Here is the call graph for this function:

Here is the caller graph for this function:

int jclose ( jfs_t fs  ) 

Close a file opened with jopen().

After a call to this function, the memory allocated for the open file will be freed.

If there was an autosync thread started for this file, it will be stopped.

Parameters:
fs open file
Returns:
0 on success, -1 on error
See also:
jopen(), jfs_autosync_start()

Definition at line 754 of file trans.c.

Referenced by jfclose(), and jopen().

Here is the call graph for this function:

Here is the caller graph for this function:

int jsync ( jfs_t fs  ) 

Sync a file.

Makes sense only when using lingering transactions.

Parameters:
fs open file
Returns:
0 on success, -1 on error

Definition at line 667 of file trans.c.

Referenced by autosync_thread(), jclose(), and jmove_journal().

Here is the call graph for this function:

Here is the caller graph for this function:

jtrans_t* jtrans_new ( jfs_t fs,
unsigned int  flags 
) [read]

Create a new transaction.

Note that the final flags to use in the transaction will be the result of ORing the flags parameter with fs' flags.

Parameters:
fs open file the transaction will apply to
flags transaction flags
Returns:
a new transaction (must be freed using jtrans_free())
See also:
jtrans_free()

Definition at line 31 of file trans.c.

Referenced by jfsck(), jpwrite(), jtrans_rollback(), jwrite(), and jwritev().

Here is the caller graph for this function:

int jtrans_add_w ( jtrans_t ts,
const void *  buf,
size_t  count,
off_t  offset 
)

Add a write operation to a transaction.

A write operation consists of a buffer, its length, and the offset to write it to.

The file will not be touched (not even locked) until commit time, where the first count bytes of buf will be written at offset.

Operations will be applied in order, and overlapping operations are permitted, in which case the latest one will prevail.

The buffer will be copied internally and can be free()d right after this function returns.

Parameters:
ts transaction
buf buffer to write
count how many bytes from the buffer to write
offset offset to write at
Returns:
0 on success, -1 on error

Definition at line 232 of file trans.c.

Referenced by jpwrite(), jwrite(), and jwritev().

Here is the call graph for this function:

Here is the caller graph for this function:

int jtrans_add_r ( jtrans_t ts,
void *  buf,
size_t  count,
off_t  offset 
)

Add a read operation to a transaction.

An operation consists of a buffer, its length, and the offset to read it from.

The file will not be touched (not even locked) until commit time, where the first count bytes at offset will be read into buf.

Note that if there is not enough data in the file to read the specified amount of bytes, the commit will fail, so do not attempt to read beyond EOF (you can use jread() for that purpose).

Operations will be applied in order, and overlapping operations are permitted, in which case the latest one will prevail.

In case of an error in jtrans_commit(), the contents of the buffer are undefined.

Parameters:
ts transaction
buf buffer to read to
count how many bytes to read
offset offset to read at
Returns:
0 on success, -1 on error
See also:
jread()

Definition at line 227 of file trans.c.

Here is the call graph for this function:

ssize_t jtrans_commit ( jtrans_t ts  ) 

Commit a transaction.

All the operations added to it using jtrans_add_w()/jtrans_add_r() will be written to/read from disk, in the same order they were added.

After this function returns successfully, all the data can be trusted to be on the disk. The commit is atomic with regards to other processes using libjio, but not accessing directly to the file.

Parameters:
ts transaction
Returns:
0 on success, or -1 if there was an error but atomic warranties were preserved, or -2 if there was an error and there is a possible break of atomic warranties (which is an indication of a severe underlying condition).

Definition at line 240 of file trans.c.

Referenced by jfsck(), jpwrite(), jtrans_rollback(), jwrite(), and jwritev().

Here is the call graph for this function:

Here is the caller graph for this function:

ssize_t jtrans_rollback ( jtrans_t ts  ) 

Rollback a transaction.

This function atomically undoes a previous committed transaction. After its successful return, the data can be trusted to be on disk. The read operations will be ignored.

Use with care.

Parameters:
ts transaction
Returns:
the same as jtrans_commit()
See also:
jtrans_commit()

Definition at line 452 of file trans.c.

Referenced by jtrans_commit().

Here is the call graph for this function:

Here is the caller graph for this function:

void jtrans_free ( jtrans_t ts  ) 

Free a transaction structure.

Parameters:
ts transaction to free
See also:
jtrans_new()

Definition at line 57 of file trans.c.

Referenced by jpwrite(), jtrans_rollback(), jwrite(), and jwritev().

Here is the caller graph for this function:

int jmove_journal ( jfs_t fs,
const char *  newpath 
)

Change the location of the journal directory.

The file MUST NOT be in use by any other thread or process. The older journal directory will be removed.

Parameters:
fs open file
newpath path to the new journal directory, which will be created if it doesn't exist
Returns:
0 on success, -1 on error

Definition at line 701 of file trans.c.

Here is the call graph for this function:

int jfs_autosync_start ( jfs_t fs,
time_t  max_sec,
size_t  max_bytes 
)

Start an autosync thread.

The thread will call jsync(fs) every max_sec seconds, or every max_bytes have been written. Only one autosync thread per open file is allowed.

Parameters:
fs open file
max_sec maximum number of seconds that should pass between each call to jsync()
max_bytes maximum number of bytes that should be written between each call to jsync()
Returns:
0 on success, -1 on error

Definition at line 84 of file autosync.c.

Here is the call graph for this function:

int jfs_autosync_stop ( jfs_t fs  ) 

Stop an autosync thread that was started using jfs_autosync_start(fs).

Parameters:
fs open file
Returns:
0 on success, -1 on error

Definition at line 109 of file autosync.c.

Referenced by jclose().

Here is the caller graph for this function:


Generated on Sat Sep 12 13:33:34 2009 for libjio (internal) by  doxygen 1.5.8