.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" 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 >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 "NISTable 3pm"
.TH NISTable 3pm "2018-11-01" "perl v5.28.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::Table \- Object Interface to Sun's Network Information Service
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \s-1NIS\s0 interface comes in two parts.  The first part is the raw
implementation of the \s-1NIS API,\s0 described in Net::NIS.  The second is
the object interface.  This document describes the object interface 
implementation.
.PP
The Table object represents an individual \s-1NIS\s0 map.  A \s-1NIS\s0 map is bound
to a Table object with the new method:
.PP
.Vb 1
\&  $obj = Net::NIS::Table\->new($map, [ $domain ]);
.Ve
.PP
For example,
.PP
.Vb 1
\&  $hostsmap = Net::NIS::Table\->new("hosts.byname");
.Ve
.PP
This will create a Table object bound to the \f(CW\*(C`hosts.byname\*(C'\fR \s-1NIS\s0 map in
the default \s-1NIS\s0 domain.  All operations on the \f(CW$hostsmap\fR object will
relate to the \f(CW\*(C`hosts.byname\*(C'\fR map.
.PP
You can also specify a non-default domain:
.PP
.Vb 1
\&  $hostsmap = Net::NIS::Table\->new("hosts.byname", "my.domain.com.au");
.Ve
.PP
Once a Table object has been bound to a \s-1NIS\s0 map, the following
methods are available:
.ie n .IP "$value = $obj\->match($key)" 5
.el .IP "\f(CW$value\fR = \f(CW$obj\fR\->match($key)" 5
.IX Item "$value = $obj->match($key)"
Returns the value for a given key.  If you only wish to look up one or
two values, this function is more efficient, as it retrieves the items
one at a time.  If you wish to retrieve many items (where many is dependent
on the size of the map, and probably what sort of machine you are on),
it is better to use the list interface, which uses just one \s-1RPC\s0
call to retrieve the entire map.
.ie n .IP "\e%data = $obj\->\fBlist()\fR" 5
.el .IP "\e%data = \f(CW$obj\fR\->\fBlist()\fR" 5
.IX Item "%data = $obj->list()"
Return a reference to an associative array which contains the entire
\&\s-1NIS\s0 map.  The keys in the \f(CW%data\fR array correspond to the keys in the \s-1NIS\s0
map.  If any error occurs that prevents the retrieval of the map, then
the undefined value is returned.  In this case, your program can use
the status method to determine the cause of the error.
.ie n .IP "\e%data = $obj\->search($srchkey)" 5
.el .IP "\e%data = \f(CW$obj\fR\->search($srchkey)" 5
.IX Item "%data = $obj->search($srchkey)"
Return a reference to an associative array which contains all entries
that have keys that contain the \f(CW$srchkey\fR.  If any error occurs that
prevents the retrieval of the map, then the undefined value is
returned.  In this case, your program can use the status method to
determine the cause of the error.
.ie n .IP "$status = $obj\->\fBstatus()\fR" 5
.el .IP "\f(CW$status\fR = \f(CW$obj\fR\->\fBstatus()\fR" 5
.IX Item "$status = $obj->status()"
Returns the status code for the last operation.  If the last operation
succeeded, then the status code is 0.  The status codes returned by
this method are described below in the \s-1ERROR CODES\s0 section.
.ie n .IP "$status = $obj\->\fBstatus_string()\fR" 5
.el .IP "\f(CW$status\fR = \f(CW$obj\fR\->\fBstatus_string()\fR" 5
.IX Item "$status = $obj->status_string()"
Returns the character representation of the status code for the last operation.  If the last operation
succeeded, then the status code is something like \*(L"operation
succeeded\*(R".  The exact strings returned by this function are
implementation dependent, and should not be used for comparison
purposes.  Use the status call, as described above.
.SH "ERROR CODES"
.IX Header "ERROR CODES"
The status method described above can return one of the following values:
.PP
.Vb 10
\&  $Net::NIS::ERR_ACCESS         Access violation
\&  $Net::NIS::ERR_BADARGS        Args to function are bad
\&  $Net::NIS::ERR_BADDB          yp data base is bad
\&  $Net::NIS::ERR_BUSY           Database is busy
\&  $Net::NIS::ERR_DOMAIN         Can\*(Aqt bind to a server which serves this domain
\&  $Net::NIS::ERR_KEY            No such key in map
\&  $Net::NIS::ERR_MAP            No such map in server\*(Aqs domain
\&  $Net::NIS::ERR_NODOM          Local domain name not set
\&  $Net::NIS::ERR_PMAP           Can\*(Aqt communicate with portmapper
\&  $Net::NIS::ERR_NOMORE         No more records in map database
\&  $Net::NIS::ERR_RESRC          Local resource allocation failure
\&  $Net::NIS::ERR_RPC            RPC failure
\&  $Net::NIS::ERR_YPBIND         Can\*(Aqt communicate with ypbind
\&  $Net::NIS::ERR_YPERR          Internal yp server or client interface error
\&  $Net::NIS::ERR_YPSERV         Can\*(Aqt communicate with ypserv
\&  $Net::NIS::ERR_VERS           YP version mismatch
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Copyright (c) 1995 Rik Harris (\fBrik.harris@fulcrum.com.au\fR). All
rights reserved.  This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.
.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.