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.