lib/Linux/SysInfo.pm

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