/ 
Net-Hesiod-1.10
River stage zero No dependents
/ Net::Hesiod

NAME

Net::Hesiod - Perl interface to Hesiod Library API

SYNOPSIS

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

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

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