From 6d25589040a06f7ae020163edc0fdd411d04e6af Mon Sep 17 00:00:00 2001 From: eknauel Date: Mon, 29 Mar 2004 12:06:37 +0000 Subject: [PATCH] moved docs --- doc/scsh-yp.txt | 160 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 160 insertions(+) create mode 100644 doc/scsh-yp.txt diff --git a/doc/scsh-yp.txt b/doc/scsh-yp.txt new file mode 100644 index 0000000..c6e0e32 --- /dev/null +++ b/doc/scsh-yp.txt @@ -0,0 +1,160 @@ + -*- 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). + +* 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 + + Mar 2004: released 0.2 + 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] +