git » libfilo » commit f984989

diff --git a/doc/libfilo.3 b/doc/libfilo.3
new file mode 100644
index 0000000..b6bfadd
--- /dev/null
+++ b/doc/libfilo.3
@@ -0,0 +1,143 @@
+.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 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).
+
+