Extensions to pstat(2)

This extension provides new functionality to the pstat() system call that enables various system management and measurement tools to eliminate their dependency on the /dev/kmem pseudo-driver.

Today, many system management and measurement tools read kernel data structures through unsupported interfaces, such as the /dev/kmem pseudo-driver, to get information about open files, resource usage, process activity, and so on. Because kernel data structures change from release to release, this access method is fragile, incurring a high maintenance cost. To insulate these applications from the release-to-release variability in private kernel data structures, HP-UX 11i provides the enhanced pstat system call and a new set of wrappers.

The pstat interface is designed to allow future expansion of the interface, while preserving source and binary compatibility of programs written using pstat wrappers. The pstat interface is available in both 64-bit and 32-bit versions. Replacing the /dev/kmem access with calls to pstat wrappers will eliminate the need to re-release applications with each new HP-UX release.

Currently, the pstat() system call provides information about various system contexts, such as static, dynamic, virtual memory, process, open files, etc. HP-UX provides a number of libc wrappers (pstat_get()*) and corresponding structures (struct pst_()*) to get information from the kernel using pstat(). As part of this enhancement, new pstat() wrappers and corresponding structures are added and some existing ones are extended.

Compatibility is significantly improved by introducing a well documented interface that guarantees binary compatibility for kernel intrusive applications between releases. There is no impact to legacy behavior of current pstat() services.

There is no impact to application performance as compared to obtaining the data from /dev/kmem. No impact to system performance is expected from these pstat extensions.

	NOTE: This release includes an enhanced version of pstat(). This version repairs some existing defects by adding more fields in pst_status struct to return process children usage information. The pstat(2) manpage reflects this added functionality. The enhancement poses no problem for 11.0 executables running on 11.0 Extension Pack or 11i, nor for any executables running on 11.0 Extension Pack, as long as they do not rely on the additional functionality. Note, however, relocatable objects may incorrectly presume that the size of returned information is the same pre- and post-patch. It is possible to determine the size of information returned. pstat() users can use the size return value of the system call to maintain relocatable object compatibility and portability across the proposed change. This is documented in the manpage. pstat() is not part of an industry standard, but was designed to accommodate changes of this nature while maintaining compatibility with earlier versions.

New Modules

The following table shows new pstat modules and the purpose of each:

pstat_getfile2()	Provides information about open files of a process
pstat_getfiledetails()	Provides stat equivalent information
pstat_getsocket()	Provides detailed socket information
pstat_getstream()	Provides detailed stream information
pstat_getpathname()	Provides full pathname of an opened file (Reverse Pathname Lookup)
pstat_getmpathname()	Provides a copy of the DNLC entries for a given file system

	NOTE: Use of the call pstat_getmpathname() is limited to uid equal to 0. Use of the calls pstat_getfiledetails(), pstat_getsocket(), pstat_getstream(), and pstat_getpathanme() is limited to uid equal to 0 or effective ID match. In the case of effective ID match, access will only be granted if the target process is not and has never run as a setuid or setgid process.

New Data Structures

The following are new data structures being added to the PSTAT module:

pst_fileinfo2	Describes per-file information. For the specified process, there is one instance of this context for each open file descriptor.
pst_fid	Used to efficiently re-access the opened files. This value is returned by pstat_getfile2(), pstat_getproc(), and pstat_getprocvm() calls. This ID is then passed to subsequent PSTAT calls such as pstat_getsocket() to efficiently re-access the opened files.
pst_filedetails	This data structure contains detailed information specific to a particular open file. For a specified file, there is only one instance of this structure. This information includes stat equivalent information.
pst_socket	The PSTAT socket structure contains detailed information pertaining to an opened socket, such as type, state, protocol, address family, and options of the socket. For a specified socket, there is only one instance of this structure.
pst_stream	The PSTAT stream structure contains detailed information pertaining to a stream entity. This includes information about the head, names of modules pushed, and the driver of the stream.
pst_mpathnode	This structure is returned by pstat_getmpathname() routine that provides a copy of the DNLC entries for a given file system. The information contained in this structure includes id of the current file or directory, parent of the current entry, and the name of the current entry. By traversing the DNLC entries in the reverse order, one can obtain the pathname for an opened file to the mount point.

In addition to the above data structures, several existing PSTAT data structures have been extended. These include: pst_dynamic, pst_vminfo, pst_vm_status, pst_status, pst_static, and pstun.

Documentation Changes

The existing pstat(2) manpage has been extended to reflect the added functionality.