--- name: "Net::NIS" section: "3pm" platform: "linux" package: "libnet-nis-perl" version: "0.44-4+b1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Net::NIS" --- # Net::NIS(3pm) Interface to Sun's Network Information Service ## NAME Net::NIS - Interface to Sun's Network Information Service ## SYNOPSIS ``` use Net::NIS; tie %hash, 'Net::NIS', $mapname [, $domainname]; $value = $hash{$key}; ``` or ``` ($status, $value) = Net::NIS::yp_match (Net::NIS::yp_get_default_domain(), $mapname, $key); ``` ## DESCRIPTION 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. ### 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} || "", "\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. ## EXPORT The magic variable **$yperr** is exported by default (see "ERRORS"). ### 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 ``` ## ERRORS Instead of having 'tie' succeed and the first access fail, **TIEHASH()** (the function executed when performing a **tie**) performs some sanity checks: it ensures the validity of the domain and map names. On failure, 'tie' returns `"undef"`, with an appropriate error value in **$yperr** : ``` tie %myhash, 'Net::NIS', 'foo-bar' or die "Unable to access foo-bar map: $yperr\n" ``` Note that the **$yperr** variable is magic, like Perl's **$!**. If accessed in a string context, it returns a human-friendly string obtained from the `"yperr_string"` library function. In a numeric context, **$yperr** returns the numeric status code returned from the last YP function. This can be compared against the error constants above, if you so desire. ### 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 \ 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... ## AUTHOR Copyright (c) 1995, 2002 Rik Harris (**rik.harris@fulcrum.com.au**), 2002-2014 Ed Santiago. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Net::NIS is currently maintained by Ed Santiago \. The Network Information Service (NIS) was formerly known as Sun Yellow Pages (YP). The functionality of the two remains the same; only the name has changed. The name Yellow Pages is a registered trademark in the United Kingdom of British Telecommunications plc, and may not be used without permission.