NIS(3pm)

📦
version 0.44 · 6 versions
, in ubuntu stonking

💖 Net::NIS — the manual, but make it slay 💖

okay bestie, sit down, hydrate, and let me tell you about Net::NIS 🌸 — the Perl interface to Sun's Network Information Service. (Yes, yes, the manpage name is NIS(3pm) and it lives in User Contributed Perl Documentation. We're keeping it cute, not renaming anything. 💅)

✨ SYNOPSIS ✨

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

or, y'know, if you're feeling ✨procedural✨:

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

🌈 DESCRIPTION 🌈

The Net::NIS interface comes in three parts, like a very iconic trio 🫶:

  1. raw The first part is the raw implementation of the NIS API. No frills, just vibes and function calls.
  2. OO The second is the object interface, described in Net::NIS::Table. Go read that one too, bestie.
  3. Tie The third is a new 'Tied' interface, allowing simple access to NIS maps using Perl hashes. This is the one that makes you go "wait, that's it? ate." 🔥

This document describes the NIS API implementation and the 'Tied' mechanism. Two for one, we love to see it.

🎀 Tied Implementation 🎀

NIS maps are simple key/value pairs — literally born to be Perl hashes. It's giving match made in heaven 💜. Net::NIS lets any given NIS map be treated as a hash (read-only, so no, you can't just start rewriting your company's passwd map, girl please 🙈). Usage:

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. (The fallback squad. They showed up anyway. 🫡)

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. Yes, lowercase, no underscore. iykyk.

If Net::NIS cannot tie to a given map, it returns undef, with an appropriate error value in the variable $yperr. See "ERRORS" below, bestie, don't skip it 🌸.

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. So like, if it's just "key not here" it's chill, but anything else? It's screaming 😭.

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. So like, Linux girlies get the full menu, everyone else gets à la carte 💅.

👑 NIS API Implementation 👑

The NIS package implements all functions described in the ypclnt(3N) manual page. Every single one. No crumbs left.

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). Lowkey a background character.
  • yp_unbind($domain) — Unbind the process from the specified $domain. This function is also rarely required. See yp_unbind(3N). Also a background character. Besties fr.
  • $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 — it is not doing fuzzy find for you, no cap). 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. So the responsibility is on you, bestie. Eyes open 👀.
  • ($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. Do not expect alphabetical. Do not expect anything. Just accept the gift. 🎁
  • ($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. Yeah. That's the tea. Use yp_all. ☕
  • ($status, \%values) = yp_all($domain, $map) — The yp_all call returns an entire map in the %values associative array. The whole thing. One shot. Iconic behavior. ✨
  • ($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. (Author said it, not me. 😭)
  • ($status, $name) = yp_master($domain, $map) — Returns the machine name of the master server for a map. Main character server energy 👑.
  • $error = yperr_string($status) — [DEPRECATED, use $yperr] Returns a string representation of the error code passed in $status. She's retired, send her flowers 💐.
  • $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. A true "technically present" moment.

🎀 EXPORT 🎀

The magic variable $yperr is exported by default (see "ERRORS"). She comes included, no extra charge 💖.

⭐ Exportable constants ⭐

The following error status constants can be imported individually, or by using the ':all' symbol. Collect them all, Pokémon style:

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 (a betrayal we simply cannot allow 🙅), 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. She shapeshifts, basically. 🦋

🌸 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. (Blame the vendor, not yourself, bestie. 🫶)

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... 😭 The author really said "good luck, girl."

🫶 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 <esm@cpan.org>. Give him a round of applause 👏.

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. So like — same girl, new name badge, and please respect the trademark, we're not trying to get a letter 💅✨.

that's the whole manual, bestie, nothing skipped, nothing summarised. 🎀

and for the little sign-off at the bottom: this page is from perl v5.42.3, dated 2026-08-19 — from me and the NIS(3pm) girlies, mwah 💋 go tie a hash, you've got this 🦋💖🌸

📦 where this page comes from