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

FreeBSD Manual Pages

  
 
  

home | help
Unix::Statgrab(3)     User Contributed Perl Documentation    Unix::Statgrab(3)

NAME
       Unix::Statgrab -	Perl extension for collecting information about	the
       machine

SYNOPSIS
	   use Unix::Statgrab;

	   my $host_stats = get_host_info();
	   print $host_stats->hostname . " is a	" . $host_stats->bitwidth . " "	. $host_stats->os_name . "\n";

	   my $filesystems = get_fs_stats();
	   my @mount_points = map { $filesystems->mnt_point($_)	} (0 ..	$filesystems->entries()	- 1);
	   print $host_stats->hostname . " has " . join( ", ", @mount_points ) . " mounted\n";

	   my $proc_list = get_process_stats();
	   my @proc_by_type;
	   foreach my $proc_entry (0 ..	$proc_list->entries() -	1) {
	       $proc_by_type[$proc_list->state($proc_entry)]++;
	   }
	   my $total_procs = 0;
	   $total_procs	+= $_ for grep { defined $_ } @proc_by_type;
	   foreach my $state (qw(SG_PROCESS_STATE_RUNNING SG_PROCESS_STATE_SLEEPING
				 SG_PROCESS_STATE_STOPPED SG_PROCESS_STATE_ZOMBIE
						 SG_PROCESS_STATE_UNKNOWN)) {
	       defined $proc_by_type[Unix::Statgrab->$state] or	next;
	       print $proc_by_type[Unix::Statgrab->$state] . " of " . $total_procs . " procs in	$state\n";
	   }

	   my $last_cpu_stats =	get_cpu_stats()	or croak( get_error()->strperror() );
	   do_sth_way_longer();
	   my $cpu_diff	= get_cpu_stats()->get_cpu_stats_diff($last_cpu_stats);

	   my $last_cpu_percent	= $last_cpu_percent->get_cpu_percents();
	   my $diff_cpu_percent	= $cpu_diff->get_cpu_percents();
	   my $now_cpu_percent = get_cpu_stats()->get_cpu_percents();

DESCRIPTION
       Unix::Statgrab is a wrapper for libstatgrab as available	from
       <http://www.i-scream.org/libstatgrab/>. It is a reasonably portable
       attempt to query	interesting stats about	your computer. It covers
       information on the operating system, CPU, memory	usage, network
       interfaces, hard-disks etc.

       Each of the provided functions follow a simple rule: It never takes any
       argument	and returns either an object (in case of success) or "undef".
       In case "undef" was returned, check the return value of "get_error".
       Also see	"ERROR HANDLING" further below.

       To avoid	error during copying documentation, the	original function
       documentation will be refererred	where reasonable. Each returned	object
       has a getter method named as the	attribute in original documentation.
       Those getters take a optional index argument, asking for	the attribute
       of the "n"th statistic item. Further, each object provides an
       "entries"() method, telling you how much	statistics for requested type
       are returned (yes, even "get_host_info()" has that, maybe we have more
       host_info when grabbing that statistic in a cluster, grid or cloud).
       Additionally, for the users of Perl's list processing features, each
       object has an "as_list"() method	which returns the statistic as list of
       hash items containing each attribute / value pair of available
       attributes.

FUNCTIONS
   drop_privileges()
       Unix::Statgrab can be told to discard setuid and	setgid privileges
       which is	usually	a good thing. If your program doesn't need the
       elevated	privileges somewhere else, call	it right after "use"ing	the
       module.

       This function is	depreciated and	might be removed in a future version
       of libstatgrab (and then	in Unix::Statgrab, too).

   get_host_info()
       Returns generic information about this machine. The object it returns
       is a Unix::Statgrab::sg_host_info.

   get_cpu_stats
       Returns information about this machine's	usage of the CPU. The object
       it returns is an	Unix::Statgrab::sg_cpu_stats.

   get_disk_io_stats
       Delivers	the disk IO per	disk stored in the kernel which	holds the
       amount of data transferred since	boot. The object it returns is a
       Unix::Statgrab::sg_disk_io_stats.

   get_fs_stats
       Returns statistics about	the mounted filesystems. The object it returns
       is a Unix::Statgrab::sg_fs_stats.

   get_load_stats
       Returns the load	average	over various span of times. The	object it
       returns is a Unix::Statgrab::sg_load_stats.

   get_mem_stats
       Returns statistics about	memory usage. The object it returns is a
       Unix::Statgrab::sg_mem_stats.

   get_swap_stats
       Returns statistics about	swap usage. The	object it returns is a
       Unix::Statgrab::sg_swap_stats.

   get_network_io_stats
       Returns statistics about	the network traffic per	network	interface as
       stored in the kernel. The object	it returns is a
       Unix::Statgrab::sg_network_io_stats.

   get_network_iface_stats
       Returns statistics about	each of	the found network interfaces in	your
       computer.  The object it	returns	is a
       Unix::Statgrab::sg_network_iface_stats.

   get_page_stats
       Returns the number of pages the system has paged	in and out since
       bootup.	The object it returns is a Unix::Statgrab::sg_page_stats.

   get_process_stats
       Returns loads of	information about the current processes.  The object
       it returns is a Unix::Statgrab::sg_process_stats.

   get_user_stats
       Returns session information about logged	on users.  The object it
       returns is a Unix::Statgrab::sg_user_stats.

ERROR HANDLING
       One function "get_error"	exists that will return	the last error
       encountered, if any. It's return	value is an object of type
       Unix::Statgrab::sg_error_details.

EXPORT
       All by default. This means all of the above functions plus the
       following constants:

	 SG_ERROR_NONE
	 SG_ERROR_INVALID_ARGUMENT
	 SG_ERROR_ASPRINTF
	 SG_ERROR_SPRINTF
	 SG_ERROR_DEVICES
	 SG_ERROR_DEVSTAT_GETDEVS
	 SG_ERROR_DEVSTAT_SELECTDEVS
	 SG_ERROR_DISKINFO
	 SG_ERROR_ENOENT
	 SG_ERROR_GETIFADDRS
	 SG_ERROR_GETMNTINFO
	 SG_ERROR_GETPAGESIZE
	 SG_ERROR_HOST
	 SG_ERROR_KSTAT_DATA_LOOKUP
	 SG_ERROR_KSTAT_LOOKUP
	 SG_ERROR_KSTAT_OPEN
	 SG_ERROR_KSTAT_READ
	 SG_ERROR_KVM_GETSWAPINFO
	 SG_ERROR_KVM_OPENFILES
	 SG_ERROR_MALLOC
	 SG_ERROR_MEMSTATUS
	 SG_ERROR_OPEN
	 SG_ERROR_OPENDIR
	 SG_ERROR_READDIR
	 SG_ERROR_PARSE
	 SG_ERROR_PDHADD
	 SG_ERROR_PDHCOLLECT
	 SG_ERROR_PDHOPEN
	 SG_ERROR_PDHREAD
	 SG_ERROR_PERMISSION
	 SG_ERROR_PSTAT
	 SG_ERROR_SETEGID
	 SG_ERROR_SETEUID
	 SG_ERROR_SETMNTENT
	 SG_ERROR_SOCKET
	 SG_ERROR_SWAPCTL
	 SG_ERROR_SYSCONF
	 SG_ERROR_SYSCTL
	 SG_ERROR_SYSCTLBYNAME
	 SG_ERROR_SYSCTLNAMETOMIB
	 SG_ERROR_SYSINFO
	 SG_ERROR_MACHCALL
	 SG_ERROR_IOKIT
	 SG_ERROR_UNAME
	 SG_ERROR_UNSUPPORTED
	 SG_ERROR_XSW_VER_MISMATCH
	 SG_ERROR_GETMSG
	 SG_ERROR_PUTMSG
	 SG_ERROR_INITIALISATION
	 SG_ERROR_MUTEX_LOCK
	 SG_ERROR_MUTEX_UNLOCK

	 sg_unknown_configuration
	 sg_physical_host
	 sg_virtual_machine
	 sg_paravirtual_machine
	 sg_hardware_virtualized

	 sg_fs_unknown
	 sg_fs_regular
	 sg_fs_special
	 sg_fs_loopback
	 sg_fs_remote
	 sg_fs_local
	 sg_fs_alltypes

	 SG_IFACE_DUPLEX_FULL
	 SG_IFACE_DUPLEX_HALF
	 SG_IFACE_DUPLEX_UNKNOWN

	 SG_IFACE_DOWN
	 SG_IFACE_UP

	 SG_PROCESS_STATE_RUNNING
	 SG_PROCESS_STATE_SLEEPING
	 SG_PROCESS_STATE_STOPPED
	 SG_PROCESS_STATE_ZOMBIE
	 SG_PROCESS_STATE_UNKNOWN

       If you don't want that, use the module thusly:

	   use Unix::Statgrab ();

       or provide a list of those symbols you want:

	   use Unix::Statgrab qw/get_network_iface_stats
				 SG_IFACE_DUPLEX_FULL
				 SG_IFACE_DUPLEX_HALF
				 SG_IFACE_DUPLEX_UNKNOWN/;

SEE ALSO
       The excellent and very complete manpage of statgrab(3). You can get
       additional information for each of the above functions by prefixing the
       function	name with "sg_"	and feed it to "man":

	   man sg_get_network_iface_stats

       libstatgrab's home is at	<http://www.i-scream.org/libstatgrab/>

SUPPORT
       You can find documentation for this module with the perldoc command.

	   perldoc Unix::Statgrab

       You can also look for information at:

       o   RT: CPAN's request tracker

	   <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Unix-Statgrab>

       o   AnnoCPAN: Annotated CPAN documentation

	   <http://annocpan.org/dist/Unix-Statgrab>

       o   CPAN	Ratings

	   <http://cpanratings.perl.org/s/Unix-Statgrab>

       o   CPAN	Search

	   <http://search.cpan.org/dist/Unix-Statgrab/>

   Where can I go for help?
       If you have a bug report, a patch or a suggestion, please open a	new
       report ticket at	CPAN (but please check previous	reports	first in case
       your issue has already been addressed). You can mail any	of the module
       maintainers, but	you are	more assured of	an answer by posting to	the
       i-scream-users list or reporting	the issue in RT.

       Report tickets should contain a detailed	description of the bug or
       enhancement request and at least	an easily verifiable way of
       reproducing the issue or	fix. Patches are always	welcome, too.

   Where can I go for help with	a concrete version?
       Bugs and	feature	requests are accepted against the latest version only.
       To get patches for earlier versions, you	need to	get an agreement with
       a developer of your choice - who	may or not report the issue and	a
       suggested fix upstream (depends on the license you have chosen).

   Business support and	maintenance
       For business support you	can contact Jens via his CPAN email address
       rehsackATcpan.org. Please keep in mind that business support is neither
       available for free nor are you eligible to receive any support based on
       the license distributed with this package.

AUTHOR
       Tassilo von Parseval, <tassilo.von.parseval@rwth-aachen.de>

       Jens Rehsack, <rehsack AT cpan.org>

COPYRIGHT AND LICENSE
       Copyright (C) 2004-2005 by Tassilo von Parseval

       Copyright (C) 2012-2018 by Jens Rehsack

       This library is free software; you can redistribute it and/or modify it
       under the terms of the GNU Lesser General Public	License	as published
       by the Free Software Foundation;	either version 2.1 of the License, or
       (at your	option)	any later version.

       The Perl/XS part	itself can be redistributed under the same terms as
       Perl itself.

       Note that - even	if LGPL	2.1+ doesn't force copyleft inherits on
       linking,	the re-use of API and header material requires at least	the
       documentation needs to be distributed under LGPL.

       In case your packaging system can split,	you can	distribute the code
       under Perl5 license and the documentation under LGPL 2.1+

perl v5.32.0			  2018-06-08		     Unix::Statgrab(3)

NAME | SYNOPSIS | DESCRIPTION | FUNCTIONS | ERROR HANDLING | EXPORT | SEE ALSO | SUPPORT | AUTHOR | COPYRIGHT AND LICENSE

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

home | help