view release on metacpan or  search on metacpan

libjio/libjio/libjio.3  view on Meta::CPAN

recovery.

It is used to perform journal checking and recovery in case of a crash. It
must be performed when nobody else is using the file (like in the case of a
filesystem which can't be mounted), and it returns 0 if success or an error
code != 0 in case of a failure. If it succeeded, it will fill jfsck_result
summarizing the outcome of the operation. The error codes can be either
.I J_ENOENT
(no such file),
.I J_ENOJOURNAL
(no journal associated with that file),
.I J_ENOMEM
(not enough free memory),
.I J_ECLEANUP
(error cleaning the journal directory), and
.I J_EIO
(I/O error). There is also a program named
.I jiofsck
which is just a simple human frontend to this function.


.SS UNIX-alike API

The UNIX-alike API, as explained before, consists of the functions
.BR jread() ", " jpread() ", " jreadv() ", " jwrite() ", " jpwrite() ", "
.BR jwritev() ", " jtruncate() "and " jlseek() .

They are all exactly like the UNIX equivalent, and behave the same way, with
the only exception that instead of a file descriptor you need to pass a
pointer to a
.IR "jfs_t" .
Again, I will not duplicate the manpage for all these functions, just refer to
the regular UNIX versions to see how to use them, they all have the same
semantics and behave the same way.

.SS BASIC FUNCTIONS

The basic functions are the ones which manipulate transactions directly:
.BR jtrans_new() ", " jtrans_add_r() ", " jtrans_add_w() ", "
.BR jtrans_commit() ", " jtrans_rollback() " and " jtrans_free()" .
These are intended to be use when your application requires direct control
over the transactions.

.BR jtrans_new() " and " jtrans_free()
just return a new
.I jtrans_t
and free a given one; the former should be called prior any use, and the
latter when you want to destroy a transaction. Note that
.B jtrans_free()
is not a disk operation, but only frees the pointers that were previously
allocated by the library; all disk operations are performed by the other two
functions.

You can add multiple read and write operations to a transaction, and they will
be applied in order.

.B jtrans_add_w()
is used to add write operations to a transaction, and it takes the same
parameters as
.BR pwrite() :
a buffer, its length and the offset where it should be applied, and adds it to
the transaction. The buffer is copied internally and can be free()d right
after this function returns.

.B jtrans_add_r()
is used to add read operations to a transaction, and it takes the same
parameters as
.BR pread() :
a buffer, its length and the offset where it should read from, and adds it to
the transaction. 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).

.B jtrans_commit()
commits the given transaction to disk. After it has returned, write operations
have been saved to the disk, and read operations have been read from it. The
commit operation is atomic with regards to other read or write operations on
different processes, as long as they all access it via libjio. It returns the
number 0 on success, -1 if there was an error but atomic warantees were
preserved, or -2 if there was an error and there is a possible break of atomic
warantees (which is an indication of a severe underlying condition).

.B jtrans_rollback()
reverses a transaction that was applied with
.BR jtrans_commit() ,
and leaves the file as it was before applying it. Be very very careful with
this function, it's quite dangerous if you don't know for sure that you're
doing the right thing. It returns the same values as
.BR jtrans_commit() .

.SH SEE ALSO

.BR open (2),
.BR read (2),
.BR write (2),
.BR readv (2),
.BR writev (2),
.BR pread (2),
.BR pwrite (2),
.BR ftruncate (2),
.BR lseek (2),
.BR close (2)

.SH BUGS

If you want to report bugs, or have any questions or comments, just let me
know at albertito@blitiri.com.ar.