From 4079f87ed21341a8654ecaa29ac3e6a2344d9252 Mon Sep 17 00:00:00 2001 From: "Greg J. Badros" Date: Mon, 13 Dec 1999 03:40:23 +0000 Subject: [PATCH] * 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. --- libguile/Makefile.am | 9 +- libguile/alist.c | 67 ++++++-- libguile/coop-threads.c | 6 - libguile/debug.c | 5 +- libguile/dynl.c | 91 +++++++++- libguile/dynwind.c | 55 +++++- libguile/error.c | 14 +- libguile/eval.c | 16 +- libguile/evalext.c | 2 +- libguile/filesys.c | 226 ++++++++++++++++++++++--- libguile/fports.c | 83 ++++++++- libguile/gc.c | 8 +- libguile/guile-doc-snarf.awk | 1 + libguile/hash.c | 7 +- libguile/hashtab.c | 45 ++++- libguile/ioext.c | 76 +++++++-- libguile/keywords.c | 6 +- libguile/list.c | 59 +++++-- libguile/load.c | 56 ++++++- libguile/macros.c | 8 +- libguile/net_db.c | 85 ++++++++-- libguile/numbers.c | 114 +++++++++++-- libguile/objprop.c | 13 +- libguile/ports.c | 119 ++++++++++--- libguile/posix.c | 317 ++++++++++++++++++++++++++++++----- libguile/procprop.c | 9 +- libguile/procs.c | 5 +- libguile/ramap.c | 51 +++++- libguile/regex-posix.c | 47 +++++- libguile/root.c | 49 +++++- libguile/scmsigs.c | 52 +++++- libguile/simpos.c | 17 +- libguile/socket.c | 219 +++++++++++++++++++++--- libguile/stacks.c | 4 +- libguile/stime.c | 76 +++++++-- libguile/strings.c | 21 ++- libguile/strop.c | 35 +++- libguile/strports.c | 11 +- libguile/struct.c | 105 +++++++++++- libguile/symbols.c | 58 +++++-- libguile/threads.c | 38 +++++ libguile/throw.c | 28 +++- libguile/unif.c | 163 +++++++++++++++--- libguile/vectors.c | 4 +- libguile/version.c | 11 +- libguile/vports.c | 41 ++++- libguile/weaks.c | 27 ++- 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{(# . #)}.") #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{#}). + +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{} + # + +(enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 0) @result{} + # +@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{} # +@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)); -- 2.20.1