@node Net/NIS, Net/NISPlus/Table, Net/FTP, Module List
@unnumbered Interface to Sun@'s Network Information Service


@unnumberedsec NAME

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

@unnumberedsec DESCRIPTION

The Net::NIS interface comes in two parts.  The first part is the raw
implementation of the NIS API.  The second is the object interface,
described in @samp{Net::NIS::Table} in this node.  This document describes the NIS API
implementation.

The NIS package implements all functions described in the @samp{ypclnt(3N)} in this node
manual page.

The following commands have been implemented:

@table @asis
@item yp_bind($domain)
Bind the process to a NIS server for the domain $domain.  This
function is rarely needed.  See @samp{yp_bind(3N)} in this node.

@item yp_unbind($domain)
Unbind the process from the specified $domain.  This function is also
rarely required.  See @samp{yp_unbind(3N)} in this node.

@item $domain = yp_get_default_domain()
Return the host@'s local domain.  (The same as the @samp{domainname} in this node
program).  See @samp{yp_get_default_domain(3N)} in this node.

@item ($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 (@emph{i.e.}
yp_match does no partial matching.  The $value is only valid if
$status is equal to $YP_SUCCESS.

@item ($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.

@item ($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 @samp{yp_first} in this node or @samp{yp_next} in this node.  The
@samp{yp_first} in this node/@samp{yp_next} in this node method is not recommended, as under some
circumstances, entries can be skipped or returned twice.  @samp{yp_all} in this node is
a better interface to use.

@item ($status, \%values) = yp_all($domain, $map)
The @samp{yp_all} in this node call returns an entire map in the %values associative
array.

@item ($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.

@item ($status, $name) = yp_master($domain, $map)
Returns the machine name of the master server for a map.

@item $error = yperr_string($status)
Returns a string representation of the error code passed in $status.

@item $status = ypprot_err($code)
Translates a NIS name service protocol error code to a ypclnt layer
error code.  Only used for the C version of @samp{yp_all} in this node, and it is only
implemented here for completeness.

@end table
@unnumberedsec ERROR CODES

The $status variable returned by the above functions can have one of
the following values:

@example
$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@'t 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@'s domain
$Net::NIS::ERR_NODOM		Local domain name not set
$Net::NIS::ERR_PMAP		Can@'t 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@'t communicate with ypbind
$Net::NIS::ERR_YPERR		Internal yp server or client interface error
$Net::NIS::ERR_YPSERV		Can@'t communicate with ypserv
$Net::NIS::ERR_VERS		YP version mismatch
@end example

@unnumberedsec AUTHOR

Copyright (c) 1995 Rik Harris (@strong{rik.harris@@fulcrum.com.au}). All
rights reserved.  This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.

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.

