mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-06-15 08:10:17 +02:00
Code Activity

* Makefile.am: Fix ETAGS_ARGS to recognize GUILE_PROC,

Browse source 
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.
This commit is contained in:
Greg J. Badros 1999-12-13 03:40:23 +00:00
parent 75948d1b31
commit 4079f87ed2
47 changed files with 2239 additions and 320 deletions
Download patch file Download diff file Expand all files Collapse all files

9
libguile/Makefile.am
View file

@ -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)

67
libguile/alist.c
View file

@ -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;

6
libguile/coop-threads.c
View file

@ -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;

5
libguile/debug.c
View file

@ -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))

91
libguile/dynl.c
View file

@ -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);

55
libguile/dynwind.c
View file

@ -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;

14
libguile/error.c
View file

@ -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);

16
libguile/eval.c
View file

@ -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,

2
libguile/evalext.c
View file

@ -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;

226
libguile/filesys.c
View file

@ -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;

83
libguile/fports.c
View file

@ -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;

8
libguile/gc.c
View file

@ -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;

1
libguile/guile-doc-snarf.awk
View file

@ -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 ; }

7
libguile/hash.c
View file

@ -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);

45
libguile/hashtab.c
View file

@ -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;

76
libguile/ioext.c
View file

@ -69,7 +69,19 @@
GUILE_PROC (scm_read_delimited_x, "%read-delimited!", 3, 3, 0,
(SCM delims, SCM buf, SCM gobble, SCM port, SCM start, SCM end),
"")
"Read characters from @var{port} into @var{buf} until one of the
characters in the @var{delims} string is encountered. If @var{gobble?}
is true, store the delimiter character in @var{buf} as well; otherwise,
discard it. If @var{port} is not specified, use the value of
@code{(current-input-port)}. If @var{start} or @var{end} are specified,
store data only into the substring of @var{buf} bounded by @var{start}
and @var{end} (which default to the beginning and end of the buffer,
respectively).
Return a pair consisting of the delimiter that terminated the string and
the number of characters read. If reading stopped at the end of file,
the delimiter returned is the @var{eof-object}; if the buffer was filled
without encountering a delimiter, this value is @var{#f}.")
#define FUNC_NAME s_scm_read_delimited_x
{
long j;
@ -218,7 +230,12 @@ scm_do_read_line (SCM port, int *len_p)
GUILE_PROC (scm_read_line, "%read-line", 0, 1, 0,
(SCM port),
"")
"Read a newline-terminated line from @var{port}, allocating storage as
necessary. The newline terminator (if any) is removed from the string,
and a pair consisting of the line and its delimiter is returned. The
delimiter may be either a newline or the @var{eof-object}; if
@code{%read-line} is called at the end of file, it returns the pair
@code{(#<eof> . #<eof>)}.")
#define FUNC_NAME s_scm_read_line
{
scm_port *pt;
@ -266,7 +283,14 @@ GUILE_PROC (scm_read_line, "%read-line", 0, 1, 0,
GUILE_PROC (scm_write_line, "write-line", 1, 1, 0,
(SCM obj, SCM port),
"")
"Display @var{obj} and a newline character to @var{port}. If @var{port}
is not specified, @code{(current-output-port)} is used. This function
is equivalent to:
@smalllisp
(display obj [port])
(newline [port])
@end smalllisp")
#define FUNC_NAME s_scm_write_line
{
scm_display (obj, port);
@ -276,7 +300,11 @@ GUILE_PROC (scm_write_line, "write-line", 1, 1, 0,
GUILE_PROC (scm_ftell, "ftell", 1, 0, 0,
(SCM object),
"")
"Returns an integer representing the current position of @var{fd/port},
measured from the beginning. Equivalent to:
@smalllisp
(seek port 0 SEEK_CUR)
@end smalllisp")
#define FUNC_NAME s_scm_ftell
{
return scm_seek (object, SCM_INUM0, SCM_MAKINUM (SEEK_CUR));
@ -285,7 +313,8 @@ GUILE_PROC (scm_ftell, "ftell", 1, 0, 0,
GUILE_PROC (scm_fseek, "fseek", 3, 0, 0,
(SCM object, SCM offset, SCM whence),
"")
"Obsolete. Almost the same as seek, above, but the return value is
unspecified.")
#define FUNC_NAME s_scm_fseek
{
scm_seek (object, offset, whence);
@ -295,7 +324,19 @@ GUILE_PROC (scm_fseek, "fseek", 3, 0, 0,
GUILE_PROC (scm_redirect_port, "redirect-port", 2, 0, 0,
(SCM old, SCM new),
"")
"This procedure takes two ports and duplicates the underlying file
descriptor from @var{old-port} into @var{new-port}. The
current file descriptor in @var{new-port} will be closed.
After the redirection the two ports will share a file position
and file status flags.
The return value is unspecified.
Unexpected behaviour can result if both ports are subsequently used
and the original and/or duplicate ports are buffered.
This procedure does not have any side effects on other ports or
revealed counts.")
#define FUNC_NAME s_scm_redirect_port
{
int ans, oldfd, newfd;
@ -332,7 +373,7 @@ GUILE_PROC (scm_redirect_port, "redirect-port", 2, 0, 0,
GUILE_PROC (scm_dup_to_fdes, "dup->fdes", 1, 1, 0,
(SCM fd_or_port, SCM fd),
"")
"Returns an integer file descriptor.")
#define FUNC_NAME s_scm_dup_to_fdes
{
int oldfd, newfd, rv;
@ -372,7 +413,8 @@ GUILE_PROC (scm_dup_to_fdes, "dup->fdes", 1, 1, 0,
GUILE_PROC (scm_fileno, "fileno", 1, 0, 0,
(SCM port),
"")
"Returns the integer file descriptor underlying @var{port}.
Does not change its revealed count.")
#define FUNC_NAME s_scm_fileno
{
port = SCM_COERCE_OUTPORT (port);
@ -387,7 +429,8 @@ GUILE_PROC (scm_fileno, "fileno", 1, 0, 0,
if it is not going to assume that the arg is a port */
GUILE_PROC (scm_isatty_p, "isatty?", 1, 0, 0,
(SCM port),
"")
"Returns @code{#t} if @var{port} is using a serial
non-file device, otherwise @code{#f}.")
#define FUNC_NAME s_scm_isatty_p
{
int rv;
@ -406,7 +449,10 @@ GUILE_PROC (scm_isatty_p, "isatty?", 1, 0, 0,
GUILE_PROC (scm_fdopen, "fdopen", 2, 0, 0,
(SCM fdes, SCM modes),
"")
"Returns a new port based on the file descriptor @var{fdes}.
Modes are given by the string @var{modes}. The revealed count of the port
is initialized to zero. The modes string is the same as that accepted
by @ref{File Ports, open-file}.")
#define FUNC_NAME s_scm_fdopen
{
SCM port;
@ -428,7 +474,12 @@ GUILE_PROC (scm_fdopen, "fdopen", 2, 0, 0,
*/
GUILE_PROC (scm_primitive_move_to_fdes, "primitive-move->fdes", 2, 0, 0,
(SCM port, SCM fd),
"")
"Moves the underlying file descriptor for @var{port} to the integer
value @var{fdes} without changing the revealed count of @var{port}.
Any other ports already using this descriptor will be automatically
shifted to new descriptors and their revealed counts reset to zero.
The return value is @code{#f} if the file descriptor already had the
required value or @code{#t} if it was moved.")
#define FUNC_NAME s_scm_primitive_move_to_fdes
{
struct scm_fport *stream;
@ -460,7 +511,8 @@ GUILE_PROC (scm_primitive_move_to_fdes, "primitive-move->fdes", 2, 0, 0,
/* Return a list of ports using a given file descriptor. */
GUILE_PROC(scm_fdes_to_ports, "fdes->ports", 1, 0, 0,
(SCM fd),
"")
"Returns a list of existing ports which have @var{fdes} as an
underlying file descriptor, without changing their revealed counts.")
#define FUNC_NAME s_scm_fdes_to_ports
{
SCM result = SCM_EOL;

6
libguile/keywords.c
View file

@ -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);

59
libguile/list.c
View file

@ -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);

56
libguile/load.c
View file

@ -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);

8
libguile/macros.c
View file

@ -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))

85
libguile/net_db.c
View file

@ -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))

114
libguile/numbers.c
View file

@ -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;

13
libguile/objprop.c
View file

@ -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;

119
libguile/ports.c
View file

@ -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);

317
libguile/posix.c
View file

@ -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

9
libguile/procprop.c
View file

@ -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;

5
libguile/procs.c
View file

@ -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;

51
libguile/ramap.c
View file

@ -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?";

47
libguile/regex-posix.c
View file

@ -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;

49
libguile/root.c
View file

@ -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));

52
libguile/scmsigs.c
View file

@ -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);

17
libguile/simpos.c
View file

@ -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;

219
libguile/socket.c
View file

@ -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;

4
libguile/stacks.c
View file

@ -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;

76
libguile/stime.c
View file

@ -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

21
libguile/strings.c
View file

@ -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;

35
libguile/strop.c
View file

@ -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;

11
libguile/strports.c
View file

@ -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,

105
libguile/struct.c
View file

@ -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);

58
libguile/symbols.c
View file

@ -458,7 +458,19 @@ GUILE_PROC(scm_string_to_symbol, "string->symbol", 1, 0, 0,
GUILE_PROC(scm_string_to_obarray_symbol, "string->obarray-symbol", 2, 1, 0,
(SCM o, SCM s, SCM softp),
"")
"Intern a new symbol in @var{obarray}, a symbol table, with name
@var{string}.
If @var{obarray} is @code{#f}, use the default system symbol table. If
@var{obarray} is @code{#t}, the symbol should not be interned in any
symbol table; merely return the pair (@var{symbol}
. @var{#<undefined>}).
The @var{soft?} argument determines whether new symbol table entries
should be created when the specified symbol is not already present in
@var{obarray}. If @var{soft?} is specified and is a true value, then
new entries should not be added for symbols not already present in the
table; instead, simply return @code{#f}.")
#define FUNC_NAME s_scm_string_to_obarray_symbol
{
SCM vcell;
@ -491,7 +503,9 @@ GUILE_PROC(scm_string_to_obarray_symbol, "string->obarray-symbol", 2, 1, 0,
GUILE_PROC(scm_intern_symbol, "intern-symbol", 2, 0, 0,
(SCM o, SCM s),
"")
"Add a new symbol to @var{obarray} with name @var{string}, bound to an
unspecified initial value. The symbol table is not modified if a symbol
with this name is already present.")
#define FUNC_NAME s_scm_intern_symbol
{
scm_sizet hval;
@ -526,7 +540,9 @@ GUILE_PROC(scm_intern_symbol, "intern-symbol", 2, 0, 0,
GUILE_PROC(scm_unintern_symbol, "unintern-symbol", 2, 0, 0,
(SCM o, SCM s),
"")
"Remove the symbol with name @var{string} from @var{obarray}. This
function returns @code{#t} if the symbol was present and @code{#f}
otherwise.")
#define FUNC_NAME s_scm_unintern_symbol
{
scm_sizet hval;
@ -564,7 +580,10 @@ GUILE_PROC(scm_unintern_symbol, "unintern-symbol", 2, 0, 0,
GUILE_PROC(scm_symbol_binding, "symbol-binding", 2, 0, 0,
(SCM o, SCM s),
"")
"Look up in @var{obarray} the symbol whose name is @var{string}, and
return the value to which it is bound. If @var{obarray} is @code{#f},
use the global symbol table. If @var{string} is not interned in
@var{obarray}, an error is signalled.")
#define FUNC_NAME s_scm_symbol_binding
{
SCM vcell;
@ -580,7 +599,8 @@ GUILE_PROC(scm_symbol_binding, "symbol-binding", 2, 0, 0,
GUILE_PROC(scm_symbol_interned_p, "symbol-interned?", 2, 0, 0,
(SCM o, SCM s),
"")
"Return @var{#t} if @var{obarray} contains a symbol with name
@var{string}, and @var{#f} otherwise.")
#define FUNC_NAME s_scm_symbol_interned_p
{
SCM vcell;
@ -600,7 +620,11 @@ GUILE_PROC(scm_symbol_interned_p, "symbol-interned?", 2, 0, 0,
GUILE_PROC(scm_symbol_bound_p, "symbol-bound?", 2, 0, 0,
(SCM o, SCM s),
"")
"Return @var{#t} if @var{obarray} contains a symbol with name
@var{string} bound to a defined value. This differs from
@var{symbol-bound?} in that the mere mention of a symbol usually causes
it to be interned; @code{symbol-bound?} determines whether a symbol has
been given any meaningful value.")
#define FUNC_NAME s_scm_symbol_bound_p
{
SCM vcell;
@ -619,7 +643,9 @@ GUILE_PROC(scm_symbol_bound_p, "symbol-bound?", 2, 0, 0,
GUILE_PROC(scm_symbol_set_x, "symbol-set!", 3, 0, 0,
(SCM o, SCM s, SCM v),
"")
"Find the symbol in @var{obarray} whose name is @var{string}, and rebind
it to @var{value}. An error is signalled if @var{string} is not present
in @var{obarray}.")
#define FUNC_NAME s_scm_symbol_set_x
{
SCM vcell;
@ -652,7 +678,7 @@ msymbolize (SCM s)
GUILE_PROC(scm_symbol_fref, "symbol-fref", 1, 0, 0,
(SCM s),
"")
"Return the contents of @var{symbol}'s @dfn{function slot}.")
#define FUNC_NAME s_scm_symbol_fref
{
SCM_VALIDATE_SYMBOL(1,s);
@ -667,7 +693,7 @@ GUILE_PROC(scm_symbol_fref, "symbol-fref", 1, 0, 0,
GUILE_PROC(scm_symbol_pref, "symbol-pref", 1, 0, 0,
(SCM s),
"")
"Return the @dfn{property list} currently associated with @var{symbol}.")
#define FUNC_NAME s_scm_symbol_pref
{
SCM_VALIDATE_SYMBOL(1,s);
@ -682,7 +708,7 @@ GUILE_PROC(scm_symbol_pref, "symbol-pref", 1, 0, 0,
GUILE_PROC(scm_symbol_fset_x, "symbol-fset!", 2, 0, 0,
(SCM s, SCM val),
"")
"Change the binding of @var{symbol}'s function slot.")
#define FUNC_NAME s_scm_symbol_fset_x
{
SCM_VALIDATE_SYMBOL(1,s);
@ -698,7 +724,7 @@ GUILE_PROC(scm_symbol_fset_x, "symbol-fset!", 2, 0, 0,
GUILE_PROC(scm_symbol_pset_x, "symbol-pset!", 2, 0, 0,
(SCM s, SCM val),
"")
"Change the binding of @var{symbol}'s property slot.")
#define FUNC_NAME s_scm_symbol_pset_x
{
SCM_VALIDATE_SYMBOL(1,s);
@ -714,7 +740,8 @@ GUILE_PROC(scm_symbol_pset_x, "symbol-pset!", 2, 0, 0,
GUILE_PROC(scm_symbol_hash, "symbol-hash", 1, 0, 0,
(SCM s),
"")
"Return the hash value derived from @var{symbol}'s name, i.e. the integer
index into @var{symbol}'s obarray at which it is stored.")
#define FUNC_NAME s_scm_symbol_hash
{
SCM_VALIDATE_SYMBOL(1,s);
@ -752,7 +779,8 @@ copy_and_prune_obarray (SCM from, SCM to)
GUILE_PROC(scm_builtin_bindings, "builtin-bindings", 0, 0, 0,
(),
"")
"Create and return a copy of the global symbol table, removing all
unbound symbols.")
#define FUNC_NAME s_scm_builtin_bindings
{
int length = SCM_LENGTH (scm_symhash);
@ -781,7 +809,9 @@ static SCM gensym_prefix;
/* :FIXME:OPTIMIZE */
GUILE_PROC (scm_gensym, "gensym", 0, 2, 0,
(SCM name, SCM obarray),
"")
"Create a new, unique symbol in @var{obarray}, using the global symbol
table by default. If @var{name} is specified, it should be used as a
prefix for the new symbol's name. The default prefix is @code{%%gensym}.")
#define FUNC_NAME s_scm_gensym
{
SCM new;

38
libguile/threads.c
View file

@ -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);

28
libguile/throw.c
View file

@ -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);

163
libguile/unif.c
View file

@ -239,7 +239,7 @@ scm_make_uve (long k, SCM prot)
GUILE_PROC(scm_uniform_vector_length, "uniform-vector-length", 1, 0, 0,
(SCM v),
"")
"Returns the number of elements in @var{uve}.")
#define FUNC_NAME s_scm_uniform_vector_length
{
SCM_ASRTGO (SCM_NIMP (v), badarg1);
@ -269,7 +269,10 @@ GUILE_PROC(scm_uniform_vector_length, "uniform-vector-length", 1, 0, 0,
GUILE_PROC(scm_array_p, "array?", 1, 1, 0,
(SCM v, SCM prot),
"")
"Returns @code{#t} if the @var{obj} is an array, and @code{#f} if not.
The @var{prototype} argument is used with uniform arrays and is described
elsewhere.")
#define FUNC_NAME s_scm_array_p
{
int nprot;
@ -336,7 +339,8 @@ loop:
GUILE_PROC(scm_array_rank, "array-rank", 1, 0, 0,
(SCM ra),
"")
"Returns the number of dimensions of @var{obj}. If @var{obj} is not an
array, @code{0} is returned.")
#define FUNC_NAME s_scm_array_rank
{
if (SCM_IMP (ra))
@ -370,7 +374,11 @@ GUILE_PROC(scm_array_rank, "array-rank", 1, 0, 0,
GUILE_PROC(scm_array_dimensions, "array-dimensions", 1, 0, 0,
(SCM ra),
"")
"@code{Array-dimensions} is similar to @code{array-shape} but replaces
elements with a @code{0} minimum with one greater than the maximum. So:
@example
(array-dimensions (make-array 'foo '(-1 3) 5)) @result{} ((-1 3) 5)
@end example")
#define FUNC_NAME s_scm_array_dimensions
{
SCM res = SCM_EOL;
@ -504,7 +512,11 @@ scm_shap2ra (SCM args, const char *what)
GUILE_PROC(scm_dimensions_to_uniform_array, "dimensions->uniform-array", 2, 1, 0,
(SCM dims, SCM prot, SCM fill),
"")
"@deffnx primitive make-uniform-vector length prototype [fill]
Creates and returns a uniform array or vector of type corresponding to
@var{prototype} with dimensions @var{dims} or length @var{length}. If
@var{fill} is supplied, it's used to fill the array, otherwise
@var{prototype} is used.")
#define FUNC_NAME s_scm_dimensions_to_uniform_array
{
scm_sizet k, vlen = 1;
@ -611,7 +623,21 @@ scm_ra_set_contp (SCM ra)
GUILE_PROC(scm_make_shared_array, "make-shared-array", 2, 0, 1,
(SCM oldra, SCM mapfunc, SCM dims),
"")
"@code{make-shared-array} can be used to create shared subarrays of other
arrays. The @var{mapper} is a function that translates coordinates in
the new array into coordinates in the old array. A @var{mapper} must be
linear, and its range must stay within the bounds of the old array, but
it can be otherwise arbitrary. A simple example:
@example
(define fred (make-array #f 8 8))
(define freds-diagonal
(make-shared-array fred (lambda (i) (list i i)) 8))
(array-set! freds-diagonal 'foo 3)
(array-ref fred 3 3) @result{} foo
(define freds-center
(make-shared-array fred (lambda (i j) (list (+ 3 i) (+ 3 j))) 2 2))
(array-ref freds-center 0 0) @result{} foo
@end example")
#define FUNC_NAME s_scm_make_shared_array
{
SCM ra;
@ -723,7 +749,25 @@ GUILE_PROC(scm_make_shared_array, "make-shared-array", 2, 0, 1,
/* args are RA . DIMS */
GUILE_PROC(scm_transpose_array, "transpose-array", 0, 0, 1,
(SCM args),
"")
"Returns an array sharing contents with @var{array}, but with dimensions
arranged in a different order. There must be one @var{dim} argument for
each dimension of @var{array}. @var{dim0}, @var{dim1}, @dots{} should
be integers between 0 and the rank of the array to be returned. Each
integer in that range must appear at least once in the argument list.
The values of @var{dim0}, @var{dim1}, @dots{} correspond to dimensions
in the array to be returned, their positions in the argument list to
dimensions of @var{array}. Several @var{dim}s may have the same value,
in which case the returned array will have smaller rank than
@var{array}.
examples:
@example
(transpose-array '#2((a b) (c d)) 1 0) @result{} #2((a c) (b d))
(transpose-array '#2((a b) (c d)) 0 0) @result{} #1(a d)
(transpose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 1 0) @result{}
#2((a 4) (b 5) (c 6))
@end example")
#define FUNC_NAME s_scm_transpose_array
{
SCM ra, res, vargs, *ve = &vargs;
@ -817,7 +861,27 @@ GUILE_PROC(scm_transpose_array, "transpose-array", 0, 0, 1,
/* args are RA . AXES */
GUILE_PROC(scm_enclose_array, "enclose-array", 0, 0, 1,
(SCM axes),
"")
"@var{dim0}, @var{dim1} @dots{} should be nonnegative integers less than
the rank of @var{array}. @var{enclose-array} returns an array
resembling an array of shared arrays. The dimensions of each shared
array are the same as the @var{dim}th dimensions of the original array,
the dimensions of the outer array are the same as those of the original
array that did not match a @var{dim}.
An enclosed array is not a general Scheme array. Its elements may not
be set using @code{array-set!}. Two references to the same element of
an enclosed array will be @code{equal?} but will not in general be
@code{eq?}. The value returned by @var{array-prototype} when given an
enclosed array is unspecified.
examples:
@example
(enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1) @result{}
#<enclosed-array (#1(a d) #1(b e) #1(c f)) (#1(1 4) #1(2 5) #1(3 6))>
(enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 0) @result{}
#<enclosed-array #2((a 1) (d 4)) #2((b 2) (e 5)) #2((c 3) (f 6))>
@end example")
#define FUNC_NAME s_scm_enclose_array
{
SCM axv, ra, res, ra_inr;
@ -900,7 +964,7 @@ GUILE_PROC(scm_enclose_array, "enclose-array", 0, 0, 1,
GUILE_PROC(scm_array_in_bounds_p, "array-in-bounds?", 0, 0, 1,
(SCM args),
"")
"Returns @code{#t} if its arguments would be acceptable to array-ref.")
#define FUNC_NAME s_scm_array_in_bounds_p
{
SCM v, ind = SCM_EOL;
@ -983,7 +1047,7 @@ SCM_REGISTER_PROC(s_array_ref, "array-ref", 1, 0, 1, scm_uniform_vector_ref);
GUILE_PROC(scm_uniform_vector_ref, "uniform-vector-ref", 2, 0, 0,
(SCM v, SCM args),
"")
"Returns the element at the @code{(index1, index2)} element in @var{array}.")
#define FUNC_NAME s_scm_uniform_vector_ref
{
long pos;
@ -1177,7 +1241,8 @@ SCM_REGISTER_PROC(s_uniform_array_set1_x, "uniform-array-set1!", 3, 0, 0, scm_ar
PROC is used (and it's called from C too). */
GUILE_PROC(scm_array_set_x, "array-set!", 2, 0, 1,
(SCM v, SCM obj, SCM args),
"")
"Sets the element at the @code{(index1, index2)} element in @var{array} to
@var{new-value}. The value returned by array-set! is unspecified.")
#define FUNC_NAME s_scm_array_set_x
{
long pos = 0;
@ -1282,7 +1347,17 @@ GUILE_PROC(scm_array_set_x, "array-set!", 2, 0, 1,
wouldn't have contiguous elements. */
GUILE_PROC(scm_array_contents, "array-contents", 1, 1, 0,
(SCM ra, SCM strict),
"")
"@deffnx primitive array-contents array strict
If @var{array} may be @dfn{unrolled} into a one dimensional shared array
without changing their order (last subscript changing fastest), then
@code{array-contents} returns that shared array, otherwise it returns
@code{#f}. All arrays made by @var{make-array} and
@var{make-uniform-array} may be unrolled, some arrays made by
@var{make-shared-array} may not be.
If the optional argument @var{strict} is provided, a shared array will
be returned only if its elements are stored internally contiguous in
memory.")
#define FUNC_NAME s_scm_array_contents
{
SCM sra;
@ -1378,7 +1453,21 @@ scm_ra2contig (SCM ra, int copy)
GUILE_PROC(scm_uniform_array_read_x, "uniform-array-read!", 1, 3, 0,
(SCM ra, SCM port_or_fd, SCM start, SCM end),
"")
"@deffnx primitive uniform-vector-read! uve [port-or-fdes] [start] [end]
Attempts to read all elements of @var{ura}, in lexicographic order, as
binary objects from @var{port-or-fdes}.
If an end of file is encountered during
uniform-array-read! the objects up to that point only are put into @var{ura}
(starting at the beginning) and the remainder of the array is
unchanged.
The optional arguments @var{start} and @var{end} allow
a specified region of a vector (or linearized array) to be read,
leaving the remainder of the vector unchanged.
@code{uniform-array-read!} returns the number of objects read.
@var{port-or-fdes} may be omitted, in which case it defaults to the value
returned by @code{(current-input-port)}.")
#define FUNC_NAME s_scm_uniform_array_read_x
{
SCM cra = SCM_UNDEFINED, v = ra;
@ -1524,7 +1613,18 @@ loop:
GUILE_PROC(scm_uniform_array_write, "uniform-array-write", 1, 3, 0,
(SCM v, SCM port_or_fd, SCM start, SCM end),
"")
"@deffnx primitive uniform-vector-write uve [port-or-fdes] [start] [end]
Writes all elements of @var{ura} as binary objects to
@var{port-or-fdes}.
The optional arguments @var{start}
and @var{end} allow
a specified region of a vector (or linearized array) to be written.
The number of objects actually written is returned.
@var{port-or-fdes} may be
omitted, in which case it defaults to the value returned by
@code{(current-output-port)}.")
#define FUNC_NAME s_scm_uniform_array_write
{
long sz, vlen, ans;
@ -1638,7 +1738,7 @@ static char cnt_tab[16] =
GUILE_PROC(scm_bit_count, "bit-count", 2, 0, 0,
(SCM item, SCM seq),
"")
"Returns the number occurrences of @var{bool} in @var{bv}.")
#define FUNC_NAME s_scm_bit_count
{
long i;
@ -1673,7 +1773,9 @@ GUILE_PROC(scm_bit_count, "bit-count", 2, 0, 0,
GUILE_PROC(scm_bit_position, "bit-position", 3, 0, 0,
(SCM item, SCM v, SCM k),
"")
"Returns the minimum index of an occurrence of @var{bool} in @var{bv}
which is at least @var{k}. If no @var{bool} occurs within the specified
range @code{#f} is returned.")
#define FUNC_NAME s_scm_bit_position
{
long i, lenw, xbits, pos;
@ -1739,7 +1841,15 @@ GUILE_PROC(scm_bit_position, "bit-position", 3, 0, 0,
GUILE_PROC(scm_bit_set_star_x, "bit-set*!", 3, 0, 0,
(SCM v, SCM kv, SCM obj),
"")
"If uve is a bit-vector @var{bv} and uve must be of the same length. If
@var{bool} is @code{#t}, uve is OR'ed into @var{bv}; If @var{bool} is @code{#f}, the
inversion of uve is AND'ed into @var{bv}.
If uve is a unsigned integer vector all the elements of uve must be
between 0 and the @code{LENGTH} of @var{bv}. The bits of @var{bv}
corresponding to the indexes in uve are set to @var{bool}.
The return value is unspecified.")
#define FUNC_NAME s_scm_bit_set_star_x
{
register long i, k, vlen;
@ -1793,7 +1903,11 @@ GUILE_PROC(scm_bit_set_star_x, "bit-set*!", 3, 0, 0,
GUILE_PROC(scm_bit_count_star, "bit-count*", 3, 0, 0,
(SCM v, SCM kv, SCM obj),
"")
"Returns
@example
(bit-count (bit-set*! (if bool bv (bit-invert! bv)) uve #t) #t).
@end example
@var{bv} is not modified.")
#define FUNC_NAME s_scm_bit_count_star
{
register long i, vlen, count = 0;
@ -1857,7 +1971,7 @@ GUILE_PROC(scm_bit_count_star, "bit-count*", 3, 0, 0,
GUILE_PROC(scm_bit_invert_x, "bit-invert!", 1, 0, 0,
(SCM v),
"")
"Modifies @var{bv} by replacing each element with its negation.")
#define FUNC_NAME s_scm_bit_invert_x
{
register long k;
@ -1940,7 +2054,7 @@ ra2l (SCM ra,scm_sizet base,scm_sizet k)
GUILE_PROC(scm_array_to_list, "array->list", 1, 0, 0,
(SCM v),
"")
"Returns a list consisting of all the elements, in order, of @var{array}.")
#define FUNC_NAME s_scm_array_to_list
{
SCM res = SCM_EOL;
@ -2047,7 +2161,10 @@ static int l2ra(SCM lst, SCM ra, scm_sizet base, scm_sizet k);
GUILE_PROC(scm_list_to_uniform_array, "list->uniform-array", 3, 0, 0,
(SCM ndim, SCM prot, SCM lst),
"")
"@deffnx procedure list->uniform-vector prot lst
Returns a uniform array of the type indicated by prototype @var{prot}
with elements the same as those of @var{lst}. Elements must be of the
appropriate type, no coercions are done.")
#define FUNC_NAME s_scm_list_to_uniform_array
{
SCM shp = SCM_EOL;
@ -2399,7 +2516,9 @@ tail:
GUILE_PROC(scm_array_prototype, "array-prototype", 1, 0, 0,
(SCM ra),
"")
"Returns an object that would produce an array of the same type as
@var{array}, if used as the @var{prototype} for
@code{make-uniform-array}.")
#define FUNC_NAME s_scm_array_prototype
{
int enclosed = 0;

4
libguile/vectors.c
View file

@ -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;

11
libguile/version.c
View file

@ -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);

41
libguile/vports.c
View file

@ -139,7 +139,46 @@ sf_close (SCM port)
GUILE_PROC(scm_make_soft_port, "make-soft-port", 2, 0, 0,
(SCM pv, SCM modes),
"")
"Returns a port capable of receiving or delivering characters as
specified by the @var{modes} string (@pxref{File Ports,
open-file}). @var{vector} must be a vector of length 6. Its components
are as follows:
@enumerate 0
@item
procedure accepting one character for output
@item
procedure accepting a string for output
@item
thunk for flushing output
@item
thunk for getting one character
@item
thunk for closing port (not by garbage collection)
@end enumerate
For an output-only port only elements 0, 1, 2, and 4 need be
procedures. For an input-only port only elements 3 and 4 need be
procedures. Thunks 2 and 4 can instead be @code{#f} if there is no useful
operation for them to perform.
If thunk 3 returns @code{#f} or an @code{eof-object} (@pxref{Input,
eof-object?, ,r4rs, The Revised^4 Report on Scheme}) it indicates that
the port has reached end-of-file. For example:
@example
(define stdout (current-output-port))
(define p (make-soft-port
(vector
(lambda (c) (write c stdout))
(lambda (s) (display s stdout))
(lambda () (display "." stdout))
(lambda () (char-upcase (read-char)))
(lambda () (display "@@" stdout)))
"rw"))
(write p p) @result{} #<input-output-soft#\space45d10#\>
@end example")
#define FUNC_NAME s_scm_make_soft_port
{
scm_port *pt;

27
libguile/weaks.c
View file

@ -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));