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_t * jopen (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_t * jtrans_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:


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_t *	jopen (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_t *	jtrans_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).