summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorGreg J. Badros <gjb@cs.washington.edu>1999-12-13 03:40:23 +0000
committerGreg J. Badros <gjb@cs.washington.edu>1999-12-13 03:40:23 +0000
commit4079f87ed21341a8654ecaa29ac3e6a2344d9252 (patch)
treed9381ae0256c3daae81acde78bf40d1d12cd12e5
parent75948d1b314685312f8d62315c4bec6bd003fca4 (diff)
downloadguile-4079f87ed21341a8654ecaa29ac3e6a2344d9252.tar.gz
* Makefile.am: Fix ETAGS_ARGS to recognize GUILE_PROC,
GUILE_PROC1. Build guile-procedures.txt, and add that file to pkgdata_DATA. * load.c: Added `pkgdata-dir', `site-dir', `library-dir' primitives. * guile-doc-snarf.awk: Drop trailing space when no arguments: e.g., "(foo )" is now "(foo)". * *.c: moved all the documentation for primitives from guile-doc/ref/{appendices,posix,scheme}.texi into the source code. This leaves about half of the primitives undocumented. Also, all the markup is currently still texinfo. I don't have a problem with texinfo per se, but the markup is not very descriptive or accurate.
-rw-r--r--libguile/Makefile.am9
-rw-r--r--libguile/alist.c67
-rw-r--r--libguile/coop-threads.c6
-rw-r--r--libguile/debug.c5
-rw-r--r--libguile/dynl.c91
-rw-r--r--libguile/dynwind.c55
-rw-r--r--libguile/error.c14
-rw-r--r--libguile/eval.c16
-rw-r--r--libguile/evalext.c2
-rw-r--r--libguile/filesys.c226
-rw-r--r--libguile/fports.c83
-rw-r--r--libguile/gc.c8
-rw-r--r--libguile/guile-doc-snarf.awk1
-rw-r--r--libguile/hash.c7
-rw-r--r--libguile/hashtab.c45
-rw-r--r--libguile/ioext.c76
-rw-r--r--libguile/keywords.c6
-rw-r--r--libguile/list.c59
-rw-r--r--libguile/load.c56
-rw-r--r--libguile/macros.c8
-rw-r--r--libguile/net_db.c85
-rw-r--r--libguile/numbers.c114
-rw-r--r--libguile/objprop.c13
-rw-r--r--libguile/ports.c119
-rw-r--r--libguile/posix.c317
-rw-r--r--libguile/procprop.c9
-rw-r--r--libguile/procs.c5
-rw-r--r--libguile/ramap.c51
-rw-r--r--libguile/regex-posix.c47
-rw-r--r--libguile/root.c49
-rw-r--r--libguile/scmsigs.c52
-rw-r--r--libguile/simpos.c17
-rw-r--r--libguile/socket.c219
-rw-r--r--libguile/stacks.c4
-rw-r--r--libguile/stime.c76
-rw-r--r--libguile/strings.c21
-rw-r--r--libguile/strop.c35
-rw-r--r--libguile/strports.c11
-rw-r--r--libguile/struct.c105
-rw-r--r--libguile/symbols.c58
-rw-r--r--libguile/threads.c38
-rw-r--r--libguile/throw.c28
-rw-r--r--libguile/unif.c163
-rw-r--r--libguile/vectors.c4
-rw-r--r--libguile/version.c11
-rw-r--r--libguile/vports.c41
-rw-r--r--libguile/weaks.c27
47 files changed, 2239 insertions, 320 deletions
diff --git a/libguile/Makefile.am b/libguile/Makefile.am
index aa980b026..1297330be 100644
--- a/libguile/Makefile.am
+++ b/libguile/Makefile.am
@@ -26,7 +26,8 @@ AUTOMAKE_OPTIONS = foreign
## building.
INCLUDES = -I.. -I$(srcdir)/.. ${THREAD_CPPFLAGS}
-ETAGS_ARGS = --regex='/SCM_\(GLOBAL_\)?\(G?PROC\|G?PROC1\|SYMBOL\|VCELL\|CONST_LONG\).*\"\([^\"]\)*\"/\3/'
+ETAGS_ARGS = --regex='/SCM_\(GLOBAL_\)?\(G?PROC\|G?PROC1\|SYMBOL\|VCELL\|CONST_LONG\).*\"\([^\"]\)*\"/\3/' \
+ --regex='/[ \t]*GUILE_[G]?PROC1?[ \t]*(\([^,]*\),[^,]*/\1/'
lib_LTLIBRARIES = libguile.la
bin_PROGRAMS = guile
@@ -165,6 +166,12 @@ SUFFIXES = .x .doc
./guile-doc-snarf $< $(DEFS) $(INCLUDES) $(CPPFLAGS) $(CFLAGS) $< \
|| { rm $@; false; }
+## GJB:FIXME:: this is ugly; generate the *.doc files from the *.x file list, above
+guile-procedures.txt: *.doc
+ cat *.doc > $@
+
+pkgdata_DATA = guile-procedures.txt
+
## Add -MG to make the .x magic work with auto-dep code.
MKDEP = gcc -M -MG $(DEFS) $(INCLUDES) $(CPPFLAGS) $(CFLAGS)
diff --git a/libguile/alist.c b/libguile/alist.c
index ed560233d..69edf3e6c 100644
--- a/libguile/alist.c
+++ b/libguile/alist.c
@@ -55,7 +55,10 @@
GUILE_PROC(scm_acons, "acons", 3, 0, 0,
(SCM w, SCM x, SCM y),
-"")
+"Adds a new key-value pair to @var{alist}. A new pair is
+created whose car is @var{key} and whose cdr is @var{value}, and the
+pair is consed onto @var{alist}, and the new list is returned. This
+function is @emph{not} destructive; @var{alist} is not modified.")
#define FUNC_NAME s_scm_acons
{
register SCM z;
@@ -74,7 +77,8 @@ GUILE_PROC(scm_acons, "acons", 3, 0, 0,
GUILE_PROC (scm_sloppy_assq, "sloppy-assq", 2, 0, 0,
(SCM x, SCM alist),
-"")
+"Behaves like @code{assq} but does not do any error checking.
+Recommended only for use in Guile internals.")
#define FUNC_NAME s_scm_sloppy_assq
{
@@ -92,7 +96,8 @@ GUILE_PROC (scm_sloppy_assq, "sloppy-assq", 2, 0, 0,
GUILE_PROC (scm_sloppy_assv, "sloppy-assv", 2, 0, 0,
(SCM x, SCM alist),
-"")
+"Behaves like @code{assv} but does not do any error checking.
+Recommended only for use in Guile internals.")
#define FUNC_NAME s_scm_sloppy_assv
{
for (; SCM_NIMP (alist) && SCM_CONSP (alist); alist = SCM_CDR (alist))
@@ -110,7 +115,8 @@ GUILE_PROC (scm_sloppy_assv, "sloppy-assv", 2, 0, 0,
GUILE_PROC (scm_sloppy_assoc, "sloppy-assoc", 2, 0, 0,
(SCM x, SCM alist),
-"")
+"Behaves like @code{assoc} but does not do any error checking.
+Recommended only for use in Guile internals.")
#define FUNC_NAME s_scm_sloppy_assoc
{
for (; SCM_NIMP (alist) && SCM_CONSP (alist); alist = SCM_CDR (alist))
@@ -130,7 +136,15 @@ GUILE_PROC (scm_sloppy_assoc, "sloppy-assoc", 2, 0, 0,
GUILE_PROC(scm_assq, "assq", 2, 0, 0,
(SCM x, SCM alist),
-"")
+"@deffnx primitive assv key alist
+@deffnx primitive assoc key alist
+Fetches the entry in @var{alist} that is associated with @var{key}. To
+decide whether the argument @var{key} matches a particular entry in
+@var{alist}, @code{assq} compares keys with @code{eq?}, @code{assv}
+uses @code{eqv?} and @code{assoc} uses @code{equal?}. If @var{key}
+cannot be found in @var{alist} (according to whichever equality
+predicate is in use), then @code{#f} is returned. These functions
+return the entire alist entry found (i.e. both the key and the value).")
#define FUNC_NAME s_scm_assq
{
SCM tmp;
@@ -167,7 +181,7 @@ GUILE_PROC(scm_assv, "assv", 2, 0, 0,
GUILE_PROC(scm_assoc, "assoc", 2, 0, 0,
(SCM x, SCM alist),
-"")
+"See @code{assq}.")
#define FUNC_NAME s_scm_assoc
{
SCM tmp;
@@ -185,7 +199,18 @@ GUILE_PROC(scm_assoc, "assoc", 2, 0, 0,
GUILE_PROC (scm_assq_ref, "assq-ref", 2, 0, 0,
(SCM alist, SCM key),
-"")
+"@deffnx primitive assv-ref alist key
+@deffnx primitive assoc-ref alist key
+Like @code{assq}, @code{assv} and @code{assoc}, except that only the
+value associated with @var{key} in @var{alist} is returned. These
+functions are equivalent to
+
+@lisp
+(let ((ent (@var{associator} @var{key} @var{alist})))
+ (and ent (cdr ent)))
+@end lisp
+
+where @var{associator} is one of @code{assq}, @code{assv} or @code{assoc}.")
#define FUNC_NAME s_scm_assq_ref
{
SCM handle;
@@ -202,7 +227,7 @@ GUILE_PROC (scm_assq_ref, "assq-ref", 2, 0, 0,
GUILE_PROC (scm_assv_ref, "assv-ref", 2, 0, 0,
(SCM alist, SCM key),
-"")
+"See @code{assq-ref}.")
#define FUNC_NAME s_scm_assv_ref
{
SCM handle;
@@ -219,7 +244,7 @@ GUILE_PROC (scm_assv_ref, "assv-ref", 2, 0, 0,
GUILE_PROC (scm_assoc_ref, "assoc-ref", 2, 0, 0,
(SCM alist, SCM key),
-"")
+"See @code{assq-ref}.")
#define FUNC_NAME s_scm_assoc_ref
{
SCM handle;
@@ -240,7 +265,16 @@ GUILE_PROC (scm_assoc_ref, "assoc-ref", 2, 0, 0,
GUILE_PROC (scm_assq_set_x, "assq-set!", 3, 0, 0,
(SCM alist, SCM key, SCM val),
-"")
+"@deffnx primitive assv-set! alist key value
+@deffnx primitive assoc-set! alist key value
+Reassociate @var{key} in @var{alist} with @var{value}: find any existing
+@var{alist} entry for @var{key} and associate it with the new
+@var{value}. If @var{alist} does not contain an entry for @var{key},
+add a new one. Return the (possibly new) alist.
+
+These functions do not attempt to verify the structure of @var{alist},
+and so may cause unusual results if passed an object that is not an
+association list.")
#define FUNC_NAME s_scm_assq_set_x
{
SCM handle;
@@ -258,7 +292,7 @@ GUILE_PROC (scm_assq_set_x, "assq-set!", 3, 0, 0,
GUILE_PROC (scm_assv_set_x, "assv-set!", 3, 0, 0,
(SCM alist, SCM key, SCM val),
-"")
+"See @code{assq-set!}.")
#define FUNC_NAME s_scm_assv_set_x
{
SCM handle;
@@ -276,7 +310,7 @@ GUILE_PROC (scm_assv_set_x, "assv-set!", 3, 0, 0,
GUILE_PROC (scm_assoc_set_x, "assoc-set!", 3, 0, 0,
(SCM alist, SCM key, SCM val),
-"")
+"See @code{assq-set!}.")
#define FUNC_NAME s_scm_assoc_set_x
{
SCM handle;
@@ -297,7 +331,10 @@ GUILE_PROC (scm_assoc_set_x, "assoc-set!", 3, 0, 0,
GUILE_PROC (scm_assq_remove_x, "assq-remove!", 2, 0, 0,
(SCM alist, SCM key),
-"")
+"@deffnx primitive assv-remove! alist key
+@deffnx primitive assoc-remove! alist key
+Delete any entry in @var{alist} associated with @var{key}, and return
+the resulting alist.")
#define FUNC_NAME s_scm_assq_remove_x
{
SCM handle;
@@ -315,7 +352,7 @@ GUILE_PROC (scm_assq_remove_x, "assq-remove!", 2, 0, 0,
GUILE_PROC (scm_assv_remove_x, "assv-remove!", 2, 0, 0,
(SCM alist, SCM key),
-"")
+"See @code{assq-remove!}.")
#define FUNC_NAME s_scm_assv_remove_x
{
SCM handle;
@@ -333,7 +370,7 @@ GUILE_PROC (scm_assv_remove_x, "assv-remove!", 2, 0, 0,
GUILE_PROC (scm_assoc_remove_x, "assoc-remove!", 2, 0, 0,
(SCM alist, SCM key),
-"")
+"See @code{assq-remove!}.")
#define FUNC_NAME s_scm_assoc_remove_x
{
SCM handle;
diff --git a/libguile/coop-threads.c b/libguile/coop-threads.c
index 88d83967b..c7f4e60a7 100644
--- a/libguile/coop-threads.c
+++ b/libguile/coop-threads.c
@@ -221,14 +221,8 @@ scheme_launch_thread (void *p)
SCM_DEFER_INTS;
}
-#ifdef __STDC__
SCM
scm_call_with_new_thread (SCM argl)
-#else
-SCM
-scm_call_with_new_thread (argl)
- SCM argl;
-#endif
{
SCM thread;
diff --git a/libguile/debug.c b/libguile/debug.c
index c8da85171..05ad8dab3 100644
--- a/libguile/debug.c
+++ b/libguile/debug.c
@@ -483,7 +483,10 @@ GUILE_PROC (scm_procedure_environment, "procedure-environment", 1, 0, 0,
*/
GUILE_PROC (scm_local_eval, "local-eval", 1, 1, 0,
(SCM exp, SCM env),
-"")
+"Evaluate @var{exp} in its environment. If @var{env} is supplied,
+it is the environment in which to evaluate @var{exp}. Otherwise,
+@var{exp} must be a memoized code object (in which case, its environment
+is implicit).")
#define FUNC_NAME s_scm_local_eval
{
if (SCM_UNBNDP (env))
diff --git a/libguile/dynl.c b/libguile/dynl.c
index 7d957e05c..b33a64a7b 100644
--- a/libguile/dynl.c
+++ b/libguile/dynl.c
@@ -173,7 +173,11 @@ scm_register_module_xxx (char *module_name, void *init_func)
GUILE_PROC (scm_registered_modules, "c-registered-modules", 0, 0, 0,
(),
-"")
+"Return a list of the object code modules that have been imported into
+the current Guile process. Each element of the list is a pair whose
+car is the name of the module (as it might be used by
+@code{use-modules}, for instance), and whose cdr is the function handle
+for that module's initializer function.")
#define FUNC_NAME s_scm_registered_modules
{
SCM res;
@@ -190,7 +194,11 @@ GUILE_PROC (scm_registered_modules, "c-registered-modules", 0, 0, 0,
GUILE_PROC (scm_clear_registered_modules, "c-clear-registered-modules", 0, 0, 0,
(),
-"")
+"Destroy the list of modules registered with the current Guile process.
+The return value is unspecified. @strong{Warning:} this function does
+not actually unlink or deallocate these modules, but only destroys the
+records of which modules have been loaded. It should therefore be used
+only by module bookkeeping operations.")
#define FUNC_NAME s_scm_clear_registered_modules
{
struct moddata *md1, *md2;
@@ -311,7 +319,9 @@ SCM_SYMBOL (sym_global, "-global");
GUILE_PROC (scm_dynamic_link, "dynamic-link", 1, 0, 1,
(SCM fname, SCM rest),
-"")
+"Open the dynamic library @var{library-file}. A library handle
+representing the opened library is returned; this handle should be used
+as the @var{lib} argument to the following functions.")
#define FUNC_NAME s_scm_dynamic_link
{
SCM z;
@@ -375,7 +385,8 @@ get_dynl_obj (SCM dobj,const char *subr,int argn)
GUILE_PROC (scm_dynamic_object_p, "dynamic-object?", 1, 0, 0,
(SCM obj),
-"")
+"Return @code{#t} if @var{obj} is a dynamic library handle, or @code{#f}
+otherwise.")
#define FUNC_NAME s_scm_dynamic_object_p
{
return SCM_BOOL(SCM_NIMP (obj) && SCM_CAR (obj) == scm_tc16_dynamic_obj);
@@ -384,7 +395,15 @@ GUILE_PROC (scm_dynamic_object_p, "dynamic-object?", 1, 0, 0,
GUILE_PROC (scm_dynamic_unlink, "dynamic-unlink", 1, 0, 0,
(SCM dobj),
-"")
+"Unlink the library represented by @var{library-handle}, and remove any
+imported symbols from the address space.
+GJB:FIXME:DOC: 2nd version below:
+Unlink the indicated object file from the application. The argument
+@var{dynobj} should be one of the values returned by
+@code{dynamic-link}. When @code{dynamic-unlink} has been called on
+@var{dynobj}, it is no longer usable as an argument to the functions
+below and you will get type mismatch errors when you try to.
+")
#define FUNC_NAME s_scm_dynamic_unlink
{
struct dynl_obj *d = get_dynl_obj (dobj, FUNC_NAME, SCM_ARG1);
@@ -398,7 +417,21 @@ GUILE_PROC (scm_dynamic_unlink, "dynamic-unlink", 1, 0, 0,
GUILE_PROC (scm_dynamic_func, "dynamic-func", 2, 0, 0,
(SCM symb, SCM dobj),
-"")
+"Import the symbol @var{func} from @var{lib} (a dynamic library handle).
+A @dfn{function handle} representing the imported function is returned.
+GJB:FIXME:DOC: 2nd version below
+Search the C function indicated by @var{function} (a string or symbol)
+in @var{dynobj} and return some Scheme object that can later be used
+with @code{dynamic-call} to actually call this function. Right now,
+these Scheme objects are formed by casting the address of the function
+to @code{long} and converting this number to its Scheme representation.
+
+Regardless whether your C compiler prepends an underscore @samp{_} to
+the global names in a program, you should @strong{not} include this
+underscore in @var{function}. Guile knows whether the underscore is
+needed or not and will add it when necessary.
+
+")
#define FUNC_NAME s_scm_dynamic_func
{
struct dynl_obj *d;
@@ -418,7 +451,25 @@ GUILE_PROC (scm_dynamic_func, "dynamic-func", 2, 0, 0,
GUILE_PROC (scm_dynamic_call, "dynamic-call", 2, 0, 0,
(SCM func, SCM dobj),
-"")
+"Call @var{lib-thunk}, a procedure of no arguments. If @var{lib-thunk}
+is a string, it is assumed to be a symbol found in the dynamic library
+@var{lib} and is fetched with @code{dynamic-func}. Otherwise, it should
+be a function handle returned by a previous call to @code{dynamic-func}.
+The return value is unspecified.
+GJB:FIXME:DOC 2nd version below
+Call the C function indicated by @var{function} and @var{dynobj}. The
+function is passed no arguments and its return value is ignored. When
+@var{function} is something returned by @code{dynamic-func}, call that
+function and ignore @var{dynobj}. When @var{function} is a string (or
+symbol, etc.), look it up in @var{dynobj}; this is equivalent to
+
+@smallexample
+(dynamic-call (dynamic-func @var{function} @var{dynobj} #f))
+@end smallexample
+
+Interrupts are deferred while the C function is executing (with
+@code{SCM_DEFER_INTS}/@code{SCM_ALLOW_INTS}).
+")
#define FUNC_NAME s_scm_dynamic_call
{
void (*fptr)();
@@ -435,7 +486,31 @@ GUILE_PROC (scm_dynamic_call, "dynamic-call", 2, 0, 0,
GUILE_PROC (scm_dynamic_args_call, "dynamic-args-call", 3, 0, 0,
(SCM func, SCM dobj, SCM args),
-"")
+"Call @var{proc}, a dynamically loaded function, passing it the argument
+list @var{args} (a list of strings). As with @code{dynamic-call},
+@var{proc} should be either a function handle or a string, in which case
+it is first fetched from @var{lib} with @code{dynamic-func}.
+
+@var{proc} is assumed to return an integer, which is used as the return
+value from @code{dynamic-args-call}.
+
+GJB:FIXME:DOC 2nd version below
+Call the C function indicated by @var{function} and @var{dynobj}, just
+like @code{dynamic-call}, but pass it some arguments and return its
+return value. The C function is expected to take two arguments and
+return an @code{int}, just like @code{main}:
+
+@smallexample
+int c_func (int argc, char **argv);
+@end smallexample
+
+The parameter @var{args} must be a list of strings and is converted into
+an array of @code{char *}. The array is passed in @var{argv} and its
+size in @var{argc}. The return value is converted to a Scheme number
+and returned from the call to @code{dynamic-args-call}.
+
+
+")
#define FUNC_NAME s_scm_dynamic_args_call
{
int (*fptr) (int argc, char **argv);
diff --git a/libguile/dynwind.c b/libguile/dynwind.c
index e367a892c..8b6fedd70 100644
--- a/libguile/dynwind.c
+++ b/libguile/dynwind.c
@@ -72,7 +72,60 @@
GUILE_PROC(scm_dynamic_wind, "dynamic-wind", 3, 0, 0,
(SCM thunk1, SCM thunk2, SCM thunk3),
-"")
+"All three arguments must be 0-argument procedures.
+
+@var{in-guard} is called, then @var{thunk}, then @var{out-guard}.
+
+If, any time during the execution of @var{thunk}, the continuation
+of the @code{dynamic-wind} expression is escaped non-locally, @var{out-guard}
+is called. If the continuation of the dynamic-wind is re-entered,
+@var{in-guard} is called. Thus @var{in-guard} and @var{out-guard} may
+be called any number of times.
+
+@example
+(define x 'normal-binding)
+@result{} x
+
+(define a-cont (call-with-current-continuation
+ (lambda (escape)
+ (let ((old-x x))
+ (dynamic-wind
+ ;; in-guard:
+ ;;
+ (lambda () (set! x 'special-binding))
+
+ ;; thunk
+ ;;
+ (lambda () (display x) (newline)
+ (call-with-current-continuation escape)
+ (display x) (newline)
+ x)
+
+ ;; out-guard:
+ ;;
+ (lambda () (set! x old-x)))))))
+
+;; Prints:
+special-binding
+;; Evaluates to:
+@result{} a-cont
+
+x
+@result{} normal-binding
+
+(a-cont #f)
+;; Prints:
+special-binding
+;; Evaluates to:
+@result{} a-cont ;; the value of the (define a-cont...)
+
+x
+@result{} normal-binding
+
+a-cont
+@result{} special-binding
+@end example
+")
#define FUNC_NAME s_scm_dynamic_wind
{
SCM ans;
diff --git a/libguile/error.c b/libguile/error.c
index 3dad73300..0e53c4c5e 100644
--- a/libguile/error.c
+++ b/libguile/error.c
@@ -89,7 +89,17 @@ scm_error (SCM key, const char *subr, const char *message, SCM args, SCM rest)
/* Scheme interface to scm_error. */
GUILE_PROC(scm_error_scm, "scm-error", 5, 0, 0,
(SCM key, SCM subr, SCM message, SCM args, SCM rest),
-"")
+"Raise an error with key @var{key}. @var{subr} can be a string naming
+the procedure associated with the error, or @code{#f}. @var{message}
+is the error message string, possibly containing @code{%S} and @code{%s}
+escapes. When an error is reported, these are replaced by formating the
+corresponding members of @var{args}: @code{%s} formats using @code{display}
+and @code{%S} formats using @code{write}. @var{data} is a
+list or @code{#f} depending on @var{key}: if @var{key} is
+@code{system-error} then it should be a list
+containing the Unix @code{errno} value; If @var{key} is @code{signal} then
+it should be a list containing the Unix signal number; otherwise it
+will usually be @code{#f}.")
#define FUNC_NAME s_scm_error_scm
{
char *szSubr;
@@ -106,7 +116,7 @@ GUILE_PROC(scm_error_scm, "scm-error", 5, 0, 0,
GUILE_PROC (scm_strerror, "strerror", 1, 0, 0,
(SCM err),
-"")
+"Returns the Unix error message corresponding to @var{errno}, an integer.")
#define FUNC_NAME s_scm_strerror
{
SCM_VALIDATE_INT(1,err);
diff --git a/libguile/eval.c b/libguile/eval.c
index 7044dda0f..a27b99868 100644
--- a/libguile/eval.c
+++ b/libguile/eval.c
@@ -3725,7 +3725,8 @@ GUILE_PROC(scm_force, "force", 1, 0, 0,
GUILE_PROC (scm_promise_p, "promise?", 1, 0, 0,
(SCM x),
-"")
+"Return true if @var{obj} is a promise, i.e. a delayed computation
+(@pxref{Delayed evaluation,,,r4rs.info,The Revised^4 Report on Scheme}).")
#define FUNC_NAME s_scm_promise_p
{
return SCM_BOOL(SCM_NIMP (x) && (SCM_TYP16 (x) == scm_tc16_promise));
@@ -3751,7 +3752,11 @@ GUILE_PROC (scm_cons_source, "cons-source", 3, 0, 0,
GUILE_PROC (scm_copy_tree, "copy-tree", 1, 0, 0,
(SCM obj),
-"")
+"Recursively copy the data tree that is bound to @var{obj}, and return a
+pointer to the new data structure. @code{copy-tree} recurses down the
+contents of both pairs and vectors (since both cons cells and vector
+cells may point to arbitrary objects), and stops recursing when it hits
+any other object.")
#define FUNC_NAME s_scm_copy_tree
{
SCM ans, tl;
@@ -3795,7 +3800,9 @@ scm_eval_3 (SCM obj, int copyp, SCM env)
GUILE_PROC(scm_eval2, "eval2", 2, 0, 0,
(SCM obj, SCM env_thunk),
-"")
+"Evaluate @var{exp}, a Scheme expression, in the environment designated
+by @var{lookup}, a symbol-lookup function. @code{(eval exp)} is
+equivalent to @code{(eval2 exp *top-level-lookup-closure*)}.")
#define FUNC_NAME s_scm_eval2
{
return scm_eval_3 (obj, 1, scm_top_level_env (env_thunk));
@@ -3804,7 +3811,8 @@ GUILE_PROC(scm_eval2, "eval2", 2, 0, 0,
GUILE_PROC(scm_eval, "eval", 1, 0, 0,
(SCM obj),
-"")
+"Evaluate @var{exp}, a list representing a Scheme expression, in the
+top-level environment.")
#define FUNC_NAME s_scm_eval
{
return scm_eval_3 (obj,
diff --git a/libguile/evalext.c b/libguile/evalext.c
index d95d949b1..fa9d26c26 100644
--- a/libguile/evalext.c
+++ b/libguile/evalext.c
@@ -69,7 +69,7 @@ scm_m_generalized_set_x (SCM xorig, SCM env)
GUILE_PROC (scm_definedp, "defined?", 1, 1, 0,
(SCM sym, SCM env),
-"")
+"Return @code{#t} if @var{sym} is defined in the top-level environment.")
#define FUNC_NAME s_scm_definedp
{
SCM vcell;
diff --git a/libguile/filesys.c b/libguile/filesys.c
index dac0af37b..c2dabd921 100644
--- a/libguile/filesys.c
+++ b/libguile/filesys.c
@@ -124,7 +124,18 @@
GUILE_PROC (scm_chown, "chown", 3, 0, 0,
(SCM object, SCM owner, SCM group),
-"")
+"Change the ownership and group of the file referred to by @var{obj} to
+the integer userid values @var{owner} and @var{group}. @var{obj} can be
+a string containing a file name or a port or integer file descriptor
+which is open on the file (in which case fchown is used as the underlying
+system call). The return value
+is unspecified.
+
+If @var{obj} is a symbolic link, either the
+ownership of the link or the ownership of the referenced file will be
+changed depending on the operating system (lchown is
+unsupported at present). If @var{owner} or @var{group} is specified
+as @code{-1}, then that ID is not changed.")
#define FUNC_NAME s_scm_chown
{
int rv;
@@ -159,7 +170,13 @@ GUILE_PROC (scm_chown, "chown", 3, 0, 0,
GUILE_PROC (scm_chmod, "chmod", 2, 0, 0,
(SCM object, SCM mode),
-"")
+"Changes the permissions of the file referred to by @var{obj}.
+@var{obj} can be a string containing a file name or a port or integer file
+descriptor which is open on a file (in which case @code{fchmod} is used
+as the underlying system call).
+@var{mode} specifies
+the new permissions as a decimal number, e.g., @code{(chmod "foo" #o755)}.
+The return value is unspecified.")
#define FUNC_NAME s_scm_chmod
{
int rv;
@@ -190,7 +207,11 @@ GUILE_PROC (scm_chmod, "chmod", 2, 0, 0,
GUILE_PROC (scm_umask, "umask", 0, 1, 0,
(SCM mode),
-"")
+"If @var{mode} is omitted, retuns a decimal number representing the current
+file creation mask. Otherwise the file creation mask is set to
+@var{mode} and the previous value is returned.
+
+E.g., @code{(umask #o022)} sets the mask to octal 22, decimal 18.")
#define FUNC_NAME s_scm_umask
{
mode_t mask;
@@ -212,7 +233,8 @@ GUILE_PROC (scm_umask, "umask", 0, 1, 0,
GUILE_PROC (scm_open_fdes, "open-fdes", 2, 1, 0,
(SCM path, SCM flags, SCM mode),
-"")
+"Similar to @code{open} but returns a file descriptor instead of a
+port.")
#define FUNC_NAME s_scm_open_fdes
{
int fd;
@@ -232,7 +254,33 @@ GUILE_PROC (scm_open_fdes, "open-fdes", 2, 1, 0,
GUILE_PROC (scm_open, "open", 2, 1, 0,
(SCM path, SCM flags, SCM mode),
-"")
+"Open the file named by @var{path} for reading and/or writing.
+@var{flags} is an integer specifying how the file should be opened.
+@var{mode} is an integer specifying the permission bits of the file, if
+it needs to be created, before the umask is applied. The default is 666
+(Unix itself has no default).
+
+@var{flags} can be constructed by combining variables using @code{logior}.
+Basic flags are:
+
+@defvar O_RDONLY
+Open the file read-only.
+@end defvar
+@defvar O_WRONLY
+Open the file write-only.
+@end defvar
+@defvar O_RDWR
+Open the file read/write.
+@end defvar
+@defvar O_APPEND
+Append to the file instead of truncating.
+@end defvar
+@defvar O_CREAT
+Create the file if it does not already exist.
+@end defvar
+
+See the Unix documentation of the @code{open} system call
+for additional flags.")
#define FUNC_NAME s_scm_open
{
SCM newpt;
@@ -266,7 +314,11 @@ GUILE_PROC (scm_open, "open", 2, 1, 0,
GUILE_PROC (scm_close, "close", 1, 0, 0,
(SCM fd_or_port),
-"")
+"Similar to close-port (@pxref{Generic Port Operations, close-port}),
+but also works on file descriptors. A side
+effect of closing a file descriptor is that any ports using that file
+descriptor are moved to a different file descriptor and have
+their revealed counts set to zero.")
#define FUNC_NAME s_scm_close
{
int rv;
@@ -395,7 +447,60 @@ scm_stat2scm (struct stat *stat_temp)
GUILE_PROC (scm_stat, "stat", 1, 0, 0,
(SCM object),
-"")
+"Returns an object containing various information
+about the file determined by @var{obj}.
+@var{obj} can be a string containing a file name or a port or integer file
+descriptor which is open on a file (in which case @code{fstat} is used
+as the underlying system call).
+
+The object returned by @code{stat} can be passed as a single parameter
+to the following procedures, all of which return integers:
+
+@table @code
+@item stat:dev
+The device containing the file.
+@item stat:ino
+The file serial number, which distinguishes this file from all other
+files on the same device.
+@item stat:mode
+The mode of the file. This includes file type information
+and the file permission bits. See @code{stat:type} and @code{stat:perms}
+below.
+@item stat:nlink
+The number of hard links to the file.
+@item stat:uid
+The user ID of the file's owner.
+@item stat:gid
+The group ID of the file.
+@item stat:rdev
+Device ID; this entry is defined only for character or block
+special files.
+@item stat:size
+The size of a regular file in bytes.
+@item stat:atime
+The last access time for the file.
+@item stat:mtime
+The last modification time for the file.
+@item stat:ctime
+The last modification time for the attributes of the file.
+@item stat:blksize
+The optimal block size for reading or writing the file, in bytes.
+@item stat:blocks
+The amount of disk space that the file occupies measured in units of
+512 byte blocks.
+@end table
+
+In addition, the following procedures return the information
+from stat:mode in a more convenient form:
+
+@table @code
+@item stat:type
+A symbol representing the type of file. Possible values are
+regular, directory, symlink, block-special, char-special,
+fifo, socket and unknown
+@item stat:perms
+An integer representing the access permission bits.
+@end table")
#define FUNC_NAME s_scm_stat
{
int rv;
@@ -440,7 +545,9 @@ GUILE_PROC (scm_stat, "stat", 1, 0, 0,
GUILE_PROC (scm_link, "link", 2, 0, 0,
(SCM oldpath, SCM newpath),
-"")
+"Creates a new name @var{path-to} in the file system for the file
+named by @var{path-from}. If @var{path-from} is a symbolic link, the
+link may or may not be followed depending on the system.")
#define FUNC_NAME s_scm_link
{
int val;
@@ -464,7 +571,8 @@ GUILE_PROC (scm_link, "link", 2, 0, 0,
GUILE_PROC (scm_rename, "rename-file", 2, 0, 0,
(SCM oldname, SCM newname),
-"")
+"Renames the file specified by @var{path-from} to @var{path-to}.
+The return value is unspecified.")
#define FUNC_NAME s_scm_rename
{
int rv;
@@ -493,7 +601,7 @@ GUILE_PROC (scm_rename, "rename-file", 2, 0, 0,
GUILE_PROC(scm_delete_file, "delete-file", 1, 0, 0,
(SCM str),
-"")
+"Deletes (or \"unlinks\") the file specified by @var{path}.")
#define FUNC_NAME s_scm_delete_file
{
int ans;
@@ -508,7 +616,10 @@ GUILE_PROC(scm_delete_file, "delete-file", 1, 0, 0,
GUILE_PROC (scm_mkdir, "mkdir", 1, 1, 0,
(SCM path, SCM mode),
-"")
+"Create a new directory named by @var{path}. If @var{mode} is omitted
+then the permissions of the directory file are set using the current
+umask. Otherwise they are set to the decimal value specified with
+@var{mode}. The return value is unspecified.")
#define FUNC_NAME s_scm_mkdir
{
#ifdef HAVE_MKDIR
@@ -541,7 +652,8 @@ GUILE_PROC (scm_mkdir, "mkdir", 1, 1, 0,
GUILE_PROC (scm_rmdir, "rmdir", 1, 0, 0,
(SCM path),
-"")
+"Remove the existing directory named by @var{path}. The directory must
+be empty for this to succeed. The return value is unspecified.")
#define FUNC_NAME s_scm_rmdir
{
#ifdef HAVE_RMDIR
@@ -569,7 +681,8 @@ long scm_tc16_dir;
GUILE_PROC (scm_directory_stream_p, "directory-stream?", 1, 0, 0,
(SCM obj),
-"")
+"Returns a boolean indicating whether @var{object} is a directory stream
+as returned by @code{opendir}.")
#define FUNC_NAME s_scm_directory_stream_p
{
return SCM_BOOL(SCM_NIMP (obj) && SCM_DIRP (obj));
@@ -578,7 +691,8 @@ GUILE_PROC (scm_directory_stream_p, "directory-stream?", 1, 0, 0,
GUILE_PROC (scm_opendir, "opendir", 1, 0, 0,
(SCM dirname),
-"")
+"Open the directory specified by @var{path} and return a directory
+stream.")
#define FUNC_NAME s_scm_opendir
{
DIR *ds;
@@ -594,7 +708,9 @@ GUILE_PROC (scm_opendir, "opendir", 1, 0, 0,
GUILE_PROC (scm_readdir, "readdir", 1, 0, 0,
(SCM port),
-"")
+"Return (as a string) the next directory entry from the directory stream
+@var{stream}. If there is no remaining entry to be read then the
+end of file object is returned.")
#define FUNC_NAME s_scm_readdir
{
struct dirent *rdent;
@@ -612,7 +728,8 @@ GUILE_PROC (scm_readdir, "readdir", 1, 0, 0,
GUILE_PROC (scm_rewinddir, "rewinddir", 1, 0, 0,
(SCM port),
-"")
+"Reset the directory port @var{stream} so that the next call to
+@code{readdir} will return the first directory entry.")
#define FUNC_NAME s_scm_rewinddir
{
SCM_VALIDATE_OPDIR(1,port);
@@ -625,7 +742,8 @@ GUILE_PROC (scm_rewinddir, "rewinddir", 1, 0, 0,
GUILE_PROC (scm_closedir, "closedir", 1, 0, 0,
(SCM port),
-"")
+"Close the directory stream @var{stream}.
+The return value is unspecified.")
#define FUNC_NAME s_scm_closedir
{
int sts;
@@ -674,7 +792,8 @@ scm_dir_free (SCM p)
GUILE_PROC (scm_chdir, "chdir", 1, 0, 0,
(SCM str),
-"")
+"Change the current working directory to @var{path}.
+The return value is unspecified.")
#define FUNC_NAME s_scm_chdir
{
int ans;
@@ -692,7 +811,7 @@ GUILE_PROC (scm_chdir, "chdir", 1, 0, 0,
GUILE_PROC (scm_getcwd, "getcwd", 0, 0, 0,
(),
-"")
+"Returns the name of the current working directory.")
#define FUNC_NAME s_scm_getcwd
{
#ifdef HAVE_GETCWD
@@ -819,7 +938,29 @@ retrieve_select_type (SELECT_TYPE *set, SCM list)
/* Static helper functions above refer to s_scm_select directly as s_select */
GUILE_PROC (scm_select, "select", 3, 2, 0,
(SCM reads, SCM writes, SCM excepts, SCM secs, SCM usecs),
-"")
+"@var{reads}, @var{writes} and @var{excepts} can be lists or vectors: it
+doesn't matter which, but the corresponding object returned will be
+of the same type.
+Each element is a port or file descriptor on which to wait for
+readability, writeability
+or exceptional conditions respectively. @var{secs} and @var{usecs}
+optionally specify a timeout: @var{secs} can be specified alone, as
+either an integer or a real number, or both @var{secs} and @var{usecs}
+can be specified as integers, in which case @var{usecs} is an additional
+timeout expressed in microseconds.
+
+Buffered input or output data is (currently, but this may change)
+ignored: select uses the underlying file descriptor of a port
+(@code{char-ready?} will check input buffers, output buffers are
+problematic).
+
+The return value is a list of subsets of the input lists or vectors for
+which the requested condition has been met.
+
+It is not quite compatible with scsh's select: scsh checks port buffers,
+doesn't accept input lists or a microsecond timeout, returns multiple
+values instead of a list and has an additional select! interface.
+")
#define FUNC_NAME s_scm_select
{
#ifdef HAVE_SELECT
@@ -905,7 +1046,31 @@ GUILE_PROC (scm_select, "select", 3, 2, 0,
GUILE_PROC (scm_fcntl, "fcntl", 2, 0, 1,
(SCM object, SCM cmd, SCM value),
-"")
+"Apply @var{command} to the specified file descriptor or the underlying
+file descriptor of the specified port. @var{value} is an optional
+integer argument.
+
+Values for @var{command} are:
+
+@table @code
+@item F_DUPFD
+Duplicate a file descriptor
+@item F_GETFD
+Get flags associated with the file descriptor.
+@item F_SETFD
+Set flags associated with the file descriptor to @var{value}.
+@item F_GETFL
+Get flags associated with the open file.
+@item F_SETFL
+Set flags associated with the open file to @var{value}
+@item F_GETOWN
+Get the process ID of a socket's owner, for @code{SIGIO} signals.
+@item F_SETOWN
+Set the process that owns a socket to @var{value}, for @code{SIGIO} signals.
+@item FD_CLOEXEC
+The value used to indicate the "close on exec" flag with @code{F_GETFL} or
+@code{F_SETFL}.
+@end table")
#define FUNC_NAME s_scm_fcntl
{
int rv;
@@ -938,7 +1103,10 @@ GUILE_PROC (scm_fcntl, "fcntl", 2, 0, 1,
GUILE_PROC (scm_fsync, "fsync", 1, 0, 0,
(SCM object),
-"")
+"Copies any unwritten data for the specified output file descriptor to disk.
+If @var{port/fd} is a port, its buffer is flushed before the underlying
+file descriptor is fsync'd.
+The return value is unspecified.")
#define FUNC_NAME s_scm_fsync
{
int fdes;
@@ -963,7 +1131,8 @@ GUILE_PROC (scm_fsync, "fsync", 1, 0, 0,
GUILE_PROC (scm_symlink, "symlink", 2, 0, 0,
(SCM oldpath, SCM newpath),
-"")
+"Create a symbolic link named @var{path-to} with the value (i.e., pointing to)
+@var{path-from}. The return value is unspecified.")
#define FUNC_NAME s_scm_symlink
{
#ifdef HAVE_SYMLINK
@@ -988,7 +1157,9 @@ GUILE_PROC (scm_symlink, "symlink", 2, 0, 0,
GUILE_PROC (scm_readlink, "readlink", 1, 0, 0,
(SCM path),
-"")
+"Returns the value of the symbolic link named by
+@var{path} (a string), i.e., the
+file that the link points to.")
#define FUNC_NAME s_scm_readlink
{
#ifdef HAVE_READLINK
@@ -1021,7 +1192,9 @@ GUILE_PROC (scm_readlink, "readlink", 1, 0, 0,
GUILE_PROC (scm_lstat, "lstat", 1, 0, 0,
(SCM str),
-"")
+"Similar to @code{stat}, but does not follow symbolic links, i.e.,
+it will return information about a symbolic link itself, not the
+file it points to. @var{path} must be a string.")
#define FUNC_NAME s_scm_lstat
{
#ifdef HAVE_LSTAT
@@ -1053,7 +1226,8 @@ GUILE_PROC (scm_lstat, "lstat", 1, 0, 0,
GUILE_PROC (scm_copy_file, "copy-file", 2, 0, 0,
(SCM oldfile, SCM newfile),
-"")
+"Copy the file specified by @var{path-from} to @var{path-to}.
+The return value is unspecified.")
#define FUNC_NAME s_scm_copy_file
{
int oldfd, newfd;
diff --git a/libguile/fports.c b/libguile/fports.c
index 8c1cf7147..73b463286 100644
--- a/libguile/fports.c
+++ b/libguile/fports.c
@@ -131,7 +131,45 @@ scm_fport_buffer_add (SCM port, int read_size, int write_size)
GUILE_PROC (scm_setvbuf, "setvbuf", 2, 1, 0,
(SCM port, SCM mode, SCM size),
-"")
+"Set the buffering mode for @var{port}. @var{mode} can be:
+@table @code
+@item _IONBF
+non-buffered
+@item _IOLBF
+line buffered
+@item _IOFBF
+block buffered, using a newly allocated buffer of @var{size} bytes.
+If @var{size} is omitted, a default size will be used.
+@end table
+
+
+@deffn primitive fcntl fd/port command [value]
+Apply @var{command} to the specified file descriptor or the underlying
+file descriptor of the specified port. @var{value} is an optional
+integer argument.
+
+Values for @var{command} are:
+
+@table @code
+@item F_DUPFD
+Duplicate a file descriptor
+@item F_GETFD
+Get flags associated with the file descriptor.
+@item F_SETFD
+Set flags associated with the file descriptor to @var{value}.
+@item F_GETFL
+Get flags associated with the open file.
+@item F_SETFL
+Set flags associated with the open file to @var{value}
+@item F_GETOWN
+Get the process ID of a socket's owner, for @code{SIGIO} signals.
+@item F_SETOWN
+Set the process that owns a socket to @var{value}, for @code{SIGIO} signals.
+@item FD_CLOEXEC
+The value used to indicate the "close on exec" flag with @code{F_GETFL} or
+@code{F_SETFL}.
+@end table
+")
#define FUNC_NAME s_scm_setvbuf
{
int cmode, csize;
@@ -219,7 +257,48 @@ scm_evict_ports (int fd)
*/
GUILE_PROC(scm_open_file, "open-file", 2, 0, 0,
(SCM filename, SCM modes),
-"")
+"Open the file whose name is @var{string}, and return a port
+representing that file. The attributes of the port are
+determined by the @var{mode} string. The way in
+which this is interpreted is similar to C stdio:
+
+The first character must be one of the following:
+
+@table @samp
+@item r
+Open an existing file for input.
+@item w
+Open a file for output, creating it if it doesn't already exist
+or removing its contents if it does.
+@item a
+Open a file for output, creating it if it doesn't already exist.
+All writes to the port will go to the end of the file.
+The "append mode" can be turned off while the port is in use
+@pxref{Ports and File Descriptors, fcntl}
+@end table
+
+The following additional characters can be appended:
+
+@table @samp
+@item +
+Open the port for both input and output. E.g., @code{r+}: open
+an existing file for both input and output.
+@item 0
+Create an "unbuffered" port. In this case input and output operations
+are passed directly to the underlying port implementation without
+additional buffering. This is likely to slow down I/O operations.
+The buffering mode can be changed while a port is in use
+@pxref{Ports and File Descriptors, setvbuf}
+@item l
+Add line-buffering to the port. The port output buffer will be
+automatically flushed whenever a newline character is written.
+@end table
+
+In theory we could create read/write ports which were buffered in one
+direction only. However this isn't included in the current interfaces.
+
+If a file cannot be opened with the access requested,
+@code{open-file} throws an exception.")
#define FUNC_NAME s_scm_open_file
{
SCM port;
diff --git a/libguile/gc.c b/libguile/gc.c
index 4d79e4a38..bcec7f7d3 100644
--- a/libguile/gc.c
+++ b/libguile/gc.c
@@ -343,7 +343,7 @@ scm_debug_newcell (void)
GUILE_PROC (scm_gc_stats, "gc-stats", 0, 0, 0,
(),
-"")
+"Returns an association list of statistics about Guile's current use of storage. ")
#define FUNC_NAME s_scm_gc_stats
{
int i;
@@ -408,7 +408,8 @@ scm_gc_end ()
GUILE_PROC (scm_object_address, "object-address", 1, 0, 0,
(SCM obj),
-"")
+"Return an integer that for the lifetime of @var{obj} is uniquely
+returned by this function for @var{obj}")
#define FUNC_NAME s_scm_object_address
{
return scm_ulong2num ((unsigned long)obj);
@@ -418,7 +419,8 @@ GUILE_PROC (scm_object_address, "object-address", 1, 0, 0,
GUILE_PROC(scm_gc, "gc", 0, 0, 0,
(),
-"")
+"Scans all of SCM objects and reclaims for further use those that are
+no longer accessible.")
#define FUNC_NAME s_scm_gc
{
SCM_DEFER_INTS;
diff --git a/libguile/guile-doc-snarf.awk b/libguile/guile-doc-snarf.awk
index 9bd6e7b21..78764af32 100644
--- a/libguile/guile-doc-snarf.awk
+++ b/libguile/guile-doc-snarf.awk
@@ -35,6 +35,7 @@ BEGIN { FS="|";
sub(/[ \t]*$/,"",location);
sub(/: /,":",location);
gsub(/[ \t]*\|.*$/,"",copy);
+ sub(/ )/,")",copy);
if (numargs != numactuals && !registering)
{ print location ":*** `" copy "' is improperly registered as having " numactuals " arguments"; }
print " \n" copy (registering?")":"") > dot_doc_file ; }
diff --git a/libguile/hash.c b/libguile/hash.c
index abb1a61bd..3a6665a77 100644
--- a/libguile/hash.c
+++ b/libguile/hash.c
@@ -146,7 +146,12 @@ scm_ihashq (SCM obj, unsigned int n)
GUILE_PROC(scm_hashq, "hashq", 2, 0, 0,
(SCM obj, SCM n),
-"")
+"@deffnx primitive hashv key size
+@deffnx primitive hash key size
+Default hash functions for Guile hash tables. @var{key} is the
+object to be hashed, and @var{size} is the size of the target hash
+table. Each function returns an integer in the range 0 to
+@var{size}-1.")
#define FUNC_NAME s_scm_hashq
{
SCM_VALIDATE_INT_MIN(2,n,0);
diff --git a/libguile/hashtab.c b/libguile/hashtab.c
index 1b438886d..7908b067e 100644
--- a/libguile/hashtab.c
+++ b/libguile/hashtab.c
@@ -166,7 +166,15 @@ scm_hash_fn_remove_x (SCM table,SCM obj,unsigned int (*hash_fn)(),SCM (*assoc_fn
GUILE_PROC (scm_hashq_get_handle, "hashq-get-handle", 2, 0, 0,
(SCM table, SCM obj),
-"")
+"@deffnx primitive hashv-get-handle table key
+@deffnx primitive hash-get-handle table key
+@deffnx primitive hashx-get-handle hasher assoc table key
+These procedures are similar to their @code{-ref} cousins, but return a
+@dfn{handle} from the hash table rather than the value associated with
+@var{key}. By convention, a handle in a hash table is the pair which
+associates a key with a value. Where @code{hashq-ref table key} returns
+only a @code{value}, @code{hashq-get-handle table key} returns the pair
+@code{(key . value)}.")
#define FUNC_NAME s_scm_hashq_get_handle
{
return scm_hash_fn_get_handle (table, obj, scm_ihashq, scm_sloppy_assq, 0);
@@ -176,7 +184,12 @@ GUILE_PROC (scm_hashq_get_handle, "hashq-get-handle", 2, 0, 0,
GUILE_PROC (scm_hashq_create_handle_x, "hashq-create-handle!", 3, 0, 0,
(SCM table, SCM obj, SCM init),
-"")
+"@deffnx primitive hashv-create-handle! table key init
+@deffnx primitive hash-create-handle! table key init
+@deffnx primitive hashx-create-handle! hasher assoc table key init
+These functions look up @var{key} in @var{table} and return its handle,
+If @var{key} is not already present, a new handle is created which
+associates @var{key} with @var{init}.")
#define FUNC_NAME s_scm_hashq_create_handle_x
{
return scm_hash_fn_create_handle_x (table, obj, init, scm_ihashq, scm_sloppy_assq, 0);
@@ -186,7 +199,12 @@ GUILE_PROC (scm_hashq_create_handle_x, "hashq-create-handle!", 3, 0, 0,
GUILE_PROC (scm_hashq_ref, "hashq-ref", 2, 1, 0,
(SCM table, SCM obj, SCM dflt),
-"")
+"@deffnx primitive hashv-ref table key [default]
+@deffnx primitive hash-ref table key [default]
+Look up @var{key} in the hash table @var{table}, and return the
+value (if any) associated with it. If @var{key} is not found,
+return @var{default} (or @code{#f} if no @var{default} argument is
+supplied).")
#define FUNC_NAME s_scm_hashq_ref
{
if (dflt == SCM_UNDEFINED)
@@ -199,7 +217,10 @@ GUILE_PROC (scm_hashq_ref, "hashq-ref", 2, 1, 0,
GUILE_PROC (scm_hashq_set_x, "hashq-set!", 3, 0, 0,
(SCM table, SCM obj, SCM val),
-"")
+"@deffnx primitive hashv-set! table key value
+@deffnx primitive hash-set! table key value
+Find the entry in @var{table} associated with @var{key}, and store
+@var{value} there.")
#define FUNC_NAME s_scm_hashq_set_x
{
return scm_hash_fn_set_x (table, obj, val, scm_ihashq, scm_sloppy_assq, 0);
@@ -210,7 +231,9 @@ GUILE_PROC (scm_hashq_set_x, "hashq-set!", 3, 0, 0,
GUILE_PROC (scm_hashq_remove_x, "hashq-remove!", 2, 0, 0,
(SCM table, SCM obj),
-"")
+"@deffnx primitive hashv-remove! table key
+@deffnx primitive hash-remove! table key
+Remove @var{key} (and any value associated with it) from @var{table}.")
#define FUNC_NAME s_scm_hashq_remove_x
{
return scm_hash_fn_remove_x (table, obj, scm_ihashq, scm_sloppy_assq, scm_delq_x, 0);
@@ -411,7 +434,17 @@ GUILE_PROC (scm_hashx_create_handle_x, "hashx-create-handle!", 5, 0, 0,
GUILE_PROC (scm_hashx_ref, "hashx-ref", 4, 1, 0,
(SCM hash,SCM assoc,SCM table,SCM obj,SCM dflt),
-"")
+"@deffnx primitive hashx-set! hasher assoc table key value
+@deffnx primitive hashx-remove! hasher assoc table key
+These behave the same way as the corresponding @code{ref} and
+@code{set!} functions described above, but use @var{hasher} as a
+hash function and @var{assoc} to compare keys. @code{hasher} must
+be a function that takes two arguments, a key to be hashed and a
+table size. @code{assoc} must be an associator function, like
+@code{assoc}, @code{assq} or @code{assv}.
+
+By way of illustration, @code{hashq-ref table key} is equivalent
+to @code{hashx-ref hashq assq table key}.")
#define FUNC_NAME s_scm_hashx_ref
{
struct scm_ihashx_closure closure;
diff --git a/libguile/ioext.c b/libguile/ioext.c
index b8c070fe9..1ac7eed7c 100644
--- a/libguile/ioext.c
+++ b/libguile/ioext.c
@@ -69,7 +69,19 @@
GUILE_PROC (scm_read_delimited_x, "%read-delimited!", 3, 3, 0,
(SCM delims, SCM buf, SCM gobble, SCM port, SCM start, SCM end),
-"")
+"Read characters from @var{port} into @var{buf} until one of the
+characters in the @var{delims} string is encountered. If @var{gobble?}
+is true, store the delimiter character in @var{buf} as well; otherwise,
+discard it. If @var{port} is not specified, use the value of
+@code{(current-input-port)}. If @var{start} or @var{end} are specified,
+store data only into the substring of @var{buf} bounded by @var{start}
+and @var{end} (which default to the beginning and end of the buffer,
+respectively).
+
+Return a pair consisting of the delimiter that terminated the string and
+the number of characters read. If reading stopped at the end of file,
+the delimiter returned is the @var{eof-object}; if the buffer was filled
+without encountering a delimiter, this value is @var{#f}.")
#define FUNC_NAME s_scm_read_delimited_x
{
long j;
@@ -218,7 +230,12 @@ scm_do_read_line (SCM port, int *len_p)
GUILE_PROC (scm_read_line, "%read-line", 0, 1, 0,
(SCM port),
-"")
+"Read a newline-terminated line from @var{port}, allocating storage as
+necessary. The newline terminator (if any) is removed from the string,
+and a pair consisting of the line and its delimiter is returned. The
+delimiter may be either a newline or the @var{eof-object}; if
+@code{%read-line} is called at the end of file, it returns the pair
+@code{(#<eof> . #<eof>)}.")
#define FUNC_NAME s_scm_read_line
{
scm_port *pt;
@@ -266,7 +283,14 @@ GUILE_PROC (scm_read_line, "%read-line", 0, 1, 0,
GUILE_PROC (scm_write_line, "write-line", 1, 1, 0,
(SCM obj, SCM port),
-"")
+"Display @var{obj} and a newline character to @var{port}. If @var{port}
+is not specified, @code{(current-output-port)} is used. This function
+is equivalent to:
+
+@smalllisp
+(display obj [port])
+(newline [port])
+@end smalllisp")
#define FUNC_NAME s_scm_write_line
{
scm_display (obj, port);
@@ -276,7 +300,11 @@ GUILE_PROC (scm_write_line, "write-line", 1, 1, 0,
GUILE_PROC (scm_ftell, "ftell", 1, 0, 0,
(SCM object),
-"")
+"Returns an integer representing the current position of @var{fd/port},
+measured from the beginning. Equivalent to:
+@smalllisp
+(seek port 0 SEEK_CUR)
+@end smalllisp")
#define FUNC_NAME s_scm_ftell
{
return scm_seek (object, SCM_INUM0, SCM_MAKINUM (SEEK_CUR));
@@ -285,7 +313,8 @@ GUILE_PROC (scm_ftell, "ftell", 1, 0, 0,
GUILE_PROC (scm_fseek, "fseek", 3, 0, 0,
(SCM object, SCM offset, SCM whence),
-"")
+"Obsolete. Almost the same as seek, above, but the return value is
+unspecified.")
#define FUNC_NAME s_scm_fseek
{
scm_seek (object, offset, whence);
@@ -295,7 +324,19 @@ GUILE_PROC (scm_fseek, "fseek", 3, 0, 0,
GUILE_PROC (scm_redirect_port, "redirect-port", 2, 0, 0,
(SCM old, SCM new),
-"")
+"This procedure takes two ports and duplicates the underlying file
+descriptor from @var{old-port} into @var{new-port}. The
+current file descriptor in @var{new-port} will be closed.
+After the redirection the two ports will share a file position
+and file status flags.
+
+The return value is unspecified.
+
+Unexpected behaviour can result if both ports are subsequently used
+and the original and/or duplicate ports are buffered.
+
+This procedure does not have any side effects on other ports or
+revealed counts.")
#define FUNC_NAME s_scm_redirect_port
{
int ans, oldfd, newfd;
@@ -332,7 +373,7 @@ GUILE_PROC (scm_redirect_port, "redirect-port", 2, 0, 0,
GUILE_PROC (scm_dup_to_fdes, "dup->fdes", 1, 1, 0,
(SCM fd_or_port, SCM fd),
-"")
+"Returns an integer file descriptor.")
#define FUNC_NAME s_scm_dup_to_fdes
{
int oldfd, newfd, rv;
@@ -372,7 +413,8 @@ GUILE_PROC (scm_dup_to_fdes, "dup->fdes", 1, 1, 0,
GUILE_PROC (scm_fileno, "fileno", 1, 0, 0,
(SCM port),
-"")
+"Returns the integer file descriptor underlying @var{port}.
+Does not change its revealed count.")
#define FUNC_NAME s_scm_fileno
{
port = SCM_COERCE_OUTPORT (port);
@@ -387,7 +429,8 @@ GUILE_PROC (scm_fileno, "fileno", 1, 0, 0,
if it is not going to assume that the arg is a port */
GUILE_PROC (scm_isatty_p, "isatty?", 1, 0, 0,
(SCM port),
-"")
+"Returns @code{#t} if @var{port} is using a serial
+non-file device, otherwise @code{#f}.")
#define FUNC_NAME s_scm_isatty_p
{
int rv;
@@ -406,7 +449,10 @@ GUILE_PROC (scm_isatty_p, "isatty?", 1, 0, 0,
GUILE_PROC (scm_fdopen, "fdopen", 2, 0, 0,
(SCM fdes, SCM modes),
-"")
+"Returns a new port based on the file descriptor @var{fdes}.
+Modes are given by the string @var{modes}. The revealed count of the port
+is initialized to zero. The modes string is the same as that accepted
+by @ref{File Ports, open-file}.")
#define FUNC_NAME s_scm_fdopen
{
SCM port;
@@ -428,7 +474,12 @@ GUILE_PROC (scm_fdopen, "fdopen", 2, 0, 0,
*/
GUILE_PROC (scm_primitive_move_to_fdes, "primitive-move->fdes", 2, 0, 0,
(SCM port, SCM fd),
-"")
+"Moves the underlying file descriptor for @var{port} to the integer
+value @var{fdes} without changing the revealed count of @var{port}.
+Any other ports already using this descriptor will be automatically
+shifted to new descriptors and their revealed counts reset to zero.
+The return value is @code{#f} if the file descriptor already had the
+required value or @code{#t} if it was moved.")
#define FUNC_NAME s_scm_primitive_move_to_fdes
{
struct scm_fport *stream;
@@ -460,7 +511,8 @@ GUILE_PROC (scm_primitive_move_to_fdes, "primitive-move->fdes", 2, 0, 0,
/* Return a list of ports using a given file descriptor. */
GUILE_PROC(scm_fdes_to_ports, "fdes->ports", 1, 0, 0,
(SCM fd),
-"")
+"Returns a list of existing ports which have @var{fdes} as an
+underlying file descriptor, without changing their revealed counts.")
#define FUNC_NAME s_scm_fdes_to_ports
{
SCM result = SCM_EOL;
diff --git a/libguile/keywords.c b/libguile/keywords.c
index bf009d3a6..c389bde13 100644
--- a/libguile/keywords.c
+++ b/libguile/keywords.c
@@ -109,7 +109,8 @@ scm_c_make_keyword (char *s)
GUILE_PROC(scm_keyword_p, "keyword?", 1, 0, 0,
(SCM obj),
-"")
+"@code{keyword?} returns @code{#t} if the argument @var{kw} is a keyword;
+it returns @code{#f} otherwise.")
#define FUNC_NAME s_scm_keyword_p
{
return SCM_BOOL(SCM_NIMP(obj) && SCM_KEYWORDP (obj));
@@ -119,7 +120,8 @@ GUILE_PROC(scm_keyword_p, "keyword?", 1, 0, 0,
GUILE_PROC(scm_keyword_dash_symbol, "keyword-dash-symbol", 1, 0, 0,
(SCM keyword),
-"")
+"@code{keyword-dash-symbol} [FIXME: have no idea what this does; it is
+not commented.]")
#define FUNC_NAME s_scm_keyword_dash_symbol
{
SCM_VALIDATE_KEYWORD(1,keyword);
diff --git a/libguile/list.c b/libguile/list.c
index 266affd39..038311b94 100644
--- a/libguile/list.c
+++ b/libguile/list.c
@@ -188,7 +188,10 @@ GUILE_PROC(scm_length, "length", 1, 0, 0,
GUILE_PROC (scm_append, "append", 0, 0, 1,
(SCM args),
-"")
+"A destructive version of @code{append} (@pxref{Pairs and Lists,,,r4rs,
+The Revised^4 Report on Scheme}). The cdr field of each list's final
+pair is changed to point to the head of the next list, so no consing is
+performed. Return a pointer to the mutated list.")
#define FUNC_NAME s_scm_append
{
SCM res = SCM_EOL;
@@ -239,7 +242,8 @@ GUILE_PROC (scm_append_x, "append!", 0, 0, 1,
GUILE_PROC(scm_last_pair, "last-pair", 1, 0, 0,
(SCM sx),
-"")
+"Return a pointer to the last pair in @var{lst}, signalling an error if
+@var{lst} is circular.")
#define FUNC_NAME s_scm_last_pair
{
register SCM res = sx;
@@ -267,7 +271,17 @@ GUILE_PROC(scm_last_pair, "last-pair", 1, 0, 0,
GUILE_PROC (scm_reverse, "reverse", 1, 0, 0,
(SCM ls),
-"")
+"A destructive version of @code{reverse} (@pxref{Pairs and Lists,,,r4rs,
+The Revised^4 Report on Scheme}). The cdr of each cell in @var{lst} is
+modified to point to the previous list element. Return a pointer to the
+head of the reversed list.
+
+Caveat: because the list is modified in place, the tail of the original
+list now becomes its head, and the head of the original list now becomes
+the tail. Therefore, the @var{lst} symbol to which the head of the
+original list was bound now points to the tail. To ensure that the head
+of the modified list is not lost, it is wise to save the return value of
+@code{reverse!}")
#define FUNC_NAME s_scm_reverse
{
SCM res = SCM_EOL;
@@ -339,7 +353,7 @@ GUILE_PROC(scm_list_ref, "list-ref", 2, 0, 0,
GUILE_PROC(scm_list_set_x, "list-set!", 3, 0, 0,
(SCM lst, SCM k, SCM val),
-"")
+"Set the @var{k}th element of @var{lst} to @var{val}.")
#define FUNC_NAME s_scm_list_set_x
{
register long i;
@@ -361,7 +375,12 @@ SCM_REGISTER_PROC(s_list_cdr_ref, "list-cdr-ref", 2, 0, 0, scm_list_tail);
GUILE_PROC(scm_list_tail, "list-tail", 2, 0, 0,
(SCM lst, SCM k),
-"")
+"Return the \"tail\" of @var{lst} beginning with its @var{k}th element.
+The first element of the list is considered to be element 0.
+
+@code{list-cdr-ref} and @code{list-tail} are identical. It may help to
+think of @code{list-cdr-ref} as accessing the @var{k}th cdr of the list,
+or returning the results of cdring @var{k} times down @var{lst}.")
#define FUNC_NAME s_scm_list_tail
{
register long i;
@@ -377,7 +396,7 @@ GUILE_PROC(scm_list_tail, "list-tail", 2, 0, 0,
GUILE_PROC(scm_list_cdr_set_x, "list-cdr-set!", 3, 0, 0,
(SCM lst, SCM k, SCM val),
-"")
+"Set the @var{k}th cdr of @var{lst} to @var{val}.")
#define FUNC_NAME s_scm_list_cdr_set_x
{
register long i;
@@ -400,7 +419,8 @@ erout:
GUILE_PROC(scm_list_head, "list-head", 2, 0, 0,
(SCM lst, SCM k),
-"")
+"Copy the first @var{k} elements from @var{lst} into a new list, and
+return it.")
#define FUNC_NAME s_scm_list_head
{
SCM answer;
@@ -424,7 +444,7 @@ GUILE_PROC(scm_list_head, "list-head", 2, 0, 0,
GUILE_PROC (scm_list_copy, "list-copy", 1, 0, 0,
(SCM lst),
-"")
+"Return a (newly-created) copy of @var{lst}.")
#define FUNC_NAME s_scm_list_copy
{
SCM newlst;
@@ -452,7 +472,12 @@ GUILE_PROC (scm_list_copy, "list-copy", 1, 0, 0,
GUILE_PROC (scm_sloppy_memq, "sloppy-memq", 2, 0, 0,
(SCM x, SCM lst),
-"")
+"@deffnx primitive sloppy-memv
+@deffnx primitive sloppy-member
+These procedures behave like @code{memq}, @code{memv} and @code{member}
+(@pxref{Pairs and Lists,,,r4rs, The Revised^4 Report on Scheme}), but do
+not perform any type or error checking. Their use is recommended only
+in writing Guile internals, not for high-level Scheme programs.")
#define FUNC_NAME s_scm_sloppy_memq
{
for(; SCM_NIMP(lst) && SCM_CONSP (lst); lst = SCM_CDR(lst))
@@ -541,7 +566,14 @@ GUILE_PROC(scm_member, "member", 2, 0, 0,
GUILE_PROC(scm_delq_x, "delq!", 2, 0, 0,
(SCM item, SCM lst),
-"")
+"@deffnx primitive delv! item lst
+@deffnx primitive delete! item lst
+These procedures are destructive versions of @code{delq}, @code{delv}
+and @code{delete}: they modify the pointers in the existing @var{lst}
+rather than creating a new list. Caveat evaluator: Like other
+destructive list functions, these functions cannot modify the binding of
+@var{lst}, and so cannot be used to delete the first element of
+@var{lst} destructively.")
#define FUNC_NAME s_scm_delq_x
{
SCM walk;
@@ -614,7 +646,12 @@ GUILE_PROC(scm_delete_x, "delete!", 2, 0, 0,
GUILE_PROC (scm_delq, "delq", 2, 0, 0,
(SCM item, SCM lst),
-"")
+"@deffnx primitive delv item lst
+@deffnx primitive delete item lst
+Return a newly-created copy of @var{lst} with @var{item} removed. These
+procedures mirror @code{memq}, @code{memv} and @code{member}:
+@code{delq} compares elements of @var{lst} against @var{item} with
+@code{eq?}, @code{delv} uses @code{eqv?} and @code{delete} uses @code{equal?}")
#define FUNC_NAME s_scm_delq
{
SCM copy = scm_list_copy (lst);
diff --git a/libguile/load.c b/libguile/load.c
index 59a099afb..5996a6846 100644
--- a/libguile/load.c
+++ b/libguile/load.c
@@ -99,7 +99,12 @@ load (void *data)
GUILE_PROC(scm_primitive_load, "primitive-load", 1, 0, 0,
(SCM filename),
-"")
+"Load @var{file} and evaluate its contents in the top-level environment.
+The load paths are not searched; @var{file} must either be a full
+pathname or be a pathname relative to the current directory. If the
+variable @code{%load-hook} is defined, it should be bound to a procedure
+that will be called before any code is loaded. See documentation for
+@code{%load-hook} later in this section.")
#define FUNC_NAME s_scm_primitive_load
{
SCM hook = *scm_loc_load_hook;
@@ -133,7 +138,9 @@ GUILE_PROC(scm_primitive_load, "primitive-load", 1, 0, 0,
#ifdef SCM_PKGDATA_DIR
GUILE_PROC (scm_sys_package_data_dir, "%package-data-dir", 0, 0, 0,
(),
-"")
+"Return the name of the directory where Scheme packages, modules and
+libraries are kept. On most Unix systems, this will be
+@samp{/usr/local/share/guile}.")
#define FUNC_NAME s_scm_sys_package_data_dir
{
return scm_makfrom0str (SCM_PKGDATA_DIR);
@@ -194,6 +201,35 @@ GUILE_PROC (scm_parse_path, "parse-path", 1, 1, 0,
}
#undef FUNC_NAME
+GUILE_PROC (scm_library_dir, "library-dir", 0,0,0,
+ (),
+"Return the directory where the Guile Scheme library files are installed.
+E.g., may return \"/usr/share/guile/1.3.5\".")
+#define FUNC_NAME s_scm_library_dir
+{
+ return scm_makfrom0str(SCM_LIBRARY_DIR);
+}
+#undef FUNC_NAME
+
+GUILE_PROC (scm_pkgdata_dir, "pkgdata-dir", 0,0,0,
+ (),
+"Return the directory where the Guile package files are installed.
+E.g., may return \"/usr/share/guile\".")
+#define FUNC_NAME s_scm_pkgdata_dir
+{
+ return scm_makfrom0str(SCM_PKGDATA_DIR);
+}
+#undef FUNC_NAME
+
+GUILE_PROC (scm_site_dir, "site-dir", 0,0,0,
+ (),
+"Return the directory where the Guile site files are installed.
+E.g., may return \"/usr/share/guile/site\".")
+#define FUNC_NAME s_scm_site_dir
+{
+ return scm_makfrom0str(SCM_SITE_DIR);
+}
+#undef FUNC_NAME
/* Initialize the global variable %load-path, given the value of the
SCM_SITE_DIR and SCM_LIBRARY_DIR preprocessor symbols and the
@@ -368,7 +404,12 @@ GUILE_PROC(scm_search_path, "search-path", 2, 1, 0,
If FILENAME is absolute, return it unchanged. */
GUILE_PROC(scm_sys_search_load_path, "%search-load-path", 1, 0, 0,
(SCM filename),
-"")
+"Search @var{%load-path} for @var{file}, which must be readable by the
+current user. If @var{file} is found in the list of paths to search or
+is an absolute pathname, return its full pathname. Otherwise, return
+@code{#f}. Filenames may have any of the optional extensions in the
+@code{%load-extensions} list; @code{%search-load-path} will try each
+extension automatically.")
#define FUNC_NAME s_scm_sys_search_load_path
{
SCM path = *scm_loc_load_path;
@@ -387,7 +428,9 @@ GUILE_PROC(scm_sys_search_load_path, "%search-load-path", 1, 0, 0,
GUILE_PROC(scm_primitive_load_path, "primitive-load-path", 1, 0, 0,
(SCM filename),
-"")
+"Search @var{%load-path} for @var{file} and load it into the top-level
+environment. If @var{file} is a relative pathname and is not found in
+the list of search paths, an error is signalled.")
#define FUNC_NAME s_scm_primitive_load_path
{
SCM full_filename;
@@ -420,7 +463,10 @@ SCM_SYMBOL (scm_end_of_file_key, "end-of-file");
GUILE_PROC (scm_read_and_eval_x, "read-and-eval!", 0, 1, 0,
(SCM port),
-"")
+"Read a form from @var{port} (standard input by default), and evaluate it
+(memoizing it in the process) in the top-level environment. If no data
+is left to be read from @var{port}, an @code{end-of-file} error is
+signalled.")
#define FUNC_NAME s_scm_read_and_eval_x
{
SCM form = scm_read (port);
diff --git a/libguile/macros.c b/libguile/macros.c
index ac9485ab5..ea3a02826 100644
--- a/libguile/macros.c
+++ b/libguile/macros.c
@@ -87,7 +87,8 @@ GUILE_PROC(scm_makmmacro, "procedure->memoizing-macro", 1, 0, 0,
GUILE_PROC (scm_macro_p, "macro?", 1, 0, 0,
(SCM obj),
-"")
+"Return @code{#t} if @var{obj} is a regular macro, a memoizing macro or a
+syntax transformer.")
#define FUNC_NAME s_scm_macro_p
{
return SCM_BOOL(SCM_NIMP (obj) && SCM_TYP16 (obj) == scm_tc16_macro);
@@ -101,7 +102,10 @@ SCM_SYMBOL (scm_sym_mmacro, "macro!");
GUILE_PROC (scm_macro_type, "macro-type", 1, 0, 0,
(SCM m),
-"")
+"Return one of the symbols @code{syntax}, @code{macro} or @code{macro!},
+depending on whether @var{obj} is a syntax tranformer, a regular macro,
+or a memoizing macro, respectively. If @var{obj} is not a macro,
+@code{#f} is returned.")
#define FUNC_NAME s_scm_macro_type
{
if (!(SCM_NIMP (m) && SCM_TYP16 (m) == scm_tc16_macro))
diff --git a/libguile/net_db.c b/libguile/net_db.c
index 4afc6d21c..86b883c5f 100644
--- a/libguile/net_db.c
+++ b/libguile/net_db.c
@@ -84,7 +84,13 @@ extern int inet_aton ();
GUILE_PROC (scm_inet_aton, "inet-aton", 1, 0, 0,
(SCM address),
-"")
+"Converts a string containing an Internet host address in the traditional
+dotted decimal notation into an integer.
+
+@smalllisp
+(inet-aton "127.0.0.1") @result{} 2130706433
+
+@end smalllisp")
#define FUNC_NAME s_scm_inet_aton
{
struct in_addr soka;
@@ -101,7 +107,12 @@ GUILE_PROC (scm_inet_aton, "inet-aton", 1, 0, 0,
GUILE_PROC (scm_inet_ntoa, "inet-ntoa", 1, 0, 0,
(SCM inetid),
-"")
+"Converts an integer Internet host address into a string with the
+traditional dotted decimal representation.
+
+@smalllisp
+(inet-ntoa 2130706433) @result{} "127.0.0.1"
+@end smalllisp")
#define FUNC_NAME s_scm_inet_ntoa
{
struct in_addr addr;
@@ -117,7 +128,11 @@ GUILE_PROC (scm_inet_ntoa, "inet-ntoa", 1, 0, 0,
#ifdef HAVE_INET_NETOF
GUILE_PROC (scm_inet_netof, "inet-netof", 1, 0, 0,
(SCM address),
-"")
+"Returns the network number part of the given integer Internet address.
+
+@smalllisp
+(inet-netof 2130706433) @result{} 127
+@end smalllisp")
#define FUNC_NAME s_scm_inet_netof
{
struct in_addr addr;
@@ -130,7 +145,12 @@ GUILE_PROC (scm_inet_netof, "inet-netof", 1, 0, 0,
#ifdef HAVE_INET_LNAOF
GUILE_PROC (scm_lnaof, "inet-lnaof", 1, 0, 0,
(SCM address),
-"")
+"Returns the local-address-with-network part of the given Internet
+address.
+
+@smalllisp
+(inet-lnaof 2130706433) @result{} 1
+@end smalllisp")
#define FUNC_NAME s_scm_lnaof
{
struct in_addr addr;
@@ -143,7 +163,12 @@ GUILE_PROC (scm_lnaof, "inet-lnaof", 1, 0, 0,
#ifdef HAVE_INET_MAKEADDR
GUILE_PROC (scm_inet_makeaddr, "inet-makeaddr", 2, 0, 0,
(SCM net, SCM lna),
-"")
+"Makes an Internet host address by combining the network number @var{net}
+with the local-address-within-network number @var{lna}.
+
+@smalllisp
+(inet-makeaddr 127 1) @result{} 2130706433
+@end smalllisp")
#define FUNC_NAME s_scm_inet_makeaddr
{
struct in_addr addr;
@@ -211,7 +236,17 @@ static void scm_resolv_error (const char *subr, SCM bad_value)
GUILE_PROC (scm_gethost, "gethost", 0, 1, 0,
(SCM name),
-"")
+"@deffnx procedure gethostbyname hostname
+@deffnx procedure gethostbyaddr address
+Look up a host by name or address, returning a host object. The
+@code{gethost} procedure will accept either a string name or an integer
+address; if given no arguments, it behaves like @code{gethostent} (see
+below). If a name or address is supplied but the address can not be
+found, an error will be thrown to one of the keys:
+@code{host-not-found}, @code{try-again}, @code{no-recovery} or
+@code{no-data}, corresponding to the equivalent @code{h_error} values.
+Unusual conditions may result in errors thrown to the
+@code{system-error} or @code{misc_error} keys.")
#define FUNC_NAME s_scm_gethost
{
SCM ans = scm_make_vector (SCM_MAKINUM (5), SCM_UNSPECIFIED);
@@ -286,7 +321,13 @@ GUILE_PROC (scm_gethost, "gethost", 0, 1, 0,
#if defined(HAVE_GETNETENT) && defined(HAVE_GETNETBYNAME) && defined(HAVE_GETNETBYADDR)
GUILE_PROC (scm_getnet, "getnet", 0, 1, 0,
(SCM name),
-"")
+"@deffnx procedure getnetbyname net-name
+@deffnx procedure getnetbyaddr net-number
+Look up a network by name or net number in the network database. The
+@var{net-name} argument must be a string, and the @var{net-number}
+argument must be an integer. @code{getnet} will accept either type of
+argument, behaving like @code{getnetent} (see below) if no arguments are
+given.")
#define FUNC_NAME s_scm_getnet
{
SCM ans;
@@ -333,7 +374,12 @@ GUILE_PROC (scm_getnet, "getnet", 0, 1, 0,
#ifdef HAVE_GETPROTOENT
GUILE_PROC (scm_getproto, "getproto", 0, 1, 0,
(SCM name),
-"")
+"@deffnx procedure getprotobyname name
+@deffnx procedure getprotobynumber number
+Look up a network protocol by name or by number. @code{getprotobyname}
+takes a string argument, and @code{getprotobynumber} takes an integer
+argument. @code{getproto} will accept either type, behaving like
+@code{getprotoent} (see below) if no arguments are supplied.")
#define FUNC_NAME s_scm_getproto
{
SCM ans;
@@ -394,7 +440,16 @@ scm_return_entry (struct servent *entry)
#ifdef HAVE_GETSERVENT
GUILE_PROC (scm_getserv, "getserv", 0, 2, 0,
(SCM name, SCM proto),
-"")
+"@deffnx procedure getservbyname name protocol
+@deffnx procedure getservbyport port protocol
+Look up a network service by name or by service number, and return a
+network service object. The @var{protocol} argument specifies the name
+of the desired protocol; if the protocol found in the network service
+database does not match this name, a system error is signalled.
+
+The @code{getserv} procedure will take either a service name or number
+as its first argument; if given no arguments, it behaves like
+@code{getservent} (see below).")
#define FUNC_NAME s_scm_getserv
{
struct servent *entry;
@@ -434,7 +489,8 @@ GUILE_PROC (scm_getserv, "getserv", 0, 2, 0,
#if defined(HAVE_SETHOSTENT) && defined(HAVE_ENDHOSTENT)
GUILE_PROC (scm_sethost, "sethost", 0, 1, 0,
(SCM arg),
-"")
+"If @var{stayopen} is omitted, this is equivalent to @code{endhostent}.
+Otherwise it is equivalent to @code{sethostent stayopen}.")
#define FUNC_NAME s_scm_sethost
{
if (SCM_UNBNDP (arg))
@@ -449,7 +505,8 @@ GUILE_PROC (scm_sethost, "sethost", 0, 1, 0,
#if defined(HAVE_SETNETENT) && defined(HAVE_ENDNETENT)
GUILE_PROC (scm_setnet, "setnet", 0, 1, 0,
(SCM arg),
-"")
+"If @var{stayopen} is omitted, this is equivalent to @code{endnetent}.
+Otherwise it is equivalent to @code{setnetent stayopen}.")
#define FUNC_NAME s_scm_setnet
{
if (SCM_UNBNDP (arg))
@@ -464,7 +521,8 @@ GUILE_PROC (scm_setnet, "setnet", 0, 1, 0,
#if defined(HAVE_SETPROTOENT) && defined(HAVE_ENDPROTOENT)
GUILE_PROC (scm_setproto, "setproto", 0, 1, 0,
(SCM arg),
-"")
+"If @var{stayopen} is omitted, this is equivalent to @code{endprotoent}.
+Otherwise it is equivalent to @code{setprotoent stayopen}.")
#define FUNC_NAME s_scm_setproto
{
if (SCM_UNBNDP (arg))
@@ -479,7 +537,8 @@ GUILE_PROC (scm_setproto, "setproto", 0, 1, 0,
#if defined(HAVE_SETSERVENT) && defined(HAVE_ENDSERVENT)
GUILE_PROC (scm_setserv, "setserv", 0, 1, 0,
(SCM arg),
-"")
+"If @var{stayopen} is omitted, this is equivalent to @code{endservent}.
+Otherwise it is equivalent to @code{setservent stayopen}.")
#define FUNC_NAME s_scm_setserv
{
if (SCM_UNBNDP (arg))
diff --git a/libguile/numbers.c b/libguile/numbers.c
index 3a74082b7..4a5acb31c 100644
--- a/libguile/numbers.c
+++ b/libguile/numbers.c
@@ -512,7 +512,13 @@ scm_lcm (SCM n1, SCM n2)
#ifndef scm_long2num
GUILE_PROC1 (scm_logand, "logand", scm_tc7_asubr,
(SCM n1, SCM n2),
-"")
+"Returns the integer which is the bit-wise AND of the two integer
+arguments.
+
+Example:
+@lisp
+(number->string (logand #b1100 #b1010) 2)
+ @result{} \"1000\"")
#define FUNC_NAME s_scm_logand
{
int i1, i2;
@@ -530,7 +536,14 @@ GUILE_PROC1 (scm_logand, "logand", scm_tc7_asubr,
GUILE_PROC1 (scm_logior, "logior", scm_tc7_asubr,
(SCM n1, SCM n2),
-"")
+"Returns the integer which is the bit-wise OR of the two integer
+arguments.
+
+Example:
+@lisp
+(number->string (logior #b1100 #b1010) 2)
+ @result{} \"1110\"
+@end lisp")
#define FUNC_NAME s_scm_logior
{
int i1, i2;
@@ -548,7 +561,14 @@ GUILE_PROC1 (scm_logior, "logior", scm_tc7_asubr,
GUILE_PROC1 (scm_logxor, "logxor", scm_tc7_asubr,
(SCM n1, SCM n2),
-"")
+"Returns the integer which is the bit-wise XOR of the two integer
+arguments.
+
+Example:
+@lisp
+(number->string (logxor #b1100 #b1010) 2)
+ @result{} \"110\"
+@end lisp")
#define FUNC_NAME s_scm_logxor
{
int i1, i2;
@@ -647,7 +667,12 @@ GUILE_PROC1 (scm_logxor, "logxor", scm_tc7_asubr,
GUILE_PROC (scm_logtest, "logtest", 2, 0, 0,
(SCM n1, SCM n2),
-"")
+"@example
+(logtest j k) @equiv{} (not (zero? (logand j k)))
+
+(logtest #b0100 #b1011) @result{} #f
+(logtest #b0100 #b0111) @result{} #t
+@end example")
#define FUNC_NAME s_scm_logtest
{
int i1, i2;
@@ -659,7 +684,15 @@ GUILE_PROC (scm_logtest, "logtest", 2, 0, 0,
GUILE_PROC (scm_logbit_p, "logbit?", 2, 0, 0,
(SCM n1, SCM n2),
-"")
+"@example
+(logbit? index j) @equiv{} (logtest (integer-expt 2 index) j)
+
+(logbit? 0 #b1101) @result{} #t
+(logbit? 1 #b1101) @result{} #f
+(logbit? 2 #b1101) @result{} #t
+(logbit? 3 #b1101) @result{} #t
+(logbit? 4 #b1101) @result{} #f
+@end example")
#define FUNC_NAME s_scm_logbit_p
{
int i1, i2;
@@ -672,7 +705,16 @@ GUILE_PROC (scm_logbit_p, "logbit?", 2, 0, 0,
GUILE_PROC (scm_lognot, "lognot", 1, 0, 0,
(SCM n),
-"")
+"Returns the integer which is the 2s-complement of the integer argument.
+
+Example:
+@lisp
+(number->string (lognot #b10000000) 2)
+ @result{} \"-10000001\"
+(number->string (lognot #b0) 2)
+ @result{} \"-1\"
+@end lisp
+")
#define FUNC_NAME s_scm_lognot
{
SCM_VALIDATE_INT(1,n);
@@ -682,7 +724,15 @@ GUILE_PROC (scm_lognot, "lognot", 1, 0, 0,
GUILE_PROC (scm_integer_expt, "integer-expt", 2, 0, 0,
(SCM z1, SCM z2),
-"")
+"Returns @var{n} raised to the non-negative integer exponent @var{k}.
+
+Example:
+@lisp
+(integer-expt 2 5)
+ @result{} 32
+(integer-expt -3 3)
+ @result{} -27
+@end lisp")
#define FUNC_NAME s_scm_integer_expt
{
SCM acc = SCM_MAKINUM (1L);
@@ -715,7 +765,16 @@ GUILE_PROC (scm_integer_expt, "integer-expt", 2, 0, 0,
GUILE_PROC (scm_ash, "ash", 2, 0, 0,
(SCM n, SCM cnt),
-"")
+"Returns an integer equivalent to
+@code{(inexact->exact (floor (* @var{int} (expt 2 @var{count}))))}.@refill
+
+Example:
+@lisp
+(number->string (ash #b1 3) 2)
+ @result{} "1000"
+(number->string (ash #b1010 -1) 2)
+ @result{} "101"
+@end lisp")
#define FUNC_NAME s_scm_ash
{
/* GJB:FIXME:: what is going on here? */
@@ -749,7 +808,17 @@ GUILE_PROC (scm_ash, "ash", 2, 0, 0,
/* GJB:FIXME: do not use SCMs as integers! */
GUILE_PROC (scm_bit_extract, "bit-extract", 3, 0, 0,
(SCM n, SCM start, SCM end),
-"")
+"Returns the integer composed of the @var{start} (inclusive) through
+@var{end} (exclusive) bits of @var{n}. The @var{start}th bit becomes
+the 0-th bit in the result.@refill
+
+Example:
+@lisp
+(number->string (bit-extract #b1101101010 0 4) 2)
+ @result{} \"1010\"
+(number->string (bit-extract #b1101101010 4 9) 2)
+ @result{} \"10110\"
+@end lisp")
#define FUNC_NAME s_scm_bit_extract
{
SCM_VALIDATE_INT(1,n);
@@ -778,7 +847,20 @@ static const char scm_logtab[] = {
GUILE_PROC (scm_logcount, "logcount", 1, 0, 0,
(SCM n),
-"")
+"Returns the number of bits in integer @var{n}. If integer is positive,
+the 1-bits in its binary representation are counted. If negative, the
+0-bits in its two's-complement binary representation are counted. If 0,
+0 is returned.
+
+Example:
+@lisp
+(logcount #b10101010)
+ @result{} 4
+(logcount 0)
+ @result{} 0
+(logcount -2)
+ @result{} 1
+@end lisp")
#define FUNC_NAME s_scm_logcount
{
register unsigned long c = 0;
@@ -815,7 +897,17 @@ static const char scm_ilentab[] = {
GUILE_PROC (scm_integer_length, "integer-length", 1, 0, 0,
(SCM n),
-"")
+"Returns the number of bits neccessary to represent @var{n}.
+
+Example:
+@lisp
+(integer-length #b10101010)
+ @result{} 8
+(integer-length 0)
+ @result{} 0
+(integer-length #b1111)
+ @result{} 4
+@end lisp")
#define FUNC_NAME s_scm_integer_length
{
register unsigned long c = 0;
diff --git a/libguile/objprop.c b/libguile/objprop.c
index 5244e1581..5d53dc031 100644
--- a/libguile/objprop.c
+++ b/libguile/objprop.c
@@ -58,7 +58,8 @@
GUILE_PROC(scm_object_properties, "object-properties", 1, 0, 0,
(SCM obj),
-"")
+"@deffnx primitive procedure-properties obj
+Return @var{obj}'s property list.")
#define FUNC_NAME s_scm_object_properties
{
return scm_hashq_ref (scm_object_whash, obj, SCM_EOL);
@@ -68,7 +69,8 @@ GUILE_PROC(scm_object_properties, "object-properties", 1, 0, 0,
GUILE_PROC(scm_set_object_properties_x, "set-object-properties!", 2, 0, 0,
(SCM obj, SCM plist),
-"")
+"@deffnx primitive set-procedure-properties! obj alist
+Set @var{obj}'s property list to @var{alist}.")
#define FUNC_NAME s_scm_set_object_properties_x
{
SCM handle = scm_hashq_create_handle_x (scm_object_whash, obj, plist);
@@ -79,7 +81,8 @@ GUILE_PROC(scm_set_object_properties_x, "set-object-properties!", 2, 0, 0,
GUILE_PROC(scm_object_property, "object-property", 2, 0, 0,
(SCM obj, SCM key),
-"")
+"@deffnx primitive procedure-property obj key
+Return the property of @var{obj} with name @var{key}.")
#define FUNC_NAME s_scm_object_property
{
SCM assoc;
@@ -90,7 +93,9 @@ GUILE_PROC(scm_object_property, "object-property", 2, 0, 0,
GUILE_PROC(scm_set_object_property_x, "set-object-property!", 3, 0, 0,
(SCM obj, SCM key, SCM val),
-"")
+"@deffnx primitive set-procedure-property! obj key value
+In @var{obj}'s property list, set the property named @var{key} to
+@var{value}.")
#define FUNC_NAME s_scm_set_object_property_x
{
SCM h;
diff --git a/libguile/ports.c b/libguile/ports.c
index fc6dc7fb0..274e9fafa 100644
--- a/libguile/ports.c
+++ b/libguile/ports.c
@@ -248,7 +248,8 @@ GUILE_PROC(scm_char_ready_p, "char-ready?", 0, 1, 0,
/* Clear a port's read buffers, returning the contents. */
GUILE_PROC (scm_drain_input, "drain-input", 1, 0, 0,
(SCM port),
-"")
+"Drains @var{PORT}'s read buffers (including any pushed-back characters)
+and returns the contents as a single string.")
#define FUNC_NAME s_scm_drain_input
{
SCM result;
@@ -301,7 +302,8 @@ GUILE_PROC(scm_current_output_port, "current-output-port", 0, 0, 0,
GUILE_PROC(scm_current_error_port, "current-error-port", 0, 0, 0,
(),
-"")
+"Return the port to which errors and warnings should be sent (the
+@dfn{standard error} in Unix and C terminology).")
#define FUNC_NAME s_scm_current_error_port
{
return scm_cur_errp;
@@ -319,7 +321,11 @@ GUILE_PROC(scm_current_load_port, "current-load-port", 0, 0, 0,
GUILE_PROC(scm_set_current_input_port, "set-current-input-port", 1, 0, 0,
(SCM port),
-"")
+"@deffnx primitive set-current-output-port port
+@deffnx primitive set-current-error-port port
+Change the ports returned by @code{current-input-port},
+@code{current-output-port} and @code{current-error-port}, respectively,
+so that they use the supplied @var{port} for input or output.")
#define FUNC_NAME s_scm_set_current_input_port
{
SCM oinp = scm_cur_inp;
@@ -477,7 +483,7 @@ scm_revealed_count (SCM port)
GUILE_PROC(scm_port_revealed, "port-revealed", 1, 0, 0,
(SCM port),
-"")
+"Returns the revealed count for @var{port}.")
#define FUNC_NAME s_scm_port_revealed
{
port = SCM_COERCE_OUTPORT (port);
@@ -489,7 +495,8 @@ GUILE_PROC(scm_port_revealed, "port-revealed", 1, 0, 0,
/* Set the revealed count for a port. */
GUILE_PROC(scm_set_port_revealed_x, "set-port-revealed!", 2, 0, 0,
(SCM port, SCM rcount),
-"")
+"Sets the revealed count for a port to a given value.
+The return value is unspecified.")
#define FUNC_NAME s_scm_set_port_revealed_x
{
port = SCM_COERCE_OUTPORT (port);
@@ -529,7 +536,10 @@ scm_mode_bits (char *modes)
GUILE_PROC(scm_port_mode, "port-mode", 1, 0, 0,
(SCM port),
-"")
+"Returns the port modes associated with the open port @var{port}. These
+will not necessarily be identical to the modes used when the port was
+opened, since modes such as \"append\" which are used only during
+port creation are not retained.")
#define FUNC_NAME s_scm_port_mode
{
char modes[3];
@@ -561,7 +571,12 @@ GUILE_PROC(scm_port_mode, "port-mode", 1, 0, 0,
*/
GUILE_PROC(scm_close_port, "close-port", 1, 0, 0,
(SCM port),
-"")
+"Close the specified port object. Returns @code{#t} if it successfully
+closes a port or @code{#f} if it was already
+closed. An exception may be raised if an error occurs, for example
+when flushing buffered output.
+See also @ref{Ports and File Descriptors, close}, for a procedure
+which can close file descriptors.")
#define FUNC_NAME s_scm_close_port
{
scm_sizet i;
@@ -585,7 +600,13 @@ GUILE_PROC(scm_close_port, "close-port", 1, 0, 0,
GUILE_PROC(scm_close_all_ports_except, "close-all-ports-except", 0, 0, 1,
(SCM ports),
-"")
+"Close all open file ports used by the interpreter
+except for those supplied as arguments. This procedure
+is intended to be used before an exec call to close file descriptors
+which are not needed in the new process.Close all open file ports used by the interpreter
+except for those supplied as arguments. This procedure
+is intended to be used before an exec call to close file descriptors
+which are not needed in the new process.")
#define FUNC_NAME s_scm_close_all_ports_except
{
int i = 0;
@@ -645,7 +666,7 @@ GUILE_PROC(scm_output_port_p, "output-port?", 1, 0, 0,
GUILE_PROC(scm_port_closed_p, "port-closed?", 1, 0, 0,
(SCM port),
-"")
+"Returns @code{#t} if @var{port} is closed or @code{#f} if it is open.")
#define FUNC_NAME s_scm_port_closed_p
{
SCM_VALIDATE_OPPORT(1,port);
@@ -664,7 +685,13 @@ GUILE_PROC(scm_eof_object_p, "eof-object?", 1, 0, 0,
GUILE_PROC(scm_force_output, "force-output", 0, 1, 0,
(SCM port),
-"")
+"Flush the specified output port, or the current output port if @var{port}
+is omitted. The current output buffer contents are passed to the
+underlying port implementation (e.g., in the case of fports, the
+data will be written to the file and the output buffer will be cleared.)
+It has no effect on an unbuffered port.
+
+The return value is unspecified.")
#define FUNC_NAME s_scm_force_output
{
if (SCM_UNBNDP (port))
@@ -681,7 +708,8 @@ GUILE_PROC(scm_force_output, "force-output", 0, 1, 0,
GUILE_PROC (scm_flush_all_ports, "flush-all-ports", 0, 0, 0,
(),
-"")
+"Equivalent to calling @code{force-output} on
+all open output ports. The return value is unspecified.")
#define FUNC_NAME s_scm_flush_all_ports
{
int i;
@@ -937,7 +965,10 @@ GUILE_PROC(scm_peek_char, "peek-char", 0, 1, 0,
GUILE_PROC (scm_unread_char, "unread-char", 2, 0, 0,
(SCM cobj, SCM port),
-"")
+"Place @var{char} in @var{port} so that it will be read by the
+next read operation. If called multiple times, the unread characters
+will be read again in last-in first-out order. If @var{port} is
+not supplied, the current input port is used.")
#define FUNC_NAME s_scm_unread_char
{
int c;
@@ -957,7 +988,10 @@ GUILE_PROC (scm_unread_char, "unread-char", 2, 0, 0,
GUILE_PROC (scm_unread_string, "unread-string", 2, 0, 0,
(SCM str, SCM port),
-"")
+"Place the string @var{str} in @var{port} so that its characters will be
+read in subsequent read operations. If called multiple times, the
+unread characters will be read again in last-in first-out order. If
+@var{port} is not supplied, the current-input-port is used.")
#define FUNC_NAME s_scm_unread_string
{
SCM_VALIDATE_STRING(1,str);
@@ -974,7 +1008,29 @@ GUILE_PROC (scm_unread_string, "unread-string", 2, 0, 0,
GUILE_PROC (scm_seek, "seek", 3, 0, 0,
(SCM object, SCM offset, SCM whence),
-"")
+"Sets the current position of @var{fd/port} to the integer @var{offset},
+which is interpreted according to the value of @var{whence}.
+
+One of the following variables should be supplied
+for @var{whence}:
+@defvar SEEK_SET
+Seek from the beginning of the file.
+@end defvar
+@defvar SEEK_CUR
+Seek from the current position.
+@end defvar
+@defvar SEEK_END
+Seek from the end of the file.
+@end defvar
+
+If @var{fd/port} is a file descriptor, the underlying system call is
+@code{lseek}. @var{port} may be a string port.
+
+The value returned is the new position in the file. This means that
+the current position of a port can be obtained using:
+@smalllisp
+(seek port 0 SEEK_CUR)
+@end smalllisp")
#define FUNC_NAME s_scm_seek
{
off_t off;
@@ -1010,7 +1066,13 @@ GUILE_PROC (scm_seek, "seek", 3, 0, 0,
GUILE_PROC (scm_truncate_file, "truncate-file", 1, 1, 0,
(SCM object, SCM length),
-"")
+"Truncates the object referred to by @var{obj} to at most @var{size} bytes.
+@var{obj} can be a string containing a file name or an integer file
+descriptor or a port. @var{size} may be omitted if @var{obj} is not
+a file name, in which case the truncation occurs at the current port.
+position.
+
+The return value is unspecified.")
#define FUNC_NAME s_scm_truncate_file
{
int rv;
@@ -1087,7 +1149,15 @@ GUILE_PROC (scm_set_port_line_x, "set-port-line!", 2, 0, 0,
GUILE_PROC (scm_port_column, "port-column", 1, 0, 0,
(SCM port),
-"")
+"@deffnx primitive port-line [input-port]
+Return the current column number or line number of @var{input-port},
+using the current input port if none is specified. If the number is
+unknown, the result is #f. Otherwise, the result is a 0-origin integer
+- i.e. the first character of the first line is line 0, column 0.
+(However, when you display a file position, for example in an error
+message, we recommand you add 1 to get 1-origin integers. This is
+because lines and column numbers traditionally start with 1, and that is
+what non-programmers will find most natural.)")
#define FUNC_NAME s_scm_port_column
{
port = SCM_COERCE_OUTPORT (port);
@@ -1098,7 +1168,9 @@ GUILE_PROC (scm_port_column, "port-column", 1, 0, 0,
GUILE_PROC (scm_set_port_column_x, "set-port-column!", 2, 0, 0,
(SCM port, SCM column),
-"")
+"@deffnx primitive set-port-line! [input-port] line
+Set the current column or line number of @var{input-port}, using the
+current input port if none is specified.")
#define FUNC_NAME s_scm_set_port_column_x
{
port = SCM_COERCE_OUTPORT (port);
@@ -1110,7 +1182,9 @@ GUILE_PROC (scm_set_port_column_x, "set-port-column!", 2, 0, 0,
GUILE_PROC (scm_port_filename, "port-filename", 1, 0, 0,
(SCM port),
-"")
+"Return the filename associated with @var{port}. This function returns
+the strings "standard input", "standard output" and "standard error"
+when called on the current input, output and error ports respectively.")
#define FUNC_NAME s_scm_port_filename
{
port = SCM_COERCE_OUTPORT (port);
@@ -1121,7 +1195,10 @@ GUILE_PROC (scm_port_filename, "port-filename", 1, 0, 0,
GUILE_PROC (scm_set_port_filename_x, "set-port-filename!", 2, 0, 0,
(SCM port, SCM filename),
-"")
+"Change the filename associated with @var{port}, using the current input
+port if none is specified. Note that this does not change the port's
+source of data, but only the value that is returned by
+@code{port-filename} and reported in diagnostic output.")
#define FUNC_NAME s_scm_set_port_filename_x
{
port = SCM_COERCE_OUTPORT (port);
@@ -1226,7 +1303,9 @@ scm_void_port (char *mode_str)
GUILE_PROC (scm_sys_make_void_port, "%make-void-port", 1, 0, 0,
(SCM mode),
-"")
+"Create and return a new void port. The @var{mode} argument describes
+the input/output modes for this port; for a description, see the
+documentation for @code{open-file} in @ref{File Ports}.")
#define FUNC_NAME s_scm_sys_make_void_port
{
SCM_VALIDATE_ROSTRING(1,mode);
diff --git a/libguile/posix.c b/libguile/posix.c
index 4e34eca09..b8354de06 100644
--- a/libguile/posix.c
+++ b/libguile/posix.c
@@ -168,7 +168,13 @@ SCM_SYMBOL (sym_write_pipe, "write pipe");
GUILE_PROC (scm_pipe, "pipe", 0, 0, 0,
(),
-"")
+"Creates a pipe which can be used for communication. The return value
+is a pair in which the CAR contains an input port and the CDR an
+output port. Data written to the output port can be read from the
+input port. Note that both ports are buffered so it may be necessary
+to flush the output port before data will actually be sent across the pipe.
+Alternatively a buffer can be added to the port using @code{setvbuf}
+(see below).")
#define FUNC_NAME s_scm_pipe
{
int fd[2], rv;
@@ -188,7 +194,7 @@ GUILE_PROC (scm_pipe, "pipe", 0, 0, 0,
#ifdef HAVE_GETGROUPS
GUILE_PROC (scm_getgroups, "getgroups", 0, 0, 0,
(),
-"")
+"Returns a vector of integers representing the current supplimentary group IDs.")
#define FUNC_NAME s_scm_getgroups
{
SCM grps, ans;
@@ -225,7 +231,9 @@ GUILE_PROC (scm_getgroups, "getgroups", 0, 0, 0,
GUILE_PROC (scm_getpwuid, "getpw", 0, 1, 0,
(SCM user),
-"")
+"Look up an entry in the user database. @var{obj} can be an integer,
+a string, or omitted, giving the behaviour of getpwuid, getpwnam
+or getpwent respectively.")
#define FUNC_NAME s_scm_getpwuid
{
SCM result;
@@ -277,7 +285,9 @@ GUILE_PROC (scm_getpwuid, "getpw", 0, 1, 0,
#ifdef HAVE_SETPWENT
GUILE_PROC (scm_setpwent, "setpw", 0, 1, 0,
(SCM arg),
-"")
+"If called with a true argument, initialize or reset the password data
+stream. Otherwise, close the stream. The @code{setpwent} and
+@code{endpwent} procedures are implemented on top of this.")
#define FUNC_NAME s_scm_setpwent
{
if (SCM_UNBNDP (arg) || SCM_FALSEP (arg))
@@ -294,7 +304,9 @@ GUILE_PROC (scm_setpwent, "setpw", 0, 1, 0,
/* Combines getgrgid and getgrnam. */
GUILE_PROC (scm_getgrgid, "getgr", 0, 1, 0,
(SCM name),
-"")
+"Look up an entry in the group database. @var{obj} can be an integer,
+a string, or omitted, giving the behaviour of getgrgid, getgrnam
+or getgrent respectively.")
#define FUNC_NAME s_scm_getgrgid
{
SCM result;
@@ -333,7 +345,9 @@ GUILE_PROC (scm_getgrgid, "getgr", 0, 1, 0,
GUILE_PROC (scm_setgrent, "setgr", 0, 1, 0,
(SCM arg),
-"")
+"If called with a true argument, initialize or reset the group data
+stream. Otherwise, close the stream. The @code{setgrent} and
+@code{endgrent} procedures are implemented on top of this.")
#define FUNC_NAME s_scm_setgrent
{
if (SCM_UNBNDP (arg) || SCM_FALSEP (arg))
@@ -348,7 +362,33 @@ GUILE_PROC (scm_setgrent, "setgr", 0, 1, 0,
GUILE_PROC (scm_kill, "kill", 2, 0, 0,
(SCM pid, SCM sig),
-"")
+"Sends a signal to the specified process or group of processes.
+
+@var{pid} specifies the processes to which the signal is sent:
+
+@table @r
+@item @var{pid} greater than 0
+The process whose identifier is @var{pid}.
+@item @var{pid} equal to 0
+All processes in the current process group.
+@item @var{pid} less than -1
+The process group whose identifier is -@var{pid}
+@item @var{pid} equal to -1
+If the process is privileged, all processes except for some special
+system processes. Otherwise, all processes with the current effective
+user ID.
+@end table
+
+@var{sig} should be specified using a variable corresponding to
+the Unix symbolic name, e.g.,
+
+@defvar SIGHUP
+Hang-up signal.
+@end defvar
+
+@defvar SIGINT
+Interrupt signal.
+@end defvar")
#define FUNC_NAME s_scm_kill
{
SCM_VALIDATE_INT(1,pid);
@@ -364,7 +404,47 @@ GUILE_PROC (scm_kill, "kill", 2, 0, 0,
GUILE_PROC (scm_waitpid, "waitpid", 1, 1, 0,
(SCM pid, SCM options),
-"")
+"This procedure collects status information from a child process which
+has terminated or (optionally) stopped. Normally it will
+suspend the calling process until this can be done. If more than one
+child process is eligible then one will be chosen by the operating system.
+
+The value of @var{pid} determines the behaviour:
+
+@table @r
+@item @var{pid} greater than 0
+Request status information from the specified child process.
+@item @var{pid} equal to -1 or WAIT_ANY
+Request status information for any child process.
+@item @var{pid} equal to 0 or WAIT_MYPGRP
+Request status information for any child process in the current process
+group.
+@item @var{pid} less than -1
+Request status information for any child process whose process group ID
+is -@var{PID}.
+@end table
+
+The @var{options} argument, if supplied, should be the bitwise OR of the
+values of zero or more of the following variables:
+
+@defvar WNOHANG
+Return immediately even if there are no child processes to be collected.
+@end defvar
+
+@defvar WUNTRACED
+Report status information for stopped processes as well as terminated
+processes.
+@end defvar
+
+The return value is a pair containing:
+
+@enumerate
+@item
+The process ID of the child process, or 0 if @code{WNOHANG} was
+specified and no process was collected.
+@item
+The integer status value.
+@end enumerate")
#define FUNC_NAME s_scm_waitpid
{
#ifdef HAVE_WAITPID
@@ -394,7 +474,9 @@ GUILE_PROC (scm_waitpid, "waitpid", 1, 1, 0,
GUILE_PROC (scm_status_exit_val, "status:exit-val", 1, 0, 0,
(SCM status),
-"")
+"Returns the exit status value, as would be
+set if a process ended normally through a
+call to @code{exit} or @code{_exit}, if any, otherwise @code{#f}.")
#define FUNC_NAME s_scm_status_exit_val
{
int lstatus;
@@ -413,7 +495,8 @@ GUILE_PROC (scm_status_exit_val, "status:exit-val", 1, 0, 0,
GUILE_PROC (scm_status_term_sig, "status:term-sig", 1, 0, 0,
(SCM status),
-"")
+"Returns the signal number which terminated the
+process, if any, otherwise @code{#f}.")
#define FUNC_NAME s_scm_status_term_sig
{
int lstatus;
@@ -430,7 +513,8 @@ GUILE_PROC (scm_status_term_sig, "status:term-sig", 1, 0, 0,
GUILE_PROC (scm_status_stop_sig, "status:stop-sig", 1, 0, 0,
(SCM status),
-"")
+"Returns the signal number which stopped the
+process, if any, otherwise @code{#f}.")
#define FUNC_NAME s_scm_status_stop_sig
{
int lstatus;
@@ -447,7 +531,7 @@ GUILE_PROC (scm_status_stop_sig, "status:stop-sig", 1, 0, 0,
GUILE_PROC (scm_getppid, "getppid", 0, 0, 0,
(),
-"")
+"Returns an integer representing the process ID of the parent process.")
#define FUNC_NAME s_scm_getppid
{
return SCM_MAKINUM (0L + getppid ());
@@ -458,7 +542,7 @@ GUILE_PROC (scm_getppid, "getppid", 0, 0, 0,
GUILE_PROC (scm_getuid, "getuid", 0, 0, 0,
(),
-"")
+"Returns an integer representing the current real user ID.")
#define FUNC_NAME s_scm_getuid
{
return SCM_MAKINUM (0L + getuid ());
@@ -469,7 +553,7 @@ GUILE_PROC (scm_getuid, "getuid", 0, 0, 0,
GUILE_PROC (scm_getgid, "getgid", 0, 0, 0,
(),
-"")
+"Returns an integer representing the current real group ID.")
#define FUNC_NAME s_scm_getgid
{
return SCM_MAKINUM (0L + getgid ());
@@ -480,7 +564,10 @@ GUILE_PROC (scm_getgid, "getgid", 0, 0, 0,
GUILE_PROC (scm_geteuid, "geteuid", 0, 0, 0,
(),
-"")
+"Returns an integer representing the current effective user ID.
+If the system does not support effective IDs, then the real ID
+is returned. @code{(feature? 'EIDs)} reports whether the system
+supports effective IDs.")
#define FUNC_NAME s_scm_geteuid
{
#ifdef HAVE_GETEUID
@@ -495,7 +582,10 @@ GUILE_PROC (scm_geteuid, "geteuid", 0, 0, 0,
GUILE_PROC (scm_getegid, "getegid", 0, 0, 0,
(),
-"")
+"Returns an integer representing the current effective group ID.
+If the system does not support effective IDs, then the real ID
+is returned. @code{(feature? 'EIDs)} reports whether the system
+supports effective IDs.")
#define FUNC_NAME s_scm_getegid
{
#ifdef HAVE_GETEUID
@@ -509,7 +599,9 @@ GUILE_PROC (scm_getegid, "getegid", 0, 0, 0,
GUILE_PROC (scm_setuid, "setuid", 1, 0, 0,
(SCM id),
-"")
+"Sets both the real and effective user IDs to the integer @var{id}, provided
+the process has appropriate privileges.
+The return value is unspecified.")
#define FUNC_NAME s_scm_setuid
{
SCM_VALIDATE_INT(1,id);
@@ -521,7 +613,9 @@ GUILE_PROC (scm_setuid, "setuid", 1, 0, 0,
GUILE_PROC (scm_setgid, "setgid", 1, 0, 0,
(SCM id),
-"")
+"Sets both the real and effective group IDs to the integer @var{id}, provided
+the process has appropriate privileges.
+The return value is unspecified.")
#define FUNC_NAME s_scm_setgid
{
SCM_VALIDATE_INT(1,id);
@@ -533,7 +627,11 @@ GUILE_PROC (scm_setgid, "setgid", 1, 0, 0,
GUILE_PROC (scm_seteuid, "seteuid", 1, 0, 0,
(SCM id),
-"")
+"Sets the effective user ID to the integer @var{id}, provided the process
+has appropriate privileges. If effective IDs are not supported, the
+real ID is set instead -- @code{(feature? 'EIDs)} reports whether the
+system supports effective IDs.
+The return value is unspecified.")
#define FUNC_NAME s_scm_seteuid
{
int rv;
@@ -553,7 +651,11 @@ GUILE_PROC (scm_seteuid, "seteuid", 1, 0, 0,
#ifdef HAVE_SETEGID
GUILE_PROC (scm_setegid, "setegid", 1, 0, 0,
(SCM id),
-"")
+"Sets the effective group ID to the integer @var{id}, provided the process
+has appropriate privileges. If effective IDs are not supported, the
+real ID is set instead -- @code{(feature? 'EIDs)} reports whether the
+system supports effective IDs.
+The return value is unspecified.")
#define FUNC_NAME s_scm_setegid
{
int rv;
@@ -574,7 +676,8 @@ GUILE_PROC (scm_setegid, "setegid", 1, 0, 0,
GUILE_PROC (scm_getpgrp, "getpgrp", 0, 0, 0,
(),
-"")
+"Returns an integer representing the current process group ID.
+This is the POSIX definition, not BSD.")
#define FUNC_NAME s_scm_getpgrp
{
int (*fn)();
@@ -585,7 +688,11 @@ GUILE_PROC (scm_getpgrp, "getpgrp", 0, 0, 0,
GUILE_PROC (scm_setpgid, "setpgid", 2, 0, 0,
(SCM pid, SCM pgid),
-"")
+"Move the process @var{pid} into the process group @var{pgid}. @var{pid} or
+@var{pgid} must be integers: they can be zero to indicate the ID of the
+current process.
+Fails on systems that do not support job control.
+The return value is unspecified.")
#define FUNC_NAME s_scm_setpgid
{
#ifdef HAVE_SETPGID
@@ -605,7 +712,10 @@ GUILE_PROC (scm_setpgid, "setpgid", 2, 0, 0,
GUILE_PROC (scm_setsid, "setsid", 0, 0, 0,
(),
-"")
+"Creates a new session. The current process becomes the session leader
+and is put in a new process group. The process will be detached
+from its controlling terminal if it has one.
+The return value is an integer representing the new process group ID.")
#define FUNC_NAME s_scm_setsid
{
#ifdef HAVE_SETSID
@@ -623,7 +733,8 @@ GUILE_PROC (scm_setsid, "setsid", 0, 0, 0,
GUILE_PROC (scm_ttyname, "ttyname", 1, 0, 0,
(SCM port),
-"")
+"Returns a string with the name of the serial terminal device underlying
+@var{port}.")
#define FUNC_NAME s_scm_ttyname
{
char *ans;
@@ -645,7 +756,8 @@ GUILE_PROC (scm_ttyname, "ttyname", 1, 0, 0,
GUILE_PROC (scm_ctermid, "ctermid", 0, 0, 0,
(),
-"")
+"Returns a string containing the file name of the controlling terminal
+for the current process.")
#define FUNC_NAME s_scm_ctermid
{
#ifdef HAVE_CTERMID
@@ -663,7 +775,16 @@ GUILE_PROC (scm_ctermid, "ctermid", 0, 0, 0,
GUILE_PROC (scm_tcgetpgrp, "tcgetpgrp", 1, 0, 0,
(SCM port),
-"")
+"Returns the process group ID of the foreground
+process group associated with the terminal open on the file descriptor
+underlying @var{port}.
+
+If there is no foreground process group, the return value is a
+number greater than 1 that does not match the process group ID
+of any existing process group. This can happen if all of the
+processes in the job that was formerly the foreground job have
+terminated, and no other job has yet been moved into the
+foreground.")
#define FUNC_NAME s_scm_tcgetpgrp
{
#ifdef HAVE_TCGETPGRP
@@ -687,7 +808,11 @@ GUILE_PROC (scm_tcgetpgrp, "tcgetpgrp", 1, 0, 0,
GUILE_PROC (scm_tcsetpgrp, "tcsetpgrp", 2, 0, 0,
(SCM port, SCM pgid),
-"")
+"Set the foreground process group ID for the terminal used by the file
+descriptor underlying @var{port} to the integer @var{pgid}.
+The calling process
+must be a member of the same session as @var{pgid} and must have the same
+controlling terminal. The return value is unspecified.")
#define FUNC_NAME s_scm_tcsetpgrp
{
#ifdef HAVE_TCSETPGRP
@@ -745,7 +870,17 @@ scm_convert_exec_args (SCM args, int pos, const char *subr)
GUILE_PROC (scm_execl, "execl", 1, 0, 1,
(SCM filename, SCM args),
-"")
+"Executes the file named by @var{path} as a new process image.
+The remaining arguments are supplied to the process; from a C program
+they are accessable as the @code{argv} argument to @code{main}.
+Conventionally the first @var{arg} is the same as @var{path}.
+All arguments must be strings.
+
+If @var{arg} is missing, @var{path} is executed with a null
+argument list, which may have system-dependent side-effects.
+
+This procedure is currently implemented using the @code{execv} system
+call, but we call it @code{execl} because of its Scheme calling interface.")
#define FUNC_NAME s_scm_execl
{
char **execargv;
@@ -761,7 +896,13 @@ GUILE_PROC (scm_execl, "execl", 1, 0, 1,
GUILE_PROC (scm_execlp, "execlp", 1, 0, 1,
(SCM filename, SCM args),
-"")
+"Similar to @code{execl}, however if
+@var{filename} does not contain a slash
+then the file to execute will be located by searching the
+directories listed in the @code{PATH} environment variable.
+
+This procedure is currently implemented using the @code{execlv} system
+call, but we call it @code{execlp} because of its Scheme calling interface.")
#define FUNC_NAME s_scm_execlp
{
char **execargv;
@@ -813,7 +954,12 @@ environ_list_to_c (SCM envlist, int arg, const char *proc)
GUILE_PROC (scm_execle, "execle", 2, 0, 1,
(SCM filename, SCM env, SCM args),
-"")
+"Similar to @code{execl}, but the environment of the new process is
+specified by @var{env}, which must be a list of strings as returned by the
+@code{environ} procedure.
+
+This procedure is currently implemented using the @code{execve} system
+call, but we call it @code{execle} because of its Scheme calling interface.")
#define FUNC_NAME s_scm_execle
{
char **execargv;
@@ -833,7 +979,12 @@ GUILE_PROC (scm_execle, "execle", 2, 0, 1,
GUILE_PROC (scm_fork, "primitive-fork", 0, 0, 0,
(),
-"")
+"Creates a new \"child\" process by duplicating the current \"parent\" process.
+In the child the return value is 0. In the parent the return value is
+the integer process ID of the child.
+
+This procedure has been renamed from @code{fork} to avoid a naming conflict
+with the scsh fork.")
#define FUNC_NAME s_scm_fork
{
int pid;
@@ -847,7 +998,8 @@ GUILE_PROC (scm_fork, "primitive-fork", 0, 0, 0,
GUILE_PROC (scm_uname, "uname", 0, 0, 0,
(),
-"")
+"Returns an object with some information about the computer system the
+program is running on.")
#define FUNC_NAME s_scm_uname
{
#ifdef HAVE_UNAME
@@ -876,7 +1028,12 @@ GUILE_PROC (scm_uname, "uname", 0, 0, 0,
GUILE_PROC (scm_environ, "environ", 0, 1, 0,
(SCM env),
-"")
+"If @var{env} is omitted, returns the current environment as a list of strings.
+Otherwise it sets the current environment, which is also the
+default environment for child processes, to the supplied list of strings.
+Each member of @var{env} should be of the form
+@code{NAME=VALUE} and values of @code{NAME} should not be duplicated.
+If @var{env} is supplied then the return value is unspecified.")
#define FUNC_NAME s_scm_environ
{
if (SCM_UNBNDP (env))
@@ -910,7 +1067,9 @@ GUILE_PROC (scm_environ, "environ", 0, 1, 0,
GUILE_PROC (scm_tmpnam, "tmpnam", 0, 0, 0,
(),
-"")
+"Create a new file in the file system with a unique name. The return
+value is the name of the new file. This function is implemented with
+the @code{tmpnam} function in the system libraries.")
#define FUNC_NAME s_scm_tmpnam
{
char name[L_tmpnam];
@@ -923,7 +1082,21 @@ GUILE_PROC (scm_tmpnam, "tmpnam", 0, 0, 0,
GUILE_PROC (scm_utime, "utime", 1, 2, 0,
(SCM pathname, SCM actime, SCM modtime),
-"")
+"@code{utime} sets the access and modification times for
+the file named by @var{path}. If @var{actime} or @var{modtime}
+is not supplied, then the current time is used.
+@var{actime} and @var{modtime}
+must be integer time values as returned by the @code{current-time}
+procedure.
+
+E.g.,
+
+@smalllisp
+(utime \"foo\" (- (current-time) 3600))
+@end smalllisp
+
+will set the access time to one hour in the past and the modification
+time to the current time.")
#define FUNC_NAME s_scm_utime
{
int rv;
@@ -950,7 +1123,31 @@ GUILE_PROC (scm_utime, "utime", 1, 2, 0,
GUILE_PROC (scm_access, "access?", 2, 0, 0,
(SCM path, SCM how),
-"")
+"Returns @code{#t} if @var{path} corresponds to an existing
+file and the current process
+has the type of access specified by @var{how}, otherwise
+@code{#f}.
+@var{how} should be specified
+using the values of the variables listed below. Multiple values can
+be combined using a bitwise or, in which case @code{#t} will only
+be returned if all accesses are granted.
+
+Permissions are checked using the real id of the current process,
+not the effective id, although it's the effective id which determines
+whether the access would actually be granted.
+
+@defvar R_OK
+test for read permission.
+@end defvar
+@defvar W_OK
+test for write permission.
+@end defvar
+@defvar X_OK
+test for execute permission.
+@end defvar
+@defvar F_OK
+test for existence of the file.
+@end defvar")
#define FUNC_NAME s_scm_access
{
int rv;
@@ -966,7 +1163,7 @@ GUILE_PROC (scm_access, "access?", 2, 0, 0,
GUILE_PROC (scm_getpid, "getpid", 0, 0, 0,
(),
-"")
+"Returns an integer representing the current process ID.")
#define FUNC_NAME s_scm_getpid
{
return SCM_MAKINUM ((unsigned long) getpid ());
@@ -975,7 +1172,17 @@ GUILE_PROC (scm_getpid, "getpid", 0, 0, 0,
GUILE_PROC (scm_putenv, "putenv", 1, 0, 0,
(SCM str),
-"")
+"Modifies the environment of the current process, which is
+also the default environment inherited by child processes.
+
+If @var{string} is of the form @code{NAME=VALUE} then it will be written
+directly into the environment, replacing any existing environment string
+with
+name matching @code{NAME}. If @var{string} does not contain an equal
+sign, then any existing string with name matching @var{string} will
+be removed.
+
+The return value is unspecified.")
#define FUNC_NAME s_scm_putenv
{
int rv;
@@ -997,7 +1204,16 @@ GUILE_PROC (scm_putenv, "putenv", 1, 0, 0,
GUILE_PROC (scm_setlocale, "setlocale", 1, 1, 0,
(SCM category, SCM locale),
-"")
+"If @var{locale} is omitted, returns the current value of the specified
+locale category
+as a system-dependent string.
+@var{category} should be specified using the values @code{LC_COLLATE},
+@code{LC_ALL} etc.
+
+Otherwise the specified locale category is set to
+the string @var{locale}
+and the new value is returned as a system-dependent string. If @var{locale}
+is an empty string, the locale will be set using envirionment variables.")
#define FUNC_NAME s_scm_setlocale
{
#ifdef HAVE_SETLOCALE
@@ -1030,7 +1246,21 @@ GUILE_PROC (scm_setlocale, "setlocale", 1, 1, 0,
GUILE_PROC (scm_mknod, "mknod", 4, 0, 0,
(SCM path, SCM type, SCM perms, SCM dev),
-"")
+"Creates a new special file, such as a file corresponding to a device.
+@var{path} specifies the name of the file. @var{type} should
+be one of the following symbols:
+regular, directory, symlink, block-special, char-special,
+fifo, or socket. @var{perms} (an integer) specifies the file permissions.
+@var{dev} (an integer) specifies which device the special file refers
+to. Its exact interpretation depends on the kind of special file
+being created.
+
+E.g.,
+@example
+(mknod "/dev/fd0" 'block-special #o660 (+ (* 2 256) 2))
+@end example
+
+The return value is unspecified.")
#define FUNC_NAME s_scm_mknod
{
#ifdef HAVE_MKNOD
@@ -1078,7 +1308,9 @@ GUILE_PROC (scm_mknod, "mknod", 4, 0, 0,
GUILE_PROC (scm_nice, "nice", 1, 0, 0,
(SCM incr),
-"")
+"Increment the priority of the current process by @var{incr}. A higher
+priority value means that the process runs less often.
+The return value is unspecified.")
#define FUNC_NAME s_scm_nice
{
#ifdef HAVE_NICE
@@ -1097,7 +1329,8 @@ GUILE_PROC (scm_nice, "nice", 1, 0, 0,
GUILE_PROC (scm_sync, "sync", 0, 0, 0,
(),
-"")
+"Flush the operating system disk buffers.
+The return value is unspecified.")
#define FUNC_NAME s_scm_sync
{
#ifdef HAVE_SYNC
diff --git a/libguile/procprop.c b/libguile/procprop.c
index 0d2023412..fd5242c64 100644
--- a/libguile/procprop.c
+++ b/libguile/procprop.c
@@ -164,7 +164,7 @@ scm_stand_in_scm_proc(SCM proc)
GUILE_PROC(scm_procedure_properties, "procedure-properties", 1, 0, 0,
(SCM proc),
-"")
+"Return @var{obj}'s property list.")
#define FUNC_NAME s_scm_procedure_properties
{
SCM_VALIDATE_PROC(1,proc);
@@ -177,7 +177,7 @@ GUILE_PROC(scm_procedure_properties, "procedure-properties", 1, 0, 0,
GUILE_PROC(scm_set_procedure_properties_x, "set-procedure-properties!", 2, 0, 0,
(SCM proc, SCM new_val),
-"")
+"Set @var{obj}'s property list to @var{alist}.")
#define FUNC_NAME s_scm_set_procedure_properties_x
{
if (!(SCM_NIMP (proc) && SCM_CLOSUREP (proc)))
@@ -190,7 +190,7 @@ GUILE_PROC(scm_set_procedure_properties_x, "set-procedure-properties!", 2, 0, 0,
GUILE_PROC(scm_procedure_property, "procedure-property", 2, 0, 0,
(SCM p, SCM k),
-"")
+"Return the property of @var{obj} with name @var{key}.")
#define FUNC_NAME s_scm_procedure_property
{
SCM assoc;
@@ -212,7 +212,8 @@ GUILE_PROC(scm_procedure_property, "procedure-property", 2, 0, 0,
GUILE_PROC(scm_set_procedure_property_x, "set-procedure-property!", 3, 0, 0,
(SCM p, SCM k, SCM v),
-"")
+"In @var{obj}'s property list, set the property named @var{key} to
+@var{value}.")
#define FUNC_NAME s_scm_set_procedure_property_x
{
SCM assoc;
diff --git a/libguile/procs.c b/libguile/procs.c
index 6099a2e10..d3b539c36 100644
--- a/libguile/procs.c
+++ b/libguile/procs.c
@@ -262,7 +262,10 @@ scm_subr_p (SCM obj)
GUILE_PROC(scm_procedure_documentation, "procedure-documentation", 1, 0, 0,
(SCM proc),
-"")
+"Return the documentation string associated with @code{proc}. By
+convention, if a procedure contains more than one expression and the
+first expression is a string constant, that string is assumed to contain
+documentation for that procedure.")
#define FUNC_NAME s_scm_procedure_documentation
{
SCM code;
diff --git a/libguile/ramap.c b/libguile/ramap.c
index a6a52793e..3d54b918f 100644
--- a/libguile/ramap.c
+++ b/libguile/ramap.c
@@ -407,7 +407,8 @@ scm_ramapc (int (*cproc)(), SCM data, SCM ra0, SCM lra, const char *what)
GUILE_PROC(scm_array_fill_x, "array-fill!", 2, 0, 0,
(SCM ra, SCM fill),
-"")
+"Stores @var{fill} in every element of @var{array}. The value returned
+is unspecified.")
#define FUNC_NAME s_scm_array_fill_x
{
SCM_RAMAPC (scm_array_fill_int, fill, ra, SCM_EOL);
@@ -778,7 +779,10 @@ SCM_REGISTER_PROC(s_array_copy_in_order_x, "array-copy-in-order!", 2, 0, 0, scm_
GUILE_PROC(scm_array_copy_x, "array-copy!", 2, 0, 0,
(SCM src, SCM dst),
-"")
+"Copies every element from vector or array @var{source} to the
+corresponding element of @var{destination}. @var{destination} must have
+the same rank as @var{source}, and be at least as large in each
+dimension. The order is unspecified.")
#define FUNC_NAME s_scm_array_copy_x
{
SCM_RAMAPC (racp, SCM_UNDEFINED, src, scm_cons (dst, SCM_EOL));
@@ -1595,7 +1599,12 @@ SCM_REGISTER_PROC(s_array_map_in_order_x, "array-map-in-order!", 2, 0, 1, scm_ar
GUILE_PROC(scm_array_map_x, "array-map!", 2, 0, 1,
(SCM ra0, SCM proc, SCM lra),
-"")
+"@var{array1}, @dots{} must have the same number of dimensions as
+@var{array0} and have a range for each index which includes the range
+for the corresponding index in @var{array0}. @var{proc} is applied to
+each tuple of elements of @var{array1} @dots{} and the result is stored
+as the corresponding element in @var{array0}. The value returned is
+unspecified. The order of application is unspecified.")
#define FUNC_NAME s_scm_array_map_x
{
SCM_VALIDATE_PROC(2,proc);
@@ -1737,7 +1746,8 @@ rafe (SCM ra0,SCM proc,SCM ras)
GUILE_PROC(scm_array_for_each, "array-for-each", 2, 0, 1,
(SCM proc, SCM ra0, SCM lra),
-"")
+"@var{proc} is applied to each tuple of elements of @var{array0} @dots{}
+in row-major order. The value returned is unspecified.")
#define FUNC_NAME s_scm_array_for_each
{
SCM_VALIDATE_PROC(1,proc);
@@ -1748,7 +1758,24 @@ GUILE_PROC(scm_array_for_each, "array-for-each", 2, 0, 1,
GUILE_PROC(scm_array_index_map_x, "array-index-map!", 2, 0, 0,
(SCM ra, SCM proc),
-"")
+"applies @var{proc} to the indices of each element of @var{array} in
+turn, storing the result in the corresponding element. The value
+returned and the order of application are unspecified.
+
+One can implement @var{array-indexes} as
+@example
+(define (array-indexes array)
+ (let ((ra (apply make-array #f (array-shape array))))
+ (array-index-map! ra (lambda x x))
+ ra))
+@end example
+Another example:
+@example
+(define (apl:index-generator n)
+ (let ((v (make-uniform-vector n 1)))
+ (array-index-map! v (lambda (i) i))
+ v))
+@end example")
#define FUNC_NAME s_scm_array_index_map_x
{
scm_sizet i;
@@ -2015,6 +2042,20 @@ scm_raequal (SCM ra0, SCM ra1)
return SCM_BOOL(raeql (ra0, SCM_BOOL_T, ra1));
}
+#if 0
+/* GJB:FIXME:: Why not use GUILE_PROC1 for array-equal? */
+GUILE_PROC1(scm_array_equal_p, "array-equal?", scm_tc7_rpsubr,
+ (SCM ra0, SCM ra1),
+"Returns @code{#t} iff all arguments are arrays with the same shape, the
+same type, and have corresponding elements which are either
+@code{equal?} or @code{array-equal?}. This function differs from
+@code{equal?} in that a one dimensional shared array may be
+@var{array-equal?} but not @var{equal?} to a vector or uniform vector.")
+#define FUNC_NAME s_scm_array_equal_p
+...
+#undef FUNC_NAME
+#endif
+
static char s_array_equal_p[] = "array-equal?";
diff --git a/libguile/regex-posix.c b/libguile/regex-posix.c
index f52c72335..ea4d6bad5 100644
--- a/libguile/regex-posix.c
+++ b/libguile/regex-posix.c
@@ -135,7 +135,8 @@ scm_regexp_error_msg (int regerrno, regex_t *rx)
GUILE_PROC (scm_regexp_p, "regexp?", 1, 0, 0,
(SCM x),
-"")
+"Return @code{#t} if @var{obj} is a compiled regular expression, or
+@code{#f} otherwise.")
#define FUNC_NAME s_scm_regexp_p
{
return SCM_BOOL(SCM_NIMP (x) && SCM_RGXP (x));
@@ -144,7 +145,44 @@ GUILE_PROC (scm_regexp_p, "regexp?", 1, 0, 0,
GUILE_PROC (scm_make_regexp, "make-regexp", 1, 0, 1,
(SCM pat, SCM flags),
-"")
+"Compile the regular expression described by @var{str}, and return the
+compiled regexp structure. If @var{str} does not describe a legal
+regular expression, @code{make-regexp} throws a
+@code{regular-expression-syntax} error.
+
+The @var{flag} arguments change the behavior of the compiled regexp.
+The following flags may be supplied:
+
+@table @code
+@item regexp/icase
+Consider uppercase and lowercase letters to be the same when matching.
+
+@item regexp/newline
+If a newline appears in the target string, then permit the @samp{^} and
+@samp{$} operators to match immediately after or immediately before the
+newline, respectively. Also, the @samp{.} and @samp{[^...]} operators
+will never match a newline character. The intent of this flag is to
+treat the target string as a buffer containing many lines of text, and
+the regular expression as a pattern that may match a single one of those
+lines.
+
+@item regexp/basic
+Compile a basic (``obsolete'') regexp instead of the extended
+(``modern'') regexps that are the default. Basic regexps do not
+consider @samp{|}, @samp{+} or @samp{?} to be special characters, and
+require the @samp{@{...@}} and @samp{(...)} metacharacters to be
+backslash-escaped (@pxref{Backslash Escapes}). There are several other
+differences between basic and extended regular expressions, but these
+are the most significant.
+
+@item regexp/extended
+Compile an extended regular expression rather than a basic regexp. This
+is the default behavior; this flag will not usually be needed. If a
+call to @code{make-regexp} includes both @code{regexp/basic} and
+@code{regexp/extended} flags, the one which comes last will override
+the earlier one.
+@end table
+")
#define FUNC_NAME s_scm_make_regexp
{
SCM flag;
@@ -187,7 +225,10 @@ GUILE_PROC (scm_make_regexp, "make-regexp", 1, 0, 1,
GUILE_PROC (scm_regexp_exec, "regexp-exec", 2, 2, 0,
(SCM rx, SCM str, SCM start, SCM flags),
-"")
+"Match the compiled regular expression @var{regexp} against @code{str}.
+If the optional integer @var{start} argument is provided, begin matching
+from that position in the string. Return a match structure describing
+the results of the match, or @code{#f} if no match could be found.")
#define FUNC_NAME s_scm_regexp_exec
{
int status, nmatches, offset;
diff --git a/libguile/root.c b/libguile/root.c
index 5d2dd8d43..023990194 100644
--- a/libguile/root.c
+++ b/libguile/root.c
@@ -337,7 +337,48 @@ cwdr (SCM proc, SCM a1, SCM args, SCM handler, SCM_STACKITEM *stack_start)
GUILE_PROC(scm_call_with_dynamic_root, "call-with-dynamic-root", 2, 0, 0,
(SCM thunk, SCM handler),
-"")
+"Evaluate @var{(thunk)} in a new dynamic context, returning its value.
+
+If an error occurs during evaluation, apply @var{handler} to the
+arguments to the throw, just as @code{throw} would. If this happens,
+@var{handler} is called outside the scope of the new root -- it is
+called in the same dynamic context in which
+@code{call-with-dynamic-root} was evaluated.
+
+If @var{thunk} captures a continuation, the continuation is rooted at
+the call to @var{thunk}. In particular, the call to
+@code{call-with-dynamic-root} is not captured. Therefore,
+@code{call-with-dynamic-root} always returns at most one time.
+
+Before calling @var{thunk}, the dynamic-wind chain is un-wound back to
+the root and a new chain started for @var{thunk}. Therefore, this call
+may not do what you expect:
+
+@example
+;; Almost certainly a bug:
+(with-output-to-port
+ some-port
+
+ (lambda ()
+ (call-with-dynamic-root
+ (lambda ()
+ (display 'fnord)
+ (newline))
+ (lambda (errcode) errcode))))
+@end example
+
+The problem is, on what port will @samp{fnord\n} be displayed? You
+might expect that because of the @code{with-output-to-port} that
+it will be displayed on the port bound to @code{some-port}. But it
+probably won't -- before evaluating the thunk, dynamic winds are
+unwound, including those created by @code{with-output-to-port}.
+So, the standard output port will have been re-set to its default value
+before @code{display} is evaluated.
+
+(This function was added to Guile mostly to help calls to functions in C
+libraries that can not tolerate non-local exits or calls that return
+multiple times. If such functions call back to the interpreter, it should
+be under a new dynamic root.)")
#define FUNC_NAME s_scm_call_with_dynamic_root
{
SCM_STACKITEM stack_place;
@@ -347,7 +388,11 @@ GUILE_PROC(scm_call_with_dynamic_root, "call-with-dynamic-root", 2, 0, 0,
GUILE_PROC(scm_dynamic_root, "dynamic-root", 0, 0, 0,
(),
-"")
+"Return an object representing the current dynamic root.
+
+These objects are only useful for comparison using @code{eq?}.
+They are currently represented as numbers, but your code should
+in no way depend on this.")
#define FUNC_NAME s_scm_dynamic_root
{
return scm_ulong2num (SCM_SEQ (scm_root->rootcont));
diff --git a/libguile/scmsigs.c b/libguile/scmsigs.c
index c46835578..6a2c3ace6 100644
--- a/libguile/scmsigs.c
+++ b/libguile/scmsigs.c
@@ -181,7 +181,32 @@ sys_deliver_signals (void)
/* user interface for installation of signal handlers. */
GUILE_PROC(scm_sigaction, "sigaction", 1, 2, 0,
(SCM signum, SCM handler, SCM flags),
-"")
+"Install or report the signal hander for a specified signal.
+
+@var{signum} is the signal number, which can be specified using the value
+of variables such as @code{SIGINT}.
+
+If @var{action} is omitted, @code{sigaction} returns a pair: the
+CAR is the current
+signal hander, which will be either an integer with the value @code{SIG_DFL}
+(default action) or @code{SIG_IGN} (ignore), or the Scheme procedure which
+handles the signal, or @code{#f} if a non-Scheme procedure handles the
+signal. The CDR contains the current @code{sigaction} flags for the handler.
+
+If @var{action} is provided, it is installed as the new handler for
+@var{signum}. @var{action} can be a Scheme procedure taking one
+argument, or the value of @code{SIG_DFL} (default action) or
+@code{SIG_IGN} (ignore), or @code{#f} to restore whatever signal handler
+was installed before @code{sigaction} was first used. Flags can
+optionally be specified for the new handler (@code{SA_RESTART} will
+always be added if it's available and the system is using rstartable
+system calls.) The return value is a pair with information about the
+old handler as described above.
+
+This interface does not provide access to the \"signal blocking\"
+facility. Maybe this is not needed, since the thread support may
+provide solutions to the problem of consistent access to data
+structures.")
#define FUNC_NAME s_scm_sigaction
{
int csig;
@@ -312,7 +337,8 @@ GUILE_PROC(scm_sigaction, "sigaction", 1, 2, 0,
GUILE_PROC (scm_restore_signals, "restore-signals", 0, 0, 0,
(void),
-"")
+"Return all signal handlers to the values they had before any call to
+@code{sigaction} was made. The return value is unspecified.")
#define FUNC_NAME s_scm_restore_signals
{
int i;
@@ -344,7 +370,15 @@ GUILE_PROC (scm_restore_signals, "restore-signals", 0, 0, 0,
GUILE_PROC(scm_alarm, "alarm", 1, 0, 0,
(SCM i),
-"")
+"Set a timer to raise a @code{SIGALRM} signal after the specified
+number of seconds (an integer). It's advisable to install a signal
+handler for
+@code{SIGALRM} beforehand, since the default action is to terminate
+the process.
+
+The return value indicates the time remaining for the previous alarm,
+if any. The new value replaces the previous alarm. If there was
+no previous alarm, the return value is zero.")
#define FUNC_NAME s_scm_alarm
{
unsigned int j;
@@ -357,7 +391,9 @@ GUILE_PROC(scm_alarm, "alarm", 1, 0, 0,
#ifdef HAVE_PAUSE
GUILE_PROC(scm_pause, "pause", 0, 0, 0,
(),
-"")
+"Pause the current process (thread?) until a signal arrives whose
+action is to either terminate the current process or invoke a
+handler procedure. The return value is unspecified.")
#define FUNC_NAME s_scm_pause
{
pause ();
@@ -368,7 +404,9 @@ GUILE_PROC(scm_pause, "pause", 0, 0, 0,
GUILE_PROC(scm_sleep, "sleep", 1, 0, 0,
(SCM i),
-"")
+"Wait for the given number of seconds (an integer) or until a signal
+arrives. The return value is zero if the time elapses or the number
+of seconds remaining otherwise.")
#define FUNC_NAME s_scm_sleep
{
unsigned long j;
@@ -413,7 +451,9 @@ GUILE_PROC(scm_usleep, "usleep", 1, 0, 0,
GUILE_PROC(scm_raise, "raise", 1, 0, 0,
(SCM sig),
-"")
+"
+Sends a specified signal @var{sig} to the current process, where
+@var{sig} is as described for the kill procedure.")
#define FUNC_NAME s_scm_raise
{
SCM_VALIDATE_INT(1,sig);
diff --git a/libguile/simpos.c b/libguile/simpos.c
index 0a57f6bae..e23397baa 100644
--- a/libguile/simpos.c
+++ b/libguile/simpos.c
@@ -65,7 +65,13 @@ extern int system();
GUILE_PROC(scm_system, "system", 0, 1, 0,
(SCM cmd),
-"")
+"Executes @var{cmd} using the operating system's "command processor".
+Under Unix this is usually the default shell @code{sh}. The value
+returned is @var{cmd}'s exit status as returned by @code{waitpid}, which
+can be interpreted using the functions above.
+
+If @code{system} is called without arguments, it returns a boolean
+indicating whether the command processor is available.")
#define FUNC_NAME s_scm_system
{
int rv;
@@ -99,7 +105,10 @@ GUILE_PROC(scm_system, "system", 0, 1, 0,
extern char *getenv();
GUILE_PROC (scm_getenv, "getenv", 1, 0, 0,
(SCM nam),
-"")
+"Looks up the string @var{name} in the current environment. The return
+value is @code{#f} unless a string of the form @code{NAME=VALUE} is
+found, in which case the string @code{VALUE} is
+returned.")
#define FUNC_NAME s_scm_getenv
{
char *val;
@@ -113,7 +122,9 @@ GUILE_PROC (scm_getenv, "getenv", 1, 0, 0,
/* simple exit, without unwinding the scheme stack or flushing ports. */
GUILE_PROC (scm_primitive_exit, "primitive-exit", 0, 1, 0,
(SCM status),
-"")
+"Terminate the current process without unwinding the Scheme stack.
+This is would typically be useful after a fork. The exit status
+is @var{status} if supplied, otherwise zero.")
#define FUNC_NAME s_scm_primitive_exit
{
int cstatus = 0;
diff --git a/libguile/socket.c b/libguile/socket.c
index bc277855d..8732d9103 100644
--- a/libguile/socket.c
+++ b/libguile/socket.c
@@ -73,7 +73,9 @@
GUILE_PROC (scm_htons, "htons", 1, 0, 0,
(SCM in),
-"")
+"Returns a new integer from @var{value} by converting from host to
+network order. @var{value} must be within the range of a C unsigned
+short integer.")
#define FUNC_NAME s_scm_htons
{
unsigned short c_in;
@@ -88,7 +90,9 @@ GUILE_PROC (scm_htons, "htons", 1, 0, 0,
GUILE_PROC (scm_ntohs, "ntohs", 1, 0, 0,
(SCM in),
-"")
+"Returns a new integer from @var{value} by converting from network to
+host order. @var{value} must be within the range of a C unsigned short
+integer.")
#define FUNC_NAME s_scm_ntohs
{
unsigned short c_in;
@@ -103,7 +107,9 @@ GUILE_PROC (scm_ntohs, "ntohs", 1, 0, 0,
GUILE_PROC (scm_htonl, "htonl", 1, 0, 0,
(SCM in),
-"")
+"Returns a new integer from @var{value} by converting from host to
+network order. @var{value} must be within the range of a C unsigned
+long integer.")
#define FUNC_NAME s_scm_htonl
{
unsigned long c_in = SCM_NUM2ULONG (1,in);
@@ -113,7 +119,9 @@ GUILE_PROC (scm_htonl, "htonl", 1, 0, 0,
GUILE_PROC (scm_ntohl, "ntohl", 1, 0, 0,
(SCM in),
-"")
+"Returns a new integer from @var{value} by converting from network to
+host order. @var{value} must be within the range of a C unsigned
+long integer.")
#define FUNC_NAME s_scm_ntohl
{
unsigned long c_in = SCM_NUM2ULONG (1,in);
@@ -138,7 +146,18 @@ scm_sock_fd_to_port (int fd, const char *proc)
GUILE_PROC (scm_socket, "socket", 3, 0, 0,
(SCM family, SCM style, SCM proto),
-"")
+"Returns a new socket port of the type specified by @var{family}, @var{style}
+and @var{protocol}. All three parameters are integers. Typical values
+for @var{family} are the values of @code{AF_UNIX}
+and @code{AF_INET}. Typical values for @var{style} are
+the values of @code{SOCK_STREAM}, @code{SOCK_DGRAM} and @code{SOCK_RAW}.
+
+@var{protocol} can be obtained from a protocol name using
+@code{getprotobyname}. A value of
+zero specifies the default protocol, which is usually right.
+
+A single socket port cannot by used for communication until
+it has been connected to another socket.")
#define FUNC_NAME s_scm_socket
{
int fd;
@@ -158,7 +177,11 @@ GUILE_PROC (scm_socket, "socket", 3, 0, 0,
#ifdef HAVE_SOCKETPAIR
GUILE_PROC (scm_socketpair, "socketpair", 3, 0, 0,
(SCM family, SCM style, SCM proto),
-"")
+"Returns a pair of connected (but unnamed) socket ports of the type specified
+by @var{family}, @var{style} and @var{protocol}.
+Many systems support only
+socket pairs of the @code{AF_UNIX} family. Zero is likely to be
+the only meaningful value for @var{protocol}.")
#define FUNC_NAME s_scm_socketpair
{
int fam;
@@ -184,7 +207,15 @@ GUILE_PROC (scm_socketpair, "socketpair", 3, 0, 0,
GUILE_PROC (scm_getsockopt, "getsockopt", 3, 0, 0,
(SCM sock, SCM level, SCM optname),
-"")
+"Returns the value of a particular socket option for the socket
+port @var{socket}. @var{level} is an integer code for type of option
+being requested, e.g., @code{SOL_SOCKET} for socket-level options.
+@var{optname} is an
+integer code for the option required and should be specified using one of
+the symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc.
+
+The returned value is typically an integer but @code{SO_LINGER} returns a
+pair of integers.")
#define FUNC_NAME s_scm_getsockopt
{
int fd;
@@ -246,7 +277,17 @@ GUILE_PROC (scm_getsockopt, "getsockopt", 3, 0, 0,
GUILE_PROC (scm_setsockopt, "setsockopt", 4, 0, 0,
(SCM sock, SCM level, SCM optname, SCM value),
-"")
+"Sets the value of a particular socket option for the socket
+port @var{socket}. @var{level} is an integer code for type of option
+being set, e.g., @code{SOL_SOCKET} for socket-level options.
+@var{optname} is an
+integer code for the option to set and should be specified using one of
+the symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc.
+@var{value} is the value to which the option should be set. For
+most options this must be an integer, but for @code{SO_LINGER} it must
+be a pair.
+
+The return value is unspecified.")
#define FUNC_NAME s_scm_setsockopt
{
int fd;
@@ -319,7 +360,23 @@ GUILE_PROC (scm_setsockopt, "setsockopt", 4, 0, 0,
GUILE_PROC (scm_shutdown, "shutdown", 2, 0, 0,
(SCM sock, SCM how),
-"")
+"Sockets can be closed simply by using @code{close-port}. The
+@code{shutdown} procedure allows reception or tranmission on a
+connection to be shut down individually, according to the parameter
+@var{how}:
+
+@table @asis
+@item 0
+Stop receiving data for this socket. If further data arrives, reject it.
+@item 1
+Stop trying to transmit data from this socket. Discard any
+data waiting to be sent. Stop looking for acknowledgement of
+data already sent; don't retransmit it if it is lost.
+@item 2
+Stop both reception and transmission.
+@end table
+
+The return value is unspecified.")
#define FUNC_NAME s_scm_shutdown
{
int fd;
@@ -392,7 +449,20 @@ scm_fill_sockaddr (int fam,SCM address,SCM *args,int which_arg,const char *proc,
GUILE_PROC (scm_connect, "connect", 3, 0, 1,
(SCM sock, SCM fam, SCM address, SCM args),
-"")
+"Initiates a connection from @var{socket} to the address
+specified by @var{address} and possibly @var{arg @dots{}}. The format
+required for @var{address}
+and @var{arg} @dots{} depends on the family of the socket.
+
+For a socket of family @code{AF_UNIX},
+only @code{address} is specified and must be a string with the
+filename where the socket is to be created.
+
+For a socket of family @code{AF_INET},
+@code{address} must be an integer Internet host address and @var{arg} @dots{}
+must be a single integer port number.
+
+The return value is unspecified.")
#define FUNC_NAME s_scm_connect
{
int fd;
@@ -413,7 +483,42 @@ GUILE_PROC (scm_connect, "connect", 3, 0, 1,
GUILE_PROC (scm_bind, "bind", 3, 0, 1,
(SCM sock, SCM fam, SCM address, SCM args),
-"")
+"Assigns an address to the socket port @var{socket}.
+Generally this only needs to be done for server sockets,
+so they know where to look for incoming connections. A socket
+without an address will be assigned one automatically when it
+starts communicating.
+
+The format of @var{address} and @var{ARG} @dots{} depends on the family
+of the socket.
+
+For a socket of family @code{AF_UNIX}, only @var{address}
+is specified and must
+be a string with the filename where the socket is to be created.
+
+For a socket of family @code{AF_INET}, @var{address} must be an integer
+Internet host address and @var{arg} @dots{} must be a single integer
+port number.
+
+The values of the following variables can also be used for @var{address}:
+
+@defvar INADDR_ANY
+Allow connections from any address.
+@end defvar
+
+@defvar INADDR_LOOPBACK
+The address of the local host using the loopback device.
+@end defvar
+
+@defvar INADDR_BROADCAST
+The broadcast address on the local network.
+@end defvar
+
+@defvar INADDR_NONE
+No address.
+@end defvar
+
+The return value is unspecified.")
#define FUNC_NAME s_scm_bind
{
int rv;
@@ -436,7 +541,13 @@ GUILE_PROC (scm_bind, "bind", 3, 0, 1,
GUILE_PROC (scm_listen, "listen", 2, 0, 0,
(SCM sock, SCM backlog),
-"")
+"This procedure enables @var{socket} to accept connection
+requests. @var{backlog} is an integer specifying
+the maximum length of the queue for pending connections.
+If the queue fills, new clients will fail to connect until the
+server calls @code{accept} to accept a connection from the queue.
+
+The return value is unspecified.")
#define FUNC_NAME s_scm_listen
{
int fd;
@@ -507,7 +618,20 @@ scm_init_addr_buffer (void)
GUILE_PROC (scm_accept, "accept", 1, 0, 0,
(SCM sock),
-"")
+"Accepts a connection on a bound, listening socket @var{socket}. If there
+are no pending connections in the queue, it waits until
+one is available unless the non-blocking option has been set on the
+socket.
+
+The return value is a
+pair in which the CAR is a new socket port for the connection and
+the CDR is an object with address information about the client which
+initiated the connection.
+
+If the address is not available then the CDR will be an empty vector.
+
+@var{socket} does not become part of the
+connection and will continue to accept new requests.")
#define FUNC_NAME s_scm_accept
{
int fd;
@@ -533,7 +657,9 @@ GUILE_PROC (scm_accept, "accept", 1, 0, 0,
GUILE_PROC (scm_getsockname, "getsockname", 1, 0, 0,
(SCM sock),
-"")
+"Returns the address of @var{socket}, in the same form as the object
+returned by @code{accept}. On many systems the address of a socket
+in the @code{AF_FILE} namespace cannot be read.")
#define FUNC_NAME s_scm_getsockname
{
int tmp_size;
@@ -555,7 +681,10 @@ GUILE_PROC (scm_getsockname, "getsockname", 1, 0, 0,
GUILE_PROC (scm_getpeername, "getpeername", 1, 0, 0,
(SCM sock),
-"")
+"Returns the address of the socket that the socket @var{socket} is connected to,
+in the same form as the object
+returned by @code{accept}. On many systems the address of a socket
+in the @code{AF_FILE} namespace cannot be read.")
#define FUNC_NAME s_scm_getpeername
{
int tmp_size;
@@ -577,7 +706,21 @@ GUILE_PROC (scm_getpeername, "getpeername", 1, 0, 0,
GUILE_PROC (scm_recv, "recv!", 2, 1, 0,
(SCM sock, SCM buf, SCM flags),
-"")
+"Receives data from the socket port @var{socket}. @var{socket} must already
+be bound to the address from which data is to be received.
+@var{buf} is a string into which
+the data will be written. The size of @var{buf} limits the amount of
+data which can be received: in the case of packet
+protocols, if a packet larger than this limit is encountered then some data
+will be irrevocably lost.
+
+The optional @var{flags} argument is a value or
+bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc.
+
+The value returned is the number of bytes read from the socket.
+
+Note that the data is read directly from the socket file descriptor:
+any unread buffered port data is ignored.")
#define FUNC_NAME s_scm_recv
{
int rv;
@@ -599,7 +742,15 @@ GUILE_PROC (scm_recv, "recv!", 2, 1, 0,
GUILE_PROC (scm_send, "send", 2, 1, 0,
(SCM sock, SCM message, SCM flags),
-"")
+"Transmits the string @var{message} on the socket port @var{socket}.
+@var{socket} must already be bound to a destination address. The
+value returned is the number of bytes transmitted -- it's possible for
+this to be less than the length of @var{message} if the socket is
+set to be non-blocking. The optional @var{flags} argument is a value or
+bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc.
+
+Note that the data is written directly to the socket file descriptor:
+any unflushed buffered port data is ignored.")
#define FUNC_NAME s_scm_send
{
int rv;
@@ -621,7 +772,27 @@ GUILE_PROC (scm_send, "send", 2, 1, 0,
GUILE_PROC (scm_recvfrom, "recvfrom!", 2, 3, 0,
(SCM sock, SCM buf, SCM flags, SCM start, SCM end),
-"")
+"Returns data from the socket port @var{socket} and also information about
+where the data was received from. @var{socket} must already
+be bound to the address from which data is to be received.
+@code{buf}, is a string into which
+the data will be written. The size of @var{buf} limits the amount of
+data which can be received: in the case of packet
+protocols, if a packet larger than this limit is encountered then some data
+will be irrevocably lost.
+
+The optional @var{flags} argument is a value or
+bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc.
+
+The value returned is a pair: the CAR is the number of bytes read from
+the socket and the CDR an address object in the same form as returned by
+@code{accept}.
+
+The @var{start} and @var{end} arguments specify a substring of @var{buf}
+to which the data should be written.
+
+Note that the data is read directly from the socket file descriptor:
+any unread buffered port data is ignored.")
#define FUNC_NAME s_scm_recvfrom
{
int rv;
@@ -681,7 +852,17 @@ GUILE_PROC (scm_recvfrom, "recvfrom!", 2, 3, 0,
GUILE_PROC (scm_sendto, "sendto", 4, 0, 1,
(SCM sock, SCM message, SCM fam, SCM address, SCM args_and_flags),
-"")
+"Transmits the string @var{message} on the socket port @var{socket}. The
+destination address is specified using the @var{family}, @var{address} and
+@var{arg} arguments, in a similar way to the @code{connect}
+procedure. The
+value returned is the number of bytes transmitted -- it's possible for
+this to be less than the length of @var{message} if the socket is
+set to be non-blocking. The optional @var{flags} argument is a value or
+bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc.
+
+Note that the data is written directly to the socket file descriptor:
+any unflushed buffered port data is ignored.")
#define FUNC_NAME s_scm_sendto
{
int rv;
diff --git a/libguile/stacks.c b/libguile/stacks.c
index 0e83aaeee..8b2a2e6ce 100644
--- a/libguile/stacks.c
+++ b/libguile/stacks.c
@@ -412,7 +412,7 @@ SCM scm_stack_type;
GUILE_PROC (scm_stack_p, "stack?", 1, 0, 0,
(SCM obj),
-"")
+"Return @code{#t} if @var{obj} is a calling stack.")
#define FUNC_NAME s_scm_stack_p
{
return SCM_BOOL(SCM_NIMP (obj) && SCM_STACKP (obj));
@@ -514,7 +514,7 @@ GUILE_PROC (scm_make_stack, "make-stack", 0, 0, 1,
GUILE_PROC (scm_stack_id, "stack-id", 1, 0, 0,
(SCM stack),
-"")
+"Return the identifier given to @var{stack} by @code{start-stack}.")
#define FUNC_NAME s_scm_stack_id
{
scm_debug_frame *dframe;
diff --git a/libguile/stime.c b/libguile/stime.c
index 06db12480..e266d03eb 100644
--- a/libguile/stime.c
+++ b/libguile/stime.c
@@ -131,7 +131,7 @@ struct timeb scm_your_base = {0};
GUILE_PROC(scm_get_internal_real_time, "get-internal-real-time", 0, 0, 0,
(),
-"")
+"Returns the number of time units since the interpreter was started.")
#define FUNC_NAME s_scm_get_internal_real_time
{
struct timeb time_buffer;
@@ -166,7 +166,25 @@ GUILE_PROC(scm_get_internal_real_time, "get-internal-real-time", 0, 0, 0,
GUILE_PROC (scm_times, "times", 0, 0, 0,
(void),
-"")
+"Returns an object with information about real and processor time.
+The following procedures accept such an object as an argument and
+return a selected component:
+
+@table @code
+@item tms:clock
+The current real time, expressed as time units relative to an
+arbitrary base.
+@item tms:utime
+The CPU time units used by the calling process.
+@item tms:stime
+The CPU time units used by the system on behalf of the calling process.
+@item tms:cutime
+The CPU time units used by terminated child processes of the calling
+process, whose status has been collected (e.g., using @code{waitpid}).
+@item tms:cstime
+Similarly, the CPU times units used by the system on behalf of
+terminated child processes.
+@end table")
#define FUNC_NAME s_scm_times
{
#ifdef HAVE_TIMES
@@ -199,7 +217,9 @@ static long scm_my_base = 0;
GUILE_PROC(scm_get_internal_run_time, "get-internal-run-time", 0, 0, 0,
(void),
-"")
+"Returns the number of time units of processor time used by the interpreter.
+Both "system" and "user" time
+are included but subprocesses are not.")
#define FUNC_NAME s_scm_get_internal_run_time
{
return scm_long2num(mytime()-scm_my_base);
@@ -208,7 +228,8 @@ GUILE_PROC(scm_get_internal_run_time, "get-internal-run-time", 0, 0, 0,
GUILE_PROC(scm_current_time, "current-time", 0, 0, 0,
(void),
-"")
+"Returns the number of seconds since 1970-01-01 00:00:00 UTC, excluding
+leap seconds.")
#define FUNC_NAME s_scm_current_time
{
timet timv;
@@ -223,7 +244,9 @@ GUILE_PROC(scm_current_time, "current-time", 0, 0, 0,
GUILE_PROC (scm_gettimeofday, "gettimeofday", 0, 0, 0,
(void),
-"")
+"Returns a pair containing the number of seconds and microseconds since
+1970-01-01 00:00:00 UTC, excluding leap seconds. Note: whether true
+microsecond resolution is available depends on the operating system.")
#define FUNC_NAME s_scm_gettimeofday
{
#ifdef HAVE_GETTIMEOFDAY
@@ -316,7 +339,11 @@ restorezone (SCM zone, char **oldenv, const char *subr)
GUILE_PROC (scm_localtime, "localtime", 1, 1, 0,
(SCM time, SCM zone),
-"")
+"Returns an object representing the broken down components of @var{time},
+an integer like the one returned by @code{current-time}. The time zone
+for the calculation is optionally specified by @var{zone} (a string),
+otherwise the @code{TZ} environment variable or the system default is
+used.")
#define FUNC_NAME s_scm_localtime
{
timet itime;
@@ -382,7 +409,9 @@ GUILE_PROC (scm_localtime, "localtime", 1, 1, 0,
GUILE_PROC (scm_gmtime, "gmtime", 1, 0, 0,
(SCM time),
-"")
+"Returns an object representing the broken down components of @var{time},
+an integer like the one returned by @code{current-time}. The values
+are calculated for UTC.")
#define FUNC_NAME s_scm_gmtime
{
timet itime;
@@ -439,7 +468,14 @@ bdtime2c (SCM sbd_time, struct tm *lt, int pos, const char *subr)
GUILE_PROC (scm_mktime, "mktime", 1, 1, 0,
(SCM sbd_time, SCM zone),
-"")
+"@var{bd-time} is an object representing broken down time and @code{zone}
+is an optional time zone specifier (otherwise the TZ environment variable
+or the system default is used).
+
+Returns a pair: the CAR is a corresponding
+integer time value like that returned
+by @code{current-time}; the CDR is a broken down time object, similar to
+as @var{bd-time} but with normalized values.")
#define FUNC_NAME s_scm_mktime
{
timet itime;
@@ -508,7 +544,10 @@ GUILE_PROC (scm_mktime, "mktime", 1, 1, 0,
GUILE_PROC (scm_tzset, "tzset", 0, 0, 0,
(void),
-"")
+"Initialize the timezone from the TZ environment variable or the system
+default. Usually this is done automatically by other procedures which
+use the time zone, but this procedure may need to be used if TZ
+is changed.")
#define FUNC_NAME s_scm_tzset
{
tzset();
@@ -518,7 +557,13 @@ GUILE_PROC (scm_tzset, "tzset", 0, 0, 0,
GUILE_PROC (scm_strftime, "strftime", 2, 0, 0,
(SCM format, SCM stime),
-"")
+"Formats a time specification @var{time} using @var{template}. @var{time}
+is an object with time components in the form returned by @code{localtime}
+or @code{gmtime}. @var{template} is a string which can include formatting
+specifications introduced by a @code{%} character. The formatting of
+month and day names is dependent on the current locale. The value returned
+is the formatted string.
+@xref{Formatting Date and Time, , , libc, The GNU C Library Reference Manual}.)")
#define FUNC_NAME s_scm_strftime
{
struct tm t;
@@ -551,7 +596,16 @@ GUILE_PROC (scm_strftime, "strftime", 2, 0, 0,
GUILE_PROC (scm_strptime, "strptime", 2, 0, 0,
(SCM format, SCM string),
-"")
+"Performs the reverse action to @code{strftime}, parsing @var{string}
+according to the specification supplied in @var{template}. The
+interpretation of month and day names is dependent on the current
+locale. The
+value returned is a pair. The CAR has an object with time components
+in the form returned by @code{localtime} or @code{gmtime},
+but the time zone components
+are not usefully set.
+The CDR reports the number of characters from @var{string} which
+were used for the conversion.")
#define FUNC_NAME s_scm_strptime
{
#ifdef HAVE_STRPTIME
diff --git a/libguile/strings.c b/libguile/strings.c
index 3ed6fa2fc..d245ad9c9 100644
--- a/libguile/strings.c
+++ b/libguile/strings.c
@@ -68,7 +68,18 @@ GUILE_PROC(scm_string_p, "string?", 1, 0, 0,
GUILE_PROC(scm_read_only_string_p, "read-only-string?", 1, 0, 0,
(SCM x),
-"")
+"Return true of OBJ can be read as a string,
+
+This illustrates the difference between @code{string?} and
+@code{read-only-string?}:
+
+@example
+(string? \"a string\") @result{} #t
+(string? 'a-symbol) @result{} #f
+
+(read-only-string? \"a string\") @result{} #t
+(read-only-string? 'a-symbol) @result{} #t
+@end example")
#define FUNC_NAME s_scm_read_only_string_p
{
if (SCM_IMP (x))
@@ -342,7 +353,13 @@ GUILE_PROC(scm_string_append, "string-append", 0, 0, 1,
GUILE_PROC(scm_make_shared_substring, "make-shared-substring", 1, 2, 0,
(SCM str, SCM frm, SCM to),
-"")
+"Return a shared substring of @var{str}. The semantics are the same as
+for the @code{substring} function: the shared substring returned
+includes all of the text from @var{str} between indexes @var{start}
+(inclusive) and @var{end} (exclusive). If @var{end} is omitted, it
+defaults to the end of @var{str}. The shared substring returned by
+@code{make-shared-substring} occupies the same storage space as
+@var{str}.")
#define FUNC_NAME s_scm_make_shared_substring
{
long f;
diff --git a/libguile/strop.c b/libguile/strop.c
index 996fd37f9..2aecdecbb 100644
--- a/libguile/strop.c
+++ b/libguile/strop.c
@@ -88,7 +88,10 @@ scm_i_index (SCM *str, SCM chr, int direction, SCM sub_start,
GUILE_PROC(scm_string_index, "string-index", 2, 2, 0,
(SCM str, SCM chr, SCM frm, SCM to),
-"")
+"Return the index of the first occurrence of @var{chr} in @var{str}. The
+optional integer arguments @var{frm} and @var{to} limit the search to
+a portion of the string. This procedure essentially implements the
+@code{index} or @code{strchr} functions from the C library.")
#define FUNC_NAME s_scm_string_index
{
int pos;
@@ -106,7 +109,9 @@ GUILE_PROC(scm_string_index, "string-index", 2, 2, 0,
GUILE_PROC(scm_string_rindex, "string-rindex", 2, 2, 0,
(SCM str, SCM chr, SCM frm, SCM to),
-"")
+"Like @code{string-index}, but search from the right of the string rather
+than from the left. This procedure essentially implements the
+@code{rindex} or @code{strrchr} functions from the C library.")
#define FUNC_NAME s_scm_string_rindex
{
int pos;
@@ -129,7 +134,22 @@ SCM_REGISTER_PROC(s_substring_move_right_x, "substring-move-right!", 5, 0, 0, sc
GUILE_PROC(scm_substring_move_x, "substring-move!", 5, 0, 0,
(SCM str1, SCM start1, SCM end1, SCM str2, SCM start2),
-"")
+"Copy the substring of @var{str1} bounded by @var{start1} and @var{end1}
+into @var{str2} beginning at position @var{end2}.
+@code{substring-move-right!} begins copying from the rightmost character
+and moves left, and @code{substring-move-left!} copies from the leftmost
+character moving right.
+
+It is useful to have two functions that copy in different directions so
+that substrings can be copied back and forth within a single string. If
+you wish to copy text from the left-hand side of a string to the
+right-hand side of the same string, and the source and destination
+overlap, you must be careful to copy the rightmost characters of the
+text first, to avoid clobbering your data. Hence, when @var{str1} and
+@var{str2} are the same string, you should use
+@code{substring-move-right!} when moving text from left to right, and
+@code{substring-move-left!} otherwise. If @code{str1} and @samp{str2}
+are different strings, it does not matter which function you use.")
#define FUNC_NAME s_scm_substring_move_x
{
long s1, s2, e, len;
@@ -157,7 +177,8 @@ GUILE_PROC(scm_substring_move_x, "substring-move!", 5, 0, 0,
GUILE_PROC(scm_substring_fill_x, "substring-fill!", 4, 0, 0,
(SCM str, SCM start, SCM end, SCM fill),
-"")
+"Change every character in @var{str} between @var{start} and @var{end} to
+@var{fill-char}.")
#define FUNC_NAME s_scm_substring_fill_x
{
long i, e;
@@ -176,7 +197,8 @@ GUILE_PROC(scm_substring_fill_x, "substring-fill!", 4, 0, 0,
GUILE_PROC(scm_string_null_p, "string-null?", 1, 0, 0,
(SCM str),
-"")
+"Return @code{#t} if @var{str}'s length is nonzero, and @code{#f}
+otherwise.")
#define FUNC_NAME s_scm_string_null_p
{
SCM_VALIDATE_ROSTRING(1,str);
@@ -229,7 +251,8 @@ GUILE_PROC(scm_string_fill_x, "string-fill!", 2, 0, 0,
GUILE_PROC(scm_string_upcase_x, "string-upcase!", 1, 0, 0,
(SCM v),
-"")
+"@deffnx primitive string-downcase! str
+Upcase or downcase every character in @code{str}, respectively.")
#define FUNC_NAME s_scm_string_upcase_x
{
register long k;
diff --git a/libguile/strports.c b/libguile/strports.c
index 13b7ef8c6..40677cb10 100644
--- a/libguile/strports.c
+++ b/libguile/strports.c
@@ -297,7 +297,9 @@ SCM scm_strport_to_string (SCM port)
GUILE_PROC(scm_call_with_output_string, "call-with-output-string", 1, 0, 0,
(SCM proc),
-"")
+"Calls the one-argument procedure @var{proc} with a newly created output
+port. When the function returns, the string composed of the characters
+written into the port is returned.")
#define FUNC_NAME s_scm_call_with_output_string
{
SCM p;
@@ -337,7 +339,9 @@ scm_strprint_obj (SCM obj)
GUILE_PROC(scm_call_with_input_string, "call-with-input-string", 2, 0, 0,
(SCM str, SCM proc),
-"")
+"Calls the one-argument procedure @var{proc} with a newly created input
+port from which @var{string}'s contents may be read. The value yielded
+by the @var{proc} is returned.")
#define FUNC_NAME s_scm_call_with_input_string
{
SCM p = scm_mkstrport(SCM_INUM0, str, SCM_OPN | SCM_RDNG, FUNC_NAME);
@@ -376,7 +380,8 @@ scm_eval_0str (const char *expr)
GUILE_PROC (scm_eval_string, "eval-string", 1, 0, 0,
(SCM string),
-"")
+"Evaluate @var{string} as the text representation of a Scheme form
+or forms, and return whatever value they produce.")
#define FUNC_NAME s_scm_eval_string
{
SCM port = scm_mkstrport (SCM_INUM0, string, SCM_OPN | SCM_RDNG,
diff --git a/libguile/struct.c b/libguile/struct.c
index f6670486b..f3c50509a 100644
--- a/libguile/struct.c
+++ b/libguile/struct.c
@@ -68,7 +68,16 @@ SCM scm_struct_table;
GUILE_PROC (scm_make_struct_layout, "make-struct-layout", 1, 0, 0,
(SCM fields),
-"")
+"Return a new structure layout object.
+
+@var{fields} must be a read-only string made up of pairs of characters
+strung together. The first character of each pair describes a field
+type, the second a field protection. Allowed types are 'p' for
+GC-protected Scheme data, 'u' for unprotected binary data, and 's' for
+fields that should point to the structure itself. Allowed protections
+are 'w' for mutable fields, 'r' for read-only fields, and 'o' for opaque
+fields. The last field protection specification may be capitalized to
+indicate that the field is a tail-array.")
#define FUNC_NAME s_scm_make_struct_layout
{
SCM new_sym;
@@ -233,7 +242,7 @@ scm_struct_init (SCM handle, int tail_elts, SCM inits)
GUILE_PROC (scm_struct_p, "struct?", 1, 0, 0,
(SCM x),
-"")
+"Return #t iff @var{obj} is a structure object, else #f.")
#define FUNC_NAME s_scm_struct_p
{
return SCM_BOOL(SCM_NIMP (x) && SCM_STRUCTP (x));
@@ -242,7 +251,7 @@ GUILE_PROC (scm_struct_p, "struct?", 1, 0, 0,
GUILE_PROC (scm_struct_vtable_p, "struct-vtable?", 1, 0, 0,
(SCM x),
-"")
+"Return #t iff obj is a vtable structure.")
#define FUNC_NAME s_scm_struct_vtable_p
{
SCM layout;
@@ -360,7 +369,19 @@ scm_struct_free_entity (SCM *vtable, SCM *data)
GUILE_PROC (scm_make_struct, "make-struct", 2, 0, 1,
(SCM vtable, SCM tail_array_size, SCM init),
-"")
+"Create a new structure.
+
+@var{type} must be a vtable structure (@xref{Vtables}).
+
+@var{tail-elts} must be a non-negative integer. If the layout
+specification indicated by @var{type} includes a tail-array,
+this is the number of elements allocated to that array.
+
+The @var{inits} are optional arguments describing how successive fields
+of the structure should be initialized. Only fields with protection 'r'
+or 'w' can be initialized -- fields of protection 's' are automatically
+initialized to point to the new structure itself; fields of protection 'o'
+can not be initialized by Scheme programs.")
#define FUNC_NAME s_scm_make_struct
{
SCM layout;
@@ -401,7 +422,71 @@ GUILE_PROC (scm_make_struct, "make-struct", 2, 0, 1,
GUILE_PROC (scm_make_vtable_vtable, "make-vtable-vtable", 2, 0, 1,
(SCM extra_fields, SCM tail_array_size, SCM init),
-"")
+"Return a new, self-describing vtable structure.
+
+@var{new-fields} is a layout specification describing fields
+of the resulting structure beginning at the position bound to
+@code{vtable-offset-user}.
+
+@var{tail-size} specifies the size of the tail-array (if any) of
+this vtable.
+
+@var{inits} initializes the fields of the vtable. Minimally, one
+initializer must be provided: the layout specification for instances
+of the type this vtable will describe. If a second initializer is
+provided, it will be interpreted as a print call-back function.
+
+@example
+;;; loading ,a...
+(define x
+ (make-vtable-vtable (make-struct-layout (quote pw))
+ 0
+ 'foo))
+
+(struct? x)
+@result{} #t
+(struct-vtable? x)
+@result{} #t
+(eq? x (struct-vtable x))
+@result{} #t
+(struct-ref x vtable-offset-user)
+@result{} foo
+(struct-ref x 0)
+@result{} pruosrpwpw
+
+
+(define y
+ (make-struct x
+ 0
+ (make-struct-layout (quote pwpwpw))
+ 'bar))
+
+(struct? y)
+@result{} #t
+(struct-vtable? y)
+@result{} #t
+(eq? x y)
+@result{} ()
+(eq? x (struct-vtable y))
+@result{} #t
+(struct-ref y 0)
+@result{} pwpwpw
+(struct-ref y vtable-offset-user)
+@result{} bar
+
+
+(define z (make-struct y 0 'a 'b 'c))
+
+(struct? z)
+@result{} #t
+(struct-vtable? z)
+@result{} ()
+(eq? y (struct-vtable z))
+@result{} #t
+(map (lambda (n) (struct-ref z n)) '(0 1 2))
+@result{} (a b c)
+@end example
+")
#define FUNC_NAME s_scm_make_vtable_vtable
{
SCM fields;
@@ -439,7 +524,13 @@ GUILE_PROC (scm_make_vtable_vtable, "make-vtable-vtable", 2, 0, 1,
GUILE_PROC (scm_struct_ref, "struct-ref", 2, 0, 0,
(SCM handle, SCM pos),
-"")
+"@deffnx primitive struct-set! struct n value
+Access (or modify) the @var{n}th field of @var{struct}.
+
+If the field is of type 'p', then it can be set to an arbitrary value.
+
+If the field is of type 'u', then it can only be set to a non-negative
+integer value small enough to fit in one machine word.")
#define FUNC_NAME s_scm_struct_ref
{
SCM answer = SCM_UNDEFINED;
@@ -592,7 +683,7 @@ GUILE_PROC (scm_struct_set_x, "struct-set!", 3, 0, 0,
GUILE_PROC (scm_struct_vtable, "struct-vtable", 1, 0, 0,
(SCM handle),
-"")
+"Return the vtable structure that describes the type of @var{struct}.")
#define FUNC_NAME s_scm_struct_vtable
{
SCM_VALIDATE_STRUCT(1,handle);
diff --git a/libguile/symbols.c b/libguile/symbols.c
index 7bf7e34f5..ee39fca1e 100644
--- a/libguile/symbols.c
+++ b/libguile/symbols.c
@@ -458,7 +458,19 @@ GUILE_PROC(scm_string_to_symbol, "string->symbol", 1, 0, 0,
GUILE_PROC(scm_string_to_obarray_symbol, "string->obarray-symbol", 2, 1, 0,
(SCM o, SCM s, SCM softp),
-"")
+"Intern a new symbol in @var{obarray}, a symbol table, with name
+@var{string}.
+
+If @var{obarray} is @code{#f}, use the default system symbol table. If
+@var{obarray} is @code{#t}, the symbol should not be interned in any
+symbol table; merely return the pair (@var{symbol}
+. @var{#<undefined>}).
+
+The @var{soft?} argument determines whether new symbol table entries
+should be created when the specified symbol is not already present in
+@var{obarray}. If @var{soft?} is specified and is a true value, then
+new entries should not be added for symbols not already present in the
+table; instead, simply return @code{#f}.")
#define FUNC_NAME s_scm_string_to_obarray_symbol
{
SCM vcell;
@@ -491,7 +503,9 @@ GUILE_PROC(scm_string_to_obarray_symbol, "string->obarray-symbol", 2, 1, 0,
GUILE_PROC(scm_intern_symbol, "intern-symbol", 2, 0, 0,
(SCM o, SCM s),
-"")
+"Add a new symbol to @var{obarray} with name @var{string}, bound to an
+unspecified initial value. The symbol table is not modified if a symbol
+with this name is already present.")
#define FUNC_NAME s_scm_intern_symbol
{
scm_sizet hval;
@@ -526,7 +540,9 @@ GUILE_PROC(scm_intern_symbol, "intern-symbol", 2, 0, 0,
GUILE_PROC(scm_unintern_symbol, "unintern-symbol", 2, 0, 0,
(SCM o, SCM s),
-"")
+"Remove the symbol with name @var{string} from @var{obarray}. This
+function returns @code{#t} if the symbol was present and @code{#f}
+otherwise.")
#define FUNC_NAME s_scm_unintern_symbol
{
scm_sizet hval;
@@ -564,7 +580,10 @@ GUILE_PROC(scm_unintern_symbol, "unintern-symbol", 2, 0, 0,
GUILE_PROC(scm_symbol_binding, "symbol-binding", 2, 0, 0,
(SCM o, SCM s),
-"")
+"Look up in @var{obarray} the symbol whose name is @var{string}, and
+return the value to which it is bound. If @var{obarray} is @code{#f},
+use the global symbol table. If @var{string} is not interned in
+@var{obarray}, an error is signalled.")
#define FUNC_NAME s_scm_symbol_binding
{
SCM vcell;
@@ -580,7 +599,8 @@ GUILE_PROC(scm_symbol_binding, "symbol-binding", 2, 0, 0,
GUILE_PROC(scm_symbol_interned_p, "symbol-interned?", 2, 0, 0,
(SCM o, SCM s),
-"")
+"Return @var{#t} if @var{obarray} contains a symbol with name
+@var{string}, and @var{#f} otherwise.")
#define FUNC_NAME s_scm_symbol_interned_p
{
SCM vcell;
@@ -600,7 +620,11 @@ GUILE_PROC(scm_symbol_interned_p, "symbol-interned?", 2, 0, 0,
GUILE_PROC(scm_symbol_bound_p, "symbol-bound?", 2, 0, 0,
(SCM o, SCM s),
-"")
+"Return @var{#t} if @var{obarray} contains a symbol with name
+@var{string} bound to a defined value. This differs from
+@var{symbol-bound?} in that the mere mention of a symbol usually causes
+it to be interned; @code{symbol-bound?} determines whether a symbol has
+been given any meaningful value.")
#define FUNC_NAME s_scm_symbol_bound_p
{
SCM vcell;
@@ -619,7 +643,9 @@ GUILE_PROC(scm_symbol_bound_p, "symbol-bound?", 2, 0, 0,
GUILE_PROC(scm_symbol_set_x, "symbol-set!", 3, 0, 0,
(SCM o, SCM s, SCM v),
-"")
+"Find the symbol in @var{obarray} whose name is @var{string}, and rebind
+it to @var{value}. An error is signalled if @var{string} is not present
+in @var{obarray}.")
#define FUNC_NAME s_scm_symbol_set_x
{
SCM vcell;
@@ -652,7 +678,7 @@ msymbolize (SCM s)
GUILE_PROC(scm_symbol_fref, "symbol-fref", 1, 0, 0,
(SCM s),
-"")
+"Return the contents of @var{symbol}'s @dfn{function slot}.")
#define FUNC_NAME s_scm_symbol_fref
{
SCM_VALIDATE_SYMBOL(1,s);
@@ -667,7 +693,7 @@ GUILE_PROC(scm_symbol_fref, "symbol-fref", 1, 0, 0,
GUILE_PROC(scm_symbol_pref, "symbol-pref", 1, 0, 0,
(SCM s),
-"")
+"Return the @dfn{property list} currently associated with @var{symbol}.")
#define FUNC_NAME s_scm_symbol_pref
{
SCM_VALIDATE_SYMBOL(1,s);
@@ -682,7 +708,7 @@ GUILE_PROC(scm_symbol_pref, "symbol-pref", 1, 0, 0,
GUILE_PROC(scm_symbol_fset_x, "symbol-fset!", 2, 0, 0,
(SCM s, SCM val),
-"")
+"Change the binding of @var{symbol}'s function slot.")
#define FUNC_NAME s_scm_symbol_fset_x
{
SCM_VALIDATE_SYMBOL(1,s);
@@ -698,7 +724,7 @@ GUILE_PROC(scm_symbol_fset_x, "symbol-fset!", 2, 0, 0,
GUILE_PROC(scm_symbol_pset_x, "symbol-pset!", 2, 0, 0,
(SCM s, SCM val),
-"")
+"Change the binding of @var{symbol}'s property slot.")
#define FUNC_NAME s_scm_symbol_pset_x
{
SCM_VALIDATE_SYMBOL(1,s);
@@ -714,7 +740,8 @@ GUILE_PROC(scm_symbol_pset_x, "symbol-pset!", 2, 0, 0,
GUILE_PROC(scm_symbol_hash, "symbol-hash", 1, 0, 0,
(SCM s),
-"")
+"Return the hash value derived from @var{symbol}'s name, i.e. the integer
+index into @var{symbol}'s obarray at which it is stored.")
#define FUNC_NAME s_scm_symbol_hash
{
SCM_VALIDATE_SYMBOL(1,s);
@@ -752,7 +779,8 @@ copy_and_prune_obarray (SCM from, SCM to)
GUILE_PROC(scm_builtin_bindings, "builtin-bindings", 0, 0, 0,
(),
-"")
+"Create and return a copy of the global symbol table, removing all
+unbound symbols.")
#define FUNC_NAME s_scm_builtin_bindings
{
int length = SCM_LENGTH (scm_symhash);
@@ -781,7 +809,9 @@ static SCM gensym_prefix;
/* :FIXME:OPTIMIZE */
GUILE_PROC (scm_gensym, "gensym", 0, 2, 0,
(SCM name, SCM obarray),
-"")
+"Create a new, unique symbol in @var{obarray}, using the global symbol
+table by default. If @var{name} is specified, it should be used as a
+prefix for the new symbol's name. The default prefix is @code{%%gensym}.")
#define FUNC_NAME s_scm_gensym
{
SCM new;
diff --git a/libguile/threads.c b/libguile/threads.c
index d22081765..0bb25512b 100644
--- a/libguile/threads.c
+++ b/libguile/threads.c
@@ -85,14 +85,52 @@ long scm_tc16_condvar;
#ifdef USE_COOP_THREADS
SCM_REGISTER_PROC(s_single_thread_p, "single-active-thread?", 0, 0, 0, scm_single_thread_p);
#endif
+
+/* GJB:FIXME:DOC: SCM_REGISTER_PROC needs to permit a docstring,
+ or these need to move into the file where the proc is defined. */
+
SCM_REGISTER_PROC(s_yield, "yield", 0, 0, 0, scm_yield);
+/* If one or more threads are waiting to execute, calling yield forces an
+immediate context switch to one of them. Otherwise, yield has no effect.
+*/
+
SCM_REGISTER_PROC(s_call_with_new_thread, "call-with-new-thread", 0, 0, 1, scm_call_with_new_thread);
+/* Evaluate @var{(thunk)} in a new thread, and new dynamic context,
+returning a new thread object representing the thread.
+
+If an error occurs during evaluation, call error-thunk, passing it an
+error code describing the condition. [Error codes are currently
+meaningless integers. In the future, real values will be specified.]
+If this happens, the error-thunk is called outside the scope of the new
+root -- it is called in the same dynamic context in which
+with-new-thread was evaluated, but not in the callers thread.
+
+All the evaluation rules for dynamic roots apply to threads.
+*/
+
SCM_REGISTER_PROC(s_join_thread, "join-thread", 1, 0, 0, scm_join_thread);
+/* Suspend execution of the calling thread until the target @var{thread}
+terminates, unless the target @var{thread} has already terminated.
+*/
+
SCM_REGISTER_PROC(s_make_mutex, "make-mutex", 0, 0, 0, scm_make_mutex);
+/* Create a new mutex object. */
+
SCM_REGISTER_PROC(s_lock_mutex, "lock-mutex", 1, 0, 0, scm_lock_mutex);
+/* Lock @var{mutex}. If the mutex is already locked, the calling thread
+blocks until the mutex becomes available. The function returns when
+the calling thread owns the lock on @var{mutex}. */
+
SCM_REGISTER_PROC(s_unlock_mutex, "unlock-mutex", 1, 0, 0, scm_unlock_mutex);
+/* Unlocks @var{mutex} if the calling thread owns the lock on @var{mutex}.
+Calling unlock-mutex on a mutex not owned by the current thread results
+in undefined behaviour. Once a mutex has been unlocked, one thread
+blocked on @var{mutex} is awakened and grabs the mutex lock. */
+
SCM_REGISTER_PROC(s_make_condition_variable, "make-condition-variable", 0, 0, 0, scm_make_condition_variable);
+
SCM_REGISTER_PROC(s_wait_condition_variable, "wait-condition-variable", 2, 0, 0, scm_wait_condition_variable);
+
SCM_REGISTER_PROC(s_signal_condition_variable, "signal-condition-variable", 1, 0, 0, scm_signal_condition_variable);
diff --git a/libguile/throw.c b/libguile/throw.c
index cdc793e58..3a19ffde0 100644
--- a/libguile/throw.c
+++ b/libguile/throw.c
@@ -528,7 +528,25 @@ scm_handle_by_throw (void *handler_data, SCM tag, SCM args)
GUILE_PROC(scm_catch, "catch", 3, 0, 0,
(SCM tag, SCM thunk, SCM handler),
-"")
+"Invoke @var{thunk} in the dynamic context of @var{handler} for
+exceptions matching @var{key}. If thunk throws to the symbol @var{key},
+then @var{handler} is invoked this way:
+
+@example
+(handler key args ...)
+@end example
+
+@var{key} is a symbol or #t.
+
+@var{thunk} takes no arguments. If @var{thunk} returns normally, that
+is the return value of @code{catch}.
+
+Handler is invoked outside the scope of its own @code{catch}. If
+@var{handler} again throws to the same key, a new handler from further
+up the call chain is invoked.
+
+If the key is @code{#t}, then a throw to @emph{any} symbol will match
+this call to @code{catch}.")
#define FUNC_NAME s_scm_catch
{
struct scm_body_thunk_data c;
@@ -583,7 +601,13 @@ GUILE_PROC(scm_lazy_catch, "lazy-catch", 3, 0, 0,
GUILE_PROC(scm_throw, "throw", 1, 0, 1,
(SCM key, SCM args),
-"")
+"Invoke the catch form matching @var{key}, passing @var{args} to the
+@var{handler}.
+
+@var{key} is a symbol. It will match catches of the same symbol or of
+#t.
+
+If there is no handler at all, an error is signaled.")
#define FUNC_NAME s_scm_throw
{
SCM_VALIDATE_SYMBOL(1,key);
diff --git a/libguile/unif.c b/libguile/unif.c
index 401b461f3..b595e6297 100644
--- a/libguile/unif.c
+++ b/libguile/unif.c
@@ -239,7 +239,7 @@ scm_make_uve (long k, SCM prot)
GUILE_PROC(scm_uniform_vector_length, "uniform-vector-length", 1, 0, 0,
(SCM v),
-"")
+"Returns the number of elements in @var{uve}.")
#define FUNC_NAME s_scm_uniform_vector_length
{
SCM_ASRTGO (SCM_NIMP (v), badarg1);
@@ -269,7 +269,10 @@ GUILE_PROC(scm_uniform_vector_length, "uniform-vector-length", 1, 0, 0,
GUILE_PROC(scm_array_p, "array?", 1, 1, 0,
(SCM v, SCM prot),
-"")
+"Returns @code{#t} if the @var{obj} is an array, and @code{#f} if not.
+
+The @var{prototype} argument is used with uniform arrays and is described
+elsewhere.")
#define FUNC_NAME s_scm_array_p
{
int nprot;
@@ -336,7 +339,8 @@ loop:
GUILE_PROC(scm_array_rank, "array-rank", 1, 0, 0,
(SCM ra),
-"")
+"Returns the number of dimensions of @var{obj}. If @var{obj} is not an
+array, @code{0} is returned.")
#define FUNC_NAME s_scm_array_rank
{
if (SCM_IMP (ra))
@@ -370,7 +374,11 @@ GUILE_PROC(scm_array_rank, "array-rank", 1, 0, 0,
GUILE_PROC(scm_array_dimensions, "array-dimensions", 1, 0, 0,
(SCM ra),
-"")
+"@code{Array-dimensions} is similar to @code{array-shape} but replaces
+elements with a @code{0} minimum with one greater than the maximum. So:
+@example
+(array-dimensions (make-array 'foo '(-1 3) 5)) @result{} ((-1 3) 5)
+@end example")
#define FUNC_NAME s_scm_array_dimensions
{
SCM res = SCM_EOL;
@@ -504,7 +512,11 @@ scm_shap2ra (SCM args, const char *what)
GUILE_PROC(scm_dimensions_to_uniform_array, "dimensions->uniform-array", 2, 1, 0,
(SCM dims, SCM prot, SCM fill),
-"")
+"@deffnx primitive make-uniform-vector length prototype [fill]
+Creates and returns a uniform array or vector of type corresponding to
+@var{prototype} with dimensions @var{dims} or length @var{length}. If
+@var{fill} is supplied, it's used to fill the array, otherwise
+@var{prototype} is used.")
#define FUNC_NAME s_scm_dimensions_to_uniform_array
{
scm_sizet k, vlen = 1;
@@ -611,7 +623,21 @@ scm_ra_set_contp (SCM ra)
GUILE_PROC(scm_make_shared_array, "make-shared-array", 2, 0, 1,
(SCM oldra, SCM mapfunc, SCM dims),
-"")
+"@code{make-shared-array} can be used to create shared subarrays of other
+arrays. The @var{mapper} is a function that translates coordinates in
+the new array into coordinates in the old array. A @var{mapper} must be
+linear, and its range must stay within the bounds of the old array, but
+it can be otherwise arbitrary. A simple example:
+@example
+(define fred (make-array #f 8 8))
+(define freds-diagonal
+ (make-shared-array fred (lambda (i) (list i i)) 8))
+(array-set! freds-diagonal 'foo 3)
+(array-ref fred 3 3) @result{} foo
+(define freds-center
+ (make-shared-array fred (lambda (i j) (list (+ 3 i) (+ 3 j))) 2 2))
+(array-ref freds-center 0 0) @result{} foo
+@end example")
#define FUNC_NAME s_scm_make_shared_array
{
SCM ra;
@@ -723,7 +749,25 @@ GUILE_PROC(scm_make_shared_array, "make-shared-array", 2, 0, 1,
/* args are RA . DIMS */
GUILE_PROC(scm_transpose_array, "transpose-array", 0, 0, 1,
(SCM args),
-"")
+"Returns an array sharing contents with @var{array}, but with dimensions
+arranged in a different order. There must be one @var{dim} argument for
+each dimension of @var{array}. @var{dim0}, @var{dim1}, @dots{} should
+be integers between 0 and the rank of the array to be returned. Each
+integer in that range must appear at least once in the argument list.
+
+The values of @var{dim0}, @var{dim1}, @dots{} correspond to dimensions
+in the array to be returned, their positions in the argument list to
+dimensions of @var{array}. Several @var{dim}s may have the same value,
+in which case the returned array will have smaller rank than
+@var{array}.
+
+examples:
+@example
+(transpose-array '#2((a b) (c d)) 1 0) @result{} #2((a c) (b d))
+(transpose-array '#2((a b) (c d)) 0 0) @result{} #1(a d)
+(transpose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 1 0) @result{}
+ #2((a 4) (b 5) (c 6))
+@end example")
#define FUNC_NAME s_scm_transpose_array
{
SCM ra, res, vargs, *ve = &vargs;
@@ -817,7 +861,27 @@ GUILE_PROC(scm_transpose_array, "transpose-array", 0, 0, 1,
/* args are RA . AXES */
GUILE_PROC(scm_enclose_array, "enclose-array", 0, 0, 1,
(SCM axes),
-"")
+"@var{dim0}, @var{dim1} @dots{} should be nonnegative integers less than
+the rank of @var{array}. @var{enclose-array} returns an array
+resembling an array of shared arrays. The dimensions of each shared
+array are the same as the @var{dim}th dimensions of the original array,
+the dimensions of the outer array are the same as those of the original
+array that did not match a @var{dim}.
+
+An enclosed array is not a general Scheme array. Its elements may not
+be set using @code{array-set!}. Two references to the same element of
+an enclosed array will be @code{equal?} but will not in general be
+@code{eq?}. The value returned by @var{array-prototype} when given an
+enclosed array is unspecified.
+
+examples:
+@example
+(enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1) @result{}
+ #<enclosed-array (#1(a d) #1(b e) #1(c f)) (#1(1 4) #1(2 5) #1(3 6))>
+
+(enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 0) @result{}
+ #<enclosed-array #2((a 1) (d 4)) #2((b 2) (e 5)) #2((c 3) (f 6))>
+@end example")
#define FUNC_NAME s_scm_enclose_array
{
SCM axv, ra, res, ra_inr;
@@ -900,7 +964,7 @@ GUILE_PROC(scm_enclose_array, "enclose-array", 0, 0, 1,
GUILE_PROC(scm_array_in_bounds_p, "array-in-bounds?", 0, 0, 1,
(SCM args),
-"")
+"Returns @code{#t} if its arguments would be acceptable to array-ref.")
#define FUNC_NAME s_scm_array_in_bounds_p
{
SCM v, ind = SCM_EOL;
@@ -983,7 +1047,7 @@ SCM_REGISTER_PROC(s_array_ref, "array-ref", 1, 0, 1, scm_uniform_vector_ref);
GUILE_PROC(scm_uniform_vector_ref, "uniform-vector-ref", 2, 0, 0,
(SCM v, SCM args),
-"")
+"Returns the element at the @code{(index1, index2)} element in @var{array}.")
#define FUNC_NAME s_scm_uniform_vector_ref
{
long pos;
@@ -1177,7 +1241,8 @@ SCM_REGISTER_PROC(s_uniform_array_set1_x, "uniform-array-set1!", 3, 0, 0, scm_ar
PROC is used (and it's called from C too). */
GUILE_PROC(scm_array_set_x, "array-set!", 2, 0, 1,
(SCM v, SCM obj, SCM args),
-"")
+"Sets the element at the @code{(index1, index2)} element in @var{array} to
+@var{new-value}. The value returned by array-set! is unspecified.")
#define FUNC_NAME s_scm_array_set_x
{
long pos = 0;
@@ -1282,7 +1347,17 @@ GUILE_PROC(scm_array_set_x, "array-set!", 2, 0, 1,
wouldn't have contiguous elements. */
GUILE_PROC(scm_array_contents, "array-contents", 1, 1, 0,
(SCM ra, SCM strict),
-"")
+"@deffnx primitive array-contents array strict
+If @var{array} may be @dfn{unrolled} into a one dimensional shared array
+without changing their order (last subscript changing fastest), then
+@code{array-contents} returns that shared array, otherwise it returns
+@code{#f}. All arrays made by @var{make-array} and
+@var{make-uniform-array} may be unrolled, some arrays made by
+@var{make-shared-array} may not be.
+
+If the optional argument @var{strict} is provided, a shared array will
+be returned only if its elements are stored internally contiguous in
+memory.")
#define FUNC_NAME s_scm_array_contents
{
SCM sra;
@@ -1378,7 +1453,21 @@ scm_ra2contig (SCM ra, int copy)
GUILE_PROC(scm_uniform_array_read_x, "uniform-array-read!", 1, 3, 0,
(SCM ra, SCM port_or_fd, SCM start, SCM end),
-"")
+"@deffnx primitive uniform-vector-read! uve [port-or-fdes] [start] [end]
+Attempts to read all elements of @var{ura}, in lexicographic order, as
+binary objects from @var{port-or-fdes}.
+If an end of file is encountered during
+uniform-array-read! the objects up to that point only are put into @var{ura}
+(starting at the beginning) and the remainder of the array is
+unchanged.
+
+The optional arguments @var{start} and @var{end} allow
+a specified region of a vector (or linearized array) to be read,
+leaving the remainder of the vector unchanged.
+
+@code{uniform-array-read!} returns the number of objects read.
+@var{port-or-fdes} may be omitted, in which case it defaults to the value
+returned by @code{(current-input-port)}.")
#define FUNC_NAME s_scm_uniform_array_read_x
{
SCM cra = SCM_UNDEFINED, v = ra;
@@ -1524,7 +1613,18 @@ loop:
GUILE_PROC(scm_uniform_array_write, "uniform-array-write", 1, 3, 0,
(SCM v, SCM port_or_fd, SCM start, SCM end),
-"")
+"@deffnx primitive uniform-vector-write uve [port-or-fdes] [start] [end]
+Writes all elements of @var{ura} as binary objects to
+@var{port-or-fdes}.
+
+The optional arguments @var{start}
+and @var{end} allow
+a specified region of a vector (or linearized array) to be written.
+
+The number of objects actually written is returned.
+@var{port-or-fdes} may be
+omitted, in which case it defaults to the value returned by
+@code{(current-output-port)}.")
#define FUNC_NAME s_scm_uniform_array_write
{
long sz, vlen, ans;
@@ -1638,7 +1738,7 @@ static char cnt_tab[16] =
GUILE_PROC(scm_bit_count, "bit-count", 2, 0, 0,
(SCM item, SCM seq),
-"")
+"Returns the number occurrences of @var{bool} in @var{bv}.")
#define FUNC_NAME s_scm_bit_count
{
long i;
@@ -1673,7 +1773,9 @@ GUILE_PROC(scm_bit_count, "bit-count", 2, 0, 0,
GUILE_PROC(scm_bit_position, "bit-position", 3, 0, 0,
(SCM item, SCM v, SCM k),
-"")
+"Returns the minimum index of an occurrence of @var{bool} in @var{bv}
+which is at least @var{k}. If no @var{bool} occurs within the specified
+range @code{#f} is returned.")
#define FUNC_NAME s_scm_bit_position
{
long i, lenw, xbits, pos;
@@ -1739,7 +1841,15 @@ GUILE_PROC(scm_bit_position, "bit-position", 3, 0, 0,
GUILE_PROC(scm_bit_set_star_x, "bit-set*!", 3, 0, 0,
(SCM v, SCM kv, SCM obj),
-"")
+"If uve is a bit-vector @var{bv} and uve must be of the same length. If
+@var{bool} is @code{#t}, uve is OR'ed into @var{bv}; If @var{bool} is @code{#f}, the
+inversion of uve is AND'ed into @var{bv}.
+
+If uve is a unsigned integer vector all the elements of uve must be
+between 0 and the @code{LENGTH} of @var{bv}. The bits of @var{bv}
+corresponding to the indexes in uve are set to @var{bool}.
+
+The return value is unspecified.")
#define FUNC_NAME s_scm_bit_set_star_x
{
register long i, k, vlen;
@@ -1793,7 +1903,11 @@ GUILE_PROC(scm_bit_set_star_x, "bit-set*!", 3, 0, 0,
GUILE_PROC(scm_bit_count_star, "bit-count*", 3, 0, 0,
(SCM v, SCM kv, SCM obj),
-"")
+"Returns
+@example
+(bit-count (bit-set*! (if bool bv (bit-invert! bv)) uve #t) #t).
+@end example
+@var{bv} is not modified.")
#define FUNC_NAME s_scm_bit_count_star
{
register long i, vlen, count = 0;
@@ -1857,7 +1971,7 @@ GUILE_PROC(scm_bit_count_star, "bit-count*", 3, 0, 0,
GUILE_PROC(scm_bit_invert_x, "bit-invert!", 1, 0, 0,
(SCM v),
-"")
+"Modifies @var{bv} by replacing each element with its negation.")
#define FUNC_NAME s_scm_bit_invert_x
{
register long k;
@@ -1940,7 +2054,7 @@ ra2l (SCM ra,scm_sizet base,scm_sizet k)
GUILE_PROC(scm_array_to_list, "array->list", 1, 0, 0,
(SCM v),
-"")
+"Returns a list consisting of all the elements, in order, of @var{array}.")
#define FUNC_NAME s_scm_array_to_list
{
SCM res = SCM_EOL;
@@ -2047,7 +2161,10 @@ static int l2ra(SCM lst, SCM ra, scm_sizet base, scm_sizet k);
GUILE_PROC(scm_list_to_uniform_array, "list->uniform-array", 3, 0, 0,
(SCM ndim, SCM prot, SCM lst),
-"")
+"@deffnx procedure list->uniform-vector prot lst
+Returns a uniform array of the type indicated by prototype @var{prot}
+with elements the same as those of @var{lst}. Elements must be of the
+appropriate type, no coercions are done.")
#define FUNC_NAME s_scm_list_to_uniform_array
{
SCM shp = SCM_EOL;
@@ -2399,7 +2516,9 @@ tail:
GUILE_PROC(scm_array_prototype, "array-prototype", 1, 0, 0,
(SCM ra),
-"")
+"Returns an object that would produce an array of the same type as
+@var{array}, if used as the @var{prototype} for
+@code{make-uniform-array}.")
#define FUNC_NAME s_scm_array_prototype
{
int enclosed = 0;
diff --git a/libguile/vectors.c b/libguile/vectors.c
index 8b1d05498..96dad819b 100644
--- a/libguile/vectors.c
+++ b/libguile/vectors.c
@@ -266,7 +266,7 @@ scm_vector_equal_p(SCM x, SCM y)
GUILE_PROC (scm_vector_move_left_x, "vector-move-left!", 5, 0, 0,
(SCM vec1, SCM start1, SCM end1, SCM vec2, SCM start2),
-"")
+"Vector version of @code{substring-move-left!}.")
#define FUNC_NAME s_scm_vector_move_left_x
{
long i;
@@ -289,7 +289,7 @@ GUILE_PROC (scm_vector_move_left_x, "vector-move-left!", 5, 0, 0,
GUILE_PROC (scm_vector_move_right_x, "vector-move-right!", 5, 0, 0,
(SCM vec1, SCM start1, SCM end1, SCM vec2, SCM start2),
-"")
+"Vector version of @code{substring-move-right!}.")
#define FUNC_NAME s_scm_vector_move_right_x
{
long i;
diff --git a/libguile/version.c b/libguile/version.c
index 2c453b0c5..316dc0455 100644
--- a/libguile/version.c
+++ b/libguile/version.c
@@ -76,7 +76,16 @@ GUILE_PROC(scm_minor_version, "minor-version", 0, 0, 0,
GUILE_PROC(scm_version, "version", 0, 0, 0,
(),
-"")
+"@deffnx primitive major-version
+@deffnx primitive minor-version
+Return a string describing Guile's version number, or its major or minor
+version numbers, respectively.
+
+@example
+(version) @result{} "1.3a"
+(major-version) @result{} "1"
+(minor-version) @result{} "3a"
+@end example")
#define FUNC_NAME s_scm_version
{
return scm_makfrom0str (GUILE_VERSION);
diff --git a/libguile/vports.c b/libguile/vports.c
index 3a3169959..e35c9733d 100644
--- a/libguile/vports.c
+++ b/libguile/vports.c
@@ -139,7 +139,46 @@ sf_close (SCM port)
GUILE_PROC(scm_make_soft_port, "make-soft-port", 2, 0, 0,
(SCM pv, SCM modes),
-"")
+"Returns a port capable of receiving or delivering characters as
+specified by the @var{modes} string (@pxref{File Ports,
+open-file}). @var{vector} must be a vector of length 6. Its components
+are as follows:
+
+@enumerate 0
+@item
+procedure accepting one character for output
+@item
+procedure accepting a string for output
+@item
+thunk for flushing output
+@item
+thunk for getting one character
+@item
+thunk for closing port (not by garbage collection)
+@end enumerate
+
+For an output-only port only elements 0, 1, 2, and 4 need be
+procedures. For an input-only port only elements 3 and 4 need be
+procedures. Thunks 2 and 4 can instead be @code{#f} if there is no useful
+operation for them to perform.
+
+If thunk 3 returns @code{#f} or an @code{eof-object} (@pxref{Input,
+eof-object?, ,r4rs, The Revised^4 Report on Scheme}) it indicates that
+the port has reached end-of-file. For example:
+
+@example
+(define stdout (current-output-port))
+(define p (make-soft-port
+ (vector
+ (lambda (c) (write c stdout))
+ (lambda (s) (display s stdout))
+ (lambda () (display "." stdout))
+ (lambda () (char-upcase (read-char)))
+ (lambda () (display "@@" stdout)))
+ "rw"))
+
+(write p p) @result{} #<input-output-soft#\space45d10#\>
+@end example")
#define FUNC_NAME s_scm_make_soft_port
{
scm_port *pt;
diff --git a/libguile/weaks.c b/libguile/weaks.c
index 386b82f8f..4f5b68e45 100644
--- a/libguile/weaks.c
+++ b/libguile/weaks.c
@@ -57,7 +57,9 @@
GUILE_PROC(scm_make_weak_vector, "make-weak-vector", 1, 1, 0,
(SCM k, SCM fill),
-"")
+"Return a weak vector with @var{size} elements. If the optional
+argument @var{fill} is given, all entries in the vector will be set to
+@var{fill}. The default value for @var{fill} is the empty list.")
#define FUNC_NAME s_scm_make_weak_vector
{
SCM v;
@@ -77,7 +79,11 @@ SCM_REGISTER_PROC(s_list_to_weak_vector, "list->weak-vector", 1, 0, 0, scm_weak_
GUILE_PROC(scm_weak_vector, "weak-vector", 0, 0, 1,
(SCM l),
-"")
+"@deffnx primitive list->weak-vector l
+Construct a weak vector from a list: @code{weak-vector} uses the list of
+its arguments while @code{list->weak-vector} uses its only argument
+@var{l} (a list) to construct a weak vector the same way
+@code{vector->list} would.")
#define FUNC_NAME s_scm_weak_vector
{
SCM res;
@@ -99,7 +105,8 @@ GUILE_PROC(scm_weak_vector, "weak-vector", 0, 0, 1,
GUILE_PROC(scm_weak_vector_p, "weak-vector?", 1, 0, 0,
(SCM x),
-"")
+"Return @var{#t} if @var{obj} is a weak vector. Note that all weak
+hashes are also weak vectors.")
#define FUNC_NAME s_scm_weak_vector_p
{
return SCM_BOOL(SCM_NIMP (x) && SCM_WVECTP (x) && !SCM_IS_WHVEC (x));
@@ -114,7 +121,13 @@ GUILE_PROC(scm_weak_vector_p, "weak-vector?", 1, 0, 0,
GUILE_PROC(scm_make_weak_key_hash_table, "make-weak-key-hash-table", 1, 0, 0,
(SCM k),
-"")
+"@deffnx primitive make-weak-value-hash-table size
+@deffnx primitive make-doubly-weak-hash-table size
+Return a weak hash table with @var{size} buckets. As with any hash
+table, choosing a good size for the table requires some caution.
+
+You can modify weak hash tables in exactly the same way you would modify
+regular hash tables. (@pxref{Hash Tables})")
#define FUNC_NAME s_scm_make_weak_key_hash_table
{
SCM v;
@@ -162,7 +175,11 @@ GUILE_PROC (scm_make_doubly_weak_hash_table, "make-doubly-weak-hash-table", 1, 0
GUILE_PROC(scm_weak_key_hash_table_p, "weak-key-hash-table?", 1, 0, 0,
(SCM x),
-"")
+"@deffnx primitive weak-value-hash-table? obj
+@deffnx primitive doubly-weak-hash-table? obj
+Return @var{#t} if @var{obj} is the specified weak hash table. Note
+that a doubly weak hash table is neither a weak key nor a weak value
+hash table.")
#define FUNC_NAME s_scm_weak_key_hash_table_p
{
return SCM_BOOL(SCM_NIMP (x) && SCM_WVECTP (x) && SCM_IS_WHVEC(x));