0 # lY>:ʁvCq)F q? Guide to Porting lsof 4 to Unix OS Dialects ********************************************************************** | The latest release of lsof is always available via anonymous ftp | | from lsof.itap.purdue.edu. Look in pub/lsof.README for its | | location. | ********************************************************************** Contents How Lsof Works /proc-based Linux Lsof -- a Different Approach General Guidelines Organization Source File Naming Conventions Coding Philosophies Data Requirements Dlsof.h and #include's Definitions That Affect Compilation Options: Common and Special Defining Dialect-Specific Symbols and Global Storage Coding Dialect-specific Functions Function Prototype Definitions and the _PROTOTYPE Macro The Makefile The Mksrc Shell Script The MkKernOpts Shell Script Testing and the lsof Test Suite Where Next? How Lsof Works -------------- Before getting on with porting guidelines, just a word or two about how lsof works. Lsof obtains data about open UNIX dialect files by reading the kernel's proc structure information, following it to the related user structure, then reading the open file structures stored (usually) in the user structure. Typically lsof uses the kernel memory devices, /dev/kmem, /dev/mem, etc. to read kernel data. Lsof stores information from the proc and user structures in an internal, local proc structure table. It then processes the open file structures by reading the file system nodes that lie behind them, extracting and storing relevant data in internal local file structures that are linked to the internal local process structure. Once all data has been gathered, lsof reports it from its internal, local tables. There are a few variants on this subject. Some systems don't have just proc structures, but have task structures, too, (e.g., NeXTSTEP and OSF/1 derivatives). For some dialects lsof gets proc structures or process information (See "/proc-based Linux Lsof -- a Different Approach) from files of the /proc file system. It's not necessary for lsof to read user structures on some systems (recent versions of HP-UX), because the data lsof needs can be found in the task or proc structures. In the end lsof gathers the same data, just from slightly different sources. /proc-based Linux Lsof -- a Different Approach ============================================== For a completely different approach to lsof construction, take a look at the /proc-based Linux sources in .../dialects/linux/proc. (The sources in .../dialects/linux/kmem are for a traditional lsof that uses /dev/kmem to read information from kernel structures.) The /proc-based lsof obtains all its information from the Linux /proc file system. Consequently, it is relatively immune to changes in Linux kernel structures and doesn't need to be re-compiled each time the Linux kernel version changes. There are some down-sides to the Linux /proc-based lsof: * It must run setuid-root in order to be able to read the /proc file system branches for all processes. In contrast, the /dev/kmem-based Linux lsof usually needs only setgid permission. * It depends on the exact character format of /proc files, so it is sensitive to changes in /proc file composition. * It is limited to the information a /proc file system implementor decides to provide. For example, if a /proc/net/ file lacks an inode number, the /proc-based lsof can't connect open socket files to that protocol. Another deficiency is that the /proc-based may not be able to report file offset (position) information, when it isn't available in the /proc//fd/ entry for a file. In contrast the /dev/kmem-based lsof has full access to kernel structures and "sees" new data as soon as it appears. Of course, that new data requires that lsof be recompiled and usually also requires ch