lslk - list local locks


SYNOPSIS

       lslk  [ -abhnOvw ] [ -i i ] [ -k k ] [ -p p ] [ -S [t] ] [
       paths ]


DESCRIPTION

       Lslk revision 1.28 lists information about locks  held  on
       files  with  local inodes on systems running the following
       UNIX dialects:

            AIX 3.2.5, 4.1.4, 4.2[.1], and AIX 4.3[.[12]]
            DEC OSF/1, Digital UNIX, and Tru64 UNIX [2345].[01] and 3.2
            Linux
            SCO OpenDesktop or OpenServer 3.0 and 5.0.[0245]
            Sequent PTX 2.1.9, 4.2.1, 4.3, and 4.4
            Solaris 2.[345], 2.5.1, 2.6, 7, and 8 (excluding Veritas
               VxFS local files)
            SunOS 4.1.3

       The lock may belong to a process on the local system or to
       a  process on an NFS client system to which the local sys­
       tem is an NFS server.  Notes: Linux  and  PTX  2.1.9  lslk
       don't  report  on  locks held by NFS clients; Solaris lslk
       won't report locks held on local Veritas VxFS files.


OPTIONS

       In the absence of any options, lslk lists all locks  asso­
       ciated with the local files of the system.

       When  selection  options are specified, the listing of all
       locks is disabled, and  the  selection  options  are  ORed
       together.   Only locks meeting any selection criterion are
       listed.

       When the -a option is specified, the listing of all  locks
       is disabled, and the selection options are ANDed together.
       Only locks that meet all selection criteria are listed.

       -a       This option causes list selection options  to  be
                ANDed, as described above.

       -b       This option causes lslk to avoid kernel functions
                that might block  -  lstat(2),  readlink(2),  and
                stat(2).

                See  the  BLOCKS AND TIMEOUTS and AVOIDING KERNEL
                BLOCKS sections for  information  on  using  this
                option.

       -i i     This  option  selects  the listing of locks whose
                owning process is on the Internet host whose name
                or network address is i.

                -i i options.

       -k k     This option specifies k as an  alternate  to  the
                default  kernel name list file path.  The default
                kernel name list file path is listed  in  the  -h
                help output.

                It  may be necessary to specify an alternate ker­
                nel name list path when the file at  the  default
                path isn't the booted kernel -- e.g., the default
                is /vmunix, but the booted kernel file  is  /vmu­
                nix.new.

                Unless lslk accesses the correct kernel name list
                file, it may derive incorrect addresses for  sym­
                bols in kernel memory, causing it to fail.

       -n       This  option  inhibits  the conversion of network
                host names to network addresses and  the  conver­
                sion  of network addresses to network host names.

                This option may be useful when the host  name  to
                address  translation  service  (e.g.,  the Domain
                Name Server) is slow or inoperative.

                If you use this option on hosts whose kernel lock
                table  contains  only  host  names - e.g., SCO or
                Solaris - or you use this option and also  select
                the  listing  of  locks  by  an  Internet network
                address with the -i i option, lslk  will  not  be
                able  to locate any locks with the specified net­
                work address, nor will it be able to report  net­
                work  addresses  in  its  output.   The -n option
                inhibits the necessary conversion of kernel  lock
                table host names to network addresses.

       -O       This  option  directs lslk to bypass the strategy
                it uses to avoid being  blocked  by  some  kernel
                operations  -  i.e.,  doing  them in forked child
                processes.   See  the  BLOCKS  AND  TIMEOUTS  and
                AVOIDING KERNEL BLOCKS sections for more informa­
                tion on kernel operations that may block lslk.

       -p p     This option selects the listing  of  locks  whose
                owning  process  IDentification (PID) numbers are
                in the comma-separated list, p.

       -S [t]   This option specifies an optional  time-out  sec­
                onds value for kernel functions - lstat(2), read­
                link(2), and stat(2) - that might otherwise dead­
                lock.   The  minimum  for  t is two; the default,
                fifteen; when no value is specified, the  default
                is used.

                information.

       -v       When this option is specified, lslk lists version
                information  -  i.e.,  where, when and how it was
                constructed.

       -w       This option  suppresses  non-fatal  warning  mes­
                sages.

       paths    This  option  specifies a list of file path names
                for which lslk is to list lock information.


OUTPUT

       Lslk lists the information for each  lock  on  a  separate
       line  in  the following columns.  (The columns are dynami­
       cally sized.)

       SRC     indicates the source of the  process  holding  the
               lock.

               If the source is a local process, its command name
               is displayed, or ``(unknown)'' if the command name
               can't be determined.

               If  the  source is a remote process, the host name
               or network number where the  remote  process  exe­
               cutes is displayed.

       PID     is  the  Process IDentification number of the pro­
               cess holding the lock.

       DEV     is the device (major and minor numbers)  on  which
               the locked file resides.

       INUM    is the inode number of the locked file.

       SZ      is the size of the locked file.

       TY      is the lock type:
                         r    read;
                         rw   read and write;
                         w    write;
                         ?    unknown.

       M       is  the  mandatory state of the lock: 0 if none; 1
               if set.  (See chmod(1)).

       ST      is the relative byte offset of the lock.

       WH      is the starting offset (``whence'') of the lock.

       END     is the ending offset of the lock.


       NAME    is the name of the locked file, if it  was  speci­
               fied as a path argument.

               If  there is no path argument name, then the mount
               point and device paths of the file system on which
               the locked file resides are displayed.


BLOCKS AND TIMEOUTS

       Lslk  can be blocked by some kernel functions that it uses
       - lstat(2), readlink(2), and stat(2).  These functions are
       stalled  in  the kernel, for example, when the hosts where
       mounted NFS file systems reside become inaccessible.

       Lslk attempts to break these blocks with timers and  child
       processes,  but  the  techniques  are not wholly reliable.
       When lslk does manage to break a block, it will report the
       break  with  an  error  message.  The messages may be sup­
       pressed with the -w option.

       The default timeout value may be  displayed  with  the  -h
       option, and it may be changed with the -S [t] option.  The
       minimum for t is two seconds, but you should  avoid  small
       values,  since  slow system responsiveness can cause short
       timeouts to expire  unexpectedly  and  perhaps  stop  lslk
       before it can produce any output.

       When  lslk  has  to  break  a  block  during its access of
       mounted file system information,  it  normally  continues,
       although  with less information available to display about
       open files.

       Lslk can also be  directed  to  avoid  the  protection  of
       timers and child processes when using the kernel functions
       that might block by specifying the -O option.  While  this
       will allow lslk to start up with less overhead, it exposes
       lslk completely to the kernel situations that might  block
       it.  Use this option cautiously.


AVOIDING KERNEL BLOCKS

       You can use the -b option to tell lslk to avoid using ker­
       nel functions that would block.  Some cautions apply.

       First, using this option usually requires that your system
       supply  alternate  device  numbers  in place of the device
       numbers that lslk would normally obtain with the  lstat(2)
       and  stat(2)  kernel  functions.  See the ALTERNATE DEVICE
       NUMBERS section for more information on  alternate  device
       numbers.

       Second, you can't specify the names of files you want lslk
       to locate locks for  unless  they're  file  system  names.
       This  is  because  lslk needs to know the device and inode

       and  the  -b  option  prevents  lslk  from obtaining them.
       Moreover, since lslk only has device numbers for the  file
       systems  that have alternates, its ability to locate locks
       on file systems depends completely on the availability and
       accuracy  of  the alternates.  If no alternates are avail­
       able, or if they're  incorrect,  lslk  won't  be  able  to
       locate locks on the named file systems.

       Third,  if  the names of your file system directories that
       lslk obtains from your system's mount table  are  symbolic
       links,  lslk  won't be able to resolve the links.  This is
       because the -b option causes  lslk  to  avoid  the  kernel
       readlink(2) function it uses to resolve symbolic links.

       Finally,  using the -b option causes lslk to issue warning
       messages when it needs to use the  kernel  functions  that
       the -b option directs it to avoid.  You can suppress these
       messages by specifying the -w option, but if you  do,  you
       won't  see  the  alternate  device numbers reported in the
       warning messages.


ALTERNATE DEVICE NUMBERS

       On some dialects, when lslk has to break a  block  because
       it  can't  get information about a mounted file system via
       the lstat(2) and stat(2) kernel functions, or because  you
       specified  the  -b  option,  lslk  can  obtain some of the
       information it needs - the device number and possibly  the
       file system type - from the system mount table.  When that
       is  possible,  lslk  will  report  the  device  number  it
       obtained.   (You can suppress the report by specifying the
       -w option.)

       You can assist this process if your mount  table  is  sup­
       ported with an /etc/mtab or /etc/mnttab file that contains
       an options field by adding a ``dev=xxxx'' field for  mount
       points that do not have one in their options strings.

       The ``xxxx'' portion of the field is the hexadecimal value
       of the file system's device number.  (Consult  the  st_dev
       field  of the output of the lstat(2) and stat(2) functions
       for the appropriate values for your file systems.)  Here's
       an  example  from a Solaris 2.5 /etc/mnttab for a UFS file
       system:

            ... ufs suid,rw,dev=80001f ...

       Some dialects that  do  not  use  an  ASCII  /etc/mtab  or
       /etc/mnttab  file for the mount table may still provide an
       alternative device number in their internal mount  tables.
       This  includes  AIX,  DEC  OSF/1,  Digital UNIX, and Tru64
       UNIX.  Lslk knows how to  obtain  the  alternative  device
       number  for these dialects and uses it when its attempt to
       lstat(2) or stat(2) the file system is blocked.

       numbers  for  file  systems from its mount table, use this
       lslk incantation to see if it reports any alternate device
       numbers:

              lslk -b

       Look  for  standard error file warning messages that begin
       ``assuming "dev=xxxx" from ...''.


DIAGNOSTICS

       Errors are identified with messages on the standard  error
       file.

       Lslk  returns  a one (1) if an error was detected or if it
       couldn't list lock information for all the names that were
       specified.


EXAMPLES

       To list all locks, use:

              lslk

       To  list  locks  from  the  host  ``klaatu''  in the local
       domain, use:

              lslk -i klaatu

       To list locks  from  the  hosts  helios.cc.purdue.edu  and
       vic1.cc.purdue.edu, use:

              lslk -i helios.cc.purdue.edu -i vic1.cc.purdue.edu

       To list locks held by processes 1234 and 56789, use:

              lslk -p 1234,56789

       To  list  all  locks  held by process 1234 on host klaatu,
       use:

              lslk -p 1234 -a -i klaatu


PERMISSION

       Lslk must have permission  to  access  the  system  memory
       files  -  e.g.,  /dev/kmem and /dev/mem.  Permission to do
       that is granted when the lslk process is run from  a  root
       shell,  or  when  its  ``setgid''  group matches the group
       (e.g., ``sys'') that can read the system memory files.


BUGS

       Perhaps it should be possible to specify the host on which
       a search target PID is located.

       DEC  OSF/1,  Digital  UNIX, and Tru64 UNIX lslk won't find

       locks applied with the fcntl(2) and lockf(3) functions.

       Linux  lslk will not report locks held by NFS clients.  It
       may have difficulty reporting locks held on dynamic inodes
       (e.g., for the Win-95 file system type, smbfs).

              Solaris lslk won't find locks held on local Veritas
              VxFS files by local or remote processes.


FILES

       /dev/kmem    kernel virtual memory device

       /dev/mem     physical memory device


AUTHORS

       Lslk was written by Victor A.  Abell  <abe@purdue.edu>  of
       the Purdue University Computing Center (PUCC).

       Chris Eleveld <chris@sector7.com> did the DEC OSF/1, Digi­
       tal UNIX, Linux, and Tru64 UNIX ports.


SEE ALSO

       chmod(1),  fcntl(2),   fcntl(5),   flock(3B),   lockd(1M),
       lstat(2), lockf(3C), readlink(2), stat(2).


Man(1) output converted with man2html