/ 
BSD-Sysctl-0.01
River stage one • 1 direct dependent • 1 total dependent
/ BSD::Sysctl

NAME

BSD::Sysctl - Fetch sysctl values from BSD-like systems

VERSION

This document describes version 0.01 of BSD::Sysctl, release 2006-07-22.

SYNOPSIS

use BSD::Sysctl 'sysctl';

# exact values will vary
print sysctl('kern.lastpid'); # 20621

my $loadavg = sysctl('vm.loadavg');
print $loadavg->[1]; # 0.1279 (5 minute load average)

my $vm = sysctl('vm.vmtotal');
print "number of free pages: $vm->{pagefree}\n";

DESCRIPTION

Note: this is an alpha release.

BSD::Sysctl offers a native Perl interface for fetching sysctl values that describe the kernel state of BSD-like operating systems. This is around 80 times faster than scraping the output of the sysctl(8) program.

This module handles the conversion of symbolic sysctl variable names to the internal numeric format, and this information, along with the details of how to format the results, are cached. Hence, the first call to sysctl requires three system calls, however, subsequent calls require only one call.

ROUTINES

sysctl

Perform a sysctl system call. Takes the symbolic name of a sysctl variable name, for instance kern.maxfilesperproc, net.inet.ip.ttl. In most circumstances, a scalar is returned (in the event that the variable has a single value).

In some circumstances a reference to an array is returned, when the variable represents a list of values (for instance, kern.cp_time).

In other circumstances, a reference to a hash is returned, when the variable represents a heterogeneous collection of values (for instance, kern.clockrate, vm.vmtotal). In these cases, the hash key names are reasonably self-explanatory, however, passing familiarity with kernel data structures is expected.

A certain number of opaque variables are fully decoded (and the results are returned as hashes), whereas the sysctl binary renders them as a raw hexdump (for example, net.inet.tcp.stats).

sysctl_set

Perform a sysctl system call to set a sysctl variable to a new value. This requires root privileges. NOT YET IMPLEMENTED.

sysctl_exists

Check whether the variable name exists. Returns true or false depending on whether the name is recognised by the system.

Checking whether a variable exists does not perform the conversion to the numeric OID (and the attendant caching).

DIAGNOSTICS

"uncached mib: [sysctl name]"

A sysctl variable name was passed to the internal function _mib_lookup, but _mib_lookup doesn't now how to deal with it, since _mib_info has not been called for this variable name. This is normally impossible if you stick to the public functions.

"get sysctl [sysctl name] failed"

The kernel system call to get the value associated with a sysctl variable failed. If sysctl ... from the command line succeeds (that is, using the sysctl(8) program), this is a bug that should be reported.

"[sysctl name] unhandled format type=[number]"

The sysctl call returned a variable that we don't know how to format, at least for the time being. This is a bug that should be reported.

LIMITATIONS

At the current time, only FreeBSD versions 4.x through 6.x are supported.

Setting sysctl values is currently not supported. This functionality will be developed in subsequent versions.

I am looking for volunteers to help port this module to NetBSD and OpenBSD (or access to such machines), and possibly even Solaris. If you are interested in helping, please consult the README file for more information.

BUGS

This is my first XS module. I may be doing wild and dangerous things and not realise it. Gentle nudges in the right direction will be gratefully received.

Some sysctl values cannot be fetched, even though the sysctl program can (as it uses an undocumented approach). This functionality may be added in the future.

Other sysctl values cannot be displayed, since they appear to be pointers, and dump core when dereferenced. In this case, a result of -1 is returned. Most values of this type occur in the dev. hierarchy.

Some sysctl values are 64-bit quantities. I am not all sure that these are handled correctly.

Please report all bugs at http://rt.cpan.org/NoAuth/Bugs.html?Dist=BSD-Sysctl|rt.cpan.org.

A short snippet demonstrating the problem, along with the expected and actual output, and the version of BSD::Sysctl used, will be appreciated.

AUTHOR

David Landgren.

Copyright (C) 2006, all rights reserved.

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.