NAME

VERSION

SYNOPSIS

    use Unix::Lsof;

    my $lr = lsof("-p",$$);

    if ($lr->has_errors()) {
        print qq(Errors encountered: $lr->errors());
    }

    my @pids         = $lr->get_pids();
    my @file_types   = $lr->get_values( "file type" );
    my $access_modes = $lr->get_values( "access mode" );

    # Print out file name and type
    my @filenames    = $lr->get_arrayof_rows( "file type", "file name" );
    for my $p (@filenames) {
        print "File type: $p->[0] - File name: $p->[1]\n";
    }

    # Print a list of open IPv4 connections
    my %filetype     = $lr->get_hashof_rows( "file type", "n", "protocol name" );
    for my $conn ( @{ $filetype{"IPv4"} } ) {
        print qq(IPv4 connection to: $conn->{"n"}, protocol: $conn->{"protocol name"}\n);
    }

    # Print out a list of open files larger than 1kb
    my @filesize     = $lr->get_arrayof_columns( "file name", "file size" );
    for my $i ( 0..scalar( @{ $filesize[1] } ) ) {
        if ( $filesize[1][$i] >= 1024 ) {
            print "File $filesize[0][$1] is over 1k\n";
        }
    }

    # Print out the size of text files found
    my $fs           = $lr->get_hashof_columns( "file name", "file size" );
    for my $i ( 0..scalar( @{ $fs->{"file name"} } ) ) {
        if ( $fs->{"file name"}[$i] =~ m/\.txt\z/ ) {
            print qq(Found $fs->{"file size"}[$i] bytes large text file\n);
        }
    }

    # The same as previous, using filters
    my @file_list    = $lr->get_values( { "file name" => qr/\.txt\z/ },
                                        "file size" );
    for my $f (@file_list) {
        print qq(Found $f bytes large text file);
    }

   # Looking for text files between 1 and 4k
   my @file_list     = $lr->get_filenames( { "file name" => qr/\.txt\z/,
                                             "file size"  => sub { $_[0] > 1024 &&
                                                                   $_[0] <= 4096  }
                                        }, "file name");

DESCRIPTION

The "Unix::Lsof::Result" object is returned when calling "<Unix::Lsof-"lsof()>> in scalar context. When evaluated in boolean context the object will evaluate to true unless no STDOUT output is obtained from running the "lsof" binary <b>and </b> STDERR output was obtained from the same run. This allows for the following logic :

    if ($lf = $lsof(@params)) {
        # we got output or no errors, some success was had
        warn "Errors: ".$lf->errors()
            if $lf->has_errors();
        # normal processing continues
        # ...
    } else {
        # no output and we have an error message, something is badly wrong
        die "Errors: ".$lf->errors();
    }

Note that you will only find out whether any errors were encountered by examining the "has_errors" return value, examining truth of the object itself only makes sense if you just care about some valid output being returned (e.g. if you're passing in a list of files, some of which may not exist).

All of the output accessor methods (i.e. the methods starting with "get_", for example "get_values", "get_arrayof_rows") have the following properties:

• Only return unique values

  All output accessor methods will only return unique result sets, e.g. if a single file is opened by multiple programs

     $lf->get_arrayof_rows( "file name", "process id");
      

  will return as many rows as there are processes opening the file, whereas

     $lf->get_arrayof_rows( "file name", "file type");
      

  will only return a single row, since file name and file type are the same for all return sets.

• Returns list or reference depending on calling context

  The accessor methods are sensitive to their calling context and will return either a list or a reference to an array/hash.

    # This will return a list
    @e = $lf->get_pids();
  
    # This will return an array reference
    $e = $lf->get_pids()
      

• Fields can be specified either with their full name or single character

  When specifying a list of fields which you want returned from the accessor, you can either use the single character associated with that field (see the lsof man page section "OUTPUT FOR OTHER PROGRAMS" for a list of these) or the full field name as given in ther "Unix::Lsof" perldoc, or the full field name with spaces replaced by underscores (e.g. file_name instead of "file name").

• Filters

  The method can optionally be provided with a "filter" which limits the data returned. For this, pass a hash reference as the first argument, of the format

      {
        <field name> => <filter>,
        <field name> => <filter>,
        ...
      }
      

  where <filter> can be either a scalar value, a reference to a regular expression or a reference to a subroutine. Only record sets that match on all fields will be returned. A subroutine must return true to "match", the field value is passed in normally as the first element of the @_ array.

  Example:

      {
          "process id"   => 4242,
          "n"            => qr/\.txt\z/i,
          "command_name" => sub { $_[0] =~ m/kde/ || $_[0] eq "cupsd" }
      }
      

  Limitations: is is very well possible to specify a filter that completely excludes any files, e.g.

      { "process id" => "-1" }
      

  . Also, to specify more than one condition on a given field name (e.g. greater than 100 but not 105) you need to use a sub e.g.

      { "process id" => sub { $_[0] > 100 && $_[0] != 105 } }
      

  The same goes if you need to "or" a set of constraints. Note that there is currently no way to "or" constraints over several fields (e.g. process id equals 1000 or user id equals 42).

INTERFACE

DIAGNOSTICS

"%s is not in the list of fields returned by lsof"

You requested a field which was not in the list of fields returned by the lsof binary. Check that you spelt the field name correctly and that it is in the list of field names specified in the "Unix::Lsof" docs. Also check that the field name is supported on the platform you are running lsof on.

"Invalid filter specified for "%s""

You specified an invalid filter. Valid filters are strings, numbers or references to regular expressions or subroutines. See the documentation on "Filters" above.

CONFIGURATION AND ENVIRONMENT

DEPENDENCIES

•

version

INCOMPATIBILITIES

BUGS AND LIMITATIONS

No bugs have been reported so far. As with "Unix::Lsof", there are a number of improvements that could be made to this module, particularly with regards to filtering. Further development is almost certainly strictly "develop by bugreport", so if you want a feature added, please open a wishlist item in the RT web interface and let me know. I'm more than happy to do more work on this module, but want to see what concrete improvements people would like to have. As always, patches are more than welcome.

ACKNOWLEDGEMENTS

AUTHOR

LICENCE AND COPYRIGHT

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

DISCLAIMER OF WARRANTY

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.