-*- outline -*-

			     scsh-yp 0.1

* Introduction

  Scsh-yp is a package for scsh, the Scheme shell[1] that provides
  bindings to the YP/NIS functions.  This enables the scsh user to
  lookup data in a NIS or YP database without calling the apropriate
  external program (i. e. ypbind, ypmatch etc).

** How to install

   Scsh has the ability to load shared object files dynamically at run
   time.  That makes it easy to add functionality like scsh-yp to an
   existing scsh installation without having to recompile everything.
   In order to build such a shared module run

   ./configure --prefix=<path> --with-scsh-includes=<path>

   It is important to provide a correct path to the scsh include
   directory of your system.  Once the configure script found out how
   to build shared objects for your system you can run 'make' to build
   scsh-yp and 'make install' to copy the files to the installation
   directory.

** Running scsh-yp

   Scsh-yp comes with an script called 'load-yp.scm' which loads the
   shared object and loads the scheme package and interface
   definitions for scsh-yp. 

   If the installation directory in scsh's libary path scsh-yp load
   scsh-yp at start-up by saying

   scsh -lel scsh-yp-0.1/scheme/load-yp.scm

   The scsh user manual explains how to set the library path.  Now
   everything is set up to open the package "yp":

   ,open yp

* Using scsh-yp

** conditions and errors

   yp-error?
   yp-communication-error?
   yp-unknown-resource-error?
   yp-internal-error?

   yp-bad-arguments?
   yp-bad-database?
   yp-binding-error?
   yp-unknown-key?
   yp-unknown-map?
   yp-no-domain?
   yp-portmap-failure?
   yp-allocation-failure?
   yp-rpc-failure?
   yp-bind-failure?
   yp-server-error?


** function reference

   This sections gives an brief overview on the functions provided by
   the scsh-yp package.  The man pages of the underlying yp_*()
   function calls explain these functions in greater detail.  Almost
   all of the functions listed here have an optional parameter
   DOMAIN that tells YP/NIS which YP/NIS domain you are referring to.
   If this parameter is left out, the default domain will be used,
   that is, the domain name that can be obtained with
   YP-GET-DEFAULT-DOMAIN.

   (yp-get-default-domain) -> string
   Returns the default YP/NIS domain.

   (yp-bind [domain]) -> #t 
   Connect and use to the YP/NIS domain domain.  Returns #t on success
   or raises a yp-error condition.
 
   (yp-unbind [domain]) -> #t
   Unbind from the domain domain.  Returns #t on success or raises a
   yp-error condition.

   (yp-match map key [domain]) -> list-of-strings
   Returns the entries in map (string) that match key (string).  Make
   sure to use a full NIS/YP map name, e.g. "passwd.byname" instead
   "passwd".  May raise an yp-error condition.

   (yp-order map [domain]) -> integer
   Returns the order number of a map (string).  May raise an yp-error.

   (yp-master map [domain]) -> string
   Returns the master server that serves map (string).  May raise an
   yp-error.

   (yp-first map [domain]) -> {string string}
   (yp-next map key [domain]) -> {string-or-bool string-or-bool}
   Use YP-FIRST and YP-NEXT to step through all entries of map
   (string).  YP-FIRST returns two strings: The key and the complete
   map entry for that key.  To obtain the next value(s) in the map
   call YP-NEXT with the key.  If YP-NEXT hits the end of the map it
   returns {#f #f}.  See `Examples' section for an example.  Both
   functions may raise an yp-error.

   (yp-map->list map [domain]) -> list-of-pairs
   Reads all entries from a YP/NIS map (string) and return them as a
   list of pairs.  The CAR of each pair is the key of the entry, the
   CDR the complete entry.  May raise an yp-error.

Footnotes: 
[1]  <http://www.scsh.net/>