Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

RedHat 9 (Linux i386) - man page for lockdev (redhat section 3)

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

NAME
       lockdev,  liblockdev, dev_testlock, dev_lock, dev_relock, dev_unlock - manage device lock-
       files

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  con-
       tains  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 prob-
       lem 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 dif-
       ferent 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 pro-
       gram.
       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 send-
       ing 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  struc-
       ture  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;  ver-
       sion 2 dated June, 1991.

Linux Manpage				   26 Dec 1997				       LOCKDEV(3)


All times are GMT -4. The time now is 06:25 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password