LOCKDEV(3)						     Linux Programmer's Manual							LOCKDEV(3)

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 func-
       tion liblockdev_incr_debug() , or sending SIGUSR1 to the running process, to increment the value of the integer by one, or using the  func-
       tion 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  pro-
       gram 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 pub-
       lished by the Free Software Foundation; version 2 dated June, 1991.

Linux Manpage							    26 Dec 1997 							LOCKDEV(3)