documentation

README

@@ -0,0 +1,115 @@
+						-*- 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/>
+