scsh-yp/README

196 lines
6.1 KiB
Plaintext
Raw Normal View History

2003-12-04 08:19:26 -05:00
-*- outline -*-
2003-12-04 04:06:17 -05:00
2003-12-04 08:19:26 -05:00
scsh-yp 0.1
2003-12-04 04:06:17 -05:00
* 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
2003-12-04 08:19:26 -05:00
lookup data in a NIS or YP database without calling the
corresponding external program (i. e. ypbind, ypmatch etc).
2003-12-04 04:06:17 -05:00
** 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
2003-12-04 08:19:26 -05:00
directory of your scsh library path.
2003-12-04 04:06:17 -05:00
** 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.
2003-12-04 08:19:26 -05:00
If the installation directory of scsh-yp is in scsh's library path
scsh-yp load scsh-yp at start-up by
2003-12-04 04:06:17 -05:00
2003-12-04 08:19:26 -05:00
scsh -lel scsh-yp-0.1/scheme/load-yp.scm
2003-12-04 04:06:17 -05:00
The scsh user manual explains how to set the library path. Now
everything is set up to open the package "yp":
2003-12-04 08:19:26 -05:00
,open yp
2003-12-04 04:06:17 -05:00
2003-12-04 08:19:26 -05:00
You can also load scsh-yp interactively using the command
,exec ,load <path>/scheme/load-yp.scm
where <path> is the argument of the --prefix option of configure.
2003-12-04 04:06:17 -05:00
2003-12-04 08:19:26 -05:00
* Using scsh-yp
2003-12-04 04:06:17 -05:00
2003-12-04 08:19:26 -05:00
** 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.
2003-12-04 04:06:17 -05:00
** 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
2003-12-04 08:19:26 -05:00
Connect and use to the YP/NIS domain DOMAIN. Returns #t on success
2003-12-04 04:06:17 -05:00
or raises a yp-error condition.
(yp-unbind [domain]) -> #t
2003-12-04 08:19:26 -05:00
Unbind from the domain DOMAIN. Returns #t on success or raises a
2003-12-04 04:06:17 -05:00
yp-error condition.
(yp-match map key [domain]) -> list-of-strings
2003-12-04 08:19:26 -05:00
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.
2003-12-04 04:06:17 -05:00
(yp-order map [domain]) -> integer
2003-12-04 08:19:26 -05:00
Returns the order number of a MAP (a string). May raise an yp-error.
2003-12-04 04:06:17 -05:00
(yp-master map [domain]) -> string
2003-12-04 08:19:26 -05:00
Returns the master server that serves MAP (a string). May raise an
2003-12-04 04:06:17 -05:00
yp-error.
(yp-first map [domain]) -> {string string}
(yp-next map key [domain]) -> {string-or-bool string-or-bool}
2003-12-04 08:19:26 -05:00
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
2003-12-04 04:06:17 -05:00
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
2003-12-04 08:19:26 -05:00
returns {#f #f}. Both functions may raise an yp-error.
2003-12-04 04:06:17 -05:00
(yp-map->list map [domain]) -> list-of-pairs
2003-12-04 08:19:26 -05:00
Reads all entries from a YP/NIS MAP (a string) and return them as a
2003-12-04 04:06:17 -05:00
list of pairs. The CAR of each pair is the key of the entry, the
2003-12-04 08:19:26 -05:00
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 <scsh-bugs@zurich.ai.mit.edu>.
* 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<EFBFBD>bingen, December 2003
2003-12-04 04:06:17 -05:00
Footnotes:
[1] <http://www.scsh.net/>