Tied Implementation

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.

NIS API Implementation

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.

Exportable constants

The following error status constants can be imported individually, or by using the ':all' symbol:

    YPERR_SUCCESS       There is no error
    YPERR_BADARGS       Args to function are bad
    YPERR_RPC           RPC failure
    YPERR_DOMAIN        Can't bind to a server with this domain
    YPERR_MAP           No such map in server's domain
    YPERR_KEY           No such key in map
    YPERR_YPERR         Internal yp server or client error
    YPERR_RESRC         Local resource allocation failure
    YPERR_NOMORE        No more records in map database
    YPERR_PMAP          Can't communicate with portmapper
    YPERR_YPBIND        Can't communicate with ypbind
    YPERR_YPSERV        Can't communicate with ypserv
    YPERR_NODOM         Local domain name not set
    YPERR_BADDB         yp data base is bad
    YPERR_VERS          YP version mismatch
    YPERR_ACCESS        Access violation
    YPERR_BUSY          Database is busy

Other Errors

    Your vendor has not defined Net::NIS macro YPERR_xxxx

This indicates that one of the standard YPERR_xxx constants is not defined in your host's <rpcsct/ypclnt.h> file. You might see this during make test on an old system, perhaps.

    Unable to find 'KEY' in 'MAP'.  Reason: ...

If an attempt to access a tied variable fails for any reason other than 'no such key in map', FETCH() raises this fatal exception. It probably indicates that YP has gone down, or there is some other fatal error. This can be caught with eval{}, but I'm not sure what you can do about it...