-*- 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 corresponding 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= --with-scsh-includes= 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 of your scsh library path. ** 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 of scsh-yp is in scsh's library path you can load scsh-yp at start-up by 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 You can also load scsh-yp interactively using the command ,exec ,load /scheme/load-yp.scm where is the argument of the --prefix option of configure. * Using scsh-yp ** yp-error condition hierarchy Scsh-yp uses scsh's condition system to signal exceptions. In this system conditions are organized hierarchially. Use one of the following predicates to check what kind of error occurred: yp-error? | +-- yp-communication-error? | | | +-- yp-bad-domain? | +-- yp-no-domain? | +-- yp-portmap-failure? | +-- yp-rpc-failure? | +-- yp-bind-failure? | +-- yp-binding-error? | +-- yp-server-error? | +-- yp-bad-arguments? | +-- yp-bad-database? | +-- yp-unknown-resource-error? | | | +-- yp-unknown-key? | +-- yp-unknown-map? | +-- yp-internal-error? These errors correspond to the return codes of C yp_*() function calls. The yp_* man pages explain the error codes in detail. ** 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 omitted, 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 (a string) that match KEY (a string). Make sure to use a full NIS/YP map name, e.g. "passwd.byname" instead of "passwd". May raise an yp-error condition. (yp-order map [domain]) -> integer Returns the order number of a MAP (a string). May raise an yp-error. (yp-master map [domain]) -> string Returns the master server that serves MAP (a 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 (a 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}. Both functions may raise an yp-error. (yp-map->list map [domain]) -> list-of-pairs Reads all entries from a YP/NIS MAP (a string) and return them as a list of pairs. The CAR of each pair is the key of the entry, the CDR contains the complete entry. May raise an yp-error. ** Examples Using yp-first and yp-next to obtain a list of all keys in the map passwd.byname (uses RECEIVE from SRFI 8): ,---- | define (yp-all-keys map domain) | (receive (key val) (yp-first map domain) | (let loop ((key key) (res (cons key '()))) | (receive (key val) | (yp-next map key domain) | (if val | (loop key (cons key res)) | res))))) | | > (yp-all-keys "passwd.byname" "wsi") | (... very long list ...) `---- Searching for an entry in passwd.byname an parsing the result: ,---- | (define (yp-account-data user) | (let ((splitter (infix-splitter (rx ":")))) | (cond ((yp-match "passwd.byname" user) | => splitter) | (else #f)))) | | > (yp-account-data "knauel") | '("knauel" "geheim" "5324" "3010" "Eric Knauel" | "/afs/informatik.uni-tuebingen.de/home/knauel" "/bin/tcsh") | > (yp-account-data "klabautermann") | | Error: yp-unknown-key | 5 | (yp-match map "passwd.byname" key "klabautermann" domain ---) | 1> `---- * Caveats There is only a synchronous high-level interface to YP/NIS, so calling a yp_*() function causes scsh and all scsh threads to block. I hope to solve that problem in a future version of scsh-yp. * Bug reporting Please report bugs to . * Version history Dec 2003: released 0.1 * Acknowlegdements I would like to thank Martin Gasbichler who was fearless enough to engage in a battle with automake and wrote the automake build files. Eric Knauel Tübingen, December 2003 Footnotes: [1]