view release on metacpan or  search on metacpan

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

/** 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.
 *
 * @param name path to the file to open
 * @param flags flags to pass to open(2)
 * @param mode mode to pass to open(2)
 * @param jflags journal flags
 * @returns a new jfs_t that identifies the open file on success, or NULL on
 *	error
 * @see jclose(), open()
 * @ingroup basic
 */
jfs_t *jopen(const char *name, int flags, int mode, unsigned int jflags);

/** 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.
 *
 * @param fs open file
 * @returns 0 on success, -1 on error
 * @see jopen(), jfs_autosync_start()
 * @ingroup basic
 */
int jclose(jfs_t *fs);

/** Sync a file. Makes sense only when using lingering transactions.
 *
 * @param fs open file
 * @returns 0 on success, -1 on error
 * @ingroup basic
 */
int jsync(jfs_t *fs);

/** 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.
 *
 * @param fs open file the transaction will apply to
 * @param flags transaction flags
 * @returns a new transaction (must be freed using jtrans_free())
 * @see jtrans_free()
 * @ingroup basic
 */
jtrans_t *jtrans_new(jfs_t *fs, unsigned int flags);

/** 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.
 *
 * @param ts transaction
 * @param buf buffer to write
 * @param count how many bytes from the buffer to write
 * @param offset offset to write at
 * @returns 0 on success, -1 on error
 * @ingroup basic
 */
int jtrans_add_w(jtrans_t *ts, const 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.
 *
 * @param ts transaction
 * @param buf buffer to read to
 * @param count how many bytes to read
 * @param offset offset to read at
 * @returns 0 on success, -1 on error
 * @ingroup basic
 * @see jread()
 */
int jtrans_add_r(jtrans_t *ts, void *buf, size_t count, off_t offset);

/** 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.
 *
 * @param 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).
 * @ingroup basic
 */
ssize_t jtrans_commit(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.
 *
 * @param ts transaction
 * @returns the same as jtrans_commit()
 * @see jtrans_commit()
 * @ingroup basic
 */
ssize_t jtrans_rollback(jtrans_t *ts);

/** Free a transaction structure.
 *
 * @param ts transaction to free
 * @see jtrans_new()
 * @ingroup basic