Functions of An Lsof API
In the functions I describe I have made no direct reference to
a particular API. Instead, I've tried to describe a general
interface as independent of Unix dialect implementation details
as I can make it.
I envision an lsof API having these functions:
* Get basic process information about a process or a set
of processes.
* Get extended information for a single process.
* Get extended information for a file or a set of files.
* Get file name cache information. (This function may
not be needed if the extended file information has
path name.)
Get Basic Process Information
=============================
Lsof should be able to get the following basic information
on a single process or a set of processes. The process set
might include all processes -- and generally will.
* The process ID (PID)
* The parent process ID (PPID)
* The process group ID (PGRP)
* The owner of the process (UID)
* The status of the process -- i.e., is it a "zombie", is
it a system process, is it swapped out, etc.?
* The command being executed by the process
* Reference values for the current working and root directories
that can be supplied to the get extended file information
function to learn more about these directories.
File Reference Value
====================
The file reference values should be globally unique, so lsof
can report them for analysis of all open files by the lsof
user. Vnode address might be a good reference value. Adding
file structure address and file descriptor number to the
file reference value, when they are available, might be
necessary.
The file reference value might look like this:
struct file_ref_val {
pid_t frv_pid; /* PID owning or using this file */
void *frv_node: /* file's kernel vnode address */
void *frv_file; /* file's kernel file structure address
* (NULL if not applicable) */
int frv_fd; /* file's descriptor number
* (if frv_file is non-NULL) */
};
Implementation Suggestion:
=========================
I like best the way AIX delivers a full process table
information set. It supplies its getproc() function with
a receiving table address and count. Those parameters are
started at a table of size 1. Getproc() returns an ENOSPC
error if the supplied size isn't big enough, and an estimate
in the first entry of the supplied structure buffer of how
many entries would be enough. The caller realloc()s its
buffer to the suggested reply value and calls getproc()
again.
Get Extended Process Information
================================
I envision this function applying to a single process. Lsof
would use it after determining a given process is of further
interest by looking at its basic information.
This function needs to return two variable size arrays:
* A list of file reference values for the executing text
file, shared libraries, and memory mapped files -- and any
other process-related files -- in use by the process. Lsof
should be able to use these as arguments to the get extended
file information function.
* A list of file reference values for open file descriptors.
Lsof should be able to use these as arguments to the get
extended file information function.
These file reference values should also be usable in
identifying processes that share the same file descriptor.
The file structure address could be used to do that.
Get Extended File Information
=============================
This function takes a file reference value -- a process current
working directory response value or a file descriptor reference
value -- and returns the information lsof needs for a full
report on the file. The basic information would include:
* File type -- regular file, directory, socket, NFS file,
FIFO, pipe, etc.
* Access mode -- how the file was opened -- read, write, or
read and write
* Type of lock that the owning process has applied to the
file -- read, write, full file, partial file
* Current position -- file offset
* File link count
* Number of current users of the file
* FIle system information (when the file resides on a file
system) -- mounted-on directory and device names, file
system type, file system (major,minor) device doublets (raw
and cooked), file system root inode number
* Indication of the type of further file data -- socket, FIFO,
character, etc.
o For sockets:
. Protocol -- Internet, Unix, etc.
. For TCP/IP sockets:
x Protocol -- IPPROTO_*
x Identifier -- e.g. protocol control block address
x Type -- IPv4 or IPv6
x Local and remote host Internet numbers and port numbers
x Connection state -- e.g. ESTABLISHED or Unbound
x Read and write queue sizes
x Read and write window sizes
. For Unix domain sockets
x Identifier -- e.g., protocol control block address
x Remote peer identifier
x File reference value for any name bound to the
Unix domain socket
x Name bound to the Unix domain socket
x Read and write queue sizes
o For pipes and FIFOs:
. Remote peer identifier -- e.g., a file reference value
. Any associated name
. Node number, if applicable
. Data in pipe or FIFO -- read and write quantities
o For streams
. Stream device identification:
x (major,minor) device number doublets (raw and "cooked")
x Node number
x Path name
. Stream module names
. Stream queue read and write sizes
o For character device files
. raw and cooked (major,minor) device number doublets
. Character device node number
. Optional -- device node path name
o For regular files
. File system (major,minor) device number doublet -- both raw
and "cooked"
. Device "node" number
. File size
. Full path name (optional -- see the get file name cache
function description)
o For fattach()'d files:
. Attached-to file's file reference value
Get File Name Cache Information
===============================
This function is an option to having the get extended file
information function return full path names.
If this function is used, it would return information from
the kernel's name cache with file reference values that can
be connected to extended file information.
For example, this function might return:
* Vnode address
* (major,minor) device number doublet
* Capability ID (a unique-ifier)
* Name
* Parent vnode address and capability ID
Vic Abell <abe@purdue.edu>
March 20, 1999