.ds VN 1.29
.TH LSLK 8 Revision-\*(VN
.if !\n()P .nr )P 1v
.SH NOTICE
.nf
!!!NOTICE!!!   !!!NOTICE!!!   !!!NOTICE!!!   !!!NOTICE!!!   !!!NOTICE!!!!
.br
!                                                                       !
.br
! Revision 1.29 represents the end of life for lslk.  I don't have time !
.br
! to support it.  Please don't report bugs to me.  I will politely      !
.br
! decline to work on them.                                              !
.br
!                                                                       !
.br
! Vic Abell <abe@purdue.edu>, July 11, 2001                             !
.br
!                                                                       !
.br
!!!NOTICE!!!   !!!NOTICE!!!   !!!NOTICE!!!   !!!NOTICE!!!   !!!NOTICE!!!!
.fi
.SH NAME
lslk \- list local locks
.SH SYNOPSIS
.B lslk
[
.B \-abhnOvw
] [
.BI \-i " i"
] [
.BI \-k " k"
] [
.BI \-p " p"
] [
.BI \-S " [t]"
] [
.I paths
]
.SH DESCRIPTION
.I Lslk
revision \*(VN lists information about locks held on files with
local inodes on systems running the following UNIX dialects:
.PP
.nf
	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
.fi
.PP
The lock may belong to a process on the local system or to a
process on an NFS client system to which the local system is
an NFS server.
Notes: Linux and PTX 2.1.9
.I lslk
don't report on locks held by NFS clients;
Solaris
.I lslk
won't report locks held on local Veritas VxFS files.
.SH OPTIONS
In the absence of any options,
.I lslk
lists all locks associated with the local files of the system.
.PP
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.
.PP
When the
.B \-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.
.TP \w'paths'u+4
.B \-a
This option causes list selection options to be ANDed, as described
above.
.TP
.B \-b
This option causes
.I lslk
to avoid kernel functions that might block \-
.IR lstat (2),
.IR readlink (2),
and
.IR stat (2).
.IP
See the
.B "BLOCKS AND TIMEOUTS"
and
.B "AVOIDING KERNEL BLOCKS"
sections for information on using this option.
.TP
.BI \-i " i"
This option selects the listing of locks whose owning process is
on the Internet host whose name or network address is \fIi\fP.
.IP
Multiple addresses may be declared with multiple
.BI \-i " i"
options.
.TP
.BI \-k " k"
This option specifies \fIk\fP as an alternate to the default kernel name
list file path.
The default kernel name list file path is listed in the
.B \-h
help output.
.IP
It may be necessary to specify an alternate kernel name list path
when the file at the default path isn't the booted kernel -- e.g.,
the default is
.IR /vmunix ,
but the booted kernel file is
.IR /vmunix.new .
.IP
Unless
.I lslk
accesses the correct kernel name list file, it may derive incorrect
addresses for symbols in kernel memory, causing it to fail.
.TP
.B \-n
This option inhibits the conversion of network host names to
network addresses and the conversion of network addresses to
network host names.
.IP
This option may be useful when the host name to address translation
service (e.g., the Domain Name Server) is slow or inoperative.
.IP
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
.BI \-i " i"
option,
.I lslk
will not be able to locate any locks with the specified network address,
nor will it be able to report network addresses in its output.
The
.B \-n
option inhibits the necessary conversion of kernel lock table host names
to network addresses.
.TP
.B \-O
This option directs
.I 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
.B "BLOCKS AND TIMEOUTS"
and
.B "AVOIDING KERNEL BLOCKS"
sections for more information on kernel operations that may block
.IR lslk .
.TP
.BI \-p " p"
This option selects the listing of locks whose owning process
IDentification (PID) numbers are in the comma\-separated list,
.IR p .
.TP
.BI \-S " [t]"
This option specifies an optional time-out seconds value for kernel
functions \-
.IR lstat (2),
.IR readlink (2),
and
.IR stat (2)
\- that might otherwise deadlock.
The minimum for
.I t
is two;
the default, fifteen; when no value is specified, the default is used.
.IP
See the
.B "BLOCKS AND TIMEOUTS"
section for more information.
.TP
.B \-v
When this option is specified,
.I lslk
lists version information \- i.e., where, when and how it was
constructed.
.TP
.B \-w
This option suppresses non\-fatal warning messages.
.TP
.I paths
This option specifies a list of file path names for which
.I lslk
is to list lock information.
.SH OUTPUT
.I Lslk
lists the information for each lock on a separate line in
the following columns.
(The columns are dynamically sized.)
.TP \w'NAME'u+4
SRC
indicates the source of the process holding the lock.
.IP
If the source is a local process, its command name is displayed,
or ``(unknown)'' if the command name can't be determined.
.IP
If the source is a remote process, the host name or network
number where the remote process executes is displayed.
.TP
PID
is the Process IDentification number of the process holding the lock.
.TP
DEV
is the device (major and minor numbers) on which the locked file
resides.
.TP
INUM
is the inode number of the locked file.
.TP
SZ
is the size of the locked file.
.TP
TY
is the lock type:
.nf
		r	read;
.br
		rw	read and write;
.br
		w	write;
.br
		?	unknown.
.fi
.TP
M
is the mandatory state of the lock: 0 if none; 1 if set.
(See 
.IR chmod (1)).
.TP
ST
is the relative byte offset of the lock.
.TP
WH
is the starting offset (``whence'') of the lock.
.TP
END
is the ending offset of the lock.
.TP
LEN
is the length of the lock.
.TP
NAME
is the name of the locked file, if it was specified as a
.I path
argument.
.IP
If there is no
.I path
argument name, then the mount point and device paths of the file system
on which the locked file resides are displayed.
.SH "BLOCKS AND TIMEOUTS"
.I Lslk
can be blocked by some kernel functions that it uses \-
.IR lstat (2),
.IR readlink (2),
and
.IR stat (2).
These functions are stalled in the kernel, for example, when the
hosts where mounted NFS file systems reside become inaccessible.
.PP
.I Lslk
attempts to break these blocks with timers and child processes,
but the techniques are not wholly reliable.
When
.I lslk
does manage to break a block, it will report the break with an error
message.
The messages may be suppressed with the
.B \-w
option.
.PP
The default timeout value may be displayed with the
.B \-h
option, and it may be changed with the
.BI \-S " [t]"
option.
The minimum for
.I t
is two seconds, but you should avoid small values, since slow system
responsiveness can cause short timeouts to expire unexpectedly and
perhaps stop
.I lslk
before it can produce any output.
.PP
When
.I 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.
.PP
.I 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
.B \-O
option.
While this will allow
.I lslk
to start up with less overhead, it exposes
.I lslk
completely to the kernel situations that might block it.
Use this option cautiously.
.SH "AVOIDING KERNEL BLOCKS"
.PP
You can use the
.B \-b
option to tell
.I lslk
to avoid using kernel functions that would block.
Some cautions apply.
.PP
First, using this option usually requires that your system supply
alternate device numbers in place of the device numbers that
.I lslk
would normally obtain with the
.IR lstat (2)
and
.IR stat (2)
kernel functions.
See the
.B "ALTERNATE DEVICE NUMBERS"
section for more information on alternate device numbers.
.PP
Second, you can't specify the
.I names
of files you want
.I lslk
to locate locks for unless they're file system names.
This is because
.I lslk
needs to know the device and inode numbers of files listed with
.I names
in the
.I lslk
options, and the
.B \-b
option prevents
.I lslk
from obtaining them.
Moreover, since
.I 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 available, or if they're incorrect,
.I lslk
won't be able to locate locks on the named file systems.
.PP
Third, if the names of your file system directories that
.I lslk
obtains from your system's mount table are symbolic links,
.I lslk
won't be able to resolve the links.
This is because the
.B \-b
option causes
.I lslk
to avoid the kernel
.IR readlink (2)
function it uses to resolve symbolic links.
.PP
Finally, using the
.B \-b
option causes
.I lslk
to issue warning messages when it needs to use the kernel functions
that the
.B \-b
option directs it to avoid.
You can suppress these messages by specifying the
.B \-w
option, but if you do, you won't see the alternate device numbers
reported in the warning messages.
.SH "ALTERNATE DEVICE NUMBERS"
.PP
On some dialects, when
.I lslk
has to break a block because it can't get information about a
mounted file system via the
.IR lstat (2)
and
.IR stat (2)
kernel functions, or because you specified the
.B \-b
option,
.I 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,
.I lslk
will report the device number it obtained.
(You can suppress the report by specifying the
.B \-w
option.)
.PP
You can assist this process if your mount table is supported with an
.I /etc/mtab
or
.I /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.
.PP
The ``xxxx'' portion of the field is the hexadecimal value
of the file system's device number.
(Consult the
.I st_dev
field of the output of the
.IR lstat (2)
and
.IR stat (2)
functions for the appropriate values for your file systems.)
Here's an example from a Solaris 2.5
.I /etc/mnttab
for a UFS file system:
.PP
.nf
	... ufs suid,rw,dev=80001f ...
.fi
.PP
Some dialects that do not use an ASCII
.I /etc/mtab
or
.I /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.
.I Lslk
knows how to obtain the alternative device number for these dialects
and uses it when its attempt to
.IR lstat (2)
or
.IR stat (2)
the file system is blocked.
.PP
If you're not sure your dialect supplies alternate device numbers
for file systems from its mount table, use this
.I lslk
incantation to see if it reports any alternate device numbers:
.IP
lslk -b
.PP
Look for standard error file warning messages that
begin ``assuming "dev=xxxx" from ...''.
.SH DIAGNOSTICS
Errors are identified with messages on the standard error file.
.PP
.I Lslk
returns a one (1) if an error was detected
or if it couldn't list lock information for all the
.I names
that were specified.
.SH EXAMPLES
To list all locks, use:
.IP
lslk
.PP
To list locks from the host ``klaatu'' in the local domain,
use:
.IP
lslk -i klaatu
.PP
To list locks from the hosts helios.cc.purdue.edu and
vic1.cc.purdue.edu, use:
.IP
lslk -i helios.cc.purdue.edu -i vic1.cc.purdue.edu
.PP
To list locks held by processes 1234 and 56789, use:
.IP
lslk -p 1234,56789
.PP
To list all locks held by process 1234 on host klaatu, use:
.IP
lslk -p 1234 -a -i klaatu
.SH PERMISSION
.I Lslk
must have permission to access the system memory files \- e.g.,
.I /dev/kmem
and
.IR /dev/mem \.
Permission to do that is granted when the
.I 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.
.SH BUGS
Perhaps it should be possible to specify the host on which a
search target PID is located.
.PP
DEC OSF/1, Digital UNIX, and Tru64 UNIX
.I lslk
won't find locks applied with the
.IR flock (2)
function.
It will find locks applied with the
.IR fcntl (2)
and
.IR lockf (3)
functions.
.PP
Linux
.I 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, \fIsmbfs\fP).
.IP
Solaris
.I lslk
won't find locks held on local Veritas VxFS files by local or
remote processes.
.SH FILES
.TP \w'/dev/kmem'u+4
.I /dev/kmem
kernel virtual memory device
.TP
.I /dev/mem
physical memory device
.SH AUTHORS
.I Lslk
was written by Victor A. Abell <abe@purdue.edu> of the Purdue
University Computing Center (PUCC).
.PP
Chris Eleveld <chris@sector7.com> did the DEC OSF/1, Digital UNIX,
Linux, and Tru64 UNIX ports.
.SH SEE ALSO
chmod(1),
fcntl(2),
fcntl(5),
flock(3B),
lockd(1M),
lstat(2),
lockf(3C),
readlink(2),
stat(2).