libfilo

Section: C Library Functions (3)
Updated: 27/Apr/2005
Index Return to Main Contents
 

NAME

libfilo - A file locking library

 

SYNOPSIS

#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);

 

DESCRIPTION

libfilo is a small portable library to do userspace file locking, like fcntl(2), lockf(3) or 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 fcntl(2).

 

USAGE

Locks are represented using the filock_t type. They must be initialized with filo_init, and once they won't be used anymore, destroyed by calling filo_free. Note that 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 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:

FL_LOCKR
Locks the region for reading, blocking if the lock is not immediately available.
FL_LOCKW
Locks the region for writing, blocking if the lock is not immediately available.
FL_TLOCKR
Locks the region for reading without blocking; if the lock is not immediately available return failure.
FL_TLOCKW
Locks the region for writing without blocking; if the lock is not immediately available return failure.
FL_ULOCK
Unlocks the region.

 

RETURN VALUE

All functions except filo_plockf() return 1 if success or 0 if failure; notably filo_trylock() will return 1 if the lock was acquired, or 0 if it would have blocked.

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).

 

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.

 

AUTHORS

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

 

SEE ALSO

fcntl(2), lockf(3), flock(2).


 

Index

NAME
SYNOPSIS
DESCRIPTION
USAGE
RETURN VALUE
NOTES
AUTHORS
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 21:29:16 GMT, April 27, 2005