githubmirror/lsof

NEW/lsofAPI/lsofAPI.5
238 строк7 KB
Masatake YAMATO
Import the final source tree published by Vic, the original lsof maintainer.
23 июл 2018, 06:45
23 июл 2018, 06:458662085


			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