1Unix::Statgrab(3)     User Contributed Perl Documentation    Unix::Statgrab(3)
2
3
4

NAME

6       Unix::Statgrab - Perl extension for collecting information about the
7       machine
8

SYNOPSIS

10           use Unix::Statgrab;
11
12           my $host_stats = get_host_info();
13           print $host_stats->hostname . " is a " . $host_stats->bitwidth . " " . $host_stats->os_name . "\n";
14
15           my $filesystems = get_fs_stats();
16           my @mount_points = map { $filesystems->mnt_point($_) } (0 .. $filesystems->entries() - 1);
17           print $host_stats->hostname . " has " . join( ", ", @mount_points ) . " mounted\n";
18
19           my $proc_list = get_process_stats();
20           my @proc_by_type;
21           foreach my $proc_entry (0 .. $proc_list->entries() - 1) {
22               $proc_by_type[$proc_list->state($proc_entry)]++;
23           }
24           my $total_procs = 0;
25           $total_procs += $_ for grep { defined $_ } @proc_by_type;
26           foreach my $state (qw(SG_PROCESS_STATE_RUNNING SG_PROCESS_STATE_SLEEPING
27                                 SG_PROCESS_STATE_STOPPED SG_PROCESS_STATE_ZOMBIE
28                                                 SG_PROCESS_STATE_UNKNOWN)) {
29               defined $proc_by_type[Unix::Statgrab->$state] or next;
30               print $proc_by_type[Unix::Statgrab->$state] . " of " . $total_procs . " procs in $state\n";
31           }
32
33           my $last_cpu_stats = get_cpu_stats() or croak( get_error()->strperror() );
34           do_sth_way_longer();
35           my $cpu_diff = get_cpu_stats()->get_cpu_stats_diff($last_cpu_stats);
36
37           my $last_cpu_percent = $last_cpu_percent->get_cpu_percents();
38           my $diff_cpu_percent = $cpu_diff->get_cpu_percents();
39           my $now_cpu_percent = get_cpu_stats()->get_cpu_percents();
40

DESCRIPTION

42       Unix::Statgrab is a wrapper for libstatgrab as available from
43       <http://www.i-scream.org/libstatgrab/>. It is a reasonably portable
44       attempt to query interesting stats about your computer. It covers
45       information on the operating system, CPU, memory usage, network
46       interfaces, hard-disks etc.
47
48       Each of the provided functions follow a simple rule: It never takes any
49       argument and returns either an object (in case of success) or "undef".
50       In case "undef" was returned, check the return value of "get_error".
51       Also see "ERROR HANDLING" further below.
52
53       To avoid error during copying documentation, the original function
54       documentation will be refererred where reasonable. Each returned object
55       has a getter method named as the attribute in original documentation.
56       Those getters take a optional index argument, asking for the attribute
57       of the "n"th statistic item. Further, each object provides an
58       "entries"() method, telling you how much statistics for requested type
59       are returned (yes, even "get_host_info()" has that, maybe we have more
60       host_info when grabbing that statistic in a cluster, grid or cloud).
61       Additionally, for the users of Perl's list processing features, each
62       object has an "as_list"() method which returns the statistic as list of
63       hash items containing each attribute / value pair of available
64       attributes.
65

FUNCTIONS

67   drop_privileges()
68       Unix::Statgrab can be told to discard setuid and setgid privileges
69       which is usually a good thing. If your program doesn't need the
70       elevated privileges somewhere else, call it right after "use"ing the
71       module.
72
73       This function is depreciated and might be removed in a future version
74       of libstatgrab (and then in Unix::Statgrab, too).
75
76   get_host_info()
77       Returns generic information about this machine. The object it returns
78       is a Unix::Statgrab::sg_host_info.
79
80   get_cpu_stats
81       Returns information about this machine's usage of the CPU. The object
82       it returns is an Unix::Statgrab::sg_cpu_stats.
83
84   get_disk_io_stats
85       Delivers the disk IO per disk stored in the kernel which holds the
86       amount of data transferred since boot. The object it returns is a
87       Unix::Statgrab::sg_disk_io_stats.
88
89   get_fs_stats
90       Returns statistics about the mounted filesystems. The object it returns
91       is a Unix::Statgrab::sg_fs_stats.
92
93   get_load_stats
94       Returns the load average over various span of times. The object it
95       returns is a Unix::Statgrab::sg_load_stats.
96
97   get_mem_stats
98       Returns statistics about memory usage. The object it returns is a
99       Unix::Statgrab::sg_mem_stats.
100
101   get_swap_stats
102       Returns statistics about swap usage. The object it returns is a
103       Unix::Statgrab::sg_swap_stats.
104
105   get_network_io_stats
106       Returns statistics about the network traffic per network interface as
107       stored in the kernel. The object it returns is a
108       Unix::Statgrab::sg_network_io_stats.
109
110   get_network_iface_stats
111       Returns statistics about each of the found network interfaces in your
112       computer.  The object it returns is a
113       Unix::Statgrab::sg_network_iface_stats.
114
115   get_page_stats
116       Returns the number of pages the system has paged in and out since
117       bootup.  The object it returns is a Unix::Statgrab::sg_page_stats.
118
119   get_process_stats
120       Returns loads of information about the current processes.  The object
121       it returns is a Unix::Statgrab::sg_process_stats.
122
123   get_user_stats
124       Returns session information about logged on users.  The object it
125       returns is a Unix::Statgrab::sg_user_stats.
126

ERROR HANDLING

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

EXPORT

133       All by default. This means all of the above functions plus the
134       following constants:
135
136         SG_ERROR_NONE
137         SG_ERROR_INVALID_ARGUMENT
138         SG_ERROR_ASPRINTF
139         SG_ERROR_SPRINTF
140         SG_ERROR_DEVICES
141         SG_ERROR_DEVSTAT_GETDEVS
142         SG_ERROR_DEVSTAT_SELECTDEVS
143         SG_ERROR_DISKINFO
144         SG_ERROR_ENOENT
145         SG_ERROR_GETIFADDRS
146         SG_ERROR_GETMNTINFO
147         SG_ERROR_GETPAGESIZE
148         SG_ERROR_HOST
149         SG_ERROR_KSTAT_DATA_LOOKUP
150         SG_ERROR_KSTAT_LOOKUP
151         SG_ERROR_KSTAT_OPEN
152         SG_ERROR_KSTAT_READ
153         SG_ERROR_KVM_GETSWAPINFO
154         SG_ERROR_KVM_OPENFILES
155         SG_ERROR_MALLOC
156         SG_ERROR_MEMSTATUS
157         SG_ERROR_OPEN
158         SG_ERROR_OPENDIR
159         SG_ERROR_READDIR
160         SG_ERROR_PARSE
161         SG_ERROR_PDHADD
162         SG_ERROR_PDHCOLLECT
163         SG_ERROR_PDHOPEN
164         SG_ERROR_PDHREAD
165         SG_ERROR_PERMISSION
166         SG_ERROR_PSTAT
167         SG_ERROR_SETEGID
168         SG_ERROR_SETEUID
169         SG_ERROR_SETMNTENT
170         SG_ERROR_SOCKET
171         SG_ERROR_SWAPCTL
172         SG_ERROR_SYSCONF
173         SG_ERROR_SYSCTL
174         SG_ERROR_SYSCTLBYNAME
175         SG_ERROR_SYSCTLNAMETOMIB
176         SG_ERROR_SYSINFO
177         SG_ERROR_MACHCALL
178         SG_ERROR_IOKIT
179         SG_ERROR_UNAME
180         SG_ERROR_UNSUPPORTED
181         SG_ERROR_XSW_VER_MISMATCH
182         SG_ERROR_GETMSG
183         SG_ERROR_PUTMSG
184         SG_ERROR_INITIALISATION
185         SG_ERROR_MUTEX_LOCK
186         SG_ERROR_MUTEX_UNLOCK
187
188         sg_unknown_configuration
189         sg_physical_host
190         sg_virtual_machine
191         sg_paravirtual_machine
192         sg_hardware_virtualized
193
194         sg_fs_unknown
195         sg_fs_regular
196         sg_fs_special
197         sg_fs_loopback
198         sg_fs_remote
199         sg_fs_local
200         sg_fs_alltypes
201
202         SG_IFACE_DUPLEX_FULL
203         SG_IFACE_DUPLEX_HALF
204         SG_IFACE_DUPLEX_UNKNOWN
205
206         SG_IFACE_DOWN
207         SG_IFACE_UP
208
209         SG_PROCESS_STATE_RUNNING
210         SG_PROCESS_STATE_SLEEPING
211         SG_PROCESS_STATE_STOPPED
212         SG_PROCESS_STATE_ZOMBIE
213         SG_PROCESS_STATE_UNKNOWN
214
215       If you don't want that, use the module thusly:
216
217           use Unix::Statgrab ();
218
219       or provide a list of those symbols you want:
220
221           use Unix::Statgrab qw/get_network_iface_stats
222                                 SG_IFACE_DUPLEX_FULL
223                                 SG_IFACE_DUPLEX_HALF
224                                 SG_IFACE_DUPLEX_UNKNOWN/;
225

SEE ALSO

227       The excellent and very complete manpage of statgrab(3). You can get
228       additional information for each of the above functions by prefixing the
229       function name with "sg_" and feed it to "man":
230
231           man sg_get_network_iface_stats
232
233       libstatgrab's home is at <http://www.i-scream.org/libstatgrab/>
234

SUPPORT

236       You can find documentation for this module with the perldoc command.
237
238           perldoc Unix::Statgrab
239
240       You can also look for information at:
241
242       •   RT: CPAN's request tracker
243
244           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Unix-Statgrab>
245
246       •   AnnoCPAN: Annotated CPAN documentation
247
248           <http://annocpan.org/dist/Unix-Statgrab>
249
250       •   CPAN Ratings
251
252           <http://cpanratings.perl.org/s/Unix-Statgrab>
253
254       •   CPAN Search
255
256           <http://search.cpan.org/dist/Unix-Statgrab/>
257
258   Where can I go for help?
259       If you have a bug report, a patch or a suggestion, please open a new
260       report ticket at CPAN (but please check previous reports first in case
261       your issue has already been addressed). You can mail any of the module
262       maintainers, but you are more assured of an answer by posting to the
263       i-scream-users list or reporting the issue in RT.
264
265       Report tickets should contain a detailed description of the bug or
266       enhancement request and at least an easily verifiable way of
267       reproducing the issue or fix. Patches are always welcome, too.
268
269   Where can I go for help with a concrete version?
270       Bugs and feature requests are accepted against the latest version only.
271       To get patches for earlier versions, you need to get an agreement with
272       a developer of your choice - who may or not report the issue and a
273       suggested fix upstream (depends on the license you have chosen).
274
275   Business support and maintenance
276       For business support you can contact Jens via his CPAN email address
277       rehsackATcpan.org. Please keep in mind that business support is neither
278       available for free nor are you eligible to receive any support based on
279       the license distributed with this package.
280

AUTHOR

282       Tassilo von Parseval, <tassilo.von.parseval@rwth-aachen.de>
283
284       Jens Rehsack, <rehsack AT cpan.org>
285
287       Copyright (C) 2004-2005 by Tassilo von Parseval
288
289       Copyright (C) 2012-2018 by Jens Rehsack
290
291       This library is free software; you can redistribute it and/or modify it
292       under the terms of the GNU Lesser General Public License as published
293       by the Free Software Foundation; either version 2.1 of the License, or
294       (at your option) any later version.
295
296       The Perl/XS part itself can be redistributed under the same terms as
297       Perl itself.
298
299       Note that - even if LGPL 2.1+ doesn't force copyleft inherits on
300       linking, the re-use of API and header material requires at least the
301       documentation needs to be distributed under LGPL.
302
303       In case your packaging system can split, you can distribute the code
304       under Perl5 license and the documentation under LGPL 2.1+
305
306
307
308perl v5.36.0                      2022-07-22                 Unix::Statgrab(3)
Impressum