.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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 turned on, 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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "NIS 3pm"
.TH NIS 3pm "2014-02-22" "perl v5.20.0" "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 \s-1NIS API.\s0
.IP "2. \s-1OO\s0" 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 \s-1NIS\s0 maps
using Perl hashes.
.PP
This document describes the \s-1NIS API\s0 implementation and the 'Tied' mechanism.
.SS "Tied Implementation"
.IX Subsection "Tied Implementation"
\&\s-1NIS\s0 maps are simple key/value pairs, perfectly suited for Perl
hashes.  \fBNet::NIS\fR allows any given \s-1NIS\s0 map to be treated as a
hash (read-only).  Usage is:
.PP
.Vb 1
\&    tie %hash, \*(AqNet::NIS\*(Aq, $mapname [, $domainname];
.Ve
.PP
\&\fI\f(CI$mapname\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 \*(L"usual
suspects\*(R" is consulted.
.PP
If \fI\f(CI$domainname\fI\fR is not given, the \f(CW\*(C`yp_get_default_domain\*(C'\fR
function is used to determine the current \s-1NIS\s0 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 \fB\f(CB$yperr\fB\fR.  See
\&\*(L"\s-1ERRORS\*(R"\s0.
.PP
To look up an entry in a \s-1YP\s0 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 \s-1YPERR_KEY, \s0\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 \fIkeys()\fR only works on Linux, because Linux includes
a helpful \fIyp_maplist()\fR function.  On Linux, you can get a list
of existing \s-1YP\s0 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 "\s-1NIS API\s0 Implementation"
.IX Subsection "NIS API Implementation"
The \s-1NIS\s0 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 \s-1NIS\s0 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 = \fIyp_get_default_domain()\fR" 5
.el .IP "\f(CW$domain\fR = \fIyp_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 \s-1YPERR_SUCCESS.\s0
.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 \s-1NIS\s0 maps
are stored in a \s-1DBM\s0 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 \s-1NIS+\s0
servers running in \*(L"YP-compatibility mode\*(R".  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[\s-1DEPRECATED,\s0 use \fB$yperr\fB]\fR" 5
.el .IP "\f(CW$error\fR = yperr_string($status) \fB[\s-1DEPRECATED,\s0 use \f(CB$yperr\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[\s-1DEPRECATED\s0]\fR" 5
.el .IP "\f(CW$status\fR = ypprot_err($code) \fB[\s-1DEPRECATED\s0]\fR" 5
.IX Item "$status = ypprot_err($code) [DEPRECATED]"
Translates a \s-1NIS\s0 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 \fB\f(CB$yperr\fB\fR is exported by default (see \*(L"\s-1ERRORS\*(R"\s0).
.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,
\&\s-1\fITIEHASH\s0()\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 \fB\f(CB$yperr\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 \fB\f(CB$yperr\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\f(CB$yperr\fB\fR returns the numeric status
code returned from the last \s-1YP\s0 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', \s-1\fIFETCH\s0()\fR raises this fatal
exception.  It probably indicates that \s-1YP\s0 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 (\s-1NIS\s0) was formerly known as Sun Yellow
Pages (\s-1YP\s0). 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.