Subroutines

lsof

 lsof ();
 lsof ( @lsof_arguments );
 lsof ( @lsof_arguments, \%options );
    

"lsof" accepts arguments passed on to the lsof binary. These need to be in list form, so you need to do

    $r = lsof("-p",$pid,"-a","+D","/tmp");
    

NOT

    $r = lsof("-p $pid -a +D /tmp");
    

SCALAR CONTEXT

Example:

    $lr = lsof("afile");
    

When called in scalar context, "lsof" will return a "Unix::Lsof::Result" object. Please see the documentation for that module on how to use this object. I mean it, really, take a look there, you'll almost certainly want to use the "Unix::Lsof::Result" interface which gives you lots of helper methods to dig out exactly the information you want.

LIST CONTEXT

Example:

    ($output,$error) = lsof("afile");
    

When called in list context, "lsof" will return two values, a hash reference containing the parsed output of the lsof binary, and a string containing any error messages. The output data structure looks like this (approximating "Data::Dumper" formatting here:)

   $output = {
               '<pid>' => {
                            '<process field name>' => '<value>',
                            '<process field name>' => '<value>',
                            'files' => [
                                         {
                                           '<file field name>' => '<value>',
                                           '<file field name>' => '<value>'
                                         },
                                         {
                                           '<file field name>' => '<value>',
                                           '<file field name>' => '<value>'
                                                ...
                                         },
                                       ]
                          }
                  ...
             }
    

Each process id (pid) is the key to a hash reference that contains as keys the names of process set fields and their corresponding field value. The special "files" key has an array reference as value. Each element in this array is a hash reference that contains the names of file set fields and their values. See the section OUTPUT FOR OTHER PROGRAMS in the lsof manpage if you're wondering what process and file sets are.

Process field names are:

    "command name"
    "login name"
    "process id"
    "process group id"
    "parent pid"
    "task id"
    "user id"
    

File field names are:

    "access mode"
    "structure share count"
    "device character code"
    "major/minor device number"
    "file descriptor"
    "structure address"
    "flags"
    "inode number"
    "link count"
    "lock status"
    "file name"
    "node identifier"
    "file offset"
    "protocol name"
    "raw device number"
    "file size"
    "stream module and device names"
    "file type"
    "tcp/tpi info"
    "user id"
    "zone name"
    "selinux security context"
    

Special mention needs to be made of the field "tcp/tpi info", since that will contain a list of information. Therefore, the value for this field is itself a hash reference. The keys of this hash are the long names of the information, as given in the lsof man page, the information names are:

    "read queue size"
    "send queue size"
    "socket options and values"
    "socket states"
    "connection state"
    "TCP flags and values"
    "window read size"
    "window write size"
    

Note that not all of this information is available on every dialect, see the lsof man page for more.

parse_lsof_output ( <STRING> )

This function takes the output as obtained from the lsof binary (with the -F0 option) and parses it into the data structure explained above. You need to pass the lsof STDOUT output in as a single string. Previous behaviour (passing the output as an array reference with one line of output per array element) is deprecated as of Unix::Lsof version 0.0.8 and may not work in future releases. "parse_lsof_output" does not understand the lsof STDERR output.

OPTIONS

You can (optionally) pass in a hash reference as the last argument to either "lsof" or "parse_lsof_output". This reference can contain the following options:

binary

Contains the path of the lsof binary. Use this if lsof is not in your $ENV{PATH}.

suppress_errors

Default false. If set to 1, Unix::Lsof subroutines will not emit any warning messages and will not die on a fatal error. Diagnostics suppressed in this way can be found in $err (and $UNIX::Lsof::Result->err()).

tcp_tpi_parse

See the above section on "tcp/tpi info". Possible values:

"full"

Default. Parses out the tcptpi information and uses the long names as hash keys.

"part"

Also parses out the information, but uses the short names (e.g. QS for "send queue size") as keys.

"array"

Returns an array reference instead of a hash, each element of the array contains an unparsed TCP/TPI information (e.g. "QS=0").