diff --git a/README b/README index ef5480f..f2d8345 100644 --- a/README +++ b/README @@ -1,13 +1,13 @@ - -*- outline -*- + -*- outline -*- - scsh-yp 0.1 + 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). + lookup data in a NIS or YP database without calling the + corresponding external program (i. e. ypbind, ypmatch etc). ** How to install @@ -22,7 +22,7 @@ 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. + directory of your scsh library path. ** Running scsh-yp @@ -30,37 +30,55 @@ 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 + If the installation directory of scsh-yp is in scsh's library path + scsh-yp load scsh-yp at start-up by - scsh -lel scsh-yp-0.1/scheme/load-yp.scm + 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 + ,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 -** conditions and errors +** yp-error condition hierarchy - yp-error? - yp-communication-error? - yp-unknown-resource-error? - yp-internal-error? + 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-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? + 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 @@ -77,38 +95,100 @@ Returns the default YP/NIS domain. (yp-bind [domain]) -> #t - Connect and use to the YP/NIS domain domain. Returns #t on success + 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 + 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. + 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 "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. + 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 (string). May raise an + 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 - (string). YP-FIRST returns two strings: The key and the complete + 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}. See `Examples' section for an example. Both - functions may raise an yp-error. + 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 (string) and return them as a + 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 the complete entry. May raise an yp-error. + 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 "knauel3" domain ---) + | 1> + `---- + +* Caveats + + There is only a synchronous high-level interface to YP/NIS, so, + call a yp_*() function causes to whole 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]