#include <libfilo.h>
int filo_init(filock_t *fl);
int filo_free(filock_t *fl);
int filo_lock(filock_t *fl, off_t start, off_t len, int mode);
int filo_trylock(filock_t *fl, off_t start, off_t len, int mode);
int filo_unlock(filock_t *fl, off_t start, off_t len);
int filo_plockf(filock_t *fl, int cmd, off_t start, off_t len);
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 fcntl(2).
The rest of the functions, except for filo_plockf which will be discussed later, always take a filock_t pointer, an absolute start offset start and a length len as the first three parameters. The start and the length represent the byte range to operate on, starting from start and counting up to len, so the range goes from start to start + len - 1. The length must be positive greater than 0, otherwise the call will fail. Everywhere, start is given as an absolute position, counting from the beginning of the file.
The mode parameter express if the lock is to be locked for reading or writing, and is expressed with the constants FL_RD_MODE and FL_WR_MODE respectively.
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 lockf(3), since it's a very simple one which people are used to. It takes a filock_t pointer as the first parameter, a command cmd, a start offset start, and a length len.
The cmd parameter express the way the given region should be locked, by using the following constants:
filo_plockf() instead has the oposite return values: it will return 0 if success, or -1 on failure. This behaviour is set to match lockf(3).