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

FUNCTIONS

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

ERROR HANDLING

407       One function "get_error" exists that will return the error encountered
408       during the last operation, if any. Its return value is dual-typed. In
409       string context, it returns a text representation of the error. In
410       numeric context it returns one of the following values:
411
412           SG_ERROR_ASPRINTF
413           SG_ERROR_DEVSTAT_GETDEVS
414           SG_ERROR_DEVSTAT_SELECTDEVS
415           SG_ERROR_ENOENT
416           SG_ERROR_GETIFADDRS
417           SG_ERROR_GETMNTINFO
418           SG_ERROR_GETPAGESIZE
419           SG_ERROR_KSTAT_DATA_LOOKUP
420           SG_ERROR_KSTAT_LOOKUP
421           SG_ERROR_KSTAT_OPEN
422           SG_ERROR_KSTAT_READ
423           SG_ERROR_KVM_GETSWAPINFO
424           SG_ERROR_KVM_OPENFILES
425           SG_ERROR_MALLOC
426           SG_ERROR_NONE
427           SG_ERROR_OPEN
428           SG_ERROR_OPENDIR
429           SG_ERROR_PARSE
430           SG_ERROR_SETEGID
431           SG_ERROR_SETEUID
432           SG_ERROR_SETMNTENT
433           SG_ERROR_SOCKET
434           SG_ERROR_SWAPCTL
435           SG_ERROR_SYSCONF
436           SG_ERROR_SYSCTL
437           SG_ERROR_SYSCTLBYNAME
438           SG_ERROR_SYSCTLNAMETOMIB
439           SG_ERROR_UNAME
440           SG_ERROR_UNSUPPORTED
441           SG_ERROR_XSW_VER_MISMATCH
442
443       Based on the above, you have finer control over the error handling:
444
445           my $disks = get_disk_io_stats;
446
447           if (! $disks) {
448               if (get_error == SG_ERROR_PARSE) {
449                   ...
450               } else if (get_error == SG_ERROR_OPEN) {
451                   ...
452               }
453               etc.
454           }
455

EXPORT

457       All by default. This means all of the above functions plus the
458       following constants:
459
460         SG_ERROR_ASPRINTF
461         SG_ERROR_DEVSTAT_GETDEVS
462         SG_ERROR_DEVSTAT_SELECTDEVS
463         SG_ERROR_ENOENT
464         SG_ERROR_GETIFADDRS
465         SG_ERROR_GETMNTINFO
466         SG_ERROR_GETPAGESIZE
467         SG_ERROR_KSTAT_DATA_LOOKUP
468         SG_ERROR_KSTAT_LOOKUP
469         SG_ERROR_KSTAT_OPEN
470         SG_ERROR_KSTAT_READ
471         SG_ERROR_KVM_GETSWAPINFO
472         SG_ERROR_KVM_OPENFILES
473         SG_ERROR_MALLOC
474         SG_ERROR_NONE
475         SG_ERROR_OPEN
476         SG_ERROR_OPENDIR
477         SG_ERROR_PARSE
478         SG_ERROR_SETEGID
479         SG_ERROR_SETEUID
480         SG_ERROR_SETMNTENT
481         SG_ERROR_SOCKET
482         SG_ERROR_SWAPCTL
483         SG_ERROR_SYSCONF
484         SG_ERROR_SYSCTL
485         SG_ERROR_SYSCTLBYNAME
486         SG_ERROR_SYSCTLNAMETOMIB
487         SG_ERROR_UNAME
488         SG_ERROR_UNSUPPORTED
489         SG_ERROR_XSW_VER_MISMATCH
490         SG_IFACE_DUPLEX_FULL
491         SG_IFACE_DUPLEX_HALF
492         SG_IFACE_DUPLEX_UNKNOWN
493         SG_PROCESS_STATE_RUNNING
494         SG_PROCESS_STATE_SLEEPING
495         SG_PROCESS_STATE_STOPPED
496         SG_PROCESS_STATE_UNKNOWN
497         SG_PROCESS_STATE_ZOMBIE
498
499       If you don't want that, use the module thusly:
500
501           use Unix::Statgrab ();
502
503       or provide a list of those symbols you want:
504
505           use Unix::Statgrab qw/get_network_iface_stats
506                                 SG_IFACE_DUPLEX_FULL
507                                 SG_IFACE_DUPLEX_HALF
508                                 SG_IFACE_DUPLEX_UNKNOWN/;
509

AUTHOR

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

COPYRIGHT AND LICENSE

524       Copyright (C) 2004-2005 by Tassilo von Parseval
525
526       This library is free software; you can redistribute it and/or modify it
527       under the terms of the GNU Lesser General Public License as published
528       by the Free Software Foundation; either version 2.1 of the License, or
529       (at your option) any later version.
530
531
532
533perl v5.12.0                      2005-09-22                 Unix::Statgrab(3)