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