John Nolan > Solaris-Procfs > Solaris::Procfs

Download:
Solaris-Procfs-0.26.tar.gz

Dependencies

Annotate this POD

Related Modules

BSD::Resource
Apache::GTopLimit
Apache::SizeLimit
Net::SNPP
Data::Dumper
Sys::Syslog
Devel::Leak
HTTP::Request
more...
By perlmonks.org

CPAN RT

Open  1
View/Report Bugs
Module Version: 0.26   Source  

NAME ^

Solaris::Procfs - access Solaris process information from Perl

SYNOPSIS ^

(See the EXAMPLES section below for more info.)

DESCRIPTION ^

This module is an interface the /proc filesystem on Solaris systems.

Each process on a Solaris system has a corresponding directory under /proc, named after the process id. In each of these directories are a series of files and subdirectories, which contain information about each process. The proc(4) manpage gives complete details about these files. Basically, the files contain one or more C structs with data about its corresponding process, maintained by the kernel.

This module provides methods which access these files and convert the C structs contained in them into Perl data structures. A few utility functions are also included for manipulating these files.

STATUS ^

This is pre-alpha software. It is far from finished. Parts of it need extensive rewriting and testing. However, the core functionality does seem to work properly.

Contributions and critiques would be warmly welcomed.

EXAMPLES ^

There are several different ways to invoke the functions in this module: as object methods, as functions, or as a tied hash.

As functions:

        use Solaris::Procfs;

        my $psinfo = Solaris::Procfs::psinfo( $pid );

As exported functions:

        use Solaris::Procfs (:procfiles);

        my $psinfo = psinfo( $pid );

As process objects:

        use Solaris::Procfs;
        use Solaris::Procfs::Process;

        my $p = new Solaris::Procfs::Process $pid;
        my $psinfo = $p->psinfo;

As process objects with tied hashes:

        use Solaris::Procfs;
        use Solaris::Procfs::Process;

        my $p = new Solaris::Procfs::Process $pid;
        my $psinfo = $p->{psinfo};

As a filesystem object with tied hashes:

        use Solaris::Procfs;
        use Solaris::Procfs::Filesystem;

        my $fs = new Solaris::Procfs::Filesystem;
        my $psinfo = $fs->{$pid}->{psinfo};

By default the module will fill the hash %Solaris::Procfs::TTYDEVS with a mapping of TTY device ids to the name of the TTY (it examines each file under /dev/pts). The module uses this mapping to populate fields in other hashes. If your system has a very large list of these TTYs, and you want to suppress this preloading behavior, then use the following pragma:

        use Solaris::Procfs qw(:dont_preload_tty_list);

The module will then use the string '??' to populate fields which normally contain TTY names.

FUNCTIONS ^

This module defines functions which each correspond to the files available under the directories in /proc. Complete descriptions of these files are available in the proc(4) manpage.

Unless otherwise noted, the corresponding function in the Solaris::Procfs module simply returns the contents of the file in the form of a set of nested hashrefs. Exceptions to this are listed below.

These functions can also be accessed implcitly as elements in a tied hash. When used this way, each process can be accessed as if it were one giant Perl structure, containing all the data related to that process id in the files under /proc/{pid}. To do this, you must use either the Solaris::Procfs::Process or the Solaris::Procfs::Filesystem modules. If you only use the Solaris::Procfs module, then you can only use the function-oriented interface.

Additional functions are also available.

as

Not yet implemented. The 'as' file contains the address-space image of the process.

auxv

The 'auxv' file contains the initial values of the process's aux vector in an array of auxv_t structures (see <sys/auxv.h>).

ctl

Not implemented as a function. The 'ctl' file is a write-only file to which structured messages are written directing the system to change some aspect of the process's state or control its behavior in some way. This file somewhat like a device file. See the examples directory 'examples' included in this package for some simple examples showing how to write to this file.

cwd or pcwd

Returns a string containing the absolute path to the process' current working directory. The 'cwd' file is a symbolic link to the process's current working directory.

fd

Returns a hash whose keys are the process' open file descriptors, and whose values are the absolute paths to the open files, as far as can be determined. The 'fd' directory contains references to the open files of the process. Each entry is a decimal number corresponding to an open file descriptor in the process.

ldt

Not yet implemented. The 'ldt' file exists only on x86 based machines. It is non-empty only if the process has established a local descriptor table (LDT). If non-empty, the file contains the array of currently active LDT entries in an array of elements of type struct ssd, defined in <sys/sysi86.h>, one element for each active LDT entry.

lpsinfo

The 'lpsinfo' file contains a prheader structure followed by an array of lwpsinfo structures, one for each lwp in the process.

lstatus

The 'lstatus' file contains a prheader structure followed by an array of lwpstatus structures, one for each lwp in the process.

lusage

The 'lusage' file contains a prheader structure followed by an array of prusage structures, one for each lwp in the process plus an additional element at the beginning that contains the summation over all defunct lwps.

lwp

The 'lwp' directory contains entries each of which names an lwp within the process. These entries are themselves directories containing additional files. This function returns the contents of the files 'lwpstatus', 'lwpsinfo', and 'lwpusage', translated into a set of nested hashes. Interfaces to the files 'asrs', 'gwindoes', 'lwpctl' and 'xregs' have not been implemented.

map

The 'map' file contains information about the virtual address map of the process. The file contains an array of prmap structures, each of which describes a contiguous virtual address region in the address space of the traced process.

object

Not yet implemented. The 'object' directory containing read-only files with names corresponding to the entries in the map and pagedata files. Opening such a file yields a file descriptor for the underlying mapped file associated with an address-space mapping in the process.

pagedata

Not yet implemented. Opening the 'pagedata' file enables tracking of address space references and modifications on a per-page basis.

prcred

The 'prcred' file contains a description of the credentials associated with the process (UID, GID, etc.).

psinfo

The 'psinfo' file ontains miscellaneous information about the process and the representative lwp needed by the ps(1) command.

rmap

The 'rmap' file contains information about the reserved address ranges of the process. Examples of such reservations include the address ranges reserved for the process stack and the individual thread stacks of a multi-threaded process.

root or proot

Returns a string containing the absolute path to the process' root directory. The 'root' file is a symbolic link to the process' current working directory.

sigact

The 'sigact' file contains an array of sigaction structures describing the current dispositions of all signals associated with the traced process (see sigaction(2)).

status

The 'status' file ontains state information about the process and the representative lwp.

usage

The 'usage' file contains process usage information described by a prusage structure.

watch

Not yet implemented. The 'watch' file contains an array of prwatch structures, one for each watched area established by the PCWATCH control operation.

xmap

The 'xmap' file contains information about the virtual address map of the process. This file is not documented in the proc manpage.

OTHER FUNCTIONS ^

writectl

Write control directives to a process control file (/proc/<pid>/ctl). For example, the following code will turn on microstate accounting for a given process ($pid):

        use Solaris::Procfs qw(writectl);
        writectl($pid,PCSET,PR_MSACCT); 

ERROR HANDLING ^

Most of these functions are essentially wrappers around the system calls open(), read() and write(). Basically, we are reading and writing to the files under /proc. If any of these system calls fail, they will set the system errno variable, and the function calling them will just return.

When using these functions, you should check the return value just like you would check the return value of a system call. Make sure that that the return value is defined before using it. If the value is not defined, print out the variable $! for a verbose description of the error. The most likely error message will be "No such file or directory" if the process you are accessing does not exist, or "Permission denied" or "Bad file number" if you do not have permission to access the file.

Here is an example from the file examples/ptree:

        my $psinfo = psinfo($pid);

        unless (defined $psinfo and ref $psinfo eq 'HASH') {

                warn "Cannot get psinfo on process $pid: $!\n";
        }

Here is an example from the file examples/pstop:

        writectl($pid,PCSTOP) or warn "Can't control process $pid: $!\n";

CHANGES ^

TO DO ^

THANKS ^

Much of this code is modeled after code written by Alan Burlison, and I received some helpful and timely advice from Tye McQueen.

Thanks to Daniel J. Urist for writing Proc::ProcessTable. I used his method for keeping track of TTY numbers.

Thanks to Kennth Skaar (kenneths@regina.uio.no) for fixing some memory leaks and teaching me to count (references).

Thanks to Thomas Whateley for sending a patch with functions for accessing the /proc/<pid>/xmap file.

Thanks to Dominic Dunlop for submitting a patch to the functions which access the map file.

Thanks to Brian Farrell, for sending a very useful patch which allows Solaris::Procfs to inspect the argv and environment of processes other than the currently running process.

AUTHOR ^

John Nolan jpnolan@sonic.net 1999-2003. A copyright statment is contained in the source code itself.

syntax highlighting: