.TH libfilo 3 "27/Apr/2005"
.SH NAME
libfilo - A file locking library

.SH SYNOPSIS

.B #include <libfilo.h>

.BI "int filo_init(filock_t *" fl ");"

.BI "int filo_free(filock_t *" fl ");"

.BI "int filo_lock(filock_t *" fl ", off_t " start ", off_t " len ", int " mode ");"

.BI "int filo_trylock(filock_t *" fl ", off_t " start ", off_t " len ", int " mode ");"

.BI "int filo_unlock(filock_t *" fl ", off_t " start ", off_t " len ");"

.BI "int filo_plockf(filock_t *" fl ", int " cmd ", off_t " start ", off_t " len ");"

.SH DESCRIPTION
libfilo is a small portable library to do userspace file locking, like
.BR fcntl (2),
.BR lockf (3)
or
.BR flock (2),
but within threads. It allows you to do read/write file locking with
fcntl-like semantics and it's implemented entirely in userspace.

A file lock is a special type of lock that is normally associated with an open
file, and allows you to lock file regions (usually represented by a start
offset and a length, both measured in bytes). A given region can be locked
either for reading or for writing; multiple threads can lock a region for
read, but only one can hold a writing lock.

A thread can hold only one type of lock for a region; if it attempts to lock
a region that it already has a lock for, its type is converted to the new one.
This semantics match the ones implemented by
.BR fcntl (2).

.SH USAGE
Locks are represented using the
.B filock_t
type. They must be initialized with
.BR filo_init ,
and once they won't be used anymore, destroyed by calling
.BR "filo_free" .
Note that
.B filo_free
will NOT free the filock_t pointer itself, it will just deallocate any data
structure that the library has allocated for its internal use, if any.

The rest of the functions, except for
.B filo_plockf
which will be discussed later, always take a
.B filock_t
pointer, an absolute start offset
.B start
and a length
.B len
as the first three parameters. The start
and the length represent the byte range to operate on, starting from
.B start
and counting up to
.BR "len" ,
so the range goes from
.B start
to
.BR "start + len - 1" .
The length must be positive greater than 0, otherwise the call will fail.
Everywhere,
.B start
is given as an absolute position, counting from the beginning of the file.

The
.B mode
parameter express if the lock is to be locked for reading or writing, and is
expressed with the constants
.B FL_RD_MODE
and
.B FL_WR_MODE
respectively.

.BR filo_plockf ()
is a special function, since it's based on the ones descripted above, and
provides the same functionality but with an interface similar to
.BR lockf (3),
since it's a very simple one which people are used to. It takes a
.B filock_t
pointer as the first parameter, a command
.BR cmd ,
a start offset
.BR start ,
and a length
.BR len.

The
.BR cmd
parameter express the way the given region should be locked, by using the
following constants:
.TP
.B FL_LOCKR
Locks the region for reading, blocking if the lock is not immediately
available.
.TP
.B FL_LOCKW
Locks the region for writing, blocking if the lock is not immediately
available.
.TP
.B FL_TLOCKR
Locks the region for reading without blocking; if the lock is not immediately
available return failure.
.TP
.B FL_TLOCKW
Locks the region for writing without blocking; if the lock is not immediately
available return failure.
.TP
.B FL_ULOCK
Unlocks the region.
.PP
.SH "RETURN VALUE"
All functions except
.BR filo_plockf ()
return 1 if success or 0 if failure; notably
.BR filo_trylock ()
will return 1 if the lock was acquired, or 0 if it would have blocked.

.BR filo_plockf ()
instead has the oposite return values: it will return 0 if success, or -1 on
failure. This behaviour is set to match
.BR lockf (3).

.SH NOTES
The library is normally installed with Large File Support, so you should not
link against applications that are not using it (and in fact there's a check
in the header to avoid this), since it can cause horrible bugs.

.SH AUTHORS
.B libfilo
was written by Alberto Bertogli (albertogli@telpin.com.ar). It has a website,
currently at http://users.auriga.wearlab.de/~alb/libfilo/.

.SH "SEE ALSO"
.BR fcntl (2),
.BR lockf (3),
.BR flock (2).