Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Unix::Lsof::Result(3) User Contributed Perl DocumentationUnix::Lsof::Result(3)

NAME
       Unix::Lsof::Result - Perlish interface to lsof output

VERSION
       This document describes Unix::Lsof::Result version 0.0.5

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
       This module offers multiple ways	of organising and retrieving the data
       returned	by lsof. It attempts to	make it	as easy	as possible for	the
       user to obtain the information he wants in the way he wants it.

       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:

       o   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.

       o   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()

       o   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").

       o   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
   Methods
       "has_errors"
	       $lf->has_errors();

	   Returns true	if the call to the lsof	binary returned	any STDERR
	   output.

       "errors"
	       $lf->errors();

	   Returns the STDERR output of	the lsof binary	in a single string.
	   WARNING: it is possible that	this may change	in some	future version
	   to allow for	more sophisticated error handling (though using	the
	   result of this subroutine as	a simple string	will almost certainly
	   continue to be supported).

       "get_values"
	       $lf->get_values(	$field_name );
	       $lf->get_values(	$filter, $field_name );

	   Returns a list with the values for a	single field.

       "get_pids"
	       $lf->get_values();
	       $lf->get_values(	$filter	);

	   Specialised version of get_values which returns a list of process
	   ids.

       "get_filenames"
	       $lf->get_filenames();
	       $lf->get_filenames( $filter );

	   Specialised version of get_values which returns a list of file
	   names.

       "get_arrayof_rows"
	       $lf->get_arrayof_rows( @column_names );
	       $lf->get_arrayof_rows( $filter, @column_names );

	   Returns a list of array references, each of which corresponds to a
	   row of lsof output. The order of the	values in the referenced
	   arrays corresponds to the order of the parameters passed in;	e.g. a
	   call	to

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

	   would produce a data	structure like this

	       [
		   [ filename1,	filetype1 ],
		   [ filename2,	filetype2 ],
		   ...
	       ]

       "get_arrayof_columns"
	       $lf->get_arrayof_columns( @column_names );
	       $lf->get_arrayof_columns( $filter, @column_names	);

	   Returns a list of array references, each of which correspond	to a
	   field name column. The order	of array references correspond to the
	   order of parameters passed in, e.g. a call to

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

	   would produce a data	structure like this

	       [
		   [ filename1,	filename2, ... ],
		   [ filetype1,	filetype2, ... ]
	       ]

       "get_hashof_columns"
	       $lf->get_hashof_columns(	 @column_names );
	       $lf->get_arrayof_columns( $filter, @column_names	);

	   Returns a hash references (or list which can	be assigned to a
	   hash). The hash keys	are the	column names specified in the
	   parameters, the hash	values are array references with the column
	   values. E.g.	a call to

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

	   would produce a data	structure like this

	       {
		   "file name" => [ filename1, filename2 ],
		   "file type" => [ filetype1, filetype2 ]
	       }

	   The hash keys returned are exactly of the same format as passed in
	   via the parameters, so passing in a single character	will not
	   create a full field name key. E.g.

	       $lf->get_hashof_columns(	"file_name", "t");

	   will	produce	this

	       {
		   "file_name" => [ filename1, filename2 ],
		   "t"	       => [ filetype1, filetype2 ]
	       }

       "get_hashof_rows"
	       $lf->get_hashof_rows(  $key, @column_names );
	       $lf->get_arrayof_rows( $filter, $key, @column_names );

	   Returns a hash reference (or	a list which can be assigned to	a
	   hash). The hash keys	are the	value of the field which is given as
	   the first parameter.	The hash values	are references to arrays, each
	   of which contain a row of the requested fields in a hash; e.g. a
	   call	to

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

	   would produce a data	structure like this

	       {
		   pid1	=> [
			      {
				  "file	name" => filename1,
				  "t"	      => filetype1
			      },
			      {
				  "file	name" => filename2,
				  "t"	      => filetype2
			      },
			   ],
		   pid2	=> [
			      {
				  "file	name" => filename3,
				  "t"	      => filetype3
			      }
			   ]
	       }

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
       Unix::Lsof::Result requires no configuration files or environment
       variables.

DEPENDENCIES
       Unix::Lsof::Result requires the following modules:

       o   version

INCOMPATIBILITIES
       None reported.

BUGS AND LIMITATIONS
       Please report any bugs or feature requests to
       "bug-unix-lsof@rt.cpan.org", or through the web interface at
       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Unix-Lsof>.

       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
       A very heartfelt	thanks to Vic Abell for	writing	"lsof",	it has been
       invaluable to me	over the years.	Many thanks as always to
       http://www.perlmonks.org, the monks continue to amaze and enlighten me.
       A very special thanks to	Damian Conway, who (amongst other things)
       recommends writing module documentation at the same time	as code	(in
       his excellent book "Perl	Best Practices"). I didn't follow that advice
       and as a	result writing these docs was more painful and error-prone
       than it should have been. Please	Mr. Conway, for	the next edition could
       you put more emphasis on	that recommendation so that dolts like me get
       it the first time?

AUTHOR
       Marc Beyer  "<japh@tirwhan.org>"

LICENCE	AND COPYRIGHT
       Copyright (c) 2008, Marc	Beyer "<japh@tirwhan.org>". All	rights
       reserved.

       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
       BECAUSE THIS SOFTWARE IS	LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
       FOR THE SOFTWARE, TO THE	EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
       WHEN OTHERWISE STATED IN	WRITING	THE COPYRIGHT HOLDERS AND/OR OTHER
       PARTIES PROVIDE THE SOFTWARE "AS	IS" WITHOUT WARRANTY OF	ANY KIND,
       EITHER EXPRESSED	OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
       WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
       ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF	THE SOFTWARE IS	WITH
       YOU. SHOULD THE SOFTWARE	PROVE DEFECTIVE, YOU ASSUME THE	COST OF	ALL
       NECESSARY SERVICING, REPAIR, OR CORRECTION.

       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.

perl v5.24.1			  2008-09-01		 Unix::Lsof::Result(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | INTERFACE | DIAGNOSTICS | CONFIGURATION AND ENVIRONMENT | DEPENDENCIES | INCOMPATIBILITIES | BUGS AND LIMITATIONS | ACKNOWLEDGEMENTS | AUTHOR | LICENCE AND COPYRIGHT | DISCLAIMER OF WARRANTY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Unix::Lsof::Result&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help