NAME¶
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
circumvent 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
dev_unlock() function removes the existing locks on the device. If
the pid of the owner of the lock is provided, then it checks if the lock is
assigned to that process, avoiding to remove locks assigned to other existing
processes.
RETURN VALUES¶
All the functions in
lockdev library return
ZERO on successfull
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 setting 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 running process,
to set to zero the value of the global integer.
Direct manipulation of the global integer is strongly deprecated, because the
data structure of the symbol (actually 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
recompile it. As you can check with ldd, your program will 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 Foundation; version 2 dated June, 1991.