1Unix::Statgrab(3) User Contributed Perl Documentation Unix::Statgrab(3)
2
6 Unix::Statgrab - Perl extension for collecting information about the
7 machine
8
10 use Unix::Statgrab;
11 my $host_stats = get_host_info();
13 print $host_stats->hostname . " is a " . $host_stats->bitwidth . " " . $host_stats->os_name . "\n";
14 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 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 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 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
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 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 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
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 This function is depreciated and might be removed in a future version
74 of libstatgrab (and then in Unix::Statgrab, too).
75 get_host_info()
77 Returns generic information about this machine. The object it returns
78 is a Unix::Statgrab::sg_host_info.
79 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 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 get_fs_stats
90 Returns statistics about the mounted filesystems. The object it returns
91 is a Unix::Statgrab::sg_fs_stats.
92 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 get_mem_stats
98 Returns statistics about memory usage. The object it returns is a
99 Unix::Statgrab::sg_mem_stats.
100 get_swap_stats
102 Returns statistics about swap usage. The object it returns is a
103 Unix::Statgrab::sg_swap_stats.
104 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 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 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 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 get_user_stats
124 Returns session information about logged on users. The object it
125 returns is a Unix::Statgrab::sg_user_stats.
126
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
133 All by default. This means all of the above functions plus the
134 following constants:
135 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 sg_unknown_configuration
189 sg_physical_host
190 sg_virtual_machine
191 sg_paravirtual_machine
192 sg_hardware_virtualized
193 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 SG_IFACE_DUPLEX_FULL
203 SG_IFACE_DUPLEX_HALF
204 SG_IFACE_DUPLEX_UNKNOWN
205 SG_IFACE_DOWN
207 SG_IFACE_UP
208 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 If you don't want that, use the module thusly:
216 use Unix::Statgrab ();
218 or provide a list of those symbols you want:
220 use Unix::Statgrab qw/get_network_iface_stats
222 SG_IFACE_DUPLEX_FULL
223 SG_IFACE_DUPLEX_HALF
224 SG_IFACE_DUPLEX_UNKNOWN/;
225
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 man sg_get_network_iface_stats
232 libstatgrab's home is at <http://www.i-scream.org/libstatgrab/>
234
236 You can find documentation for this module with the perldoc command.
237 perldoc Unix::Statgrab
239 You can also look for information at:
241 • RT: CPAN's request tracker
243 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Unix-Statgrab>
245 • AnnoCPAN: Annotated CPAN documentation
247 <http://annocpan.org/dist/Unix-Statgrab>
249 • CPAN Ratings
251 <http://cpanratings.perl.org/s/Unix-Statgrab>
253 • CPAN Search
255 <http://search.cpan.org/dist/Unix-Statgrab/>
257 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 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 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 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
282 Tassilo von Parseval, <tassilo.von.parseval@rwth-aachen.de>
283 Jens Rehsack, <rehsack AT cpan.org>
285
287 Copyright (C) 2004-2005 by Tassilo von Parseval
288 Copyright (C) 2012-2018 by Jens Rehsack
290 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 The Perl/XS part itself can be redistributed under the same terms as
297 Perl itself.
298 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 In case your packaging system can split, you can distribute the code
304 under Perl5 license and the documentation under LGPL 2.1+
305perl v5.36.0 2022-07-22 Unix::Statgrab(3)