Net::Hesiod - Perl interface to Hesiod Library API

Net-Hesiod documentation Contained in the Net-Hesiod distribution.

Index

Code Index:

NAME

Top

Net::Hesiod - Perl interface to Hesiod Library API

SYNOPSIS

Top

Non-OO interface

  use Net::Hesiod qw( 
		 hesiod_init hesiod_end hesiod_to_bind hesiod_resolve
		 hesiod_getpwnam hesiod_getpwuid 
		 hesiod_getservbyname hesiod_getmailhost );

  $res=hesiod_init($context);

  $bindname = hesiod_to_bind($context,$name,$type);
  @results = hesiod_resolve($context,$name,$type);

  @pwent = hesiod_getpwnam($context,$username);
  @pwent = hesiod_getpwuid($context,$uid);

  @servent = hesiod_getservbyname($context,$servicename,$proto);

  @mhent = hesiod_getmailhost($context,$username);

  hesiod_end($context);

Object-orientated interface

  use Net::Hesiod;

  my $ctxt = new Net::Hesiod;

  $bindname = $ctxt->to_bind($name,$type);
  @results = $ctxt->resolve($name,$type);

  @pwent = $ctxt->getpwnam($username);
  @pwent = $ctxt->getpwuid($uid);

  @servent = $ctxt->getservbyname($servicename,$proto);
  @mhent = $ctxt->getmailhost($username);

  $results = $ctxt->query($name,$type,$delim);
  @results = $ctxt->query($name,$type,$delim);

DESCRIPTION

Top

These routines interface to the Hesiod Library API. Hesiod is a distributed database, with records stored as text records in DNS, that is used to provide system information in clusters such as MIT's Athena project. http://web.mit.edu/is/athena/

This module provides both standard and object-orientated interfaces to the standard Hesiod library API. It requires the hesiod library to already be installed (and Hesiod configured) on the system.

Before using any of the routines, the hesiod library needs to be initialized. This can be done in the non-OO interface by calling hesiod_init. The scalar $context should be passed to subsequent calls, and when you are through with the Hesiod library, the resources should be explicitly freed with the hesiod_end routine.

In the OO interface, the constructor does the hesiod initialization, and the resources will be automatcially freed by the destructor when the Hesiod object gets destroyed. (In actuality, the constructor merely calls hesiod_init and blesses the resulting $context reference.)

hesiod_init returns 0 if successful, -1 if fails (and $! set). The OO constructor returns a new object reference if successful, and undef otherwise.

The hesiod_to_bind routine and the to_bind method convert a hesiod query on a name and type to a DNS type query. No actual lookup is done.

The hesiod_resolve routine and the resolve method perform an actual query. As with all DNS queries, multiple records can be returned, each of which is returned as separate items in returned list. Usually, only the first item is relevant.

The routines hesiod_getpwnam, hesiod_getpwuid, hesiod_getservbyname, and the related methods (getpwnam, getpwuid, and getservbyname), are hesiod versions of the Core Perl routines getpwnam, getpwuid, and getservbyname. The arrays returned have the same structure as the Core routines. NOTE: The service entry returned by hesiod_getservbyname and the related method has the port number in host-byte order, not network-byte order as the standard C servent structure does. This is consistent with the CORE getservbyname and related functions.

hesiod_getmailhost and the related method getmailhost return the Hesiod postoffice structure for the named user. The returned post office array has three elements, corresponding to the type, host, and name of the mailbox.

The method query is a convenience wrapper to the hesiod_resolve function. In scalar context, it join's the list of strings returned by the resolve routine with the $delim argument (which defaults to ', '), thus returning the entire query as a single scalar. In list context, it split's each element of the list of strings returned by the raw routine on $delim (which defaults to '\s*,\s*'), and returns an array of all the values.

The C language version of the API contains a number of routines to free storage allocated by the library for the results of these queries. The Perl API copies these results to Perl variables, then immediately frees the storage allocated by the Hesiod library, and these routines are not needed in the Perl API.

EXPORT

Nothing by default. The following routines are exportable:

hesiod_init
hesiod_end
hesiod_resolve
hesiod_to_bind
hesiod_getpwnam
hesiod_getpwuid
hesiod_getservbyname
hesiod_getmailhost

The first three can alternatively be exported with the tag resolve, and the whole list with the tag all.

AUTHOR

Top

This code is copyright (c) 2001 by Tom Payerle payerle@physics.umd.edu

All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself, or alternatively (at your option) under either the:

GNU GPL http://www.gnu.org/copyleft/gpl.html

or The Artistic License http://www.perl.com/pub/language/misc/Artistic.html

This code is provided AS IS, without any express or implied warranties.

SEE ALSO

Top

hesiod

hesiod_init, hesiod_end, hesiod_to_bind, hesiod_resolve

hesiod_getpwnam, hesiod_getpwuid, hesiod_getservbyname, hesiod_getmailhost

MIT's Athena Project http://web.mit.edu/is/athena/

Net-Hesiod documentation Contained in the Net-Hesiod distribution. 
package Net::Hesiod;

require 5;
use strict;
use Carp;

require Exporter;
require DynaLoader;
use AutoLoader;

use vars qw( @ISA @EXPORT @EXPORT_OK $VERSION %EXPORT_TAGS);
@ISA = qw(Exporter DynaLoader);

#We don't pollute namespace by default
@EXPORT = qw( );

#Some convenient tags
%EXPORT_TAGS =
(	'resolve' => [qw( hesiod_init hesiod_end hesiod_resolve)],
	'all' => [ qw(  hesiod_init hesiod_end hesiod_resolve
			hesiod_to_bind hesiod_getpwnam hesiod_getpwuid
			hesiod_getservbyname hesiod_getmailhost) ]
);

# Items to export into callers namespace by default. Note: do not export
# names by default without a very good reason. Use EXPORT_OK instead.
# Do not simply export all your public functions/methods/constants.

@EXPORT_OK = qw( hesiod_init hesiod_end hesiod_resolve
			hesiod_to_bind hesiod_getpwnam hesiod_getpwuid
			hesiod_getservbyname hesiod_getmailhost);

$VERSION = '1.11';

sub AUTOLOAD {
    # This AUTOLOAD is used to 'autoload' constants from the constant()
    # XS function.  If a constant is not found then control is passed
    # to the AUTOLOAD in AutoLoader.

    my $constname;
    use vars qw($AUTOLOAD);
    ($constname = $AUTOLOAD) =~ s/.*:://;
    croak "& not defined" if $constname eq 'constant';
    my $val = constant($constname, @_ ? $_[0] : 0);
    if ($! != 0) {
	if ($! =~ /Invalid/ || $!{EINVAL}) {
	    $AutoLoader::AUTOLOAD = $AUTOLOAD;
	    goto &AutoLoader::AUTOLOAD;
	}
	else {
	    croak "Your vendor has not defined Hesiod macro $constname";
	}
    }
    {
	no strict 'refs';
	# Fixed between 5.005_53 and 5.005_61
	if ($] >= 5.00561) {
	    *$AUTOLOAD = sub () { $val };
	}
	else {
	    *$AUTOLOAD = sub { $val };
	}
    }
    goto &$AUTOLOAD;
}

bootstrap Net::Hesiod $VERSION;

# Preloaded methods go here.

#OO Wrappers for the raw hesiod interface

sub new ($)
#Constructor
#Just call hesiod_init and bless context
{	my $class = shift;
	#If called as an instance method, create new object of same class
	if ( ref($class) ) { $class = ref($class); }

	my $context;
	my $res=hesiod_init($context);
	if ( $res ) { return undef; }
	bless $context, $class;
	return $context;
}

sub DESTROY ($)
#Destructor
#call hesiod_end on our context
{	my $obj = shift;
	if ( ! ref($obj) ) 
	{	croak "Net::Hesiod::DESTROY called as class method.";
	}
	hesiod_end($obj);
}

#Simple wrappers for the raw functions
sub to_bind($$$)
{	my $context = shift;
	if ( ! ref($context) )
	{	croak "Net::Hesiod::to_bind called as class method.";
	}
	my $name=shift;
	my $type=shift;
	return hesiod_to_bind($context,$name,$type);
}

sub resolve($$$)
{	my $context = shift;
	if ( ! ref($context) )
	{	croak "Net::Hesiod::resolve called as class method.";
	}
	my $name=shift;
	my $type=shift;
	return hesiod_resolve($context,$name,$type);
}


sub getpwnam($$)
{	my $context = shift;
	if ( ! ref($context) )
	{	croak "Net::Hesiod::getpwnam called as class method.";
	}
	my $name=shift;
	return hesiod_getpwnam($context,$name);
}

sub getpwuid($$)
{	my $context = shift;
	if ( ! ref($context) )
	{	croak "Net::Hesiod::getpwuid called as class method.";
	}
	my $uid=shift;
	return hesiod_getpwuid($context,$uid);
}

sub getservbyname($$$)
{	my $context = shift;
	if ( ! ref($context) )
	{	croak "Net::Hesiod::getservbyname called as class method.";
	}
	my $serv=shift;
	my $proto=shift;

	return hesiod_getservbyname($context,$serv,$proto);
}

sub getmailhost($$)
{	my $context = shift;
	if ( ! ref($context) )
	{	croak "Net::Hesiod::getmailhost called as class method.";
	}
	my $mh=shift;
	return hesiod_getmailhost($context,$mh);
}

sub query($$$;$)
#query is a wrapper for resolve.  IT does a hesiod_resolve for name and
#type, and depending on whether called in scalar or list context will
#return either a string of the list from resolve joined together (with $delim
#as delimiter) or a list produced by splitting each element of the list from
#resolve by the $delim character.
#$delim defaults to ", " in scalar context, and "\s*,\s*" in list context
{	my $context=shift;
	if ( ! ref($context) )
	{	croak "Net::Hesiod::query called as class method.";
	}
	my $name = shift;
	my $type = shift;
	my $delim = shift || undef;

	my @tmp = hesiod_resolve($context,$name,$type);
	my $tmp;
	if ( wantarray )
	{	#Called in list context
		if ( ! defined $delim ) { $delim = '\s*,\s*'; }

		my @res = ();
		foreach $tmp (@tmp)
		{	push @res, (split /$delim/, $tmp);
		}
		return @res;
	} else
	{	#Called in scalar context
		if ( ! defined $delim ) { $delim = ', '; }
		my $res = join "$delim", @tmp;
		return $res;
	}
}

# Autoload methods go after =cut, and are processed by the autosplit program.

1;
__END__
# Below is stub documentation for your module. You better edit it!