Skip to content
Browse files

Initial commit of lsof with Android mods.

  • Loading branch information...
0 parents commit 14bc52ecabe5e76fab8826aae5e332a6ce9fe2c3 @fhunleth committed Sep 14, 2010
Showing with 32,507 additions and 0 deletions.
  1. +47 −0 00.README.FIRST
  2. +521 −0 00CREDITS
  3. +745 −0 00DCACHE
  4. +6 −0 00DIALECTS
  5. +4,515 −0 00DIST
  6. +7,996 −0 00FAQ
  7. +100 −0 00LSOF-L
  8. +363 −0 00MANIFEST
  9. +1,805 −0 00PORTING
  10. +1,023 −0 00QUICKSTART
  11. +1,535 −0 00README
  12. +1,009 −0 00TEST
  13. +683 −0 00XCONFIG
  14. +346 −0 AFSConfig
  15. +20 −0 Android.mk
  16. +49 −0 CleanSpec.mk
  17. +5,482 −0 Configure
  18. +1,151 −0 Customize
  19. +204 −0 Inventory
  20. +170 −0 Makefile
  21. +2,428 −0 arg.c
  22. +1 −0 dfile.c
  23. +169 −0 dialects/aix/Makefile
  24. +24 −0 dialects/aix/Mksrc
  25. +7 −0 dialects/aix/aix5/README
  26. +19 −0 dialects/aix/aix5/j2/j2_lock.h
  27. +17 −0 dialects/aix/aix5/j2/private_j2_snapshot.h
  28. +728 −0 dialects/aix/ddev.c
  29. +600 −0 dialects/aix/dfile.c
  30. +442 −0 dialects/aix/dlsof.h
  31. +302 −0 dialects/aix/dmnt.c
Sorry, we could not display the entire diff because it was too big.
47 00.README.FIRST
@@ -0,0 +1,47 @@
+Now that you have the lsof distribution, I suggest:
+
+* If you're unfamiliar with lsof, read 00README for information on
+ Configuring and building lsof, 00QUICKSTART for tips on using lsof.
+
+ If you're too impatient for that, do this:
+
+ $ ./Configure <put your UNIX dialect's abbreviation here>
+ (Do the inventory step, as you prefer.)
+ (Do the customization step, as you prefer.)
+ $ make
+ $ ./lsof -h
+
+ To get a list of UNIX dialect abbreviations:
+
+ $ Configure -h
+
+ Please don't be impatient -- read the documentation first.
+
+* Read the current distribution's details in 00DIST.
+
+* If you want technical details, read 00DCACHE and 00PORTING.
+
+* If you want to cross-configure, read 00XCONFIG.
+
+* Use the test suite, described in 00TEST, by:
+
+ $ cd tests
+ $ make
+
+ and possibly:
+
+ $ make opt
+
+* If you're having trouble, read 00FAQ. (Please read 00FAQ before
+ you send a bug report.)
+
+* Lsof contributors may find their names in 00CREDITS. (Thanks, again.)
+
+* Read the lsof.man page file. Its nroff source is in lsof.8.
+
+* Consider subscribing to the lsof-l mailing list -- read 00LSOF-L
+ for details.
+
+
+Vic Abell <abe@purdue.edu>
+April 19, 2002
521 00CREDITS
@@ -0,0 +1,521 @@
+
+ Lsof Credits
+
+I owe an enormous debt to the users of lsof who have contributed
+to its steady growth. The size of the list of people who have
+helped me, while it has grown too large to include in the lsof man
+page any more, is a testimonial to their generosity.
+
+First I acknowledge a debt to the work of Dan Bernstein, Michael
+``Ford'' Ditto, Tom Dunigan, Alexander Dupuy, Vik Lall, Ray Moody,
+C. Spencer, Michael Spitzer and those who wrote Berkeley's fstat
+program, all contributors to lsof's predecessors.
+
+I thank Doug McKenzie for his HP-UX proctor program and Rich Kulawiec
+for pointing it out.
+
+Finally I thank all the following people who have used lsof, pointed
+out its flaws, described its shortcomings, offered suggestions for
+improving it, supplied code for it, gave me technical advice, and
+provided test systems where I was able to do development work.
+
+ Szilveszter Adam
+ David Addison
+ Elias Halldor Agustsson
+ Per Allansson
+ Jim Ankenbrandt
+ Richard Allen
+ Thomas Anders
+ Ric Anderson
+ Stuart Anderson
+ Michael Antlitz
+ Marc Auslander
+ Tigran Aivazian
+ Jos Backus
+ David Bacon
+ Alexis Ballier
+ Scott Ballew
+ Ade Barkah
+ Alon Bar-Lev
+ Anthony Baxter
+ John Beacom
+ Bruce Beare
+ M. Jay Beck
+ Bill Behr
+ Michael Beirne
+ Marc Bejarano
+ Andrew Bell
+ Steve Bellenot
+ Robert Benites
+ Dmitry Berezin
+ Ulrich Bernhard
+ Peter J. Bertoncini
+ Dave Bianchi
+ Mark Bixby
+ Allan Black
+ Jan Blunck
+ Achim Bohnet
+ Steve Bonds
+ Mark Bonsack
+ Volker Borchert
+ Bill Bormann
+ Ermin Borovac
+ Heddy Boubaker
+ Pieter Bowman
+ Michael Bracewell
+ H. Merijn Brand
+ Danny Braniss
+ Thomas Braunbeck
+ Kieran Broadfoot
+ Dean Brock
+ Hal Brooks
+ Andrew Brown
+ Jim Brown
+ Michael Bryan
+ Matthew Burt
+ Robert Byrnes
+ Pierfrancesco Caci
+ Bill Campbell
+ David Capshaw
+ John Caruso
+ Jon Champlin
+ Kris Chandrasekhar
+ Albert Chin-A-Young
+ Bernt Christandl
+ Marc Christensen
+ Hans Petter Christiansen
+ Tom Christiansen
+ Yves Christophe
+ Richard Chycoski
+ A. Channing Clark
+ Axel Clauberg
+ John Clear
+ David Clissold
+ Richard Coley
+ John Colgrave
+ David Comay
+ Lionel Cons
+ Bob Cook
+ Patrick Connor
+ Carl Cook
+ Jim Cooper
+ Roger Cornelius
+ Doug Crabill
+ Eric Cronin
+ Kim Culhan
+ Dave Curry
+ Robert Dahlem
+ Guy Dallaire
+ D. Chris Daniels
+ Renata Maria Dart
+ Ian Darwin
+ Carl E. Davidson
+ David Day
+ Will Day
+ Frederic Delanoy
+ Mike Depot
+ Steve Dibbell
+ Hugh Dickins
+ David DiGiacomo
+ Casper Dik
+ John DiMarco
+ Don Draper
+ Michel Dubois
+ Eric Dumazet
+ Dick Dunbar
+ Marc Duponcheel
+ Jan Dvorak
+ Calle Dybedahl
+ John Dzubera
+ Jeff Earickson
+ Greg Earle
+ Bernd Eckenfels
+ Niklas Edmundsson
+ Philip Edwards
+ Robert Ehrlich
+ Mark W. Eichin
+ Doug Eldred
+ Scott Ellentuch
+ Tom Endo
+ Craig Everhart
+ Chris Evert
+ Bob Farmer
+ Sami Farin
+ Mike Feldman
+ Quentin Fennessy
+ Ian Fitchet
+ Toralf Foerster
+ Bob Foertsch
+ Pierre-Yves Fontaniere
+ Ralph Forsythe
+ Jason Fortezzo
+ Mike Fraser
+ Curt Freeland
+ Terry Friedrichsen
+ Mike Frysinger
+ Harvey Garner
+ Carson Gaspar
+ Stuart D. Gathman
+ Brian L. Gentry
+ Dave Gilbert
+ Steve Ginsberg
+ Edwin Groothuis
+ Jin Guojun
+ Kurt Gollhardt
+ Roman Gollent
+ Steve Gonczi
+ Julian Gordon
+ Marcin Gozdalik
+ Henry Grebler
+ Richard Green
+ Chaskiel Grundman
+ Armin Gruner
+ David Gutierrez
+ Robert Hall
+ Garner Halloran
+ Adam Hammer
+ Charles Hannum
+ Vlad Harchev
+ Craig Harmer
+ Michael Haro
+ Peter Harvey
+ Steinar Haug
+ Sheldon Hearn
+ John Heasley
+ Wolfgang Hecht
+ Janet Hempstead
+ Michael Hennecke
+ Randolph J. Herber
+ Andrew Hill
+ Kurt Hillig
+ Steven Hinkle
+ Paul Hite
+ Billy Ho
+ Brett Hogden
+ Gaylord Holder
+ Kjetil Torgrim Homme
+ Pekka Honkanen
+ Jeffrey C. Honig
+ Heidi Hornstein
+ Michael A. Hovan III
+ Barbara Howe
+ J. Nelson Howell
+ Jeff Howie
+ Louis Huemiller
+ John Hughes
+ Gerrit Huizenga
+ Peter Ilieve
+ Mayer Ilovitz
+ Gregory A. Ivanov
+ John Jackson
+ Kurt Jaeger
+ Edward Jajko
+ Marian Jancar
+ Paul Jarc
+ Jakub Jelinek
+ Robert Jelinek
+ Bruce Jerrick
+ Carl Johnson
+ Dion Johnson
+ Jeff Johnson
+ Douglas B. Jones
+ LaMont Jones
+ Peter Jordan
+ Arne H. Juul
+ Pasi Kaara
+ Frank Kaefer
+ Keith Kalet
+ Claus Kalle
+ Henri Karrenbeld
+ Amir Katz
+ Henry Katz
+ Kawaljeet Kaur
+ Doug Kehn
+ Kris Kennaway
+ Terry Kennedy
+ Shane Kenney
+ Andrew Kephart
+ Robert Kiessling
+ Joshua Kinard
+ Don Kirouac
+ Steve Kirsch
+ Philip Kizer
+ Thomas Klausner
+ Roger Klorese
+ Peter Klosky
+ Przemek Klosowski
+ Angelos D. Keromytis
+ Radko Keves
+ Valdis Kletnieks
+ Chris Kordish
+ Alek O. Komarnitsky
+ Joseph Kowalski
+ Christian Krackowizer
+ Paul Kranenburg
+ Troyan Krastev
+ Brad Krebs
+ Alex Kreis
+ Johannes Kroeger
+ Vincent Kujala
+ Ken Laing
+ Shirley Lam
+ Erwin Lansing
+ Victoria H. Lau
+ Markus Lautenbacher
+ Steve Lacey
+ Marc Aurele La France
+ Chad R. Larson
+ Steve Laubscher
+ Andrei V. Lavreniyuk
+ Loc Le
+ Tin Le
+ Diane Lebel
+ Francis Le Bourse
+ Kyungjoon Lee
+ Marty Leisner
+ Maciej Lesniewski
+ Stuart Levy
+ Ben Lewis
+ Michael Lewis
+ Angel Li
+ Ambrose Li
+ Wendy Lin
+ Carl E. Lindberg
+ Onno van der Linden
+ Johan Lindquist
+ James Lingard
+ Jason Lingohr
+ Robert Lipe
+ Gabor Liptak
+ Friedel Loinger
+ Michael Long
+ Pete Lord
+ Steve Logue
+ Bela Lubkin
+ Pav Lucistnik
+ Horst Luehrsen
+ Andreas Luik
+ Timothy J. Luoma
+ Michael Mackenzie
+ Lawrence MacIntyre
+ Jerome Marchand
+ Benson Margulies
+ Claude Marinier
+ Chris Markle
+ Roy Marples
+ Eberhard Mater
+ James Mathiesen
+ Tom Matthews
+ Fletcher Mattox
+ David Mazieres
+ Brian McAllister
+ Scott McClung
+ Dale McCluskey
+ Terry McCoy
+ Sean McDermott
+ Duncan McEwan
+ Dwight McKay
+ William McVey
+ Eric McWhorter
+ Marjo F. Mercado
+ Dan Mercer
+ Bill Melvin
+ Andrew Merril
+ Richard van Meurs
+ Jim Mewes
+ Gary Millen
+ Timothy Miller
+ Davin Milun
+ Yuliy Minchev
+ Jim Mintha
+ Mike Miscevic
+ Arkadiusz Miskiewicz
+ Janardhan Molumuri
+ Nasser Momtaheni
+ Laurent Montaron
+ Phillip Moore
+ Dmitry Morozovsky
+ John Paul Morrison
+ John Gardiner Myers
+ Jeffrey Mogul
+ Dave Morrison
+ Pat Myrto
+ Toshiya Nakamura
+ Filippo Natali
+ Allan Nathanson
+ Chance Neale
+ Dan Nelson
+ Vladislav Nespor
+ Bjorn S. Nilsson
+ Anders Nordby
+ Joseph J. Nuspl Jr.
+ David O'Brien
+ Alexandre Oliva
+ Craig B. Olofson
+ Dave Olson
+ Rainer Orth
+ Sergey A. Osokin
+ Keith Parks
+ Will Partain
+ Vasco Pedro
+ Mark Peek
+ Ezra Peisach
+ Bill Pemberton
+ Lee Penn
+ Gildas Perrot
+ Jesse Perry
+ Nathan Peterson
+ Dominique Petitpierre
+ Hung Pham
+ Ray Phillips
+ Francois Pinard
+ Alex Podlecki
+ Lutz Poetschulat,
+ John Polstra
+ Scott Presnell
+ Mark Price
+ Philippe-Andre Prindeville
+ David Putz
+ Tom Qin
+ Kurtis Rader
+ Peter Radig
+ Jean-Pierre Radley
+ Tim Ramsey
+ Dewan Rashid
+ Richard J. Rauenzahn
+ Louis Rayman
+ Brian Redman
+ Eric S. Raymond
+ Erwin Reyns
+ Aaron Rhodes
+ Jim Reid
+ Jean-Luc Richier
+ Ingimar Robertson
+ Sylvain Robitaille
+ Larry Rogers
+ Malgorzata Roos
+ Larry Rosenman
+ Stephan Rossi
+ Kevin Ruderman
+ Wolfgang Rupprecht
+ Pavol Rusnak
+ Conrad J. Sabatier
+ Klaus Saggerer
+ Chris Schanzle
+ Igor Schein
+ Horst Scheuermann
+ Michael Schmitz
+ Larry Schwimmer
+ Hendrik G. Seliger
+ Igor V. Semenyuk
+ Jonathan Sergent
+ Frank Sanders
+ Berkley Shands
+ Gregory Neil Shapiro
+ Eyal Shaynis
+ Michael Shields
+ Wesley Shields
+ Philip Shin
+ Anthony Shortland
+ Dave Sill
+ John Silva
+ Chuck Silvers
+ Gerry Singleton
+ Leonard Sitongia
+ Kevin Smallwood
+ Curt Smith
+ Ben Smithurst
+ Douglas R. Smith
+ Kevin Smith
+ Chang Song
+ Josh Soref
+ John Speno
+ Kenneth Stailey
+ Piet Starreveld
+ David Steiner
+ Charles Stephens
+ Marc Stephenson
+ Chip Stettler
+ Dave Stevens
+ Jeff Stewart
+ Diana Stockdale
+ Andreas Stolcke
+ Jeff Stoner
+ Sushila Subramanian
+ Jan Ole Suhr
+ Mike Sullivan
+ Patrick D. Sullivan
+ Peter Svensson
+ Chris Sylvain
+ Miklos Szeredi
+ Paul Szabo
+ Dale Talcott
+ Jon A. Tankersley
+ Jan Tax
+ Samuel Thibault
+ Andy Thomas
+ Matthew Thurmaier
+ Chris Timmons
+ Andrzej Tobola
+ R. Lindsay Todd
+ Zdenko Tomasic
+ Michael Townsend
+ Linus Torvalds
+ Mike Tracy
+ Dan Trinkle
+ Erik Trulsson
+ Lars Tunkrans
+ Lenny Turetsky
+ Kevin Vajk
+ Peter Valchev
+ John R. Vanderpool
+ Peter Van Epp
+ Peter C. Vernam
+ Peter Vines
+ Bob Ward
+ Jules van Weerden
+ Tom Weaver
+ Fernando A.B. Whitaker
+ Tom Whitty
+ Carson Wilson
+ David J. Wilson
+ Frank Winkler
+ Marc Winkler
+ Mark Vasoll
+ Holger VanKoll
+ Robert Vernon
+ Joep Vesseur
+ Larry Virden
+ Jos Vos
+ Jun Biao Wang
+ Christopher J Warweg
+ Bill Watson
+ Florian M. Weps
+ Joel White
+ Paul Wickman
+ Martin Wilke
+ Eric Williams
+ Steve Williams
+ Steve Wilson
+ Erich Wimmer
+ Wally Winzer, Jr.
+ Patrick Wolfe
+ Stephen Woods
+ James Woodward
+ Scott Worley
+ Joshua Wright
+ Sailu Yallapragada
+ Donna Yobs
+ Ron Young
+ Blair Zajac
+ Karel Zak
+ Donald Zoch
+ Malcom Zung
+ and Waldemar Zurowski
+
+If I have omitted a contributor's name, the fault is wholly mine,
+and I apologize for the error.
+
+
+Vic Abell <abe@purdue.edu>
+July 29, 2010
745 00DCACHE
@@ -0,0 +1,745 @@
+
+ Configuring The Device Cache File Path
+
+ Contents
+
+ A. Introduction and History
+ B. Device Cache File Format
+ 1. Integrity Checks
+ 2. The Setgid and Setuid-root States
+ C. Device Cache File Path Options
+ 1. Path Named by ``-D''
+ 2. Path Named in Environment Variable
+ 3. Default System-wide Path
+ a. Build Procedure
+ 4. Default Personal Path
+ 5. Modified Default Personal Path
+ D. Displaying the Default Path
+ Appendix A, Unix Dialects Without a Device Cache
+ Appendix B, Lsof Dialects and Their Permissions
+ 1. Setuid-root Lsof Dialects
+ 2. Setgid Lsof Dialects That Surrender Setgid
+ Permission
+
+
+A. Introduction and History
+===========================
+
+Lsof writes a file of information about the contents of the nodes
+in /dev (or /devices) to reduce its startup overhead on later calls.
+It does this for all Unix dialects, except those noted in Appendix A.
+
+This file, called the device cache file, enables lsof to avoid
+calling the kernel stat(2) function on every node in /dev (or
+/devices) from which it builds a table of correspondence between
+major/minor device numbers and device names.
+
+A full scan of /dev (or /devices) on some systems may involve
+calling the sometimes-slow stat(2) function 10,000 times or more.
+Furthermore, each stat(2) call consumes space in the kernel's name
+cache, forcing from it path name components that would be more
+useful when lsof tries to associate them with open files.
+
+While it's hard to question the usefulness of the device cache,
+it's also hard to decide where it should be written. When the
+feature was first added, the device cache file was written to /tmp,
+and its ownership was set to that of the real user ID (UID) under
+which the creating lsof process was run. However, to enable any
+process to update it when /dev (or /devices) changed, lsof set its
+modes to 0666, thus allowing anyone to read or write it.
+
+The writing of a world-readable and world-writable device cache
+file to any place has security weaknesses. A clever intruder who
+carefully preserves the integrity of the file might be able to
+remove devices that would prevent lsof from observing the intruder's
+files. A clever intruder might also be able to put a symbolic link
+in place and trick lsof into writing to the link's destination with
+its effective permissions, thus bypassing the real user's (possibly
+weaker) permissions.
+
+Later the location of the device cache file was changed. It was
+converted to a personal file, located in the home directory of each
+real UID that executed lsof, and owned by that UID. Thus it was
+no longer possible for one user to affect lsof's access to the
+device cache file, nor was it possible for a user to mount a symbolic
+link attack on a restricted file, but the result was that each lsof
+user had a private copy of the device cache file.
+
+The device cache file feature has undergone some further refinements
+in path name formation to reach its present state. This documentation
+describes the path name formation options open to the lsof builder
+and user after those refinements, and how lsof attempts to insure
+that none of the options presents a security risk.
+
+
+B. Device Cache File Format
+===========================
+
+The device cache file is a flat file of ASCII text. It has an
+initial statement of how many sections the file might contain --
+the possible sections are character devices, block devices, clone
+devices, pseudo devices, and checksum. The character devices and
+checksum sections are always present.
+
+Each section has a header that numbers the entries in the section.
+
+The last section is a checksum section that contains a 16 bit cyclic
+redundancy (CRC) checksum of everything in the file but the checksum
+section itself.
+
+Lsof always sets the permission modes of the device cache file to
+0600, and the owner to the real UID of the process that executes
+lsof; the group, the real group ID (GID) of the lsof process.
+
+Setting the permission modes to 0600 means that a system-wide device
+cache file won't be usable unless the procedure that builds it
+changes the modes after lsof has written it. A suitable procedure
+for building a system-wide device cache that shows how to adjust
+these inadequate permission modes is given in the Default System-wide
+Path section.
+
+
+B.1. Integrity Checks
+=====================
+
+When lsof opens the device cache file it makes these integrity
+checks:
+
+ 1. Lsof must gain permission from access(2) to be able to
+ open the file for reading. If lsof is writing the file,
+ it usually cedes permission control to the applicable
+ directory and file modes and ownerships. (Some additional
+ checks apply and they're described in the sections on path
+ options.)
+
+ By explicit design lsof never writes to the system-wide
+ device cache file, even when the real UID of its process
+ is root. The system-wide device cache file must be written
+ with a root-owned procedure via the ``-D[b|u<path>'' options
+ -- i.e., under the system administrator's control. (See
+ the Build Procedure sub-section of the Default System-wide
+ Path section.)
+
+ 2. The device cache file's modes must be 0600 (0644 if lsof
+ is reading a system-wide device cache file) and its size
+ must be non-zero.
+
+ 3. There must be a correctly formatted section count line
+ at the beginning of the file.
+
+ 4. Each section must have a header line with a count that
+ properly numbers the lines in the section. The first words
+ of legal section titles are "device", "block", "clone",
+ "pseudo", and "CRC".
+
+ 5. The lines of a section must have the proper format.
+
+ 6. All lines are included in a 16 bit CRC, and it is recorded
+ in a non-checksummed section line at the end of the file.
+
+ 7. The checksum computed when the file is read must match the
+ checksum recorded when the file was written.
+
+ 8. The checksum section line must be followed by end-of-
+ information.
+
+ 9. Lsof must be able to get matching results from stat(2)
+ on a randomly chosen entry of the device section.
+
+
+B.2. The Setgid and Setuid-root States
+======================================
+
+There are two fundamental ways in which lsof is granted access to
+restricted system resources. Both access methods are related to the
+effective permissions given the lsof binary or executable.
+
+The first and preferable way to grant lsof access to system resources
+through the permissions endowed on its executable is the giving of
+set group ID (setgid) permission. The group is the one that has
+permission to read the kernel memory and swap devices -- e.g., /dev/kmem,
+/dev/mem, /dev/swap, etc.
+
+This method of granting access is called setgid mode because it
+enables lsof to run with an effective group ID set to the one
+granted by the permissions of its executable file and by the group
+that owns the executable file. See the getegid(2) man page for a
+further discussion of effective group ID.
+
+Usually lsof only needs setgid permission to open access to the
+kernel memory files. After they're open, lsof drops its setgid
+permission.
+
+The second and least preferable way to grant lsof access to system
+resources through the permissions endowed on its executable is the
+giving of set user ID to root (setuid-root) permission. This is
+much too strong a permission, but necessary: to use the -X option
+fully for the version of lsof for AIX 5 and above; to use the
+version of lsof for HP-UX 11.11 and above; and to use the version
+of lsof for Linux 2.1.72 and above. These lsof implementations
+require setuid-root permission to be able to access restricted
+resources -- e.g., the individual files of the /proc file system.
+(But note that the setuid-root Linux lsof doesn't need and has no
+device cache support.)
+
+Lsof never drops setuid-root permission, because it needs that
+power throughout its execution. However, when the lsof process is
+setuid-root, lsof disallows these device cache file path options:
+
+ 1. It ignores the ``-D[b|r|u]<path>'' options. It accepts
+ only the ``-Di'' and ``-Dr'' options.
+
+ 2. It refuses to recognize a path supplied via an environment
+ variable.
+
+ 3. It refuses to accept an additional path component from an
+ environment variable to be inserted in the middle of a
+ personal device cache file path.
+
+Each restriction is imposed because setuid-root power might allow
+a malicious user to form a device cache file path that would give
+read access to a normally inaccessible place (That's bad enough.),
+or write access to a critical system file (That's the worst case.)
+
+There is one further state that lsof can enter that is slightly
+different from the setuid-root and setgid states. That state occurs
+when lsof is being run from a root shell -- i.e., the lsof real
+user ID is root. To avoid accidental complications, when lsof is
+in this state, it ignores all environment variable options.
+
+In the rest of this document you will find more detailed discussion
+of the special restrictions caused by the type of permission that
+has been given the lsof executable.
+
+
+C. Device Cache File Path Options
+=================================
+
+Lsof offers five options for constructing the path to the device
+cache file. Each has special conditions and safeguards that
+surround its use. The options are:
+
+ 1. A device cache file that is named in the <path> component
+ of the parameters of lsof's ``-D'' option.
+
+ =========================================================
+ * This is a default option of the lsof distribution. *
+ * *
+ * Paths specified with this option are read-only unless *
+ * the real UID of the lsof process is root (0), or the *
+ * lsof process is able to surrender setgid permission *
+ * (See Appendix B) and it is not setuid-root. *
+ =========================================================
+
+ 2. A device cache file whose name is specified by an environment
+ variable.
+
+ =========================================================
+ * This is a default option of the lsof distribution. *
+ * *
+ * This option is enabled when the lsof dialect is able *
+ * to surrender setgid permission (See Appendix B.), and *
+ * the lsof process is not setuid-root. *
+ * *
+ * The environment variable path is read-only if the *
+ * lsof process does not surrender setgid permission *
+ * (See Appendix B.) *
+ =========================================================
+
+ 3. A system-wide default device cache file, located at a path
+ determined by the builder of lsof. The lsof builder is also
+ responsible for building the device cache file, using a
+ different lsof path formation option at a suitable time --
+ e.g., when the system is booted.
+
+ =========================================================
+ * This is option is disabled by default in the lsof *
+ * distribution. *
+ * *
+ * The path specified with this option is read-only. *
+ =========================================================
+
+ 4. A default personal device cache file, located in the UID's
+ home directory.
+
+ =========================================================
+ * This is a default option of the lsof distribution. *
+ =========================================================
+
+ 5. A personal device cache file whose name is modified by an
+ environment variable.
+
+ =========================================================
+ * This is a default option of the lsof distribution. *
+ * *
+ * The modified personal path is read-only if the lsof *
+ * process does not surrender setgid permission. *
+ * *
+ * This option is disabled when the lsof process is *
+ * setuid-root or its real UID is root (0). *
+ =========================================================
+
+When there are multiple choices for the device cache file path,
+lsof chooses from the above list in the order the list is given,
+subject to restrictions based on the effective group and user IDs
+that are in effect.
+
+Each possible path name is discussed in a later section that
+describes the restrictions that apply to it and the method for
+building lsof to use it.
+
+In one special case lsof will use two paths in order. When a
+system-wide device cache file is enabled, and lsof finds that it
+doesn't exist, lsof will attempt to use a personal device cache
+file.
+
+
+C.1. Path Named by ``-D''
+=========================
+
+The ``-D[b|r|u]<path>'' option can name a path for the device cache
+file where it is unconditionally built (`b'); read, but never
+rebuilt (`r'); and read and rebuilt, if necessary (`u').
+
+If the lsof process is setuid-root, no path may be specified with
+the ``-D'' option -- i.e., only the `i' function is accepted. The
+`r' option may be used if it doesn't have a path argument.
+
+If the lsof process is not setuid-root, nor is the real UID of the
+lsof process root, a path may accompany the `b', `r', and `u'
+functions if the lsof process surrenders setgid permission. (See
+Appendix B.) If the process doesn't surrender setgid permission,
+then a path may accompany only `r'.
+
+Lsof's permission to access a device cache file at a path specified
+with ``-D[b|r|u]<path>'' depends completely on the permission modes
+and ownerships of the file and its directory components.
+
+When the real UID of the lsof process is root (0), paths may be
+specified with ``-D[b|r|u]''.
+
+====================================================================
+* *
+* The ``-D[b|r|u]<path>'' option is enabled by default in the lsof *
+* distribution by the following definition in the dialect's *
+* machine.h header file: *
+* *
+* #define HASDCACHE 1 *
+* *
+* To disable all device cache file options, including all ``-D'' *
+* forms, change the above line in the dialect's machine.h file to: *
+* *
+* /* #define HASDCACHE 1 */ *
+* *
+* or remove it. *
+* *
+* The ``-D[b|r|u]<path>'' options are disabled when the lsof *
+* process is setuid-root. If the lsof process isn't setuid-root, *
+* nor is its real UID root (0), and if the lsof process surrenders *
+* setgid permission, ``-D[b|r|u]'' may be accompanied by a path. *
+* *
+* A path may accompany ``-D[b|u]'' when the real UID of the lsof *
+* process is root. *
+* *
+* ``-Dr'' without a path name argument is always acceptable. *
+* *
+====================================================================
+
+
+C.2. Path Named in Environment Variable
+=======================================
+
+A device cache file path may be declared in an environment variable.
+This option is defined in the dialect's machine.h header file with
+the HASENVDC definition. The value of the HASENVDC definition is
+the environment variable's name.
+
+Lsof will use the value of the environment variable named by HASENVDC
+for the device cache file path unless either of the following
+conditions apply:
+
+ 1. The lsof process is in the setuid-root state.
+or
+ 2. The effective and real UIDs of the lsof process are root
+ (0).
+
+Lsof uses the value of the HASENVDC environment variable as the
+device cache file path after it senses there is no path declared by
+a ``-D'' option.
+
+A path from an environment variable is read-only unless the lsof
+process surrenders setgid permission. (See Appendix B.)
+
+====================================================================
+* *
+* The path name environment variable option is enabled by default, *
+* and the environment variable is named LSOFDEVCACHE in the lsof *
+* distribution by the following definition in the dialect's *
+* machine.h header file: *
+* *
+* #define HASENVDC "LSOFDEVCACHE" *
+* *
+* To disable the path name environment variable option, change *
+* the above line in the dialect's machine.h header file to: *
+* *
+* /* #define HASENVDC "LSOFDEVCACHE" */ *
+* *
+* or remove it. To change the name of the environment variable, *
+* change the quoted value of the HASENVDC definition -- e.g., this *
+* form changes the environment variable name to "FOOBAR": *
+* *
+* #define HASENVDC "FOOBAR" *
+* *
+* You can disable the path name environment option by disabling *
+* all device cache file processing when you remove or by disabling *
+* the HASDCACHE definition in the dialect's machine.h header file. *
+* *
+* The path name environment option is disabled when the lsof *
+* process is setuid-root or when the real UID of the lsof process *
+* is root (0). *
+* *
+* The path named in an environment variable is read-only unless *
+* the lsof process surrenders setgid permission. (See Appendix *
+* B.) *
+* *
+====================================================================
+
+
+C.3. Default System-wide Path
+=============================
+
+When a default system-wide device cache file path is defined (It's
+not enabled by default in the lsof distribution.), lsof will use
+it after it discovers no path has been specified by a ``-D'' option
+and no path has been specified in the environment variable named
+in the string #define HASENVDC of the dialect's machine.h header
+file.
+
+Lsof must be able to open the system-wide device cache file --
+i.e., it must have read access to the file and search access to
+the directories that lead it. As part of its integrity checks,
+lsof requires that the system-wide device cache file's permission
+modes be 0644.
+
+When lsof discovers that the named system-wide device cache file
+doesn't exist, it will attempt to open a personal device cache file
+should that path formation option be enabled. This is the *only*
+case where lsof will attempt to use two device cache file paths.
+
+The system-wide device cache file is read-only; lsof will never
+attempt to write to it. However, when the real UID of the lsof
+process is root, that process may name the system-wide device
+cache file with ``-D[b|u]<path>''.
+
+====================================================================
+* *
+* The system-wide file path option is disabled by default in the *
+* lsof distribution. This place-marking definition in a dialect's *
+* machine.h header file may be altered to enable a system-wide *
+* device cache file path: *
+* *
+* /* #define HASSYSDC "/your/choice/of/path" */ *
+* *
+* To enable the system-wide name option, declaring that its path *
+* is ``/foo/bar/lsof.dc'', change the above line in the dialect's *
+* machine.h header file to: *
+* *
+* #define HASSYSDC "/foo/bar/lsof.dc" *
+* *
+* or change the quoted string of the definition to the path of *
+* your choice. *
+* *
+* You can disable the path name environment option by disabling *
+* all device cache file processing when you remove or disable the *
+* HASDCACHE definition in the dialect's machine.h header file. *
+* *
+* The system-wide device cache file is read-only. *
+* *
+====================================================================
+
+
+C.3.a. Build Procedure
+======================
+
+The system administrator must build the system-wide device cache
+file at an appropriate time -- e.g., each time the system is booted,
+and each time a node is added, deleted or modified in /dev (or
+/devices). The procedure that builds the system-wide device cache
+file must use lsof's ``-D[b|u]<path>'' options to build the file,
+and must change the file's permission modes to 0644 after it has
+been built.
+
+Here's a simple shell script procedure to build a system-wide device
+cache file. It assumes:
+
+ 1. The Unix dialect's kernel supports the interpreter script
+ execution option -- i.e., a script whose first line has
+ the form ``#!<path_to_interpreter>''.
+
+ 2. The chmod, echo, rm, sh, and test programs are located
+ in ``/bin''.
+
+ 3. The string value of the HASSYSDC definition in the dialect's
+ machine.h header file is the path ``/your/choice/of/path''.
+
+ 4. The lsof executable is located in ``/usr/local/etc''.
+
+ #!/bin/sh
+ #
+ # Simple script to build a system-wide device cache file
+ # for lsof.
+
+ HASSYSDC=/your/choice/of/path
+ /bin/rm -f $HASSYSDC
+ /usr/local/etc/lsof -Du$HASSYSDC > /dev/null 2>&1
+ if /bin/test $? -ne 0
+ then
+ /bin/echo "WARNING: failed to create $HASSYSDC"
+ exit 1
+ fi
+ /bin/chmod 0644 $HASSYSDC
+ exit 0
+
+The invocation of lsof uses the ``-Du$HASSYSDC'' option to read
+the device cache file and recreate it if necessary. The invocation
+can be made more efficient if a known process PID -- e.g., ``-p1''
+-- can be specified. However, if that PID is not always active
+when lsof is called, lsof might set its exit code non-zero, causing
+the subsequent test to believe that the lsof call failed. When in
+doubt, omit the PID specification and accept the extra lsof processing
+time for reporting and discarding all open file information.
+
+
+C.4. Default Personal Path
+==========================
+
+The default personal path option is defined by default in the lsof
+distribution. The path is formed of the home directory of the real
+UID of the lsof process, followed optionally by the contents of
+the HASPERSDCPATH environment variable, followed by ``.lsof_'',
+followed by the first component (characters up to the first period)
+of the name returned by gethostname(2).
+
+If gethostname(2) returns nothing, then nothing will follow the
+``.lsof_'' string. If the first character of what gethostname(2)
+returns is a `.', then all the gethostname(2) value will follow
+the ``/lsof_'' string. (See the ``%l'' conversion for a way to
+make lsof include the entire host name in the path.)
+
+====================================================================
+* *
+* The personal path option is enabled by default in the lsof *
+* distribution. The HASPERSDC #define in a dialect's machine.h *
+* header is a format specification that tells lsof how to form the *
+* personal device cache file path. The conversions in the format *
+* specification begin with `%' , ala the printf(3) function of the *
+* standard I/O library. These conversions are supported: *
+* *
+* ``%%'' causes a single `%' to appear in the path. *
+* *
+* ``%0'' is a separator that marks the beginning of a path *
+* for a setuid-root lsof process or one whose real *
+* UID is 0. When lsof reaches this conversion and *
+* the process is setuid-root or has a real UID of *
+* root, it erases any previously formed path and *
+* restarts with the next HASPERSDC format character. *
+* If lsof reaches this conversion and the process is *
+* not setuid-root and its real UID is not root, path *
+* formation is ended. *
+* *
+* ``%h'' causes the home directory of the real UID of the *
+* lsof process to appear in the path. *
+* *
+* ``%l'' causes the full name returned by gethostname(2) to *
+* appear in the path. *
+* *
+* ``%L'' causes the first component of the name returned by *
+* gethostname(2) to appear in the path. The first *
+* component is defined to be what appears to the *
+* left of the first `.'. If nothing appears to the *
+* left then everything will appear in the path. *
+* *
+* ``%p'' causes the value of (HASPERSDCPATH) from the *
+* process environment to appear in the path. If the *
+* (HASPERSDCPATH) value doesn't end in a '/', one *
+* will be added. *
+* *
+* ``%u'' causes the login name associated with the real UID *
+* of the lsof process to appear in the path. *
+* *
+* ``%U'' causes the real UID of the lsof process, converted *
+* to a decimal string, to appear in the path. *
+* *
+* All other characters are copied from the format to the *
+* path. CAUTION: THINK VERY CAREFULLY ABOUT THE EFFECT OF *
+* USING CHARACTERS THAT FORM AN ABSOLUTE COMPONENT LIKE *
+* ``/tmp'' IN THE FORMAT. Consider what power your dialect *
+* might have (e.g., if it is setuid-root) when lsof must *
+* create a device cache file at the path. Consider using a *
+* ``%0'' conversion to declare an alternate path for lsof *
+* processes that are setuid-root or whose real uid is root. *
+* See the "How do I put the personal device cache file in *
+* /tmp?" question and answer in 00FAQ for an explanation of *
+* this example: *
+* *
+* #define HASPERSDC "/tmp/.lsof_%u_%l_pers%0%h/.lsof_%L" *
+* *
+* This is the format specification that appears in the machine.h *
+* header files of the lsof distribution: *
+* *
+* #define HASPERSDC "%h/%p.lsof_%L" *
+* *
+* It causes the path to be formed from the home directory of the *
+* real UID of the lsof process (``%h''), followed by `/', followed *
+* by the contents of the environment variable named by *
+* HASPERSDCPATH and a trailing `/', as needed (``%p''), followed *
+* by the string ``.lsof_'', and terminated with the first *
+* component of the host's name (``%L''). *
+* *
+* To change the personal path option, change the HASPERSDC string *
+* and recompile lsof. To disable the personal path option, remove *
+* or disable HASPERSDC. The personal path option is disabled when *
+* HASDCACHE is not defined. *
+* *
+====================================================================
+
+
+C.5. Modified Default Personal Path
+===================================
+
+The modified default personal path form is a special case of the
+default personal path. In this form the value of the environment
+variable named by the HASPERSDCPATH #define is inserted in the
+personal path when the ``%p'' conversion appears in the HASPERSDC
+format specification.
+
+This allows, for example, the lsof user to move personal device
+cache files to another branch of the home directory, perhaps to a
+sub-directory where multiple device cache files may appear from
+different machines that use the same NFS- mounted home directory.
+
+The HASPERSDCPATH definition of the dialect's machine.h header file
+names the environment variable. By default in the lsof distribution
+it is LSOFPERSDCPATH.
+
+The modified personal path component is ignored when lsof process
+is setuid-root is root, lest it be maliciously or accidentally used in
+some convoluted form to access paths the real UID cannot. The
+modified personal path component is also ignored when the real UID
+of the lsof process is root (0), so that lsof will not accidentally
+use a personal environment value.
+
+If the lsof process surrenders setgid permission (See Appendix B.),
+lsof can read from and write to the modified personal path. If,
+however, the lsof process doesn't surrender setgid permission, the
+modified personal path is read-only.
+
+If your dialect runs setuid-root or doesn't surrender its setgid
+permission, and you want to use the LSOFPERSDCPATH environment
+variable to address a collection of device cache files in a
+subdirectory, you will have to gather the collection in the
+subdirectory yourself with shell copy or move commands.
+
+====================================================================
+* *
+* The modified personal path option is enabled by default in the *
+* lsof distribution with these definitions in the dialect's *
+* machine.h header file: *
+* *
+* #define HASPERSDCPATH "LSOFPERSDCPATH" *
+* and *
+* #define HASPERSDC "%h/%p.lsof_%L" *
+* *
+* The value of the definition is the name of the environment *
+* variable that contains the modified personal path name *
+* component that is inserted in the personal path when ``%p'' *
+* appears in HASPERSDC. See the Default Personal Path section *
+* for a complete description of the ``%p'' conversion. *
+* *
+* To disable the modified personal path name component, disable *
+* the HASPERSDCPATH definition in the dialect's machine.h header *
+* file -- e.g., change it to: *
+* *
+* /* #define HASPERSDCPATH "LSOFPERSDCPATH" */ *
+* *
+* or remove the definition altogether. If you do this, don't *
+* forget to remove any ``%p'' conversion from HASPERSDC. *
+* *
+* The modified personal path option is disabled when HASDCACHE is *
+* not defined. *
+* *
+* The modified personal path environment variable value is ignored *
+* when the lsof process is setuid-root or when the real UID of *
+* the lsof process is root (0). *
+* *
+* The modified personal path is read-only when the lsof process *
+* doesn't surrender its setgid permission. *
+* *
+====================================================================
+
+
+D. Displaying the Default Path
+==============================
+
+Whatever device cache file path formation options you decide to
+use, remember that the lsof help output, displayed in response to
+its ``-h'' or ``-?'' help options, will display the read-mode
+default (the highest numbered) path that lsof has been enabled to
+form from which it will read.
+
+Since some paths are read-only, the path displayed in help option
+output may not be the one to which lsof will write, should that
+become necessary. To see the read-only and write device cache file
+paths, environment variable names, and the personal device cache
+file format specification (HASPERSDC), use the -D? option.
+
+
+Appendix A, Unix Dialects Without a Device Cache
+================================================
+
+Linux lsof implementations that obtain their information from files
+in the /proc file system do not have device cache support. Generally
+lsof for Linux versions 2.1.72 and greater are /proc based.
+
+
+Appendix B, Lsof Dialects and Their Permissions
+===============================================
+
+These are the permissions recommended in the lsof distribution.
+
+
+Appendix B.1 Setuid-root Lsof Dialects
+======================================
+
+These dialect versions of lsof need root permission. For general
+use they may have to be installed setuid-root.
+
+ Apple Darwin 9 (Mac OS X 10.5)
+ HP-UX 11.11 and 11.23
+ Linux (no device cache support needed)
+
+
+Appendix B.2 Setgid Lsof Dialects That Surrender Setgid Permission
+==================================================================
+
+Lsof versions for these dialects have WILLDROPGID defined in their
+machine.h header files.
+
+ AIX 5.[12] and 5.3-ML1
+ FreeBSD 4.x, 4.1x, 5.x and [6789].x for x86-based systems
+ FreeBSD 5.x and [6789].x for Alpha, AMD64 and Sparc64-based
+ systems
+ HP-UX 11.00
+ NetBSD 1.[456], 2.x and 3.x for Alpha, x86, and SPARC-based
+ systems
+ NEXTSTEP 3.[13]
+ OpenBSD 2.[89] and 3.[0-9] for x86-based systems
+ OPENSTEP 4.x
+ SCO OpenServer Release 5.0.4 for x86-based systems
+ SCO|Caldera UnixWare 7.1.4 for x86-based systems
+ Solaris 2.6, 8, 9 and 10
+ Tru64 UNIX 5.1
+
+
+Vic Abell <abe@purdue.edu>
+January 18, 2010
6 00DIALECTS
@@ -0,0 +1,6 @@
+ AIX 5.3
+ Apple Darwin 9 (Mac OS X 10.5)
+ FreeBSD 4.9 for x86-based systems
+ FreeBSD 7.[0123], 8.0 and 9.0 for AMD64-based systems
+ Linux 2.1.72 and above for x86-based systems
+ Solaris 9, 10 and 11
4,515 00DIST
4,515 additions, 0 deletions not shown because the diff is too large. Please use a local Git client to view these changes.
7,996 00FAQ
7,996 additions, 0 deletions not shown because the diff is too large. Please use a local Git client to view these changes.
100 00LSOF-L
@@ -0,0 +1,100 @@
+
+ The Lsof Mailing List, lsof-l
+
+Information on lsof is available via a GNU Mailman mailing list, named
+lsof-l. The server is located on the host rcac.purdue.edu.
+
+
+Subscribing
+===========
+
+You may subscribe to the lsof-l mailing list by sending e-mail to:
+
+ lsof-l-subscribe@rcac.purdue.edu
+
+The body of your e-mail may be empty. You will receive a confirmation
+reply, explaining one further step you must take to complete your
+subscription.
+
+The list manager uses the e-mail address and real name in the "From:"
+line of your request to set those values in your subscription. If you
+want different values in your subscription, consult the Mailman help
+information to learn how to specify them on your subscription request.
+(See the next "Get Help" section on how to obtain Mailman help
+information.)
+
+
+Get Help
+========
+
+More information about the rcac.purdue.edu GNU Mailman server is
+available by sending e-mail to lsof-l-request@rcac.purdue.edu with
+"help" in the subject line. The body of your e-mail may be empty.
+
+The other information will be delivered by return e-mail.
+
+You can also obtain information on the Mailman e-mail commands in
+section 3.2 of the GNU Mailman documentation at:
+
+ http://www.gnu.org/software/mailman/mailman-member/mailman-member.html
+
+
+The Web Interface
+=================
+
+There is a web interface at:
+
+ https://lists.rcac.purdue.edu/listinfo/lsof-l
+
+You can use it to manage your lsof-l list entry.
+
+
+Posting and Moderation
+======================
+
+Once you have subscribed to lsof-l (and have an e-mail confirmation
+that your subscription was accepted), you may post messages to the list
+by sending e-mail directly to:
+
+ lsof-l@rcac.purdue.edu
+
+I moderate the lsof-l mailing list and try to keep its traffic low,
+mainly limiting it to announcements of new revisions, patches and
+security issues. Postings don't appear until I've approved them.
+
+
+Send Bug Reports to Me Via E-Mail
+=================================
+
+DON'T SEND BUG REPORTS TO lsof-l. Send them directly to me via e-mail
+at <abe@purdue.edu>. Make sure lsof appears in the "Subject:" line and
+make sure you first read the "Bug Reports" section of the 00README file
+of the lsof distribution.
+
+
+Unsubscribing
+=============
+
+You can unsubscribe from lsof-l by sending e-mail to:
+
+ lsof-l-unsubscribe@rcac.purdue.edu
+
+The body of your e-mail may be empty. You will receive a confirmation
+reply, explaining one further step you must take to complete the
+removal of your subscription.
+
+
+Archive
+=======
+
+There is an archive; use the link:
+
+ https://lists.rcac.purdue.edu/listinfo/lsof-l
+
+The archive link is the first one on the web page. You will need the
+password you received or set when you subscribed, or later set via
+lsof-l-request or the web interface.
+
+
+Vic Abell <abe@purdue.edu>
+May 8, 2008
363 00MANIFEST
@@ -0,0 +1,363 @@
+.:
+00.README.FIRST
+00CREDITS
+00DCACHE
+00DIALECTS
+00DIST
+00FAQ
+00LSOF-L
+00MANIFEST
+00PORTING
+00QUICKSTART
+00README
+00TEST
+00XCONFIG
+AFSConfig*
+Configure*
+Customize*
+Inventory*
+arg.c
+dialects/
+lib/
+lsof.8
+lsof.h
+lsof.man
+lsof_fields.h
+main.c
+misc.c
+node.c
+print.c
+proc.c
+proto.h
+regex.h
+scripts/
+store.c
+tests/
+usage.c
+util.c
+version
+
+./dialects:
+aix/
+darwin/
+du/
+freebsd/
+hpux/
+linux/
+n+obsd/
+n+os/
+osr/
+sun/
+uw/
+
+./dialects/aix:
+Makefile
+Mksrc*
+aix5/
+ddev.c
+dfile.c
+dlsof.h
+dmnt.c
+dnode.c
+dnode1.c
+dnode2.c
+dproc.c
+dproto.h
+dsock.c
+dstore.c
+machine.h
+
+./dialects/aix/aix5:
+README
+j2/
+
+./dialects/aix/aix5/j2:
+j2_lock.h
+private_j2_snapshot.h
+
+./dialects/darwin:
+get-hdr-loc.sh*
+kmem/
+libproc/
+
+./dialects/darwin/kmem:
+Makefile
+Mksrc*
+ddev.c
+dfile.c
+dlsof.h
+dmnt.c
+dnode.c
+dnode1.c
+dproc.c
+dproto.h
+dsock.c
+dstore.c
+machine.h
+
+./dialects/darwin/libproc:
+Makefile
+Mksrc*
+ddev.c
+dfile.c
+dlsof.h
+dmnt.c
+dproc.c
+dproto.h
+dsock.c
+dstore.c
+machine.h
+
+./dialects/du:
+Makefile
+Mksrc*
+ddev.c
+dfile.c
+dlsof.h
+dmnt.c
+dnode.c
+dproc.c
+dproto.h
+dsock.c
+dstore.c
+machine.h
+
+./dialects/freebsd:
+Makefile
+Makefile.zfs
+Mksrc*
+dlsof.h
+dmnt.c
+dnode.c
+dnode1.c
+dnode2.c
+dproc.c
+dproto.h
+dsock.c
+dstore.c
+dzfs.h
+include/
+machine.h
+
+./dialects/freebsd/include:
+procfs/
+
+./dialects/freebsd/include/procfs:
+pfsnode.h
+
+./dialects/hpux:
+kmem/
+pstat/
+
+./dialects/hpux/kmem:
+Makefile
+Mksrc*
+dfile.c
+dlsof.h
+dmnt.c
+dnode.c
+dnode1.c
+dnode2.c
+dproc.c
+dproto.h
+dsock.c
+dstore.c
+hpux11/
+machine.h
+
+./dialects/hpux/kmem/hpux11:
+ipc_s.h
+kernbits.h
+lla.h
+nfs_clnt.h
+proc.h
+rnode.h
+sth.h
+tcp_s.h
+udp_s.h
+vnode.h
+
+./dialects/hpux/pstat:
+Makefile
+Mksrc*
+dfile.c
+dlsof.h
+dproc.c
+dproto.h
+dsock.c
+dstore.c
+machine.h
+
+./dialects/linux:
+Makefile
+Mksrc*
+dfile.c
+dlsof.h
+dmnt.c
+dnode.c
+dproc.c
+dproto.h
+dsock.c
+dstore.c
+machine.h
+
+./dialects/n+obsd:
+Makefile
+Mksrc*
+dlsof.h
+dmnt.c
+dnode.c
+dnode1.c
+dproc.c
+dproto.h
+dsock.c
+dstore.c
+machine.h
+
+./dialects/n+os:
+Makefile
+Mksrc*
+dlsof.h
+dnode.c
+dnode1.c
+dproc.c
+dproto.h
+dsock.c
+dstore.c
+machine.h
+
+./dialects/osr:
+Makefile
+Mksrc*
+dfile.c
+dlsof.h
+dmnt.c
+dnode.c
+dproc.c
+dproto.h
+dsock.c
+dstore.c
+include/
+machine.h
+
+./dialects/osr/include:
+netdb.h
+sys/
+
+./dialects/osr/include/sys:
+cdefs.h
+
+./dialects/sun:
+Makefile
+Mksrc*
+ddev.c
+dfile.c
+dlsof.h
+dmnt.c
+dnode.c
+dnode1.c
+dnode2.c
+dproc.c
+dproto.h
+dsock.c
+dstore.c
+machine.h
+solaris_kaddr_filters
+
+./dialects/uw:
+Makefile
+Mksrc*
+dfile.c
+dlsof.h
+dmnt.c
+dnode.c
+dnode1.c
+dnode2.c
+dnode3.c
+dproc.c
+dproto.h
+dsock.c
+dstore.c
+machine.h
+uw7/
+
+./dialects/uw/uw7:
+README
+fs/
+sys/
+vm/
+
+./dialects/uw/uw7/fs:
+nsc_cfs/
+procfs/
+
+./dialects/uw/uw7/fs/nsc_cfs:
+cnode.h
+
+./dialects/uw/uw7/fs/procfs:
+README
+prdata.h
+
+./dialects/uw/uw7/sys:
+fs/
+
+./dialects/uw/uw7/sys/fs:
+README
+fifonode.h
+namenode.h
+
+./dialects/uw/uw7/vm:
+
+./lib:
+Makefile.skel
+ckkv.c
+cvfs.c
+dvch.c
+fino.c
+isfn.c
+lkud.c
+pdvn.c
+prfp.c
+ptti.c
+rdev.c
+regex.c
+rmnt.c
+rnam.c
+rnch.c
+rnmh.c
+snpf.c
+
+./scripts:
+00MANIFEST
+00README
+big_brother.perl5*
+count_pf.perl*
+count_pf.perl5*
+identd.perl5*
+idrlogin.perl*
+idrlogin.perl5*
+list_NULf.perl5*
+list_fields.awk
+list_fields.perl*
+shared.perl5*
+sort_res.perl5*
+watch_a_file.perl*
+xusers.awk*
+
+./tests:
+00README
+Add2TestDB*
+CkTestDB*
+LTbasic.c
+LTbigf.c
+LTdnlc.c
+LTlib.c
+LTlock.c
+LTnfs.c
+LTnlink.c
+LTsock.c
+LTszoff.c
+LTunix.c
+LsofTest.h
+Makefile
+TestDB
1,805 00PORTING
1,805 additions, 0 deletions not shown because the diff is too large. Please use a local Git client to view these changes.
1,023 00QUICKSTART
@@ -0,0 +1,1023 @@
+
+ A Quick Start for Lsof
+
+1. Introduction
+================
+
+ Agreed, the lsof man page is dense and lsof has a plethora of
+ options. There are examples, but the manual page format buries
+ them at the end. How does one get started with lsof?
+
+ This file is an attempt to answer that question. It plunges
+ immediately into examples of lsof use to solve problems that
+ involve looking at the open files of Unix processes.
+
+
+ Contents
+
+ 1. Introduction
+ 2. Finding Uses of a Specific Open File
+ 3. Finding Open Files Filling a File System
+ a. Finding an Unlinked Open File
+ 4. Finding Processes Blocking Umount
+ 5. Finding Listening Sockets
+ 6. Finding a Particular Network Connection
+ 7. Identifying a Netstat Connection
+ 8. Finding Files Open to a Named Command
+ 9. Deciphering the Remote Login Trail
+ a. The Fundamentals
+ b. The idrlogin.perl[5] Scripts
+ 10. Watching an Ftp or Rcp Transfer
+ 11. Listing Open NFS Files
+ 12. Listing Files Open by a Specific Login
+ a. Ignoring a Specific Login
+ 13. Listing Files Open to a Specific Process Group
+ 14. When Lsof Seems to Hang
+ a. Kernel lstat(), readlink(), and stat() Blockages
+ b. Problems with /dev or /devices
+ c. Host and Service Name Lookup Hangs
+ d. UID to Login Name Conversion Delays
+ 15. Output for Other Programs
+ 16. The Lsof Exit Code and Shell Scripts
+ 17. Strange messages in the NAME column
+
+ Options
+
+ A. Selection Options
+ B. Output Options
+ C. Precautionary Options
+ D. Miscellaneous Lsof Options
+
+
+2. Finding Uses of a Specific Open File
+========================================
+
+ Often you're interested in knowing who is using a specific file.
+ You know the path to it and you want lsof to tell you the processes
+ that have open references to it.
+
+ Simple -- execute lsof and give it the path name of the file of
+ interest -- e.g.,
+
+ $ lsof /etc/passwd
+
+ Caveat: this only works if lsof has permission to get the status
+ (via stat(2)) of the file at the named path. Unless the lsof
+ process has enough authority -- e.g., it is being run with a
+ real User ID (UID) of root -- this AIX example won't work:
+
+ Further caveat: this use of lsof will fail if the stat(2) kernel
+ syscall returns different file parameters -- particularly device
+ and inode numbers -- than lsof finds in kernel node structures.
+ This condition is rare and is usually documented in the 00FAQ
+ file of the lsof distribution.
+
+ $ lsof /etc/security/passwd
+ lsof: status error on /etc/security/passwd: Permission denied
+
+
+3. Finding Open Files Filling a File System
+============================================
+
+ Oh! Oh! /tmp is filling and ls doesn't show that any large files
+ are being created. Can lsof help?
+
+ Maybe. If there's a process that is writing to a file that has
+ been unlinked, lsof may be able to discover the process for you.
+ You ask it to list all open files on the file system where /tmp
+ is located.
+
+ Sometimes /tmp is a file system by itself. In that case,
+
+ $ lsof /tmp
+
+ is the appropriate command. If, however, /tmp is part of another
+ file system, typically /, then you may have to ask lsof to list
+ all files open on the containing file system and locate the
+ offending file and its process by inspection -- e.g.,
+
+ $ lsof / | more
+ or
+ $ lsof / | grep ...
+
+ Caveat: there must be a file open to a for the lsof search to
+ succeed. Sometimes the kernel may cause a file reference to
+ persist, even where there's no file open to a process. (Can you
+ say kernel bug? Maybe.) In any event, lsof won't be able to
+ help in this case.
+
+ a. Finding an Unlinked Open File
+ =================================
+
+ A pesky variant of a file that is filling a file system is an
+ unlinked file to which some process is still writing. When a
+ process opens a file and then unlinks it, the file's resources
+ remain in use by the process, but the file's directory entries
+ are removed. Hence, even when you know the directory where the
+ file once resided, you can't detect it with ls.
+
+ This can be an administrative problem when the unlinked file is
+ large, and the process that holds it open continues to write to
+ it. Only when the process closes the file will its resources,
+ particularly disk space, be released.
+
+ Lsof can help you find unlinked files on local disks. It has an
+ option, +L, that will list the link counts of open files. That
+ helps because an unlinked file on a local disk has a zero link
+ count. Note: this is NOT true for NFS files, accessed from a
+ remote server.
+
+ You could use the option to list all files and look for a zero
+ link count in the NLINK column -- e.g.,
+
+ $lsof +L
+ COMMAND PID USER FD TYPE DEVICE SIZE/OFF NLINK NODE NAME
+ ...
+ less 25366 abe txt VREG 6,0 40960 1 76319 /usr/...
+ ...
+ > less 25366 abe 3r VREG 6,0 17360 0 98768 / (/dev/sd0a)
+
+ Better yet, you can specify an upper bound to the +L option, and
+ lsof will select only files that have a link count less than the
+ upper bound. For example:
+
+ $ lsof +L1
+ COMMAND PID USER FD TYPE DEVICE SIZE/OFF NLINK NODE NAME
+ less 25366 abe 3r VREG 6,0 17360 0 98768 / (/dev/sd0a)
+
+ You can use lsof's -a (AND) option to narrow the link count search
+ to a particular file system. For example, to look for zero link
+ counts on the /home file system, use:
+
+ $ lsof -a +L1 /home
+
+ CAUTION: lsof can't always report link counts for all file types
+ -- e.g., it may not report them for FIFOs, pipes, or sockets.
+ Remember also that link counts for NFS files on an NFS client
+ host don't behave as do link counts for files on local disks.
+
+
+4. Finding Processes Blocking Umount
+=====================================
+
+ When you need to unmount a file system with the umount command,
+ you may find the operation blocked by a process that has a file
+ open on the file systems. Lsof may be able to help you find the
+ process. In response to:
+
+ $ lsof <file_system_name>
+
+ Lsof will display all open files on the named file system. It
+ will also set its exit code zero when it finds some open files
+ and non-zero when it doesn't, making this type of lsof call
+ useful in shell scripts. (See section 16.)
+
+ Consult the output of the df command for file system names.
+
+ See the caveat in the preceding section about file references
+ that persist in the kernel without open file traces. That
+ situation may hamper lsof's ability to help with umount, too.
+
+
+5. Finding Listening Sockets
+=============================
+
+ Sooner or later you may wonder if someone has installed a network
+ server that you don't know about. Lsof can list for you all the
+ network socket files open on your machine with:
+
+ $ lsof -i
+
+ The -i option without further qualification lists all open Internet
+ socket files. You can add network names or addresses, protocol
+ names, and service names or port numbers to the -i option to
+ refine the search. (See the next section.)
+
+
+6. Finding a Particular Network Connection
+===========================================
+
+ When you know the source or destination of a network connection
+ whose open files and process you'd like to identify, the -i option
+ may help.
+
+ If, for example, you want to know what process has a connection
+ open to or from the Internet host named aaa.bbb.ccc, you can ask
+ lsof to search for it with:
+
+ $ lsof -i@aaa.bbb.ccc
+
+ If you're interested in a particular protocol -- TCP or UDP --
+ and a specific port number or service name, you can add those
+ discriminators to the -i information:
+
+ $ lsof -iTCP@aaa.bbb.ccc:ftp-data
+
+ If you're interested in a particular IP version -- IPv4 or IPv6
+ -- and your UNIX dialect supports both (It does if "IPv[46]"
+ appears in the lsof -h output.), you can add the '4' or '6'
+ selector immediately after -i:
+
+ $ lsof -i4
+ $ lsof -i6
+
+
+7. Identifying a Netstat Connection
+====================================
+
+ How do I identify the process that has a network connection
+ described in netstat output? For example, if netstat says:
+
+ Proto Recv-Q Send-Q Local Address Foreign Address (state)
+ tcp 0 0 vic.1023 ipscgate.login ESTABLISHED
+
+ What process is connected to service name ``login'' on ipscgate?
+
+ Use lsof's -i option:
+
+ $lsof -iTCP@ipscgate:login
+ COMMAND PID USER FD TYPE DEVICE SIZE/OFF INODE NAME
+ rlogin 25023 abe 3u inet 0x10144168 0t184 TCP lsof.itap.purdue.edu:1023->ipscgate.cc.purdue.edu:login
+ ...
+
+ There's another way. Notice the 0x10144168 in the DEVICE column
+ of the lsof output? That's the protocol control block (PCB)
+ address. Many netstat applications will display it when given
+ the -A option:
+
+ $ netstat -A
+ PCB Proto Recv-Q Send-Q Local Address Foreign Address (state)
+ 10144168 tcp 0 0 vic.1023 ipscgate.login ESTABLISHED
+ ...
+
+ Using the PCB address, lsof, and grep, you can find the process this
+ way, too:
+
+ $ lsof -i | grep 10144168
+ rlogin 25023 abe 3u inet 0x10144168 0t184 TCP lsof.itap.purdue.edu:1023->ipscgate.cc.purdue.edu:login
+ ...
+
+ If the file is a UNIX socket and netstat reveals and adress for it,
+ like this Solaris 11 example:
+
+ $ netstat -a -f unix
+ Active UNIX domain sockets
+ Address Type Vnode Conn Local Addr Remote Addr
+ ffffff0084253b68 stream-ord 0000000 0000000
+
+ Using lsof's -U opetion and its output piped to a grep on the address
+ yields:
+
+ $ lsof -U | grep ffffff0084253b68
+ squid 1638 nobody 12u unix 18,98 0t10 9437188 /devices/pseudo/tl@0:ticots->0xffffff0084253b68 stream-ord
+ $ lsof -U |
+
+
+8. Finding Files Open to a Named Command
+=========================================
+
+ When you want to look at the files open to a particular command,
+ you can look up the PID of the process running the command and
+ use lsof's -p option to specify it.
+
+ $ lsof -p <PID>
+
+ However, there's a quicker way, using lsof's -c option, provided
+ you don't mind seeing output for every process running the named
+ command.
+
+ $ lsof -c <first_characters_of_command_name_that_interest_you>
+
+ The lsof -c option is useful when you want to see how many instances
+ of a given command are executing and what their open files are.
+ One useful example is for the sendmail command.
+
+ $ lsof -c sendmail
+
+
+9. Deciphering the Remote Login Trail
+======================================
+
+ If the network connection you're interested in tracing has been
+ initiated externally and is connected to an rlogind, sshd, or
+ telnetd process, asking lsof to identify that process might not
+ give a wholly satisfying answer. The report may be that the
+ connection exists, but to a process owned by root.
+
+ a. The Fundamentals
+ ====================
+
+ How do you get from there to the login name really using the
+ connection? You have to know a little about how real and pseudo
+ ttys are paired in your system, and then use several lsof probes
+ to identify the login.
+
+ This example comes from a Solaris 2.4 system, named klaatu.cc.
+ I've logged on to it via rlogin from lsof.itap. The first lsof
+ probe,
+
+ $ lsof -i@lsof.itap
+
+ yields (among other things):
+
+ COMMAND PID USER FD TYPE DEVICE SIZE/OFF INODE NAME
+ in.rlogin 7362 root 0u inet 0xfc0193b0 0t242 TCP klaatu.cc.purdue.edu:login->lsof.itap.purdue.edu:1023
+ ...
+
+ This confirms that a connection exists. A second lsof probe
+ shows:
+
+ $ lsof -p7362
+ COMMAND PID USER FD TYPE DEVICE SIZE/OFF INODE NAME
+ ...
+ in.rlogin 7362 root 0u inet 0xfc0193b0 0t242 TCP klaatu.cc.purdue.edu:login->lsof.itap.purdue.edu:1023
+ ...
+ in.rlogin 7362 root 3u VCHR 23, 0 0t66 52928 /devices/pseudo/clone@0:ptmx->pckt->ptm
+
+ 7362 is the Process ID (PID) of the in.rlogin process, discovered
+ in the first lsof probe. (I've abbreviated the output to simplify
+ the example.) Now comes a need to understand Solaris pseudo-ttys.
+ The key indicator is in the DEVICE column for FD 3, the major/minor
+ device number of 23,0. This translates to /dev/pts/0, so a third
+ lsof probe,
+
+ $ lsof /dev/pts/0
+ COMMAND PID USER FD TYPE DEVICE SIZE/OFF INODE NAME
+ ksh 7364 abe 0u VCHR 24, 0 0t2410 53410 /dev/pts/../../devices/pseudo/pts@0:0
+
+ shows in part that login abe has a ksh process on /dev/pts/0.
+ (The NAME that lsof shows is not /dev/pts/0 but the full expansion
+ of the symbolic link that lsof finds at /dev/pts/0.)
+
+ Here's a second example, done on an HP-UX 9.01 host named ghg.ecn.
+ Again, I've logged on to it from lsof.itap, so I start with:
+
+ $ lsof -i@lsof.itap
+ COMMAND PID USER FD TYPE DEVICE SIZE/OFF INODE NAME
+ rlogind 10214 root 0u inet 0x041d5f00 0t1536 TCP ghg.ecn.purdue.edu:login->lsof.itap.purdue.edu:1023
+ ...
+
+ Then,
+
+ $ lsof -p10214
+ COMMAND PID USER FD TYPE DEVICE SIZE/OFF INODE NAME
+ ...
+ rlogind 10214 root 0u inet 0x041d5f00 0t2005 TCP ghg.ecn.purdue.edu:login->lsof.itap.purdue.edu:1023
+ ...
+ rlogind 10214 root 3u VCHR 16,0x000030 0t2037 24642 /dev/ptym/ptys0
+
+ Here the key is the NAME /dev/ptym/ptys0. In HP-UX 9.01 tty and
+ pseudo tty devices are paired with the names like /dev/ptym/ptys0
+ and /dev/pty/ttys0, so the following lsof probe is the final step.
+
+ $ lsof /dev/pty/ttys0
+ COMMAND PID USER FD TYPE DEVICE SIZE/OFF INODE NAME
+ ksh 10215 abe 0u VCHR 17,0x000030 0t3399 22607 /dev/pty/ttys0
+ ...
+
+ Here's a third example for an AIX 4.1.4 system. I've used telnet
+ to connect to it from lsof.itap.purdue.edu. I start with:
+
+ $ lsof -i@lsof.itap.purdue.edu
+ COMMAND PID USER FD TYPE DEVICE SIZE/OFF INODE NAME
+ ...
+ telnetd 15616 root 0u inet 0x05a93400 0t5156 TCP cloud.cc.purdue.edu:telnet->lsof.itap.purdue.edu:3369
+
+ Then I look at the telnetd process:
+
+ $ lsof -p15616
+ COMMAND PID USER FD TYPE DEVICE SIZE/OFF INODE NAME
+ ...
+ telnetd 15616 root 0u inet 0x05a93400 0t5641 TCP cloud.cc.purdue.edu:telnet->lsof.itap.purdue.edu:3369
+ ...
+ telnetd 15616 root 3u VCHR 25, 0 0t5493 103 /dev/ptc/0
+
+ Here the key is /dev/ptc/0. In AIX it's paired with /dev/pts/0.
+ The last probe for that shows:
+
+ $ lsof /dev/pts/0
+ COMMAND PID USER FD TYPE DEVICE SIZE/OFF INODE NAME
+ ...
+ ksh 16642 abe 0u VCHR 26, 0 0t6461 360 /dev/pts/0
+
+ b. The idrlogin.perl[5] Scripts
+ ================================
+
+ There's another, perhaps easier way, to go about the job of
+ tracing a network connection. The lsof distribution contains
+ two Perl scripts, idrlogin.perl (Perl 4) and idrlogin.perl5
+ (Perl 5), that use lsof field output to display values for
+ shells that are parented by rlogind, sshd, or telnetd, or
+ connected directly to TCP sockets. The lsof test suite contains
+ a C library that can be adapted for use with C programs that
+ need to call lsof and process its field output.
+
+ The two Perl scripts use the lsof -R option; it causes the
+ paRent process ID (PPID) to be listed in the lsof output. The
+ scripts identify all shell processes -- e.g., ones whose command
+ names end in ``sh'' -- and determine if: 1) the ultimate ancestor
+ process before a PID greater than 2 (e.g., init's PID is 1) is
+ rlogind, sshd, or telnetd; or 2) the shell process has open
+ TCP socket files.
+
+ Here's an example of output from idlogin.perl on a Solaris 2.4
+ system:
+
+ centurion: 1 = cd src/lsof4/scripts
+ centurion: 2 = ./idrlogin.perl
+ Login Shell PID Via PID TTY From
+ oboyle ksh 12640 in.telnetd 12638 pts/5 opal.cc.purdue.edu
+ icdtest ksh 15158 in.rlogind 15155 pts/6 localhost
+ sh csh 18207 in.rlogind 18205 pts/1 babylon5.cc.purdue.edu
+ root csh 18242 in.rlogind 18205 pts/1 babylon5.cc.purdue.edu
+ trouble ksh 19208 in.rlogind 18205 pts/1 babylon5.cc.purdue.edu
+ abe ksh 21334 in.rlogind 21332 pts/2 lsof.itap.purdue.edu
+
+ The scripts assume that its parent directory contains an
+ executable lsof. If you decide to use one of the scripts, you
+ may want to customize it for your local lsof and perl paths.
+
+ Note that processes executing as remote shells are also
+ identified.
+
+ Here's another example from a UnixWare 7.1.0 system.
+
+ tweeker: 1 = cd src/lsof4/scripts
+ tweeker: 9 = ./idrlogin.perl
+ Login Shell PID Via PID TTY From
+ abe ksh 9438 in.telnetd 9436 pts/3 lsof.itap.purdue.edu
+
+
+10. Watching an Ftp or Rcp Transfer
+===================================
+
+ The nature of the Internet being one of unpredictable performance
+ at times, occasionally you want to know if a file transfer, being
+ done by ftp or rcp, is making any progress.
+
+ To use lsof for watching a file transfer, you need to know the
+ PID of the file transfer process. You can use ps to find that.
+ Then use lsof,
+
+ $ lsof -p<PID>
+
+ to examine the files open to the transfer process. Usually the
+ ftp files or interest are at file descriptors 9 and 10 or 10 and
+ 11; for rcp, 3 and 4. They describe the network socket file and
+ the local data file.
+
+ If you want to watch only those file descriptors as the file
+ transfer progresses, try these lsof forms (for ftp in the example):
+
+ $ lsof -p<PID> -ad9,10 -r
+ or
+ $ lsof -p<PID> -ad10,11 -r
+
+ Some options need explaining:
+
+ -p<PID> specifies that lsof is to restrict its attention
+ to the process whose ID is <PID>. You can specify
+ a set of PIDs by separating them with commas.
+
+ $ lsof -p 1234,5678,9012
+
+ -a specifies that lsof is to AND its tests together.
+ The two tests that are specified are tests on the
+ PID and tests on file descriptions (``d9,10'').
+
+ d9,10 specifies that lsof is to test only file descriptors
+ 9 and 10. Note that the `-' is absent, since ``-a''
+ is a unary option and can be followed immediately
+ by another lsof option.
+
+ -r tells lsof to list the requested open file information,
+ sleep for a default 15 seconds, then list the open
+ file information again. You can specify a different
+ time (in seconds) after -r and override the default.
+ Lsof issues a short line of equal signs between
+ each set of output to distinguish it.
+
+ For an rcp transfer, the above example becomes:
+
+ $ lsof -p<PID> -ad3,4 -r
+
+
+11. Listing Open NFS Files
+==========================
+
+ Lsof will list all files open on remote file systems, supported
+ by an NFS server. Just use:
+
+ $ lsof -N
+
+ Note, however, that when run on an NFS server, lsof will not list
+ files open to the server from one of its clients. That's because
+ lsof can only examine the processes running on the machine where
+ it is called -- i.e., on the NFS server.
+
+ If you run lsof on the NFS client, using the -N option, it will
+ list files open by processes on the client that are on remote
+ NFS file systems.
+
+
+12. Listing Files Open by a Specific Login
+==========================================
+
+ If you're interested in knowing what files the processes owned
+ by a particular login name have open, lsof can help.
+
+ $ lsof -u<login>
+ or
+ $ lsof -u<User ID number>
+
+ You can specify either the login name or the UID associated with
+ it. You can specify multiple login names and UID numbers, mixed
+ together, by separating them with commas.
+
+ $ lsof -u548,abe
+
+ On the subject of login names and UIDs, it's worth noting that
+ lsof can be told to report either. By default it reports login
+ names; the -l option switches reporting to UIDs. You might want
+ to use -l if login name lookup is slow for some reason.
+
+ a. Ignoring a Specific Login
+ =============================
+
+ The -u option can also be used to direct lsof to ignore a
+ specific login name or UID, or a list of them. Simply prefix
+ the login names or UIDs with a `^' character, as you might do
+ in a regular expression. The `^' prefix is useful, for example,
+ when you want to have lsof ignore the files open to system
+ processes, owned by the root (UID 0) login. Try:
+
+ $ lsof -u ^root
+ or
+ $ lsof -u ^0
+
+
+13. Listing Files Open to a Specific Process Group
+==================================================
+
+ There's a Unix collection of processes called a process group.
+ The name indicates that the processes of the group have a common
+ association and are grouped so that a signal sent to one (e.g.,
+ a keyboard kill stroke) is delivered to all.
+
+ This causes Unix to create a two element process group:
+
+ $ lsof | less
+
+ You can use lsof to look at the open files of all members of a
+ process group, if you know the process group ID number. Assuming
+ that it is 12717 for the above example, this lsof command:
+
+ $ lsof -g12717 -adcwd
+
+ would produce on a Solaris 8 system:
+
+ $ lsof -g12717 -adcwd
+ COMMAND PID PGID USER FD TYPE DEVICE SIZE/OFF NODE NAME
+ sshd 11369 12717 root cwd VDIR 0,2 189 1449175 /tmp (swap)
+ sshd 12717 12717 root cwd VDIR 136,0 1024 2 /
+
+ The ``-g12717'' option specifies the process group ID of interest;
+ the ``-adcwd'' option specifies that options are to be ANDed and
+ that lsof should limit file output to information about current
+ working directory (``cwd'') files.
+
+
+14. When Lsof Seems to Hang
+===========================
+
+ On occasion when you run lsof it seems to hang and produce no
+ output. This may result from system conditions beyond the control
+ of lsof. Lsof has a number of options that may allow you to
+ bypass the blockage.
+
+ a. Kernel lstat(), readlink(), and stat() Blockages
+ ====================================================
+
+ Lsof uses the kernel (system) calls lstat(), readlink(), and
+ stat() to locate mounted file system information. When a file
+ system has been mounted from an NFS server and that server is
+ temporarily unavailable, the calls lsof uses may block in the
+ kernel.
+
+ Lsof will announce that it is being blocked with warning messages
+ (unless they have been suppressed by the lsof builder), but
+ only after a default waiting period of fifteen seconds has
+ expired for each file system whose server is unavailable. If
+ you have a number of such file systems, the total wait may be
+ unacceptably long.
+
+ You can do two things to shorten your suffering: 1) reduce the
+ wait time with the -S option; or 2) tell lsof to avoid the
+ kernel calls that might block by specifying the -b option.
+
+ $ lsof -S 5
+ or
+ $ lsof -b
+
+ Avoiding the kernel calls that might block may result in the
+ lack of some information that lsof needs to know about mounted
+ file systems. Thus, when you use -b, lsof warns that it might
+ lack important information.
+
+ The warnings that result from using -b (unless suppressed by
+ the lsof builder) can themselves be annoying. You can suppress
+ them by adding the -w option. (Of course, if you do, you won't
+ know what warning messages lsof might have issued.)
+
+ $ lsof -bw
+
+ Note: if the lsof builder suppressed warning message issuance,
+ you don't need to use -w to suppress them. You can tell what
+ the default state of message warning issuance is by looking at
+ the -h (help) output. If it says ``-w enable warnings'' then
+ warnings are disabled by default; ``-w disable warnings'', they
+ are enabled by default.
+
+ b. Problems with /dev or /devices
+ ==================================
+
+ Lsof scans the /dev or /devices branch of your file system to
+ obtain information about your system's devices. (The scan isn't
+ necessary when a device cache file exists.)
+
+ Sometimes that scan can take a very long time, especially if
+ you have a large number of devices, and if your kernel is
+ relatively slow to process the stat() system call on device
+ nodes. You can't do anything about the stat() system call
+ speed.
+
+ However, you can make sure that lsof is allowed to use its
+ device cache file feature. When lsof can use a device cache
+ file, it retains information it gleans via the stat() calls
+ on /dev or /devices in a separate file for later, faster
+ access.
+
+ The device cache file feature is described in the lsof man
+ page. See the DEVICE CACHE FILE, LSOF PERMISSIONS THAT AFFECT
+ DEVICE CACHE FILE ACCESS, DEVICE CACHE FILE PATH FROM THE -D
+ OPTION, DEVICE CACHE PATH FROM AN ENVIRONMENT VARIABLE,
+ SYSTEM-WIDE DEVICE CACHE PATH, PERSONAL DEVICE CACHE PATH
+ (DEFAULT), and MODIFIED PERSONAL DEVICE CACHE PATH sections.
+
+ There is also a separate file in the lsof distribution, named
+ 00DCACHE, that describes the device cache file in detail,
+ including information about possible security problems.
+
+ One final observation: don't overlook the possibility that your
+ /dev or /devices tree might be damaged. See if
+
+ $ ls -R /dev
+ or
+ $ ls -R /devices
+
+ completes or hangs. If it hangs, then lsof will probably hang,
+ too, and you should try to discover why ls hangs.
+
+ c. Host and Service Name Lookup Hangs
+ ======================================
+
+ Lsof can hang up when it tries to convert an Internet dot-form
+ address to a host name, or a port number to a service name. Both
+ hangs are caused by the lookup functions of your system.
+
+ An independent check for both types of hangs can be made with
+ the netstat program. Run it without arguments. If it hangs,
+ then it is probably having lookup difficulties. When you run
+ it with -n it shouldn't hang and should report network and port
+ numbers instead of names.
+
+ Lsof has two options that serve the same purpose as netstat's
+ -n option. The lsof -n option tells it to avoid host name
+ lookups; and -P, service name lookups. Try those options when
+ you suspect lsof may be hanging because of lookup problems.
+
+ $ lsof -n
+ or
+ $ lsof -P
+ or
+ $ lsof -nP
+
+ d. UID to Login Name Conversion Delays
+ =======================================
+
+ By default lsof converts User IDentification (UID) numbers to
+ login names when it produces output. That conversion process
+ may sometimes hang because of system problems or interlocks.
+
+ You can tell lsof to skip the lookup with the -l option; it
+ will then report UIDs in the USER column.
+
+ $ lsof -l
+
+
+15. Output for Other Programs
+=============================
+
+ The -F option allows you to specify that lsof should describe
+ open files with a special form of output, called field output,
+ that can be parsed easily by a subsequent program. The lsof
+ distribution comes with sample AWK, Perl 4, and Perl 5 scripts
+ that post-process field output. The lsof test suite has a C
+ library that could be adapted for use by C programs that want to
+ process lsof field output from an in-bound pipe.
+
+ The lsof manual page describes field output in detail in its
+ OUTPUT FOR OTHER PROGRAMS section. A quick look at a sample
+ script in the scripts/ subdirectory of the lsof distribution will
+ also give you an idea how field output works.
+
+ The most important thing about field output is that it is relatively
+ homogeneous across Unix dialects. Thus, if you write a script
+ to post-process field output for AIX, it probably will work for
+ HP-UX, Solaris, and Ultrix as well.
+
+
+16. The Lsof Exit Code and Shell Scripts
+========================================
+
+ When lsof exits successfully it returns an exit code based on
+ the result of its search for specified files. (If no files were
+ specified, then the successful exit code is 0 (zero).)
+
+ If lsof was asked to search for specific files, including any
+ files on specified file systems, it returns an exit code of 0
+ (zero) if it found all the specified files and at least one file
+ on each specified file system. Otherwise it returns a 1 (one).
+
+ If lsof detects an error and makes an unsuccessful exit, it
+ returns an exit code of 1 (one).
+
+ You can use the exit code in a shell script to search for files
+ on a file system and take action based on the result -- e.g.,
+
+ #!/bin/sh
+ lsof <file_system_name> > /dev/null 2>&1
+ if test $? -eq 0
+ then
+ echo "<file_system_name> has some users."
+ else
+ echo "<file_system_name> may have no users."
+ fi
+
+
+17. Strange messages in the NAME column
+=======================================
+
+ When lsof encounters problems analyzing a particular file, it may
+ put a message in the file's NAME column. Many of those messages
+ are explained in the 00FAQ file of the lsof distribution.
+
+ So consult 00FAQ first if you encounter a NAME column message you
+ don't understand. (00FAQ is a possible source of information
+ about other unfamiliar things in lsof output, too.)
+
+ If you can't find help in 00FAQ, you can use grep to look in the
+ lsof source files for the message -- e.g.,
+
+ $ cd .../lsof_4.76_src
+ $ grep "can't identify protocol" *.[ch]
+
+ The code associated with the message will usually make clear the
+ reason for the message.
+
+ If you have an lsof source tree that has been processed by the
+ lsof Configure script, you need grep only there. If, however,
+ your source tree hasn't been processed by Configure, you may
+ have to look in the top-level lsof source directory and in the
+ dialects sub-directory for the UNIX dialect you are using - e.g.,
+
+ $ cd .../lsof_4.76_src
+ $ grep "can't identify protocol" *.[ch]
+ $ cd dialects/Linux
+ $ grep "can't identify protocol" *.[ch]
+
+ In rare cases you may have to look in the lsof library, too --
+ e.g.,
+
+ $ cd .../lsof_4.76_src
+ $ grep "can't identify protocol" *.[ch]
+ $ cd dialects/Linux
+ $ grep "can't identify protocol" *.[ch]
+ $ cd ../../lib
+ $ grep "can't identify protocol" *.[ch]
+
+
+Options
+=======
+
+ The following appendices describe the lsof options in detail.
+
+
+A. Selection Options
+====================
+
+ Lsof has a rich set of options for selecting the files to be
+ displayed. These include:
+
+ -a tells lsof to AND the set of selection options that
+ are specified. Normally lsof ORs them.
+
+ For example, if you specify the -p<PID> and -u<UID>
+ options, lsof will display all files for the
+ specified PID or for the specified UID.
+
+ By adding -a, you specify that the listed files
+ should be limited to PIDs owned by the specified
+ UIDs -- i.e., they match the PIDs *and* the UIDs.
+
+ $ lsof -p1234 -au 5678
+
+ -c specifies that lsof should list files belonging
+ to processes having the associated command name.
+
+ Hint: if you want to select files based on more than
+ one command name, use multiple -c<name> specifications.
+
+ $ lsof -clsof -cksh
+
+ -d tells lsof to select by the associated file descriptor
+ (FD) set. An FD set is a comma-separated list of
+ numbers and the names lsof normally displays in
+ its FD column: cwd, Lnn, ltx, <number>, etc. See
+ the OUTPUT section of the lsof man page for the
+ complete list of possible file descriptors. Example:
+
+ $ lsof -dcwd,0,1,2
+
+ -g tells lsof to select by the associated process
+ group ID (PGID) set. The PGID set is a comma-separated
+ list of PGID numbers. When -g is specified, it also
+ enables the display of PGID numbers.
+
+ Note: when -g isn't followed by a PGID set, it
+ simply selects the listing of PGID for all processes.
+ Examples:
+
+ $ lsof -g
+ $ lsof -g1234,5678
+
+ -i tells lsof to display Internet socket files. If no
+ protocol/address/port specification follows -i,
+ lsof lists all Internet socket files.
+
+ If a specification follows -i, lsof lists only the
+ socket files whose Internet addresses match the
+ specification.
+
+ Hint: multiple addresses may be specified with
+ multiple -i options. Examples:
+
+ $ lsof -iTCP
+ $ lsof -i@lsof.itap.purdue.edu:sendmail
+
+ -N selects the listing of files mounted on NFS devices.
+
+ -U selects the listing of socket files in the Unix
+ domain.
+
+
+B. Output Options
+==================
+
+ Lsof has these options to control its output format:
+
+ -F produce output that can be parsed by a subsequent
+ program.
+
+ -g print process group (PGID) IDs.
+
+ -l list UID numbers instead of login names.
+
+ -n list network numbers instead of host names.
+
+ -o always list file offset.
+
+ -P list port numbers instead of port service names.
+
+ -s always list file size.
+
+
+C. Precautionary Options
+=========================
+
+ Lsof uses system functions that can block or take a long time,
+ depending on the health of the Unix dialect supporting it. These
+ include:
+
+ -b directs lsof to avoid system functions -- e.g.,
+ lstat(2), readlink(2), stat(2) -- that might block
+ in the kernel. See the BLOCKS AND TIMEOUTS
+ section of the lsof man page.
+
+ You might want to use this option when you have
+ a mount from an NFS server that is not responding.
+
+ -C tells lsof to ignore the kernel's name cache. As
+ a precaution this option will have little effect on
+ lsof performance, but might be useful if the kernel's
+ name cache is scrambled. (I've never seen that
+ happen.)
+
+ -D might be used to direct lsof to ignore an existing
+ device cache file and generate a new one from /dev
+ (and /devices). This might be useful if you have
+ doubts about the integrity of an existing device
+ cache file.
+
+ -l tells lsof to list UID numbers instead of login
+ names -- this is useful when UID to login name
+ conversion is slow or inoperative.
+
+ -n tells lsof to avoid converting Internet addresses
+ to host numbers. This might be useful when your
+ host name lookup (e.g., DNS) is inoperative.
+
+ -O tells lsof to avoid its strategy of forking to
+ perform potentially blocking kernel operations.
+ While the forking allows lsof to detect that a
+ block has occurred (and possibly break it), the
+ fork operation is a costly one. Use the -O option
+ with care, lest your lsof be blocked.
+
+ -P directs lsof to list port numbers instead of trying
+ to convert them to port service names. This might
+ be useful if port to service name lookups (e.g.,
+ via NIS) are slow or failing.
+
+ -S can be used to change the lstat/readlink/stat
+ timeout interval that governs how long lsof waits
+ for response from the kernel. This might be useful
+ when an NFS server is slow or unresponsive. When
+ lsof times out of a kernel function, it may have
+ less information to display. Example:
+
+ $ lsof -S2
+
+ -w tells lsof to avoid issuing warning messages, if
+ they are enabled by default, or enable them if they
+ are disabled by default. Check the -h (help) output
+ to determine their status. If it says ``-w enable
+ warnings'', then warning messages are disabled by
+ default; ``-w disable warnings'', they are enabled
+ by default.
+
+ This may be a useful option, for example, when you
+ specify -b, if warning messages are enabled, because
+ it will suppress the warning messages lsof issues
+ about avoiding functions that might block in the