lockdev, liblockdev, dev_testlock, dev_lock, dev_relock,
dev_unlock - manage device lockfiles
SYNOPSIS
#include <lockdev.h>
pid_t dev_testlock( const char * devname);
pid_t dev_lock( const char * devname);
pid_t dev_relock( const char * devname, pid_t pid);
pid_t dev_unlock( const char * devname, pid_t pid);
cc [ flag ... ] file ... -llockdev [ library ]
DESCRIPTION
The lockdev functions act on device locks normally located
in /var/lock . The lock is acquired creating a pair of
files hardlinked between them and named after the device
name (as mandated by FSSTND) and the device's major and
minor numbers (as in SVr4 locks). This permits to circum
vent a problem using only the FSSTND lock method when the
same device exists under different names (for convenience
or when a device must be accessable by more than one group
of users).
The lock file names are typically in the form LCK..ttyS1
and LCK.004.065 , but is provided a way to easily modify
them to use the library on different architectures. The
content of those files is the pid of the process who owns
the lock.
The dev_testlock() function simply checks if the device is
in some way locked and if the owner of the lock is still
active (otherwise it removes the lock). It recognise a
valid lock even if only one of the two lock files exists
(and is owned by an existing process), thus permitting a
safe use of this library together with programs using only
FSSTND or SVr4 lock style.
The dev_lock() function first checks if the device is
already locked and then tries to acquire the lock building
the two lock files. First it creates the file which name
contains the major and minor numbers (in SVr4 style), then
it creates the file with the device name in its name. This
order reduces the clashes with other processes trying to
lock the same device (even with a different name) and
using this library. It has no problem with processes that
uses only the FSSTND algorithm.
The dev_relock() function changes the owner of an existing
lock; if the pid of the old owner is provided, then it
checks if the lock was correctly assigned (otherwise there
is the possibility of a process acquiring a lock which was
owned by another unrelated process). If the device was not
locked, locks it.
the device. If the pid of the owner of the lock is pro
vided, then it checks if the lock is assigned to that pro
cess, avoiding to remove locks assigned to other existing
processes.
RETURN VALUES
All the functions in lockdev library return ZERO on suc
cessfull completion of the function (dev_testlock returns
zero if there is no lock on the device), otherwise, if the
device is currently locked by an existing process, they
return the pid of the process owner of the lock. They
return a negative number when some kind of error happens.
Actually they all return only (-1).
DEBUGGING
The API has symbols used only for debugging purposis
int liblockdev_debug
void liblockdev_incr_debug( void );
void liblockdev_reset_debug( void );
which can be used when the liblockdev library is compiled
with -DDEBUG flag as when using make install-dbg , which
compiles a debug shared library and installs it under
/usr/local/lib/debug (or /usr/lib/debug).
The value of the global integer is set to 1 by the DEBUG
define, and can be set to a different value passing a flag
like -DDEBUG=3 during compilation of the library, or set
ting the environment variable LIBLOCKDEV_DEBUG to the
wanted value before executing your program.
During execution of your program, the flag's value can be
changed from your program or from another terminal,
respectively using the function liblockdev_incr_debug() ,
or sending SIGUSR1 to the running process, to increment
the value of the integer by one, or using the function
liblockdev_reset_debug() , or sending SIGUSR2 to the run
ning process, to set to zero the value of the global inte
ger.
Direct manipulation of the global integer is strongly dep
recated, because the data structure of the symbol (actu
ally an integer) could be changed later in some way, or
even become a macro.
The library prints on stdout some informations like error
conditions (level of 1), normal termination conditions (2)
or function calling (3).
To use the debug shared library, simply define in your
environment the variable LD_LIBRARY_PATH=/usr/lib/debug
(or /usr/local/lib/debug if built using make install-dbg)
and call gdb or directly your program without any need to
load the debug library instead of the normal one.
Beware that if your program is setuid or setgid, you must
become root to let this work, because ld.so ignores the
LD_LIBRARY_PATH variable for security reasons.
On Debian GNU/Linux systems exists a debug binary package
named liblockdev1-dbg which installs a shared library
built with all debugging options (and the -DDEBUG flag)
into /usr/lib/debug .
FILES
/var/lock/LCK..<device>
/var/lock/LCK.<major>.<minor>
/usr/lib/liblockdev.so.1
/usr/lib/debug/liblockdev.so.1
HISTORY
(c) 1997 by Fabrizio Polacco <fab@prosa.it>.
This program is free software; you can redistribute it
and/or modify it under the terms of the GNU Lesser General
Public License as published by the Free Software Founda
tion; version 2 dated June, 1991.
Man(1) output converted with
man2html