Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
NIS(3)		      User Contributed Perl Documentation		NIS(3)

       Net::NIS	- Interface to Sun's Network Information Service

	 use Net::NIS;
	 tie %hash, 'Net::NIS',	$mapname [, $domainname];
	 $value	= $hash{$key};


	 ($status, $value) = Net::NIS::yp_match
				 $mapname, $key);

       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'

   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".


	 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:

	    Bind the process to	a NIS server for the domain $domain.  This
	    function is	rarely needed.	See yp_bind(3N).

	    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

       ($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

       ($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 = 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.

       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

       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 <rpcsct/ypclnt.h>	file.  You might see this
       during makeA 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

       Copyright (c) 1995, 2002	Rik Harris (,
       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.

perl v5.32.0			  2014-02-22				NIS(3)


Want to link to this manual page? Use this URL:

home | help