lib/Linux/SysInfo.pm

   1 package Linux::SysInfo;
   2
   3 use strict;
   4 use warnings;
   5
   6 =head1 NAME
   7
   8 Linux::SysInfo - Perl interface to the sysinfo(2) Linux system call.
   9
  10 =head1 VERSION
  11
  12 Version 0.13
  13
  14 =cut
  15
  16 our $VERSION;
  17 BEGIN {
  18  $VERSION = '0.13';
  19 }
  20
  21 =head1 SYNOPSIS
  22
  23     use Linux::SysInfo qw/sysinfo/;
  24
  25     my $si = sysinfo;
  26     print "$_: $si->{$_}\n" for keys %$si;
  27
  28 =head1 DESCRIPTION
  29
  30 This module is a wrapper around the C<sysinfo(2)> Linux system call.
  31 It gives information about the current uptime, load average, memory usage and processes running.
  32 Other systems have also this system call (e.g. Solaris), but in most cases the returned information is different.
  33
  34 =head1 CONSTANTS
  35
  36 =head2 C<LS_HAS_EXTENDED>
  37
  38 This constant is set to C<1> if your kernel supports the three extended fields C<totalhigh>, C<freehigh> and C<mem_unit> ; and to C<0> otherwise.
  39
  40 =head1 FUNCTIONS
  41
  42 =cut
  43
  44 BEGIN {
  45  require XSLoader;
  46  XSLoader::load(__PACKAGE__, $VERSION);
  47 }
  48
  49 =head2 C<sysinfo>
  50
  51 This function takes no argument.
  52 It returns C<undef> on failure or a hash reference whose keys are the members name of the C<struct sysinfo> on success :
  53
  54 =over 4
  55
  56 =item *
  57
  58 C<uptime>
  59
  60 Seconds elapsed since the system booted.
  61
  62 =item *
  63
  64 C<load1>, C<load5>, C<load15>
  65
  66 1, 5 and 15 minutes load average.
  67
  68 =item *
  69
  70 C<totalram>
  71
  72 Total usable main memory size.
  73
  74 =item *
  75
  76 C<freeram>
  77
  78 Available memory size.
  79
  80 =item *
  81
  82 C<sharedram>
  83
  84 Amount of shared memory.
  85
  86 =item *
  87
  88 C<bufferram>
  89
  90 Memory used by buffers.
  91
  92 =item *
  93
  94 C<totalswap>
  95
  96 Total swap space size.
  97
  98 =item *
  99
 100 C<freeswap>
 101
 102 Swap space still available.
 103
 104 =item *
 105
 106 C<procs>
 107
 108 Number of current processes.
 109
 110 =back
 111
 112 Prior to Linux 2.3.23 on i386 and 2.3.48 on all other architectures, the memory sizes were given in bytes.
 113 Since then, the following members are also available and all the memory sizes are given as multiples of C<mem_unit> bytes :
 114
 115 =over 4
 116
 117 =item *
 118
 119 C<totalhigh>
 120
 121 Total high memory size.
 122
 123 =item *
 124
 125 C<freehigh>
 126
 127 Available high memory size.
 128
 129 =item *
 130
 131 C<mem_unit>
 132
 133 Memory unit size in bytes.
 134
 135 =back
 136
 137 =head1 EXPORT
 138
 139 The only function of this module, C<sysinfo>, and the constant C<LS_HAS_EXTENDED> are only exported on request.
 140 Functions are also exported by the C<:funcs> tag, and constants by C<:consts>.
 141
 142 =cut
 143
 144 use base qw/Exporter/;
 145
 146 our @EXPORT         = ();
 147 our %EXPORT_TAGS    = (
 148  'funcs'  => [ qw/sysinfo/ ],
 149  'consts' => [ qw/LS_HAS_EXTENDED/ ]
 150 );
 151 our @EXPORT_OK      = map { @$_ } values %EXPORT_TAGS;
 152 $EXPORT_TAGS{'all'} = [ @EXPORT_OK ];
 153
 154 =head1 BINARY COMPATIBILITY
 155
 156 If you upgrade your kernel to a greater version than 2.3.23 on i386 or 2.3.48 on any other platform, you will need to rebuild the module to access the extended fields.
 157
 158 Moreover, since the perl hash function has changed after the 5.6 version, you will also need to recompile the module if you upgrade your perl from a version earlier than 5.6.
 159
 160 =head1 DEPENDENCIES
 161
 162 L<perl> 5.6.
 163
 164 =head1 SEE ALSO
 165
 166 The C<sysinfo(2)> man page.
 167
 168 L<Sys::Info> : Gather information about your system.
 169
 170 L<Sys::CpuLoad> : Try several different methods to retrieve the load average.
 171
 172 L<BSD::getloadavg> : Wrapper to the C<getloadavg(3)> BSD system call.
 173
 174 =head1 AUTHOR
 175
 176 Vincent Pit, C<< <perl at profvince.com> >>, L<http://www.profvince.com>.
 177
 178 You can contact me by mail or on C<irc.perl.org> (vincent).
 179
 180 =head1 BUGS
 181
 182 Please report any bugs or feature requests to C<bug-linux-sysinfo at rt.cpan.org>, or through the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Linux-SysInfo>.
 183 I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
 184
 185 =head1 SUPPORT
 186
 187 You can find documentation for this module with the perldoc command.
 188
 189     perldoc Linux::SysInfo
 190
 191 Tests code coverage report is available at L<http://www.profvince.com/perl/cover/Linux-SysInfo>.
 192
 193 =head1 COPYRIGHT & LICENSE
 194
 195 Copyright 2007,2008,2009,2010 Vincent Pit, all rights reserved.
 196
 197 This program is free software; you can redistribute it and/or modify it
 198 under the same terms as Perl itself.
 199
 200 =cut
 201
 202 1; # End of Linux::SysInfo