Unix::Statgrab(3pm)

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           local $, = "\n";
13
14           my $host = get_host_info or
15               die get_error;
16
17           print $host->os_name,
18                 $host->os_release,
19                 $host->os_version,
20                 ...;
21
22           my $disks = get_disk_io_stats or
23               die get_error;
24
25           for (0 .. $disks->num_disks - 1) {
26               print $disks->disk_name($_),
27                     $disks->read_bytes($_),
28                     ...;
29           }
30

DESCRIPTION

32       Unix::Statgrab is a wrapper for libstatgrab as available from
33       <http://www.i-scream.org/libstatgrab/>. It is a reasonably portable
34       attempt to query interesting stats about your computer. It covers
35       information on the operating system, CPU, memory usage, network inter‐
36       faces, hard-disks etc.
37
38       Each of the provided functions follow a simple rule: It never takes any
39       argument and returns either an object (in case of success) or "undef".
40       In case "undef" was returned, check the return value of "get_error".
41       Also see "ERROR HANDLING" further below.
42

FUNCTIONS

44       drop_privileges()
45
46       Unix::Statgrab can be told to discard setuid and setgid privileges
47       which is usually a good thing. If your program doesn't need the ele‐
48       vated privileges somewhere else, call it right after "use"ing the mod‐
49       ule.
50
51       get_host_info()
52
53       Returns generic information about this machine. The object it returns
54       supports the following methods:
55
56       * os_name
57       * os_release
58       * os_version
59       * platform
60       * hostname
61       * uptime
62
63       get_cpu_stats
64
65       Returns information about this machine's usage of the CPU. The object
66       it returns supports the following methods, all of which return the num‐
67       ber of ticks the processor has spent in the respective states:
68
69       * user
70       * kernel
71       * idle
72       * iowait
73       * swap
74       * nice
75       * total
76       * systime
77           The system time in seconds.
78
79       get_cpu_stats_diff
80
81       Returns the differences in ticks for each of the states since last time
82       "get_cpu_stats" or "get_cpu_stats_diff" was called.  If
83       "cpu_get_stats_diff" is called for the first time (and "get_cpu_stats"
84       wasn't called before) its return values will be the same as
85       "get_cpu_stats".
86
87       Its return value supports the same methods as "get_cpu_stats". "sys‐
88       time" then will be the seconds since the last call of this function.
89
90       get_cpu_percents
91
92       Calls "get_cpu_stats_diff" under the hood but instead of returning
93       ticks, it returns percentages. Its return value provides the same meth‐
94       ods as "get_cpu_stats" and "get_cpu_stats_diff".
95
96       get_disk_io_stats
97
98       Returns the disk IO per disk stored in the kernel which holds the
99       amount of data transferred since bootup. Unlike most other methods pre‐
100       sented in this manpage, the methods you can call on its return value
101       take an additional optional parameter which specifies which disk you
102       want information about. If you do not provide this parameter, 0 (=
103       first disk) is assumed.
104
105       * num_disks
106           The number of disks that were found on this machine.
107
108       * disk_name($disk)
109       * read_bytes($disk)
110       * write_bytes($disk)
111       * systime($disk)
112           The system time in seconds over which "read_bytes" and
113           "write_bytes" were transferred.
114
115       get_disk_io_stats_diff
116
117       The same as "get_disk_io_stats" except that it will report the differ‐
118       ence to the last call of either "get_disk_io_stats" or
119       "get_disk_io_stats_diff". Provides the same methods as
120       "get_disk_io_stats".
121
122       get_fs_stats
123
124       Returns statistics about the mounted filesystems, including free space
125       and inode usage. The provided methods again take one optional argument
126       which specifies which partition you want information about. If you do
127       not provide this parameter, 0 (= first mounted filesystem) is assumed:
128
129       * num_fs
130           The number of mounted filesystems that were found on this machine.
131
132       * device_name($fs)
133       * fs_type($fs)
134       * mnt_point($fs)
135       * size($fs)
136           Size in bytes.
137
138       * used($fs)
139       * avail($fs)
140       * total_inodes($fs)
141       * used_inodes($fs)
142       * free_inodes($fs)
143       * avail_inodes($fs)
144       * io_size($fs)
145           The recommended size in bytes when doing I/O operations on this
146           device.
147
148       * block_size($fs)
149       * total_blocks($fs)
150       * free_blocks($fs)
151       * used_blocks($fs)
152       * avail_blocks($fs)
153
154       get_load_stats()
155
156       Returns the load average over various span of times. The following
157       methods are provided:
158
159       * min1
160           Load average over 1 minute.
161
162       * min5
163       * min15
164
165       get_mem_stats()
166
167       Returns statistics about memory usage. The following methods exist:
168
169       * total
170           Total memory in bytes.
171
172       * free
173       * used
174       * cache
175           Amount of cache used in bytes.
176
177       get_swap_stats()
178
179       Returns statistics about swap usage. The following methods exist:
180
181       * total
182           Total swap memory in bytes.
183
184       * used
185       * free
186
187       get_network_io_stats()
188
189       Returns statistics about the network traffic per network interface as
190       stored in the kernel. Again, the provided methods support one optional
191       parameter specifiying which network interface to query. If the parame‐
192       ter is missing, 0 (= first interface) is assumed.
193
194       * num_ifaces
195           The number of network interfaces found on your machine.
196
197       * interface_name($if)
198       * tx($if)
199           The number of bytes transmitted.
200
201       * rx($if)
202           The number of bytes received.
203
204       * ipackets($if)
205           The number of packets received.
206
207       * opackets($if)
208           The number of bytes transmitted.
209
210       * ierrors($if)
211           The number of receive errors
212
213       * oerrors($if)
214           The number of transmit errors
215
216       * collisions($if)
217       * systime
218           The time period over which "tx" and "rx" were transferred.
219
220       get_network_io_stats_diff()
221
222       The same as "get_network_io_stats" except that it will report on the
223       difference to the last time "get_network_io_stats" or "get_net‐
224       work_io_stats_diff" was called. It supports the same methods as
225       "get_network_io_stats".
226
227       get_network_iface_stats()
228
229       Returns statistics about each of the found network interfaces in your
230       computer. The provided methods take one optional argument being the
231       interface to query. If this parameter is missing, 0 (= first interface)
232       is assumed.
233
234       * num_ifaces
235           The number of interfaces found.
236
237       * interface_name($if)
238       * speed($if)
239           The speed of the interface, in megabits/sec
240
241       * dup($if)
242           One of "SG_IFACE_DUPLEX_FULL", "SG_IFACE_DUPLEX_HALF" and
243           "SG_IFACE_DUPLEX_UNKNOWN". Unknown could mean that duplex hasn't
244           been negotiated yet.
245
246       * up($if)
247           Whether the interface is up.
248
249       get_page_stats()
250
251       Returns the number of pages the system has paged in  and  out since
252       bootup. It supports the following methods:
253
254       * pages_pagein
255       * pages_pageout
256       * systime
257           The time period over which pages_pagein and pages_pageout were
258           transferred, in seconds.
259
260       get_page_stats_diff()
261
262       The same as "get_page_stats" except that it will report the difference
263       to the last time "get_page_stats" or "get_page_stats_diff" was called.
264       Supports the same methods as "get_page_stats".
265
266       get_user_stats()
267
268       Returns information about the currently logged in users. It supports
269       the following methods:
270
271       * num_entries
272           The number of currently logged in users.
273
274       * name_list
275           A list of the users currently logged in.
276
277       get_process_stats()
278
279       Returns loads of information about the current processes. This function
280       only returns a container. If you want to look at the processes
281       returned, call "all_procs" on its return value.
282
283       The processes can also be sorted by various criteria by using the
284       "sort_by" method. This will change the internal order of the container.
285       This method returns the container object so you can do some method
286       chaining:
287
288           my $procs = get_process_stats;
289           $procs->sort_by("name");
290           print $_->proc_name, "\n" foreach $procs->all_procs;
291
292           # syntactically sweeter
293
294           print $_->proc_name, "\n"
295               foreach get_process_stats->sort_by("name")->all_procs;
296
297       Available sorting methods are "name", "pid", "uid", "gid", "size",
298       "res", "cpu" and "time".
299
300       You can also sort the list returned by "all_procs". For that you can
301       use one of the eight sorting routines thusly:
302
303           my $p = get_process_stats;
304
305           my @by_name = sort sort_procs_by_name $p->all_procs;
306           my @by_pid  = sort sort_procs_by_pid  $p->all_procs;
307           my @by_uid  = sort sort_procs_by_uid  $p->all_procs;
308           # etc.
309
310       Each object returned by "all_procs" supports the following methods:
311
312       * proc_name
313       * proc_title
314           The full command line with which the process was started.
315
316       * pid
317       * parent_pid
318       * pgid
319           Process ID of process group leader.
320
321       * uid
322       * euid
323           Effective user ID.
324
325       * gid
326       * egid
327           Effective group ID.
328
329       * proc_size
330           In bytes.
331
332       * proc_resident
333           In bytes.
334
335       * time_spent
336           Time running in seconds.
337
338       * cpu_percent
339       * nice
340       * state
341           One of "SG_PROCESS_STATE_RUNNING", "SG_PROCESS_STATE_SLEEPING",
342           "SG_PROCESS_STATE_STOPPED", "SG_PROCESS_STATE_ZOMBIE" and
343           "SG_PROCESS_STATE_UNKNOWN".
344

ERROR HANDLING

346       One function "get_error" exists that will return the error encountered
347       during the last operation, if any. Its return value is dual-typed. In
348       string context, it returns a text representation of the error. In
349       numeric context it returns one of the following values:
350
351           SG_ERROR_ASPRINTF
352           SG_ERROR_DEVSTAT_GETDEVS
353           SG_ERROR_DEVSTAT_SELECTDEVS
354           SG_ERROR_ENOENT
355           SG_ERROR_GETIFADDRS
356           SG_ERROR_GETMNTINFO
357           SG_ERROR_GETPAGESIZE
358           SG_ERROR_KSTAT_DATA_LOOKUP
359           SG_ERROR_KSTAT_LOOKUP
360           SG_ERROR_KSTAT_OPEN
361           SG_ERROR_KSTAT_READ
362           SG_ERROR_KVM_GETSWAPINFO
363           SG_ERROR_KVM_OPENFILES
364           SG_ERROR_MALLOC
365           SG_ERROR_NONE
366           SG_ERROR_OPEN
367           SG_ERROR_OPENDIR
368           SG_ERROR_PARSE
369           SG_ERROR_SETEGID
370           SG_ERROR_SETEUID
371           SG_ERROR_SETMNTENT
372           SG_ERROR_SOCKET
373           SG_ERROR_SWAPCTL
374           SG_ERROR_SYSCONF
375           SG_ERROR_SYSCTL
376           SG_ERROR_SYSCTLBYNAME
377           SG_ERROR_SYSCTLNAMETOMIB
378           SG_ERROR_UNAME
379           SG_ERROR_UNSUPPORTED
380           SG_ERROR_XSW_VER_MISMATCH
381
382       Based on the above, you have finer control over the error handling:
383
384           my $disks = get_disk_io_stats;
385
386           if (! $disks) {
387               if (get_error == SG_ERROR_PARSE) {
388                   ...
389               } else if (get_error == SG_ERROR_OPEN) {
390                   ...
391               }
392               etc.
393           }
394

EXPORT

396       All by default. This means all of the above functions plus the follow‐
397       ing constants:
398
399         SG_ERROR_ASPRINTF
400         SG_ERROR_DEVSTAT_GETDEVS
401         SG_ERROR_DEVSTAT_SELECTDEVS
402         SG_ERROR_ENOENT
403         SG_ERROR_GETIFADDRS
404         SG_ERROR_GETMNTINFO
405         SG_ERROR_GETPAGESIZE
406         SG_ERROR_KSTAT_DATA_LOOKUP
407         SG_ERROR_KSTAT_LOOKUP
408         SG_ERROR_KSTAT_OPEN
409         SG_ERROR_KSTAT_READ
410         SG_ERROR_KVM_GETSWAPINFO
411         SG_ERROR_KVM_OPENFILES
412         SG_ERROR_MALLOC
413         SG_ERROR_NONE
414         SG_ERROR_OPEN
415         SG_ERROR_OPENDIR
416         SG_ERROR_PARSE
417         SG_ERROR_SETEGID
418         SG_ERROR_SETEUID
419         SG_ERROR_SETMNTENT
420         SG_ERROR_SOCKET
421         SG_ERROR_SWAPCTL
422         SG_ERROR_SYSCONF
423         SG_ERROR_SYSCTL
424         SG_ERROR_SYSCTLBYNAME
425         SG_ERROR_SYSCTLNAMETOMIB
426         SG_ERROR_UNAME
427         SG_ERROR_UNSUPPORTED
428         SG_ERROR_XSW_VER_MISMATCH
429         SG_IFACE_DUPLEX_FULL
430         SG_IFACE_DUPLEX_HALF
431         SG_IFACE_DUPLEX_UNKNOWN
432         SG_PROCESS_STATE_RUNNING
433         SG_PROCESS_STATE_SLEEPING
434         SG_PROCESS_STATE_STOPPED
435         SG_PROCESS_STATE_UNKNOWN
436         SG_PROCESS_STATE_ZOMBIE
437
438       If you don't want that, use the module thusly:
439
440           use Unix::Statgrab ();
441
442       or provide a list of those symbols you want:
443
444           use Unix::Statgrab qw/get_network_iface_stats
445                                 SG_IFACE_DUPLEX_FULL
446                                 SG_IFACE_DUPLEX_HALF
447                                 SG_IFACE_DUPLEX_UNKNOWN/;
448

AUTHOR

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

COPYRIGHT AND LICENSE

462       Copyright (C) 2004-2005 by Tassilo von Parseval
463
464       This library is free software; you can redistribute it and/or modify it
465       under the terms of the GNU Lesser General Public License as published
466       by the Free Software Foundation; either version 2.1 of the License, or
467       (at your option) any later version.
468
469
470
471perl v5.8.8                       2005-09-22                 Unix::Statgrab(3)