The Net::NIS interface comes in three parts:
1. raw
The first part is the raw implementation of the NIS API.
2. OO
The second is the object interface, described in Net::NIS::Table.
3. Tie
The third is a new 'Tied' interface, allowing simple access to NIS maps using Perl hashes.
This document describes the NIS API implementation and the 'Tied' mechanism.
TiedImplementation
NIS maps are simple key/value pairs, perfectly suited for Perl hashes. Net::NIS allows any given NIS map
to be treated as a hash (read-only). Usage is:
tie %hash, 'Net::NIS', $mapname [, $domainname];
$mapname must be specified, and be a valid map in the given domain. If the file /var/yp/nicknames
exists, it is used to obtain a list of acceptable shortcut names, such as "aliases" for "mail.aliases".
Otherwise, a hardcoded set of the "usual suspects" is consulted.
If $domainname is not given, the "yp_get_default_domain" function is used to determine the current NIS
domain. This is usually the same as will be displayed by the "domainname" command.
If Net::NIS cannot tie to a given map, it returns "undef", with an appropriate error value in the
variable $yperr. See "ERRORS".
To look up an entry in a YP map, simply use the entry name as a key in the tied hash. Net::NIS returns a
string if the key exists in the map, or "undef" if it is not found. For any errors other than YPERR_KEY,
Net::NIS raises a fatal exception through "croak".
Example
tie %alias, 'Net::NIS', 'mail.aliases'
or die "Cannot tie to mail.aliases YP map: $yperr\n";
print "postmaster is ", $alias{postmaster} || "<unknown>", "\n";
As a special case, the magic map __YPMASTER can be used as an equivalent to 'ypwhich -m':
tie %ypmaster, 'Net::NIS', '__YPMASTER' or die ...;
printf "ypmaster(passwd) = %s\n", $ypmaster{'passwd.byname'};
print $_, "\n" for sort keys %ypmaster; # Only works on Linux!
Note that keys() only works on Linux, because Linux includes a helpful yp_maplist() function. On Linux,
you can get a list of existing YP maps. On other OSes, you can't -- but given the name of an existing
map, $ypmaster{$map} will work as expected.
NISAPIImplementation
The NIS package implements all functions described in the ypclnt(3N) manual page.
The following commands have been implemented:
yp_bind($domain)
Bind the process to a NIS server for the domain $domain. This function is rarely needed. See
yp_bind(3N).
yp_unbind($domain)
Unbind the process from the specified $domain. This function is also rarely required. See
yp_unbind(3N).
$domain = yp_get_default_domain()
Return the host's local domain. (The same as the domainname program). See
yp_get_default_domain(3N).
($status, $value) = yp_match($domain, $map, $key)
Return the $value for the given $key in the $map for the domain $domain. The $key must be an exact
match for an item in the map (i.e. yp_match does no partial matching. The $value is only valid if
$status is equal to YPERR_SUCCESS.
If called in scalar context, yp_match returns only $value, and it is up to the user to check $yperr.
($status, $key, $value) = yp_first($domain, $map)
Return the first key-value pair from $map in $domain. As the NIS maps are stored in a DBM table,
the order of the returned values is not obvious.
($status, $key, $value) = yp_next($domain, $map, $key)
Return the next key-value pair from $map in $domain. The $key must be provided from the previous
yp_first or yp_next. The yp_first/yp_next method is not recommended, as under some circumstances,
entries can be skipped or returned twice. yp_all is a better interface to use.
($status, \%values) = yp_all($domain, $map)
The yp_all call returns an entire map in the %values associative array.
($status, $order) = yp_order($domain, $map)
This function returns the order number for $domain. Whatever that is. It mustn't be very
important, since it's not implemented on NIS+ servers running in "YP-compatibility mode". I put it
in for completeness.
($status, $name) = yp_master($domain, $map)
Returns the machine name of the master server for a map.
$error = yperr_string($status) [DEPRECATED,use$yperr]
Returns a string representation of the error code passed in $status.
$status = ypprot_err($code) [DEPRECATED]
Translates a NIS name service protocol error code to a ypclnt layer error code. Only used for the C
version of yp_all, and it is only implemented here for completeness.
Install Now
PNG Icons
