scsh-yp/doc/scsh-yp.txt

161 lines
4.9 KiB
Plaintext
Raw Blame History

-*- 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 and 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 <scsh-bugs@zurich.ai.mit.edu>.
* 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
<knauel@informatik.uni-tuebingen.de>
T<>bingen, December 2003
Footnotes:
[1] <http://www.scsh.net/>