Man Linux: Main Page and Category List

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.