.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "NIS 3pm"
.TH NIS 3pm 2024-03-11 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Net::NIS \- Interface to Sun's Network Information Service
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 3
\&  use Net::NIS;
\&  tie %hash, \*(AqNet::NIS\*(Aq, $mapname [, $domainname];
\&  $value = $hash{$key};
.Ve
.PP
or
.PP
.Vb 3
\&  ($status, $value) = Net::NIS::yp_match
\&                          (Net::NIS::yp_get_default_domain(),
\&                          $mapname, $key);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The Net::NIS interface comes in three parts:
.IP "1. raw" 4
.IX Item "1. raw"
The first part is the raw implementation of the NIS API.
.IP "2. OO" 4
.IX Item "2. OO"
The second is the object interface, described in Net::NIS::Table.
.IP "3. Tie" 4
.IX Item "3. Tie"
The third is a new 'Tied' interface, allowing simple access to NIS maps
using Perl hashes.
.PP
This document describes the NIS API implementation and the 'Tied' mechanism.
.SS "Tied Implementation"
.IX Subsection "Tied Implementation"
NIS maps are simple key/value pairs, perfectly suited for Perl
hashes.  \fBNet::NIS\fR allows any given NIS map to be treated as a
hash (read-only).  Usage is:
.PP
.Vb 1
\&    tie %hash, \*(AqNet::NIS\*(Aq, $mapname [, $domainname];
.Ve
.PP
\&\fR\f(CI$mapname\fR\fI\fR must be specified, and be a valid map in the given
domain.  If the file \fI/var/yp/nicknames\fR exists, it is used to
obtain a list of acceptable shortcut names, such as \f(CW\*(C`aliases\*(C'\fR
for \f(CW\*(C`mail.aliases\*(C'\fR.  Otherwise, a hardcoded set of the "usual
suspects" is consulted.
.PP
If \fR\f(CI$domainname\fR\fI\fR is not given, the \f(CW\*(C`yp_get_default_domain\*(C'\fR
function is used to determine the current NIS domain.  This
is usually the same as will be displayed by the \f(CW\*(C`domainname\*(C'\fR
command.
.PP
If \fBNet::NIS\fR cannot tie to a given \fImap\fR, it returns \f(CW\*(C`undef\*(C'\fR,
with an appropriate error value in the variable \fR\f(CB$yperr\fR\fB\fR.  See
"ERRORS".
.PP
To look up an entry in a YP map, simply use the entry name as
a key in the tied hash.  \fBNet::NIS\fR returns a string if the
key exists in the map, or \f(CW\*(C`undef\*(C'\fR if it is not found.
For any errors other than YPERR_KEY, \fBNet::NIS\fR raises a fatal
exception through \f(CW\*(C`croak\*(C'\fR.
.PP
\&\fBExample\fR
.PP
.Vb 3
\&  tie %alias, \*(AqNet::NIS\*(Aq, \*(Aqmail.aliases\*(Aq
\&    or die "Cannot tie to mail.aliases YP map: $yperr\en";
\&  print "postmaster is ", $alias{postmaster} || "<unknown>", "\en";
.Ve
.PP
As a special case, the magic map \fB_\|_YPMASTER\fR can be used as
an equivalent to 'ypwhich \-m':
.PP
.Vb 2
\&  tie %ypmaster, \*(AqNet::NIS\*(Aq, \*(Aq_\|_YPMASTER\*(Aq or die ...;
\&  printf "ypmaster(passwd) = %s\en", $ypmaster{\*(Aqpasswd.byname\*(Aq};
\&
\&  print  $_, "\en"    for sort keys %ypmaster;   # Only works on Linux!
.Ve
.PP
Note that \fBkeys()\fR only works on Linux, because Linux includes
a helpful \fByp_maplist()\fR 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, \f(CW$ypmaster\fR{$map} will work as expected.
.SS "NIS API Implementation"
.IX Subsection "NIS API Implementation"
The NIS package implements all functions described in the ypclnt(3N)
manual page.
.PP
The following commands have been implemented:
.IP yp_bind($domain) 5
.IX Item "yp_bind($domain)"
Bind the process to a NIS server for the domain \f(CW$domain\fR.  This
function is rarely needed.  See yp_bind(3N).
.IP yp_unbind($domain) 5
.IX Item "yp_unbind($domain)"
Unbind the process from the specified \f(CW$domain\fR.  This function is also
rarely required.  See yp_unbind(3N).
.ie n .IP "$domain = \fByp_get_default_domain()\fR" 5
.el .IP "\f(CW$domain\fR = \fByp_get_default_domain()\fR" 5
.IX Item "$domain = yp_get_default_domain()"
Return the host's local domain.  (The same as the domainname
program).  See yp_get_default_domain(3N).
.ie n .IP "($status, $value) = yp_match($domain, $map, $key)" 5
.el .IP "($status, \f(CW$value\fR) = yp_match($domain, \f(CW$map\fR, \f(CW$key\fR)" 5
.IX Item "($status, $value) = yp_match($domain, $map, $key)"
Return the \f(CW$value\fR for the given \f(CW$key\fR in the \f(CW$map\fR for the domain
\&\f(CW$domain\fR.  The \f(CW$key\fR must be an exact match for an item in the map (\fIi.e.\fR
yp_match does no partial matching.  The \f(CW$value\fR is only valid if
\&\f(CW$status\fR is equal to YPERR_SUCCESS.
.Sp
If called in scalar context, yp_match returns only \f(CW$value\fR, and it
is up to the user to check \f(CW$yperr\fR.
.ie n .IP "($status, $key, $value) = yp_first($domain, $map)" 5
.el .IP "($status, \f(CW$key\fR, \f(CW$value\fR) = yp_first($domain, \f(CW$map\fR)" 5
.IX Item "($status, $key, $value) = yp_first($domain, $map)"
Return the first key-value pair from \f(CW$map\fR in \f(CW$domain\fR.  As the NIS maps
are stored in a DBM table, the order of the returned values is
not obvious.
.ie n .IP "($status, $key, $value) = yp_next($domain, $map, $key)" 5
.el .IP "($status, \f(CW$key\fR, \f(CW$value\fR) = yp_next($domain, \f(CW$map\fR, \f(CW$key\fR)" 5
.IX Item "($status, $key, $value) = yp_next($domain, $map, $key)"
Return the next key-value pair from \f(CW$map\fR in \f(CW$domain\fR.  The \f(CW$key\fR 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.
.ie n .IP "($status, \e%values) = yp_all($domain, $map)" 5
.el .IP "($status, \e%values) = yp_all($domain, \f(CW$map\fR)" 5
.IX Item "($status, %values) = yp_all($domain, $map)"
The yp_all call returns an entire map in the \f(CW%values\fR associative
array.
.ie n .IP "($status, $order) = yp_order($domain, $map)" 5
.el .IP "($status, \f(CW$order\fR) = yp_order($domain, \f(CW$map\fR)" 5
.IX Item "($status, $order) = yp_order($domain, $map)"
This function returns the order number for \f(CW$domain\fR.  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.
.ie n .IP "($status, $name) = yp_master($domain, $map)" 5
.el .IP "($status, \f(CW$name\fR) = yp_master($domain, \f(CW$map\fR)" 5
.IX Item "($status, $name) = yp_master($domain, $map)"
Returns the machine name of the master server for a map.
.ie n .IP "$error = yperr_string($status) \fB[DEPRECATED, use \fR\fB$yperr\fR\fB]\fR" 5
.el .IP "\f(CW$error\fR = yperr_string($status) \fB[DEPRECATED, use \fR\f(CB$yperr\fR\fB]\fR" 5
.IX Item "$error = yperr_string($status) [DEPRECATED, use $yperr]"
Returns a string representation of the error code passed in \f(CW$status\fR.
.ie n .IP "$status = ypprot_err($code) \fB[DEPRECATED]\fR" 5
.el .IP "\f(CW$status\fR = ypprot_err($code) \fB[DEPRECATED]\fR" 5
.IX Item "$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.
.SH EXPORT
.IX Header "EXPORT"
The magic variable \fR\f(CB$yperr\fR\fB\fR is exported by default (see "ERRORS").
.SS "Exportable constants"
.IX Subsection "Exportable constants"
The following error status constants can be imported individually, or
by using the ':all' symbol:
.PP
.Vb 10
\&    YPERR_SUCCESS       There is no error
\&    YPERR_BADARGS       Args to function are bad
\&    YPERR_RPC           RPC failure
\&    YPERR_DOMAIN        Can\*(Aqt bind to a server with this domain
\&    YPERR_MAP           No such map in server\*(Aqs 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\*(Aqt communicate with portmapper
\&    YPERR_YPBIND        Can\*(Aqt communicate with ypbind
\&    YPERR_YPSERV        Can\*(Aqt 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
.Ve
.SH ERRORS
.IX Header "ERRORS"
Instead of having 'tie' succeed and the first access fail,
\&\fBTIEHASH()\fR (the function executed when performing a \fBtie\fR) performs
some sanity checks: it ensures the validity of the domain and
map names.  On failure, 'tie' returns \f(CW\*(C`undef\*(C'\fR, with an appropriate
error value in \fR\f(CB$yperr\fR\fB\fR :
.PP
.Vb 2
\&    tie %myhash, \*(AqNet::NIS\*(Aq, \*(Aqfoo\-bar\*(Aq
\&      or die "Unable to access foo\-bar map: $yperr\en"
.Ve
.PP
Note that the \fR\f(CB$yperr\fR\fB\fR variable is magic, like Perl's \fB$!\fR.
If accessed in a string context, it returns a human-friendly
string obtained from the \f(CW\*(C`yperr_string\*(C'\fR library function.
In a numeric context, \fB\fR\f(CB$yperr\fR\fB\fR returns the numeric status
code returned from the last YP function.  This can be compared
against the error constants above, if you so desire.
.SS "Other Errors"
.IX Subsection "Other Errors"
.Vb 1
\&    Your vendor has not defined Net::NIS macro YPERR_xxxx
.Ve
.PP
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.
.PP
.Vb 1
\&    Unable to find \*(AqKEY\*(Aq in \*(AqMAP\*(Aq.  Reason: ...
.Ve
.PP
If an attempt to access a tied variable fails for any reason
other than 'no such key in map', \fBFETCH()\fR 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...
.SH AUTHOR
.IX Header "AUTHOR"
Copyright (c) 1995, 2002 Rik Harris (\fBrik.harris@fulcrum.com.au\fR),
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.
.PP
Net::NIS is currently maintained by Ed Santiago <esm@cpan.org>.
.PP
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.