* Minor docstring updates.

[bpt/guile.git] / doc / maint / guile.texi

@paragraphindent 0

\facons
@c snarfed from alist.c:60
@deffn primitive acons key value alist
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.
@end deffn

\fsloppy-assq
@c snarfed from alist.c:83
@deffn primitive sloppy-assq key alist
Behaves like @code{assq} but does not do any error checking.
Recommended only for use in Guile internals.
@end deffn

\fsloppy-assv
@c snarfed from alist.c:101
@deffn primitive sloppy-assv key alist
Behaves like @code{assv} but does not do any error checking.
Recommended only for use in Guile internals.
@end deffn

\fsloppy-assoc
@c snarfed from alist.c:119
@deffn primitive sloppy-assoc key alist
Behaves like @code{assoc} but does not do any error checking.
Recommended only for use in Guile internals.
@end deffn

\fassq
@c snarfed from alist.c:146
@deffn primitive assq key 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).
@end deffn

\fassv
@c snarfed from alist.c:167
@deffn primitive assv key alist
Behaves like @code{assq} but uses @code{eqv?} for key comparison.
@end deffn

\fassoc
@c snarfed from alist.c:188
@deffn primitive assoc key alist
Behaves like @code{assq} but uses @code{equal?} for key comparison.
@end deffn

\fassq-ref
@c snarfed from alist.c:232
@deffn primitive assq-ref alist 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}.
@end deffn

\fassv-ref
@c snarfed from alist.c:249
@deffn primitive assv-ref alist key
Behaves like @code{assq-ref} but uses @code{eqv?} for key comparison.
@end deffn

\fassoc-ref
@c snarfed from alist.c:266
@deffn primitive assoc-ref alist key
Behaves like @code{assq-ref} but uses @code{equal?} for key comparison.
@end deffn

\fassq-set!
@c snarfed from alist.c:295
@deffn primitive assq-set! alist key 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.
@end deffn

\fassv-set!
@c snarfed from alist.c:313
@deffn primitive assv-set! alist key val
Behaves like @code{assq-set!} but uses @code{eqv?} for key comparison.
@end deffn

\fassoc-set!
@c snarfed from alist.c:331
@deffn primitive assoc-set! alist key val
Behaves like @code{assq-set!} but uses @code{equal?} for key comparison.
@end deffn

\fassq-remove!
@c snarfed from alist.c:355
@deffn primitive assq-remove! alist key
@deffnx primitive assv-remove! alist key
@deffnx primitive assoc-remove! alist key
Delete the first entry in @var{alist} associated with @var{key}, and return
the resulting alist.
@end deffn

\fassv-remove!
@c snarfed from alist.c:371
@deffn primitive assv-remove! alist key
Behaves like @code{assq-remove!} but uses @code{eqv?} for key comparison.
@end deffn

\fassoc-remove!
@c snarfed from alist.c:387
@deffn primitive assoc-remove! alist key
Behaves like @code{assq-remove!} but uses @code{equal?} for key comparison.
@end deffn

\fmake-arbiter
@c snarfed from arbiters.c:84
@deffn primitive make-arbiter name
Return an object of type arbiter and name @var{name}. Its
state is initially unlocked.  Arbiters are a way to achieve
process synchronization.
@end deffn

\ftry-arbiter
@c snarfed from arbiters.c:94
@deffn primitive try-arbiter arb
Return @code{#t} and lock the arbiter @var{arb} if the arbiter
was unlocked. Otherwise, return @code{#f}.
@end deffn

\frelease-arbiter
@c snarfed from arbiters.c:115
@deffn primitive release-arbiter arb
Return @code{#t} and unlock the arbiter @var{arb} if the
arbiter was locked. Otherwise, return @code{#f}.
@end deffn

\fasync
@c snarfed from async.c:290
@deffn primitive async thunk
Create a new async for the procedure @var{thunk}.
@end deffn

\fsystem-async
@c snarfed from async.c:300
@deffn primitive system-async thunk
Create a new async for the procedure @var{thunk}.  Also
add it to the system's list of active async objects.
@end deffn

\fasync-mark
@c snarfed from async.c:317
@deffn primitive async-mark a
Mark the async @var{a} for future execution.
@end deffn

\fsystem-async-mark
@c snarfed from async.c:333
@deffn primitive system-async-mark a
Mark the async @var{a} for future execution.
@end deffn

\frun-asyncs
@c snarfed from async.c:353
@deffn primitive run-asyncs list_of_a
Execute all thunks from the asyncs of the list @var{list_of_a}.
@end deffn

\fnoop
@c snarfed from async.c:387
@deffn primitive noop . args
Do nothing.  When called without arguments, return @code{#f},
otherwise return the first argument.
@end deffn

\funmask-signals
@c snarfed from async.c:439
@deffn primitive unmask-signals
Unmask signals. The returned value is not specified.
@end deffn

\fmask-signals
@c snarfed from async.c:450
@deffn primitive mask-signals
Mask signals. The returned value is not specified.
@end deffn

\fdisplay-error
@c snarfed from backtrace.c:262
@deffn primitive display-error stack port subr message args rest
Display an error message to the output port @var{port}.
@var{stack} is the saved stack for the error, @var{subr} is
the name of the procedure in which the error occured and
@var{message} is the actual error message, which may contain
formatting instructions. These will format the arguments in
the list @var{args} accordingly.  @var{rest} is currently
ignored.
@end deffn

\fdisplay-application
@c snarfed from backtrace.c:399
@deffn primitive display-application frame [port [indent]]
Display a procedure application @var{frame} to the output port
@var{port}. @var{indent} specifies the indentation of the
output.
@end deffn

\fdisplay-backtrace
@c snarfed from backtrace.c:617
@deffn primitive display-backtrace stack port [first [depth]]
Display a backtrace to the output port @var{port}. @var{stack}
is the stack to take the backtrace from, @var{first} specifies
where in the stack to start and @var{depth} how much frames
to display. Both @var{first} and @var{depth} can be @code{#f},
which means that default values will be used.
@end deffn

\fbacktrace
@c snarfed from backtrace.c:640
@deffn primitive backtrace
Display a backtrace of the stack saved by the last error
to the current output port.
@end deffn

\fnot
@c snarfed from boolean.c:56
@deffn primitive not x
Return @code{#t} iff @var{x} is @code{#f}, else return @code{#f}.
@end deffn

\fboolean?
@c snarfed from boolean.c:66
@deffn primitive boolean? obj
Return @code{#t} iff @var{obj} is either @code{#t} or @code{#f}.
@end deffn

\fchar?
@c snarfed from chars.c:56
@deffn primitive char? x
Return @code{#t} iff @var{x} is a character, else @code{#f}.
@end deffn

\fchar=?
@c snarfed from chars.c:65
@deffn primitive char=? x y
Return @code{#t} iff @var{x} is the same character as @var{y}, else @code{#f}.
@end deffn

\fchar<?
@c snarfed from chars.c:78
@deffn primitive char<? x y
Return @code{#t} iff @var{x} is less than @var{y} in the ASCII sequence,
else @code{#f}.
@end deffn

\fchar<=?
@c snarfed from chars.c:90
@deffn primitive char<=? x y
Return @code{#t} iff @var{x} is less than or equal to @var{y} in the
ASCII sequence, else @code{#f}.
@end deffn

\fchar>?
@c snarfed from chars.c:102
@deffn primitive char>? x y
Return @code{#t} iff @var{x} is greater than @var{y} in the ASCII
sequence, else @code{#f}.
@end deffn

\fchar>=?
@c snarfed from chars.c:114
@deffn primitive char>=? x y
Return @code{#t} iff @var{x} is greater than or equal to @var{y} in the
ASCII sequence, else @code{#f}.
@end deffn

\fchar-ci=?
@c snarfed from chars.c:126
@deffn primitive char-ci=? x y
Return @code{#t} iff @var{x} is the same character as @var{y} ignoring
case, else @code{#f}.
@end deffn

\fchar-ci<?
@c snarfed from chars.c:138
@deffn primitive char-ci<? x y
Return @code{#t} iff @var{x} is less than @var{y} in the ASCII sequence
ignoring case, else @code{#f}.
@end deffn

\fchar-ci<=?
@c snarfed from chars.c:150
@deffn primitive char-ci<=? x y
Return @code{#t} iff @var{x} is less than or equal to @var{y} in the
ASCII sequence ignoring case, else @code{#f}.
@end deffn

\fchar-ci>?
@c snarfed from chars.c:162
@deffn primitive char-ci>? x y
Return @code{#t} iff @var{x} is greater than @var{y} in the ASCII
sequence ignoring case, else @code{#f}.
@end deffn

\fchar-ci>=?
@c snarfed from chars.c:174
@deffn primitive char-ci>=? x y
Return @code{#t} iff @var{x} is greater than or equal to @var{y} in the
ASCII sequence ignoring case, else @code{#f}.
@end deffn

\fchar-alphabetic?
@c snarfed from chars.c:187
@deffn primitive char-alphabetic? chr
Return @code{#t} iff @var{chr} is alphabetic, else @code{#f}.
Alphabetic means the same thing as the isalpha C library function.
@end deffn

\fchar-numeric?
@c snarfed from chars.c:198
@deffn primitive char-numeric? chr
Return @code{#t} iff @var{chr} is numeric, else @code{#f}.
Numeric means the same thing as the isdigit C library function.
@end deffn

\fchar-whitespace?
@c snarfed from chars.c:209
@deffn primitive char-whitespace? chr
Return @code{#t} iff @var{chr} is whitespace, else @code{#f}.
Whitespace means the same thing as the isspace C library function.
@end deffn

\fchar-upper-case?
@c snarfed from chars.c:222
@deffn primitive char-upper-case? chr
Return @code{#t} iff @var{chr} is uppercase, else @code{#f}.
Uppercase means the same thing as the isupper C library function.
@end deffn

\fchar-lower-case?
@c snarfed from chars.c:234
@deffn primitive char-lower-case? chr
Return @code{#t} iff @var{chr} is lowercase, else @code{#f}.
Lowercase means the same thing as the islower C library function.
@end deffn

\fchar-is-both?
@c snarfed from chars.c:248
@deffn primitive char-is-both? chr
Return @code{#t} iff @var{chr} is either uppercase or lowercase, else @code{#f}.
Uppercase and lowercase are as defined by the isupper and islower
C library functions.
@end deffn

\fchar->integer
@c snarfed from chars.c:262
@deffn primitive char->integer chr
Return the number corresponding to ordinal position of @var{chr} in the
ASCII sequence.
@end deffn

\finteger->char
@c snarfed from chars.c:274
@deffn primitive integer->char n
Return the character at position @var{n} in the ASCII sequence.
@end deffn

\fchar-upcase
@c snarfed from chars.c:285
@deffn primitive char-upcase chr
Return the uppercase character version of @var{chr}.
@end deffn

\fchar-downcase
@c snarfed from chars.c:296
@deffn primitive char-downcase chr
Return the lowercase character version of @var{chr}.
@end deffn

\fdebug-options-interface
@c snarfed from debug.c:80
@deffn primitive debug-options-interface [setting]
Option interface for the debug options. Instead of using
this procedure directly, use the procedures @code{debug-enable},
@code{debug-disable}, @code{debug-set!} and @var{debug-options}.
@end deffn

\fwith-traps
@c snarfed from debug.c:128
@deffn primitive with-traps thunk
Call @var{thunk} with traps enabled.
@end deffn

\fmemoized?
@c snarfed from debug.c:170
@deffn primitive memoized? obj
Return @code{#t} if @var{obj} is memoized.
@end deffn

\funmemoize
@c snarfed from debug.c:376
@deffn primitive unmemoize m
Unmemoize the memoized expression @var{m},
@end deffn

\fmemoized-environment
@c snarfed from debug.c:386
@deffn primitive memoized-environment m
Return the environment of the memoized expression @var{m}.
@end deffn

\fprocedure-name
@c snarfed from debug.c:396
@deffn primitive procedure-name proc
Return the name of the procedure @var{proc}
@end deffn

\fprocedure-source
@c snarfed from debug.c:422
@deffn primitive procedure-source proc
Return the source of the procedure @var{proc}.
@end deffn

\fprocedure-environment
@c snarfed from debug.c:456
@deffn primitive procedure-environment proc
Return the environment of the procedure @var{proc}.
@end deffn

\flocal-eval
@c snarfed from debug.c:488
@deffn primitive local-eval exp [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).
@end deffn

\fdebug-object?
@c snarfed from debug.c:576
@deffn primitive debug-object? obj
Return @code{#t} if @var{obj} is a debug object.
@end deffn

\fc-registered-modules
@c snarfed from dynl.c:183
@deffn primitive c-registered-modules
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, and whose cdr is the function handle
for that module's initializer function.  The name is the string that
has been passed to scm_register_module_xxx.
@end deffn

\fc-clear-registered-modules
@c snarfed from dynl.c:204
@deffn primitive c-clear-registered-modules
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.
@end deffn

\fdynamic-link
@c snarfed from dynl.c:356
@deffn primitive dynamic-link fname
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.
@end deffn

\fdynamic-object?
@c snarfed from dynl.c:372
@deffn primitive dynamic-object? obj
Return @code{#t} if @var{obj} is a dynamic library handle, or @code{#f}
otherwise.
@end deffn

\fdynamic-unlink
@c snarfed from dynl.c:388
@deffn primitive dynamic-unlink 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} must have been obtained by a call to
@code{dynamic-link}.  After @code{dynamic-unlink} has been
called on @var{dynobj}, its content is no longer accessible.
@end deffn

\fdynamic-func
@c snarfed from dynl.c:415
@deffn primitive dynamic-func name dobj
Search the dynamic object @var{dobj} for the C function
indicated by the string @var{name} and return some Scheme
handle that can later be used with @code{dynamic-call} to
actually call the function.

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.
@end deffn

\fdynamic-call
@c snarfed from dynl.c:460
@deffn primitive dynamic-call func 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}).
@end deffn

\fdynamic-args-call
@c snarfed from dynl.c:494
@deffn primitive dynamic-args-call func dobj 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}.
@end deffn

\fdynamic-wind
@c snarfed from dynwind.c:115
@deffn primitive dynamic-wind thunk1 thunk2 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
@end deffn

\fenvironment?
@c snarfed from environments.c:135
@deffn primitive environment? obj
Return @code{#t} if @var{obj} is an environment, or @code{#f}
otherwise.
@end deffn

\fenvironment-bound?
@c snarfed from environments.c:146
@deffn primitive environment-bound? env sym
Return @code{#t} if @var{sym} is bound in @var{env}, or
@code{#f} otherwise.
@end deffn

\fenvironment-ref
@c snarfed from environments.c:161
@deffn primitive environment-ref env sym
Return the value of the location bound to @var{sym} in
@var{env}. If @var{sym} is unbound in @var{env}, signal an
@code{environment:unbound} error.
@end deffn

\fenvironment-fold
@c snarfed from environments.c:231
@deffn primitive environment-fold env proc init
Iterate over all the bindings in @var{env}, accumulating some
value.
For each binding in @var{env}, apply @var{proc} to the symbol
bound, its value, and the result from the previous application
of @var{proc}.
Use @var{init} as @var{proc}'s third argument the first time
@var{proc} is applied.
If @var{env} contains no bindings, this function simply returns
@var{init}.
If @var{env} binds the symbol sym1 to the value val1, sym2 to
val2, and so on, then this procedure computes:
@example
  (proc sym1 val1
        (proc sym2 val2
              ...
              (proc symn valn
                    init)))
@end example
Each binding in @var{env} will be processed exactly once.
@code{environment-fold} makes no guarantees about the order in
which the bindings are processed.
Here is a function which, given an environment, constructs an
association list representing that environment's bindings,
using environment-fold:
@example
  (define (environment->alist env)
    (environment-fold env
                      (lambda (sym val tail)
                        (cons (cons sym val) tail))
                      '()))
@end example
@end deffn

\fenvironment-define
@c snarfed from environments.c:266
@deffn primitive environment-define env sym val
Bind @var{sym} to a new location containing @var{val} in
@var{env}. If @var{sym} is already bound to another location
in @var{env} and the binding is mutable, that binding is
replaced.  The new binding and location are both mutable. The
return value is unspecified.
If @var{sym} is already bound in @var{env}, and the binding is
immutable, signal an @code{environment:immutable-binding} error.
@end deffn

\fenvironment-undefine
@c snarfed from environments.c:292
@deffn primitive environment-undefine env sym
Remove any binding for @var{sym} from @var{env}. If @var{sym}
is unbound in @var{env}, do nothing.  The return value is
unspecified.
If @var{sym} is already bound in @var{env}, and the binding is
immutable, signal an @code{environment:immutable-binding} error.
@end deffn

\fenvironment-set!
@c snarfed from environments.c:320
@deffn primitive environment-set! env sym val
If @var{env} binds @var{sym} to some location, change that
location's value to @var{val}.  The return value is
unspecified.
If @var{sym} is not bound in @var{env}, signal an
@code{environment:unbound} error.  If @var{env} binds @var{sym}
to an immutable location, signal an
@code{environment:immutable-location} error.
@end deffn

\fenvironment-cell
@c snarfed from environments.c:355
@deffn primitive environment-cell env sym for_write
Return the value cell which @var{env} binds to @var{sym}, or
@code{#f} if the binding does not live in a value cell.
The argument @var{for-write} indicates whether the caller
intends to modify the variable's value by mutating the value
cell.  If the variable is immutable, then
@code{environment-cell} signals an
@code{environment:immutable-location} error.
If @var{sym} is unbound in @var{env}, signal an
@code{environment:unbound} error.
If you use this function, you should consider using
@code{environment-observe}, to be notified when @var{sym} gets
re-bound to a new value cell, or becomes undefined.
@end deffn

\fenvironment-observe
@c snarfed from environments.c:407
@deffn primitive environment-observe env proc
Whenever @var{env}'s bindings change, apply @var{proc} to
@var{env}.
This function returns an object, token, which you can pass to
@code{environment-unobserve} to remove @var{proc} from the set
of procedures observing @var{env}.  The type and value of
token is unspecified.
@end deffn

\fenvironment-observe-weak
@c snarfed from environments.c:424
@deffn primitive environment-observe-weak env proc
This function is the same as environment-observe, except that
the reference @var{env} retains to @var{proc} is a weak
reference. This means that, if there are no other live,
non-weak references to @var{proc}, it will be
garbage-collected, and dropped from @var{env}'s
list of observing procedures.
@end deffn

\fenvironment-unobserve
@c snarfed from environments.c:460
@deffn primitive environment-unobserve token
Cancel the observation request which returned the value
@var{token}.  The return value is unspecified.
If a call @code{(environment-observe env proc)} returns
@var{token}, then the call @code{(environment-unobserve token)}
will cause @var{proc} to no longer be called when @var{env}'s
bindings change.
@end deffn

\fmake-leaf-environment
@c snarfed from environments.c:1040
@deffn primitive make-leaf-environment
Create a new leaf environment, containing no bindings.
All bindings and locations created in the new environment
will be mutable.
@end deffn

\fleaf-environment?
@c snarfed from environments.c:1063
@deffn primitive leaf-environment? object
Return @code{#t} if object is a leaf environment, or @code{#f}
otherwise.
@end deffn

\fmake-eval-environment
@c snarfed from environments.c:1429
@deffn primitive make-eval-environment local imported
Return a new environment object eval whose bindings are the
union of the bindings in the environments @var{local} and
@var{imported}, with bindings from @var{local} taking
precedence. Definitions made in eval are placed in @var{local}.
Applying @code{environment-define} or
@code{environment-undefine} to eval has the same effect as
applying the procedure to @var{local}.
Note that eval incorporates @var{local} and @var{imported} by
reference:
If, after creating eval, the program changes the bindings of
@var{local} or @var{imported}, those changes will be visible
in eval.
Since most Scheme evaluation takes place in eval environments,
they transparently cache the bindings received from @var{local}
and @var{imported}. Thus, the first time the program looks up
a symbol in eval, eval may make calls to @var{local} or
@var{imported} to find their bindings, but subsequent
references to that symbol will be as fast as references to
bindings in finite environments.
In typical use, @var{local} will be a finite environment, and
@var{imported} will be an import environment
@end deffn

\feval-environment?
@c snarfed from environments.c:1466
@deffn primitive eval-environment? object
Return @code{#t} if object is an eval environment, or @code{#f}
otherwise.
@end deffn

\feval-environment-local
@c snarfed from environments.c:1476
@deffn primitive eval-environment-local env
Return the local environment of eval environment @var{env}.
@end deffn

\feval-environment-set-local!
@c snarfed from environments.c:1488
@deffn primitive eval-environment-set-local! env local
Change @var{env}'s local environment to @var{local}.
@end deffn

\feval-environment-imported
@c snarfed from environments.c:1514
@deffn primitive eval-environment-imported env
Return the imported environment of eval environment @var{env}.
@end deffn

\feval-environment-set-imported!
@c snarfed from environments.c:1526
@deffn primitive eval-environment-set-imported! env imported
Change @var{env}'s imported environment to @var{imported}.
@end deffn

\fmake-import-environment
@c snarfed from environments.c:1846
@deffn primitive make-import-environment imports conflict_proc
Return a new environment @var{imp} whose bindings are the union
of the bindings from the environments in @var{imports};
@var{imports} must be a list of environments. That is,
@var{imp} binds a symbol to a location when some element of
@var{imports} does.
If two different elements of @var{imports} have a binding for
the same symbol, the @var{conflict-proc} is called with the
following parameters:  the import environment, the symbol and
the list of the imported environments that bind the symbol.
If the @var{conflict-proc} returns an environment @var{env},
the conflict is considered as resolved and the binding from
@var{env} is used.  If the @var{conflict-proc} returns some
non-environment object, the conflict is considered unresolved
and the symbol is treated as unspecified in the import
environment.
The checking for conflicts may be performed lazily, i. e. at
the moment when a value or binding for a certain symbol is
requested instead of the moment when the environment is
created or the bindings of the imports change.
All bindings in @var{imp} are immutable. If you apply
@code{environment-define} or @code{environment-undefine} to
@var{imp}, Guile will signal an
 @code{environment:immutable-binding} error. However,
notice that the set of bindings in @var{imp} may still change,
if one of its imported environments changes.
@end deffn

\fimport-environment?
@c snarfed from environments.c:1875
@deffn primitive import-environment? object
Return @code{#t} if object is an import environment, or
@code{#f} otherwise.
@end deffn

\fimport-environment-imports
@c snarfed from environments.c:1886
@deffn primitive import-environment-imports env
Return the list of environments imported by the import
environment @var{env}.
@end deffn

\fimport-environment-set-imports!
@c snarfed from environments.c:1899
@deffn primitive import-environment-set-imports! env imports
Change @var{env}'s list of imported environments to
@var{imports}, and check for conflicts.
@end deffn

\fmake-export-environment
@c snarfed from environments.c:2164
@deffn primitive make-export-environment private signature
Return a new environment @var{exp} containing only those
bindings in private whose symbols are present in
@var{signature}. The @var{private} argument must be an
environment.

The environment @var{exp} binds symbol to location when
@var{env} does, and symbol is exported by @var{signature}.

@var{signature} is a list specifying which of the bindings in
@var{private} should be visible in @var{exp}. Each element of
@var{signature} should be a list of the form:
  (symbol attribute ...)
where each attribute is one of the following:
@table @asis
@item the symbol @code{mutable-location}
  @var{exp} should treat the
  location bound to symbol as mutable. That is, @var{exp}
  will pass calls to @code{environment-set!} or
  @code{environment-cell} directly through to private.
@item the symbol @code{immutable-location}
  @var{exp} should treat
  the location bound to symbol as immutable. If the program
  applies @code{environment-set!} to @var{exp} and symbol, or
  calls @code{environment-cell} to obtain a writable value
  cell, @code{environment-set!} will signal an
  @code{environment:immutable-location} error. Note that, even
  if an export environment treats a location as immutable, the
  underlying environment may treat it as mutable, so its
  value may change.
@end table
It is an error for an element of signature to specify both
@code{mutable-location} and @code{immutable-location}. If
neither is specified, @code{immutable-location} is assumed.

As a special case, if an element of signature is a lone
symbol @var{sym}, it is equivalent to an element of the form
@code{(sym)}.

All bindings in @var{exp} are immutable. If you apply
@code{environment-define} or @code{environment-undefine} to
@var{exp}, Guile will signal an
@code{environment:immutable-binding} error. However,
notice that the set of bindings in @var{exp} may still change,
if the bindings in private change.
@end deffn

\fexport-environment?
@c snarfed from environments.c:2199
@deffn primitive export-environment? object
Return @code{#t} if object is an export environment, or
@code{#f} otherwise.
@end deffn

\fexport-environment-private
@c snarfed from environments.c:2209
@deffn primitive export-environment-private env
Return the private environment of export environment @var{env}.
@end deffn

\fexport-environment-set-private!
@c snarfed from environments.c:2221
@deffn primitive export-environment-set-private! env private
Change the private environment of export environment @var{env}.
@end deffn

\fexport-environment-signature
@c snarfed from environments.c:2243
@deffn primitive export-environment-signature env
Return the signature of export environment @var{env}.
@end deffn

\fexport-environment-set-signature!
@c snarfed from environments.c:2317
@deffn primitive export-environment-set-signature! env signature
Change the signature of export environment @var{env}.
@end deffn

\feq?
@c snarfed from eq.c:64
@deffn primitive eq? x y
Return @code{#t} iff @var{x} references the same object as @var{y}.
@code{eq?} is similar to @code{eqv?} except that in some cases it is
capable of discerning distinctions finer than those detectable by
@code{eqv?}.
@end deffn

\feqv?
@c snarfed from eq.c:78
@deffn primitive eqv? x y
The @code{eqv?} procedure defines a useful equivalence relation on objects.
Briefly, it returns @code{#t} if @var{x} and @var{y} should normally be
regarded as the same object.  This relation is left slightly open to
interpretation, but works for comparing immediate integers, characters,
and inexact numbers.
@end deffn

\fequal?
@c snarfed from eq.c:127
@deffn primitive equal? x y
Return @code{#t} iff @var{x} and @var{y} are recursively @code{eqv?} equivalent.
@code{equal?} recursively compares the contents of pairs,
vectors, and strings, applying @code{eqv?} on other objects such as
numbers and symbols.  A rule of thumb is that objects are generally
@code{equal?}  if they print the same.  @code{equal?} may fail to
terminate if its arguments are circular data structures.
@end deffn

\fscm-error
@c snarfed from error.c:112
@deffn primitive scm-error key subr message args 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{~A}
escapes.  When an error is reported, these are replaced by formating the
corresponding members of @var{args}: @code{~A} (was @code{%s}) formats using @code{display}
and @code{~S} (was @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}.
@end deffn

\fstrerror
@c snarfed from error.c:153
@deffn primitive strerror err
Returns the Unix error message corresponding to @var{err}, an integer.
@end deffn

\fapply:nconc2last
@c snarfed from eval.c:3221
@deffn primitive apply:nconc2last lst
Given a list (@var{arg1} @dots{} @var{args}), this function
conses the @var{arg1} @dots{} arguments onto the front of
@var{args}, and returns the resulting list. Note that
@var{args} is a list; thus, the argument to this function is
a list whose last element is a list.
Note: Rather than do new consing, @code{apply:nconc2last}
destroys its argument, so use with care.
@end deffn

\fforce
@c snarfed from eval.c:3754
@deffn primitive force x
If the promise @var{x} has not been computed yet, compute and
return @var{x}, otherwise just return the previously computed
value.
@end deffn

\fpromise?
@c snarfed from eval.c:3777
@deffn primitive promise? obj
Return true if @var{obj} is a promise, i.e. a delayed computation
(@pxref{Delayed evaluation,,,r4rs.info,The Revised^4 Report on Scheme}).
@end deffn

\fcons-source
@c snarfed from eval.c:3789
@deffn primitive cons-source xorig x y
Create and return a new pair whose car and cdr are @var{x} and @var{y}.
Any source properties associated with @var{xorig} are also associated
with the new pair.
@end deffn

\fcopy-tree
@c snarfed from eval.c:3811
@deffn primitive copy-tree 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.
@end deffn

\fprimitive-eval
@c snarfed from eval.c:3912
@deffn primitive primitive-eval exp
Evaluate @var{exp} in the top-level environment specified by
the current module.
@end deffn

\feval
@c snarfed from eval.c:3977
@deffn primitive eval exp module
Evaluate @var{exp}, a list representing a Scheme expression,
in the top-level environment specified by @var{module}.
While @var{exp} is evaluated (using @var{primitive-eval}),
@var{module} is made the current module.  The current module
is reset to its previous value when @var{eval} returns.
@end deffn

\feval2
@c snarfed from eval.c:4020
@deffn primitive eval2 obj env_thunk
Evaluate @var{exp}, a Scheme expression, in the environment
designated by @var{lookup}, a symbol-lookup function."
Do not use this version of eval, it does not play well
with the module system.  Use @code{eval} or
@code{primitive-eval} instead.
@end deffn

\feval-options-interface
@c snarfed from eval.c:1685
@deffn primitive eval-options-interface [setting]
Option interface for the evaluation options. Instead of using
this procedure directly, use the procedures @code{eval-enable},
@code{eval-disable}, @code{eval-set!} and @var{eval-options}.
@end deffn

\fevaluator-traps-interface
@c snarfed from eval.c:1702
@deffn primitive evaluator-traps-interface [setting]
Option interface for the evaluator trap options.
@end deffn

\fdefined?
@c snarfed from evalext.c:74
@deffn primitive defined? sym [env]
Return @code{#t} if @var{sym} is defined in the top-level environment.
@end deffn

\fmap-in-order
@c snarfed from evalext.c:146
@deffn primitive map-in-order
scm_map
@end deffn

\fprogram-arguments
@c snarfed from feature.c:79
@deffn primitive program-arguments
@deffnx procedure command-line
Return the list of command line arguments passed to Guile, as a list of
strings.  The list includes the invoked program name, which is usually
@code{"guile"}, but excludes switches and parameters for command line
options like @code{-e} and @code{-l}.
@end deffn

\fchown
@c snarfed from filesys.c:140
@deffn primitive chown object owner group
Change the ownership and group of the file referred to by @var{object} to
the integer values @var{owner} and @var{group}.  @var{object} can be
a string containing a file name or, if the platform
supports fchown, a port or integer file descriptor
which is open on the file.  The return value
is unspecified.

If @var{object} 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.
@end deffn

\fchmod
@c snarfed from filesys.c:180
@deffn primitive chmod object 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.
@end deffn

\fumask
@c snarfed from filesys.c:214
@deffn primitive umask [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.
@end deffn

\fopen-fdes
@c snarfed from filesys.c:237
@deffn primitive open-fdes path flags [mode]
Similar to @code{open} but returns a file descriptor instead of a
port.
@end deffn

\fopen
@c snarfed from filesys.c:280
@deffn primitive open path flags [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.
@end deffn

\fclose
@c snarfed from filesys.c:318
@deffn primitive close 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.
@end deffn

\fclose-fdes
@c snarfed from filesys.c:346
@deffn primitive close-fdes fd
A simple wrapper for the @code{close} system call.
Close file descriptor @var{fd}, which must be an integer.
Unlike close (@pxref{Ports and File Descriptors, close}),
the file descriptor will be closed even if a port is using it.
The return value is unspecified.
@end deffn

\fstat
@c snarfed from filesys.c:518
@deffn primitive stat 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
@end deffn

\flink
@c snarfed from filesys.c:564
@deffn primitive link oldpath newpath
Creates a new name @var{newpath} in the file system for the
file named by @var{oldpath}.  If @var{oldpath} is a symbolic
link, the link may or may not be followed depending on the
system.
@end deffn

\frename-file
@c snarfed from filesys.c:586
@deffn primitive rename-file oldname newname
Renames the file specified by @var{oldname} to @var{newname}.
The return value is unspecified.
@end deffn

\fdelete-file
@c snarfed from filesys.c:615
@deffn primitive delete-file str
Deletes (or "unlinks") the file specified by @var{path}.
@end deffn

\fmkdir
@c snarfed from filesys.c:634
@deffn primitive mkdir path [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.
@end deffn

\frmdir
@c snarfed from filesys.c:663
@deffn primitive rmdir path
Remove the existing directory named by @var{path}.  The directory must
be empty for this to succeed.  The return value is unspecified.
@end deffn

\fdirectory-stream?
@c snarfed from filesys.c:689
@deffn primitive directory-stream? obj
Returns a boolean indicating whether @var{object} is a directory stream
as returned by @code{opendir}.
@end deffn

\fopendir
@c snarfed from filesys.c:700
@deffn primitive opendir dirname
Open the directory specified by @var{path} and return a directory
stream.
@end deffn

\freaddir
@c snarfed from filesys.c:718
@deffn primitive readdir 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.
@end deffn

\frewinddir
@c snarfed from filesys.c:741
@deffn primitive rewinddir port
Reset the directory port @var{stream} so that the next call to
@code{readdir} will return the first directory entry.
@end deffn

\fclosedir
@c snarfed from filesys.c:758
@deffn primitive closedir port
Close the directory stream @var{stream}.
The return value is unspecified.
@end deffn

\fchdir
@c snarfed from filesys.c:808
@deffn primitive chdir str
Change the current working directory to @var{path}.
The return value is unspecified.
@end deffn

\fgetcwd
@c snarfed from filesys.c:825
@deffn primitive getcwd
Returns the name of the current working directory.
@end deffn

\fselect
@c snarfed from filesys.c:1022
@deffn primitive select reads writes excepts [secs [usecs]]
This procedure has a variety of uses: waiting for the ability
to provide input, accept output, or the existance of
exceptional conditions on a collection of ports or file
descriptors, or waiting for a timeout to occur.
It also returns if interrupted by a signal.

@var{reads}, @var{writes} and @var{excepts} can be lists or
vectors, with each member a port or a file descriptor.
The value returned is a list of three corresponding
lists or vectors containing only the members which meet the
specified requirement.  The ability of port buffers to
provide input or accept output is taken into account.
Ordering of the input lists or vectors is not preserved.

The optional arguments @var{secs} and @var{usecs} specify the
timeout.  Either @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.  If @var{secs} is omitted or is @code{#f} then
select will wait for as long as it takes for one of the other
conditions to be satisfied.

The scsh version of @code{select} differs as follows:
Only vectors are accepted for the first three arguments.
The @var{usecs} argument is not supported.
Multiple values are returned instead of a list.
Duplicates in the input vectors appear only once in output.
An additional @code{select!} interface is provided.
@end deffn

\ffcntl
@c snarfed from filesys.c:1167
@deffn primitive fcntl object cmd [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
@end deffn

\ffsync
@c snarfed from filesys.c:1203
@deffn primitive fsync 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.
@end deffn

\fsymlink
@c snarfed from filesys.c:1230
@deffn primitive symlink oldpath newpath
Create a symbolic link named @var{path-to} with the value (i.e., pointing to)
@var{path-from}.  The return value is unspecified.
@end deffn

\freadlink
@c snarfed from filesys.c:1252
@deffn primitive readlink path
Returns the value of the symbolic link named by
@var{path} (a string), i.e., the
file that the link points to.
@end deffn

\flstat
@c snarfed from filesys.c:1282
@deffn primitive lstat 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.
@end deffn

\fcopy-file
@c snarfed from filesys.c:1307
@deffn primitive copy-file oldfile newfile
Copy the file specified by @var{path-from} to @var{path-to}.
The return value is unspecified.
@end deffn

\fdirname
@c snarfed from filesys.c:1354
@deffn primitive dirname filename
Return the directory name component of the file name
@var{filename}. If @var{filename} does not contain a directory
component, @code{.} is returned.
@end deffn

\fbasename
@c snarfed from filesys.c:1387
@deffn primitive basename filename [suffix]
Return the base name of the file name @var{filename}. The
base name is the file name without any directory components.
If @var{suffix} is privided, and is equal to the end of
@var{basename}, it is removed also.
@end deffn

\fmake-fluid
@c snarfed from fluids.c:128
@deffn primitive make-fluid
Return a newly created fluid.
Fluids are objects of a certain type (a smob) that can hold one SCM
value per dynamic root.  That is, modifications to this value are
only visible to code that executes within the same dynamic root as
the modifying code.  When a new dynamic root is constructed, it
inherits the values from its parent.  Because each thread executes
in its own dynamic root, you can use fluids for thread local storage.
@end deffn

\ffluid?
@c snarfed from fluids.c:141
@deffn primitive fluid? obj
Return #t iff @var{obj} is a fluid; otherwise, return #f.
@end deffn

\ffluid-ref
@c snarfed from fluids.c:151
@deffn primitive fluid-ref fluid
Return the value associated with @var{fluid} in the current dynamic root.
If @var{fluid} has not been set, then this returns #f.
@end deffn

\ffluid-set!
@c snarfed from fluids.c:168
@deffn primitive fluid-set! fluid value
Set the value associated with @var{fluid} in the current dynamic root.
@end deffn

\fwith-fluids*
@c snarfed from fluids.c:227
@deffn primitive with-fluids* fluids values thunk
Set @var{fluids} to @var{values} temporary, and call @var{thunk}.
@var{fluids} must be a list of fluids and @var{values} must be the same
number of their values to be applied.  Each substitution is done
one after another.  @var{thunk} must be a procedure with no argument.
@end deffn

\fsetvbuf
@c snarfed from fports.c:148
@deffn primitive setvbuf port mode [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
@end deffn

\ffile-port?
@c snarfed from fports.c:229
@deffn primitive file-port? obj
Determine whether @var{obj} is a port that is related to a file.
@end deffn

\fopen-file
@c snarfed from fports.c:282
@deffn primitive open-file filename 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.
@end deffn

\fgc-stats
@c snarfed from gc.c:742
@deffn primitive gc-stats
Returns an association list of statistics about Guile's current use of storage.
@end deffn

\fobject-address
@c snarfed from gc.c:839
@deffn primitive object-address obj
Return an integer that for the lifetime of @var{obj} is uniquely
returned by this function for @var{obj}
@end deffn

\fgc
@c snarfed from gc.c:850
@deffn primitive gc
Scans all of SCM objects and reclaims for further use those that are
no longer accessible.
@end deffn

\funhash-name
@c snarfed from gc.c:2291
@deffn primitive unhash-name name
Flushes the glocs for @var{name}, or all glocs if @var{name}
is @code{#t}.
@end deffn

\f%compute-slots
@c snarfed from goops.c:290
@deffn primitive %compute-slots class
Return a list consisting of the names of all slots belonging to
class @var{class}, i. e. the slots of @var{class} and of all of
its superclasses.
@end deffn

\fget-keyword
@c snarfed from goops.c:375
@deffn primitive get-keyword key l default_value
Determine an associated value for the keyword @var{key} from
the list @var{l}.  The list @var{l} has to consist of an even
number of elements, where, starting with the first, every
second element is a keyword, followed by its associated value.
If @var{l} does not hold a value for @var{key}, the value
@var{default_value} is returned.
@end deffn

\f%initialize-object
@c snarfed from goops.c:398
@deffn primitive %initialize-object obj initargs
Initialize the object @var{obj} with the given arguments
@var{initargs}.
@end deffn

\f%prep-layout!
@c snarfed from goops.c:479
@deffn primitive %prep-layout! class
@end deffn

\f%inherit-magic!
@c snarfed from goops.c:542
@deffn primitive %inherit-magic! class dsupers
@end deffn

\finstance?
@c snarfed from goops.c:783
@deffn primitive instance? obj
Return @code{#t} if @var{obj} is an instance.
@end deffn

\fclass-name
@c snarfed from goops.c:798
@deffn primitive class-name obj
Return the class name of @var{obj}.
@end deffn

\fclass-direct-supers
@c snarfed from goops.c:808
@deffn primitive class-direct-supers obj
Return the direct superclasses of the class @var{obj}.
@end deffn

\fclass-direct-slots
@c snarfed from goops.c:818
@deffn primitive class-direct-slots obj
Return the direct slots of the class @var{obj}.
@end deffn

\fclass-direct-subclasses
@c snarfed from goops.c:828
@deffn primitive class-direct-subclasses obj
Return the direct subclasses of the class @var{obj}.
@end deffn

\fclass-direct-methods
@c snarfed from goops.c:838
@deffn primitive class-direct-methods obj
Return the direct methods of the class @var{obj}
@end deffn

\fclass-precedence-list
@c snarfed from goops.c:848
@deffn primitive class-precedence-list obj
Return the class precedence list of the class @var{obj}.
@end deffn

\fclass-slots
@c snarfed from goops.c:858
@deffn primitive class-slots obj
Return the slot list of the class @var{obj}.
@end deffn

\fclass-environment
@c snarfed from goops.c:868
@deffn primitive class-environment obj
Return the environment of the class @var{obj}.
@end deffn

\fgeneric-function-name
@c snarfed from goops.c:879
@deffn primitive generic-function-name obj
Return the name of the generic function @var{obj}.
@end deffn

\fgeneric-function-methods
@c snarfed from goops.c:889
@deffn primitive generic-function-methods obj
Return the methods of the generic function @var{obj}.
@end deffn

\fmethod-generic-function
@c snarfed from goops.c:900
@deffn primitive method-generic-function obj
Return the generic function fot the method @var{obj}.
@end deffn

\fmethod-specializers
@c snarfed from goops.c:910
@deffn primitive method-specializers obj
Return specializers of the method @var{obj}.
@end deffn

\fmethod-procedure
@c snarfed from goops.c:920
@deffn primitive method-procedure obj
Return the procedure of the method @var{obj}.
@end deffn

\faccessor-method-slot-definition
@c snarfed from goops.c:930
@deffn primitive accessor-method-slot-definition obj
Return the slot definition of the accessor @var{obj}.
@end deffn

\f%tag-body
@c snarfed from goops.c:940
@deffn primitive %tag-body body
Internal GOOPS magic---don't use this function!
@end deffn

\fmake-unbound
@c snarfed from goops.c:955
@deffn primitive make-unbound
Return the unbound value.
@end deffn

\funbound?
@c snarfed from goops.c:964
@deffn primitive unbound? obj
Return @code{#t} if @var{obj} is unbound.
@end deffn

\fassert-bound
@c snarfed from goops.c:974
@deffn primitive assert-bound value obj
Return @var{value} if it is bound, and invoke the
@var{slot-unbound} method of @var{obj} if it is not.
@end deffn

\f@@assert-bound-ref
@c snarfed from goops.c:986
@deffn primitive @@assert-bound-ref obj index
Like @code{assert-bound}, but use @var{index} for accessing
the value from @var{obj}.
@end deffn

\f%fast-slot-ref
@c snarfed from goops.c:998
@deffn primitive %fast-slot-ref obj index
Return the slot value with index @var{index} from @var{obj}.
@end deffn

\f%fast-slot-set!
@c snarfed from goops.c:1015
@deffn primitive %fast-slot-set! obj index value
Set the slot with index @var{index} in @var{obj} to
@var{value}.
@end deffn

\fslot-ref-using-class
@c snarfed from goops.c:1143
@deffn primitive slot-ref-using-class class obj slot_name
@end deffn

\fslot-set-using-class!
@c snarfed from goops.c:1162
@deffn primitive slot-set-using-class! class obj slot_name value
@end deffn

\fslot-bound-using-class?
@c snarfed from goops.c:1176
@deffn primitive slot-bound-using-class? class obj slot_name
@end deffn

\fslot-exists-using-class?
@c snarfed from goops.c:1191
@deffn primitive slot-exists-using-class? class obj slot_name
@end deffn

\fslot-ref
@c snarfed from goops.c:1207
@deffn primitive slot-ref obj slot_name
Return the value from @var{obj}'s slot with the name
@var{slot_name}.
@end deffn

\fslot-set!
@c snarfed from goops.c:1224
@deffn primitive slot-set! obj slot_name value
Set the slot named @var{slot_name} of @var{obj} to @var{value}.
@end deffn

\fslot-bound?
@c snarfed from goops.c:1241
@deffn primitive slot-bound? obj slot_name
Return @code{#t} if the slot named @var{slot_name} of @var{obj}
is bound.
@end deffn

\fslot-exists?
@c snarfed from goops.c:1259
@deffn primitive slot-exists? obj slot_name
Return @code{#t} if @var{obj} has a slot named @var{slot_name}.
@end deffn

\f%allocate-instance
@c snarfed from goops.c:1302
@deffn primitive %allocate-instance class initargs
Create a new instance of class @var{class} and initialize it
from the arguments @var{initargs}.
@end deffn

\f%set-object-setter!
@c snarfed from goops.c:1375
@deffn primitive %set-object-setter! obj setter
@end deffn

\f%modify-instance
@c snarfed from goops.c:1400
@deffn primitive %modify-instance old new
@end deffn

\f%modify-class
@c snarfed from goops.c:1426
@deffn primitive %modify-class old new
@end deffn

\f%invalidate-class
@c snarfed from goops.c:1450
@deffn primitive %invalidate-class class
@end deffn

\f%invalidate-method-cache!
@c snarfed from goops.c:1571
@deffn primitive %invalidate-method-cache! gf
@end deffn

\fgeneric-capability?
@c snarfed from goops.c:1597
@deffn primitive generic-capability? proc
@end deffn

\fenable-primitive-generic!
@c snarfed from goops.c:1610
@deffn primitive enable-primitive-generic! . subrs
@end deffn

\fprimitive-generic-generic
@c snarfed from goops.c:1630
@deffn primitive primitive-generic-generic subr
@end deffn

\fmake
@c snarfed from goops.c:1989
@deffn primitive make . args
Make a new object.  @var{args} must contain the class and
all necessary initialization information.
@end deffn

\ffind-method
@c snarfed from goops.c:2082
@deffn primitive find-method . l
@end deffn

\f%method-more-specific?
@c snarfed from goops.c:2102
@deffn primitive %method-more-specific? m1 m2 targs
@end deffn

\f%goops-loaded
@c snarfed from goops.c:2634
@deffn primitive %goops-loaded
Announce that GOOPS is loaded and perform initialization
on the C level which depends on the loaded GOOPS modules.
@end deffn

\fmake-guardian
@c snarfed from guardians.c:336
@deffn primitive make-guardian [greedy_p]
Create a new guardian.
A guardian protects a set of objects from garbage collection,
allowing a program to apply cleanup or other actions.

@code{make-guardian} returns a procedure representing the guardian.
Calling the guardian procedure with an argument adds the
argument to the guardian's set of protected objects.
Calling the guardian procedure without an argument returns
one of the protected objects which are ready for garbage
collection, or @code{#f} if no such object is available.
Objects which are returned in this way are removed from
the guardian.

@code{make-guardian} takes one optional argument that says whether the
new guardian should be greedy or sharing.  If there is any chance
that any object protected by the guardian may be resurrected,
then you should make the guardian greedy (this is the default).

See R. Kent Dybvig, Carl Bruggeman, and David Eby (1993)
"Guardians in a Generation-Based Garbage Collector".
ACM SIGPLAN Conference on Programming Language Design
and Implementation, June 1993.

(the semantics are slightly different at this point, but the
paper still (mostly) accurately describes the interface).
@end deffn

\fguardian-destroyed?
@c snarfed from guardians.c:364
@deffn primitive guardian-destroyed? guardian
Return @code{#t} if @var{guardian} has been destroyed, otherwise @code{#f}.
@end deffn

\fguardian-greedy?
@c snarfed from guardians.c:382
@deffn primitive guardian-greedy? guardian
Return @code{#t} if @var{guardian} is a greedy guardian, otherwise @code{#f}.
@end deffn

\fdestroy-guardian!
@c snarfed from guardians.c:393
@deffn primitive destroy-guardian! guardian
Destroys @var{guardian}, by making it impossible to put any more
objects in it or get any objects from it.  It also unguards any
objects guarded by @var{guardian}.
@end deffn

\fhashq
@c snarfed from hash.c:202
@deffn primitive hashq key size
Determine a hash value for @var{key} that is suitable for
lookups in a hashtable of size @var{size}, where @code{eq?} is
used as the equality predicate.  The function returns an
integer in the range 0 to @var{size} - 1.  Note that
@code{hashq} may use internal addresses.  Thus two calls to
hashq where the keys are @code{eq?} are not guaranteed to
deliver the same value if the key object gets garbage collected
in between.  This can happen, for example with symbols:
@code{(hashq 'foo n) (gc) (hashq 'foo n)} may produce two
different values, since @code{foo} will be garbage collected.
@end deffn

\fhashv
@c snarfed from hash.c:238
@deffn primitive hashv key size
Determine a hash value for @var{key} that is suitable for
lookups in a hashtable of size @var{size}, where @code{eqv?} is
used as the equality predicate.  The function returns an
integer in the range 0 to @var{size} - 1.  Note that
@code{(hashv key)} may use internal addresses.  Thus two calls
to hashv where the keys are @code{eqv?} are not guaranteed to
deliver the same value if the key object gets garbage collected
in between.  This can happen, for example with symbols:
@code{(hashv 'foo n) (gc) (hashv 'foo n)} may produce two
different values, since @code{foo} will be garbage collected.
@end deffn

\fhash
@c snarfed from hash.c:261
@deffn primitive hash key size
Determine a hash value for @var{key} that is suitable for
lookups in a hashtable of size @var{size}, where @code{equal?}
is used as the equality predicate.  The function returns an
integer in the range 0 to @var{size} - 1.
@end deffn

\fhashq-get-handle
@c snarfed from hashtab.c:174
@deffn primitive hashq-get-handle table obj
This procedure is similar to its @code{-ref} cousin, but returns 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)}.
@end deffn

\fhashq-create-handle!
@c snarfed from hashtab.c:186
@deffn primitive hashq-create-handle! table key init
This function looks up @var{key} in @var{table} and returns its handle.
If @var{key} is not already present, a new handle is created which
associates @var{key} with @var{init}.
@end deffn

\fhashq-ref
@c snarfed from hashtab.c:199
@deffn primitive hashq-ref table obj [dflt]
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).  Uses @code{eq?} for equality testing.
@end deffn

\fhashq-set!
@c snarfed from hashtab.c:213
@deffn primitive hashq-set! table obj val
Find the entry in @var{table} associated with @var{key}, and
store @var{value} there. Uses @code{eq?} for equality testing.
@end deffn

\fhashq-remove!
@c snarfed from hashtab.c:225
@deffn primitive hashq-remove! table obj
Remove @var{key} (and any value associated with it) from
@var{table}.  Uses @code{eq?} for equality tests.
@end deffn

\fhashv-get-handle
@c snarfed from hashtab.c:242
@deffn primitive hashv-get-handle table obj
This procedure is similar to its @code{-ref} cousin, but returns 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{hashv-ref table key} returns
only a @code{value}, @code{hashv-get-handle table key} returns the pair
@code{(key . value)}.
@end deffn

\fhashv-create-handle!
@c snarfed from hashtab.c:254
@deffn primitive hashv-create-handle! table key init
This function looks up @var{key} in @var{table} and returns its handle.
If @var{key} is not already present, a new handle is created which
associates @var{key} with @var{init}.
@end deffn

\fhashv-ref
@c snarfed from hashtab.c:267
@deffn primitive hashv-ref table obj [dflt]
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).  Uses @code{eqv?} for equality testing.
@end deffn

\fhashv-set!
@c snarfed from hashtab.c:281
@deffn primitive hashv-set! table obj val
Find the entry in @var{table} associated with @var{key}, and
store @var{value} there. Uses @code{eqv?} for equality testing.
@end deffn

\fhashv-remove!
@c snarfed from hashtab.c:292
@deffn primitive hashv-remove! table obj
Remove @var{key} (and any value associated with it) from
@var{table}.  Uses @code{eqv?} for equality tests.
@end deffn

\fhash-get-handle
@c snarfed from hashtab.c:308
@deffn primitive hash-get-handle table obj
This procedure is similar to its @code{-ref} cousin, but returns 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{hash-ref table key} returns
only a @code{value}, @code{hash-get-handle table key} returns the pair
@code{(key . value)}.
@end deffn

\fhash-create-handle!
@c snarfed from hashtab.c:320
@deffn primitive hash-create-handle! table key init
This function looks up @var{key} in @var{table} and returns its handle.
If @var{key} is not already present, a new handle is created which
associates @var{key} with @var{init}.
@end deffn

\fhash-ref
@c snarfed from hashtab.c:333
@deffn primitive hash-ref table obj [dflt]
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).  Uses @code{equal?} for equality testing.
@end deffn

\fhash-set!
@c snarfed from hashtab.c:348
@deffn primitive hash-set! table obj val
Find the entry in @var{table} associated with @var{key}, and
store @var{value} there. Uses @code{equal?} for equality
testing.
@end deffn

\fhash-remove!
@c snarfed from hashtab.c:360
@deffn primitive hash-remove! table obj
Remove @var{key} (and any value associated with it) from
@var{table}.  Uses @code{equal?} for equality tests.
@end deffn

\fhashx-get-handle
@c snarfed from hashtab.c:429
@deffn primitive hashx-get-handle hash assoc table obj
This behaves the same way as the corresponding @code{-get-handle}
function, but uses @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}.
@end deffn

\fhashx-create-handle!
@c snarfed from hashtab.c:447
@deffn primitive hashx-create-handle! hash assoc table obj init
This behaves the same way as the corresponding @code{-create-handle}
function, but uses @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}.
@end deffn

\fhashx-ref
@c snarfed from hashtab.c:468
@deffn primitive hashx-ref hash assoc table obj [dflt]
This behaves the same way as the corresponding @code{ref}
function, but uses @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}.
@end deffn

\fhashx-set!
@c snarfed from hashtab.c:492
@deffn primitive hashx-set! hash assoc table obj val
This behaves the same way as the corresponding @code{set!}
function, but uses @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-set! table key} is equivalent
to @code{hashx-set! hashq assq table key}.
@end deffn

\fhash-fold
@c snarfed from hashtab.c:529
@deffn primitive hash-fold proc init table
An iterator over hash-table elements.
Accumulates and returns a result by applying PROC successively.
The arguments to PROC are "(key value prior-result)" where key
and value are successive pairs from the hash table TABLE, and
prior-result is either INIT (for the first application of PROC)
or the return value of the previous application of PROC.
For example, @code{(hash-fold acons () tab)} will convert a hash
table into an a-list of key-value pairs.
@end deffn

\fmake-hook-with-name
@c snarfed from hooks.c:216
@deffn primitive make-hook-with-name name [n_args]
Create a named hook with the name @var{name} for storing
procedures of arity @var{n_args}.
@end deffn

\fmake-hook
@c snarfed from hooks.c:230
@deffn primitive make-hook [n_args]
Create a hook for storing procedure of arity @var{n_args}.
@end deffn

\fhook?
@c snarfed from hooks.c:240
@deffn primitive hook? x
Return @code{#t} if @var{x} is a hook.
@end deffn

\fhook-empty?
@c snarfed from hooks.c:250
@deffn primitive hook-empty? hook
Return @code{#t} if @var{hook} is an empty hook.
@end deffn

\fadd-hook!
@c snarfed from hooks.c:263
@deffn primitive add-hook! hook proc [append_p]
Add the procedure @var{proc} to the hook @var{hook}. The
procedure is added to the end if @var{append_p} is true,
otherwise it is added to the front.
@end deffn

\fremove-hook!
@c snarfed from hooks.c:289
@deffn primitive remove-hook! hook proc
Remove the procedure @var{proc} from the hook @var{hook}.
@end deffn

\freset-hook!
@c snarfed from hooks.c:302
@deffn primitive reset-hook! hook
Remove all procedures from the hook @var{hook}.
@end deffn

\frun-hook
@c snarfed from hooks.c:315
@deffn primitive run-hook hook . args
Apply all procedures from the hook @var{hook} to the arguments
@var{args}.
@end deffn

\fhook->list
@c snarfed from hooks.c:342
@deffn primitive hook->list hook
Convert the procedure list of @var{hook} to a list.
@end deffn

\fread-string!/partial
@c snarfed from ioext.c:114
@deffn primitive read-string!/partial str [port_or_fdes [start [end]]]
Read characters from an fport or file descriptor into a
string @var{str}.  This procedure is scsh-compatible
and can efficiently read large strings.  It will:

@itemize
@item
attempt to fill the entire string, unless the @var{start}
and/or @var{end} arguments are supplied.  i.e., @var{start}
defaults to 0 and @var{end} defaults to
@code{(string-length str)}
@item
use the current input port if @var{port_or_fdes} is not
supplied.
@item
read any characters that are currently available,
without waiting for the rest (short reads are possible).

@item
wait for as long as it needs to for the first character to
become available, unless the port is in non-blocking mode
@item
return @code{#f} if end-of-file is encountered before reading
any characters, otherwise return the number of characters
read.
@item
return 0 if the port is in non-blocking mode and no characters
are immediately available.
@item
return 0 if the request is for 0 bytes, with no
end-of-file check
@end itemize
@end deffn

\fftell
@c snarfed from ioext.c:173
@deffn primitive ftell 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
@end deffn

\ffseek
@c snarfed from ioext.c:186
@deffn primitive fseek object offset whence
Obsolete.  Almost the same as seek, above, but the return value is
unspecified.
@end deffn

\fredirect-port
@c snarfed from ioext.c:208
@deffn primitive redirect-port old 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.
@end deffn

\fdup->fdes
@c snarfed from ioext.c:245
@deffn primitive dup->fdes fd_or_port [fd]
Returns an integer file descriptor.
@end deffn

\fdup2
@c snarfed from ioext.c:292
@deffn primitive dup2 oldfd newfd
A simple wrapper for the @code{dup2} system call.
Copies the file descriptor @var{oldfd} to descriptor
number @var{newfd}, replacing the previous meaning
of @var{newfd}.  Both @var{oldfd} and @var{newfd} must
be integers.
Unlike for dup->fdes or primitive-move->fdes, no attempt
is made to move away ports which are using @var{newfd}.
The return value is unspecified.
@end deffn

\ffileno
@c snarfed from ioext.c:311
@deffn primitive fileno port
Returns the integer file descriptor underlying @var{port}.
Does not change its revealed count.
@end deffn

\fisatty?
@c snarfed from ioext.c:327
@deffn primitive isatty? port
Returns @code{#t} if @var{port} is using a serial
non-file device, otherwise @code{#f}.
@end deffn

\ffdopen
@c snarfed from ioext.c:349
@deffn primitive fdopen fdes 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}.
@end deffn

\fprimitive-move->fdes
@c snarfed from ioext.c:374
@deffn primitive primitive-move->fdes port 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.
@end deffn

\ffdes->ports
@c snarfed from ioext.c:407
@deffn primitive fdes->ports fd
Returns a list of existing ports which have @var{fdes} as an
underlying file descriptor, without changing their revealed counts.
@end deffn

\fmake-keyword-from-dash-symbol
@c snarfed from keywords.c:71
@deffn primitive make-keyword-from-dash-symbol symbol
Make a keyword object from a @var{symbol} that starts with a dash.
@end deffn

\fkeyword?
@c snarfed from keywords.c:112
@deffn primitive keyword? obj
Returns @code{#t} if the argument @var{obj} is a keyword, else @code{#f}.
@end deffn

\fkeyword-dash-symbol
@c snarfed from keywords.c:123
@deffn primitive keyword-dash-symbol keyword
Return the dash symbol for @var{keyword}.
This is the inverse of @code{make-keyword-from-dash-symbol}.
@end deffn

\fnil-cons
@c snarfed from lang.c:71
@deffn primitive nil-cons x y
Create a new cons cell with @var{x} as the car and @var{y} as
the cdr, but convert @var{y} to Scheme's end-of-list if it is
a LISP nil.
@end deffn

\fnil-car
@c snarfed from lang.c:86
@deffn primitive nil-car x
Return the car of @var{x}, but convert it to LISP nil if it
is Scheme's end-of-list.
@end deffn

\fnil-cdr
@c snarfed from lang.c:99
@deffn primitive nil-cdr x
Return the cdr of @var{x}, but convert it to LISP nil if it
is Scheme's end-of-list.
@end deffn

\fnull
@c snarfed from lang.c:114
@deffn primitive null x
Return LISP's @code{t} if @var{x} is nil in the LISP sense,
return LISP's nil otherwise.
@end deffn

\fnil-eq
@c snarfed from lang.c:143
@deffn primitive nil-eq x y
Compare @var{x} and @var{y} and return LISP's t if they are
@code{eq?}, return LISP's nil otherwise.
@end deffn

\flist
@c snarfed from list.c:84
@deffn primitive list . objs
Return a list containing @var{objs}, the arguments to
@code{list}.
@end deffn

\flist*
@c snarfed from list.c:94
@deffn primitive list*
scm_cons_star
@end deffn

\fcons*
@c snarfed from list.c:105
@deffn primitive cons* arg . rest
Like @code{list}, but the last arg provides the tail of the
constructed list, returning @code{(cons @var{arg1} (cons
@var{arg2} (cons @dots{} @var{argn})))}.  Requires at least one
argument.  If given one argument, that argument is returned as
result.  This function is called @code{list*} in some other
Schemes and in Common LISP.
@end deffn

\fnull?
@c snarfed from list.c:129
@deffn primitive null? x
Return @code{#t} iff @var{x} is the empty list, else @code{#f}.
@end deffn

\flist?
@c snarfed from list.c:139
@deffn primitive list? x
Return @code{#t} iff @var{x} is a proper list, else @code{#f}.
@end deffn

\flength
@c snarfed from list.c:180
@deffn primitive length lst
Return the number of elements in list @var{lst}.
@end deffn

\fappend
@c snarfed from list.c:209
@deffn primitive append . args
Return a list consisting of the elements the lists passed as
arguments.
@example
(append '(x) '(y))          @result{}  (x y)
(append '(a) '(b c d))      @result{}  (a b c d)
(append '(a (b)) '((c)))    @result{}  (a (b) (c))
@end example
The resulting list is always newly allocated, except that it
shares structure with the last list argument.  The last
argument may actually be any object; an improper list results
if the last argument is not a proper list.
@example
(append '(a b) '(c . d))    @result{}  (a b c . d)
(append '() 'a)             @result{}  a
@end example
@end deffn

\fappend!
@c snarfed from list.c:242
@deffn primitive append! . 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.
@end deffn

\flast-pair
@c snarfed from list.c:268
@deffn primitive last-pair lst
Return a pointer to the last pair in @var{lst}, signalling an error if
@var{lst} is circular.
@end deffn

\freverse
@c snarfed from list.c:298
@deffn primitive reverse lst
Return a new list that contains the elements of @var{lst} but
in reverse order.
@end deffn

\freverse!
@c snarfed from list.c:332
@deffn primitive reverse! lst [new_tail]
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!}
@end deffn

\flist-ref
@c snarfed from list.c:358
@deffn primitive list-ref list k
Return the @var{k}th element from @var{list}.
@end deffn

\flist-set!
@c snarfed from list.c:382
@deffn primitive list-set! list k val
Set the @var{k}th element of @var{list} to @var{val}.
@end deffn

\flist-cdr-ref
@c snarfed from list.c:405
@deffn primitive list-cdr-ref
scm_list_tail
@end deffn

\flist-tail
@c snarfed from list.c:414
@deffn primitive list-tail lst k
@deffnx primitive list-cdr-ref lst 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-tail} and @code{list-cdr-ref} 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}.
@end deffn

\flist-cdr-set!
@c snarfed from list.c:430
@deffn primitive list-cdr-set! list k val
Set the @var{k}th cdr of @var{list} to @var{val}.
@end deffn

\flist-head
@c snarfed from list.c:459
@deffn primitive list-head lst k
Copy the first @var{k} elements from @var{lst} into a new list, and
return it.
@end deffn

\flist-copy
@c snarfed from list.c:483
@deffn primitive list-copy lst
Return a (newly-created) copy of @var{lst}.
@end deffn

\fsloppy-memq
@c snarfed from list.c:517
@deffn primitive sloppy-memq x lst
This procedure behaves like @code{memq}, but does no type or error checking.
Its use is recommended only in writing Guile internals,
not for high-level Scheme programs.
@end deffn

\fsloppy-memv
@c snarfed from list.c:534
@deffn primitive sloppy-memv x lst
This procedure behaves like @code{memv}, but does no type or error checking.
Its use is recommended only in writing Guile internals,
not for high-level Scheme programs.
@end deffn

\fsloppy-member
@c snarfed from list.c:551
@deffn primitive sloppy-member x lst
This procedure behaves like @code{member}, but does no type or error checking.
Its use is recommended only in writing Guile internals,
not for high-level Scheme programs.
@end deffn

\fmemq
@c snarfed from list.c:591
@deffn primitive memq x lst
Return the first sublist of @var{lst} whose car is @code{eq?}
to @var{x} where the sublists of @var{lst} are the non-empty
lists returned by @code{(list-tail @var{lst} @var{k})} for
@var{k} less than the length of @var{lst}.  If @var{x} does not
occur in @var{lst}, then @code{#f} (not the empty list) is
returned.
@end deffn

\fmemv
@c snarfed from list.c:608
@deffn primitive memv x lst
Return the first sublist of @var{lst} whose car is @code{eqv?}
to @var{x} where the sublists of @var{lst} are the non-empty
lists returned by @code{(list-tail @var{lst} @var{k})} for
@var{k} less than the length of @var{lst}.  If @var{x} does not
occur in @var{lst}, then @code{#f} (not the empty list) is
returned.
@end deffn

\fmember
@c snarfed from list.c:629
@deffn primitive member x lst
Return the first sublist of @var{lst} whose car is
@code{equal?} to @var{x} where the sublists of @var{lst} are
the non-empty lists returned by @code{(list-tail @var{lst}
@var{k})} for @var{k} less than the length of @var{lst}.  If
@var{x} does not occur in @var{lst}, then @code{#f} (not the
empty list) is returned.
@end deffn

\fdelq!
@c snarfed from list.c:655
@deffn primitive delq! item 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.
@end deffn

\fdelv!
@c snarfed from list.c:679
@deffn primitive delv! item lst
Destructively remove all elements from @var{lst} that are
@code{eqv?} to @var{item}.
@end deffn

\fdelete!
@c snarfed from list.c:704
@deffn primitive delete! item lst
Destructively remove all elements from @var{lst} that are
@code{equal?} to @var{item}.
@end deffn

\fdelq
@c snarfed from list.c:733
@deffn primitive delq item lst
Return a newly-created copy of @var{lst} with elements
@code{eq?} to @var{item} removed.  This procedure mirrors
@code{memq}: @code{delq} compares elements of @var{lst} against
@var{item} with @code{eq?}.
@end deffn

\fdelv
@c snarfed from list.c:746
@deffn primitive delv item lst
Return a newly-created copy of @var{lst} with elements
@code{eqv?}  to @var{item} removed.  This procedure mirrors
@code{memv}: @code{delv} compares elements of @var{lst} against
@var{item} with @code{eqv?}.
@end deffn

\fdelete
@c snarfed from list.c:759
@deffn primitive delete item lst
Return a newly-created copy of @var{lst} with elements
@code{equal?}  to @var{item} removed.  This procedure mirrors
@code{member}: @code{delete} compares elements of @var{lst}
against @var{item} with @code{equal?}.
@end deffn

\fdelq1!
@c snarfed from list.c:772
@deffn primitive delq1! item lst
Like @code{delq!}, but only deletes the first occurrence of
@var{item} from @var{lst}.  Tests for equality using
@code{eq?}.  See also @code{delv1!} and @code{delete1!}.
@end deffn

\fdelv1!
@c snarfed from list.c:800
@deffn primitive delv1! item lst
Like @code{delv!}, but only deletes the first occurrence of
@var{item} from @var{lst}.  Tests for equality using
@code{eqv?}.  See also @code{delq1!} and @code{delete1!}.
@end deffn

\fdelete1!
@c snarfed from list.c:828
@deffn primitive delete1! item lst
Like @code{delete!}, but only deletes the first occurrence of
@var{item} from @var{lst}.  Tests for equality using
@code{equal?}.  See also @code{delq1!} and @code{delv1!}.
@end deffn

\fprimitive-load
@c snarfed from load.c:112
@deffn primitive primitive-load filename
Load the file named @var{filename} and evaluate its contents in
the top-level environment. The load paths are not searched;
@var{filename} 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 the
documentation for @code{%load-hook} later in this section.
@end deffn

\f%package-data-dir
@c snarfed from load.c:147
@deffn primitive %package-data-dir
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}.
@end deffn

\f%library-dir
@c snarfed from load.c:159
@deffn primitive %library-dir
Return the directory where the Guile Scheme library files are installed.
E.g., may return "/usr/share/guile/1.3.5".
@end deffn

\f%site-dir
@c snarfed from load.c:171
@deffn primitive %site-dir
Return the directory where the Guile site files are installed.
E.g., may return "/usr/share/guile/site".
@end deffn

\fparse-path
@c snarfed from load.c:223
@deffn primitive parse-path path [tail]
Parse @var{path}, which is expected to be a colon-separated
string, into a list and return the resulting list with
@var{tail} appended. If @var{path} is @code{#f}, @var{tail}
is returned.
@end deffn

\fsearch-path
@c snarfed from load.c:273
@deffn primitive search-path path filename [extensions]
Search @var{path} for a directory containing a file named
@var{filename}. The file must be readable, and not a directory.
If we find one, return its full filename; otherwise, return
@code{#f}.  If @var{filename} is absolute, return it unchanged.
If given, @var{extensions} is a list of strings; for each
directory in @var{path}, we search for @var{filename}
concatenated with each @var{extension}.
@end deffn

\f%search-load-path
@c snarfed from load.c:420
@deffn primitive %search-load-path filename
Search @var{%load-path} for the file named @var{filename},
which must be readable by the current user.  If @var{filename}
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.
@end deffn

\fprimitive-load-path
@c snarfed from load.c:441
@deffn primitive primitive-load-path filename
Search @var{%load-path} for the file named @var{filename} and
load it into the top-level environment.  If @var{filename} is a
relative pathname and is not found in the list of search paths,
an error is signalled.
@end deffn

\fread-and-eval!
@c snarfed from load.c:476
@deffn primitive read-and-eval! [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.
@end deffn

\fprocedure->syntax
@c snarfed from macros.c:60
@deffn primitive procedure->syntax code
Returns a @dfn{macro} which, when a symbol defined to this value
appears as the first symbol in an expression, returns the result
of applying @var{code} to the expression and the environment.
@end deffn

\fprocedure->macro
@c snarfed from macros.c:82
@deffn primitive procedure->macro code
Returns a @dfn{macro} which, when a symbol defined to this value
appears as the first symbol in an expression, evaluates the result
of applying @var{code} to the expression and the environment.
The value returned from @var{code} which has been passed to
@code{procedure->memoizing-macro} replaces the form passed to
@var{code}.  For example:

@example
(define trace
  (procedure->macro
   (lambda (x env) `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x))))))

(trace @i{foo}) @equiv{} (set! @i{foo} (tracef @i{foo} '@i{foo})).
@end example
@end deffn

\fprocedure->memoizing-macro
@c snarfed from macros.c:104
@deffn primitive procedure->memoizing-macro code
Returns a @dfn{macro} which, when a symbol defined to this value
appears as the first symbol in an expression, evaluates the result
of applying @var{proc} to the expression and the environment.
The value returned from @var{proc} which has been passed to
@code{procedure->memoizing-macro} replaces the form passed to
@var{proc}.  For example:

@example
(define trace
  (procedure->macro
   (lambda (x env) `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x))))))

(trace @i{foo}) @equiv{} (set! @i{foo} (tracef @i{foo} '@i{foo})).
@end example
@end deffn

\fmacro?
@c snarfed from macros.c:116
@deffn primitive macro? obj
Return @code{#t} if @var{obj} is a regular macro, a memoizing macro or a
syntax transformer.
@end deffn

\fmacro-type
@c snarfed from macros.c:133
@deffn primitive macro-type 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.
@end deffn

\fmacro-name
@c snarfed from macros.c:151
@deffn primitive macro-name m
Return the name of the macro @var{m}.
@end deffn

\fmacro-transformer
@c snarfed from macros.c:162
@deffn primitive macro-transformer m
Return the transformer of the macro @var{m}.
@end deffn

\finteraction-environment
@c snarfed from modules.c:102
@deffn primitive interaction-environment
This procedure returns a specifier for the environment that contains
implementation-defined bindings, typically a superset of those listed in
the report.  The intent is that this procedure will return the
environment in which the implementation would evaluate expressions
dynamically typed by the user.
@end deffn

\fstandard-eval-closure
@c snarfed from modules.c:271
@deffn primitive standard-eval-closure module
Return an eval closure for the module @var{module}.
@end deffn

\finet-aton
@c snarfed from net_db.c:96
@deffn primitive inet-aton 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
@end deffn

\finet-ntoa
@c snarfed from net_db.c:116
@deffn primitive inet-ntoa 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
@end deffn

\finet-netof
@c snarfed from net_db.c:135
@deffn primitive inet-netof address
Returns the network number part of the given integer Internet address.

@smalllisp
(inet-netof 2130706433) @result{} 127
@end smalllisp
@end deffn

\finet-lnaof
@c snarfed from net_db.c:152
@deffn primitive inet-lnaof address
Returns the local-address-with-network part of the given Internet
address.

@smalllisp
(inet-lnaof 2130706433) @result{} 1
@end smalllisp
@end deffn

\finet-makeaddr
@c snarfed from net_db.c:169
@deffn primitive inet-makeaddr net 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
@end deffn

\fgethost
@c snarfed from net_db.c:254
@deffn primitive gethost [host]
@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.
@end deffn

\fgetnet
@c snarfed from net_db.c:335
@deffn primitive getnet [net]
@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.
@end deffn

\fgetproto
@c snarfed from net_db.c:385
@deffn primitive getproto [protocol]
@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.
@end deffn

\fgetserv
@c snarfed from net_db.c:452
@deffn primitive getserv [name [protocol]]
@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).
@end deffn

\fsethost
@c snarfed from net_db.c:491
@deffn primitive sethost [stayopen]
If @var{stayopen} is omitted, this is equivalent to @code{endhostent}.
Otherwise it is equivalent to @code{sethostent stayopen}.
@end deffn

\fsetnet
@c snarfed from net_db.c:507
@deffn primitive setnet [stayopen]
If @var{stayopen} is omitted, this is equivalent to @code{endnetent}.
Otherwise it is equivalent to @code{setnetent stayopen}.
@end deffn

\fsetproto
@c snarfed from net_db.c:523
@deffn primitive setproto [stayopen]
If @var{stayopen} is omitted, this is equivalent to @code{endprotoent}.
Otherwise it is equivalent to @code{setprotoent stayopen}.
@end deffn

\fsetserv
@c snarfed from net_db.c:539
@deffn primitive setserv [stayopen]
If @var{stayopen} is omitted, this is equivalent to @code{endservent}.
Otherwise it is equivalent to @code{setservent stayopen}.
@end deffn

\fexact?
@c snarfed from numbers.c:106
@deffn primitive exact? x
Return @code{#t} if @var{x} is an exact number, @code{#f}
otherwise.
@end deffn

\fodd?
@c snarfed from numbers.c:123
@deffn primitive odd? n
Return @code{#t} if @var{n} is an odd number, @code{#f}
otherwise.
@end deffn

\feven?
@c snarfed from numbers.c:140
@deffn primitive even? n
Return @code{#t} if @var{n} is an even number, @code{#f}
otherwise.
@end deffn

\flogand
@c snarfed from numbers.c:755
@deffn primitive logand n1 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"
@end lisp
@end deffn

\flogior
@c snarfed from numbers.c:842
@deffn primitive logior n1 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
@end deffn

\flogxor
@c snarfed from numbers.c:928
@deffn primitive logxor n1 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
@end deffn

\flogtest
@c snarfed from numbers.c:997
@deffn primitive logtest n1 n2
@example
(logtest j k) @equiv{} (not (zero? (logand j k)))

(logtest #b0100 #b1011) @result{} #f
(logtest #b0100 #b0111) @result{} #t
@end example
@end deffn

\flogbit?
@c snarfed from numbers.c:1054
@deffn primitive logbit? index j
@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
@end deffn

\flognot
@c snarfed from numbers.c:1102
@deffn primitive lognot 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
@end deffn

\finteger-expt
@c snarfed from numbers.c:1118
@deffn primitive integer-expt n k
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
@end deffn

\fash
@c snarfed from numbers.c:1166
@deffn primitive ash n cnt
The function ash performs an arithmetic shift left by @var{CNT}
bits (or shift right, if @var{cnt} is negative).
'Arithmetic' means, that the function does not guarantee to
keep the bit structure of @var{n}, but rather guarantees that
the result will always be rounded towards minus infinity.
Therefore, the results of ash and a corresponding bitwise
shift will differ if N is negative.

Formally, the function returns an integer equivalent to
@code{(inexact->exact (floor (* @var{n} (expt 2 @var{cnt}))))}.

Example:
@lisp
(number->string (ash #b1 3) 2)
   @result{} "1000"
(number->string (ash #b1010 -1) 2)
   @result{} "101"
@end lisp
@end deffn

\fbit-extract
@c snarfed from numbers.c:1219
@deffn primitive bit-extract n start 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
@end deffn

\flogcount
@c snarfed from numbers.c:1291
@deffn primitive logcount 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
@end deffn

\finteger-length
@c snarfed from numbers.c:1342
@deffn primitive integer-length 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
@end deffn

\fnumber->string
@c snarfed from numbers.c:2288
@deffn primitive number->string n [radix]
Return a string holding the external representation of the
number @var{n} in the given @var{radix}.  If @var{n} is
inexact, a radix of 10 will be used.
@end deffn

\fstring->number
@c snarfed from numbers.c:2873
@deffn primitive string->number string [radix]
Returns a number of the maximally precise representation
expressed by the given @var{string}. @var{radix} must be an
exact integer, either 2, 8, 10, or 16. If supplied, @var{radix}
is a default radix that may be overridden by an explicit radix
prefix in @var{string} (e.g. "#o177"). If @var{radix} is not
supplied, then the default radix is 10. If string is not a
syntactically valid notation for a number, then
@code{string->number} returns @code{#f}.
@end deffn

\fnumber?
@c snarfed from numbers.c:2940
@deffn primitive number?
scm_number_p
@end deffn

\fcomplex?
@c snarfed from numbers.c:2952
@deffn primitive complex? x
Return @code{#t} if @var{x} is a complex number, @code{#f}
else.  Note that the sets of real, rational and integer
values form subsets of the set of complex numbers, i. e. the
predicate will also be fulfilled if @var{x} is a real,
rational or integer number.
@end deffn

\freal?
@c snarfed from numbers.c:2960
@deffn primitive real?
scm_real_p
@end deffn

\frational?
@c snarfed from numbers.c:2973
@deffn primitive rational? x
Return @code{#t} if @var{x} is a rational number, @code{#f}
else.  Note that the set of integer values forms a subset of
the set of rational numbers, i. e. the predicate will also be
fulfilled if @var{x} is an integer number.  Real numbers
will also satisfy this predicate, because of their limited
precision.
@end deffn

\finteger?
@c snarfed from numbers.c:2994
@deffn primitive integer? x
Return @code{#t} if @var{x} is an integer number, @code{#f}
else.
@end deffn

\finexact?
@c snarfed from numbers.c:3019
@deffn primitive inexact? x
Return @code{#t} if @var{x} is an inexact number, @code{#f}
else.
@end deffn

\f$expt
@c snarfed from numbers.c:4071
@deffn primitive $expt x y
Return @var{x} raised to the power of @var{y}. This
procedure does not accept complex arguments.
@end deffn

\f$atan2
@c snarfed from numbers.c:4087
@deffn primitive $atan2 x y
Return the arc tangent of the two arguments @var{x} and
@var{y}. This is similar to calculating the arc tangent of
@var{x} / @var{y}, except that the signs of both arguments
are used to determine the quadrant of the result. This
procedure does not accept complex arguments.
@end deffn

\fmake-rectangular
@c snarfed from numbers.c:4100
@deffn primitive make-rectangular real imaginary
Return a complex number constructed of the given @var{real} and
@var{imaginary} parts.
@end deffn

\fmake-polar
@c snarfed from numbers.c:4113
@deffn primitive make-polar x y
Return the complex number @var{x} * e^(i * @var{y}).
@end deffn

\finexact->exact
@c snarfed from numbers.c:4231
@deffn primitive inexact->exact z
Returns an exact number that is numerically closest to @var{z}.
@end deffn

\fclass-of
@c snarfed from objects.c:88
@deffn primitive class-of x
Return the class of @var{x}.
@end deffn

\fentity?
@c snarfed from objects.c:359
@deffn primitive entity? obj
Return @code{#t} if @var{obj} is an entity.
@end deffn

\foperator?
@c snarfed from objects.c:368
@deffn primitive operator? obj
Return @code{#t} if @var{obj} is an operator.
@end deffn

\fset-object-procedure!
@c snarfed from objects.c:380
@deffn primitive set-object-procedure! obj proc
Return the object procedure of @var{obj} to @var{proc}.
@var{obj} must be either an entity or an operator.
@end deffn

\fmake-class-object
@c snarfed from objects.c:440
@deffn primitive make-class-object metaclass layout
Create a new class object of class @var{metaclass}, with the
slot layout specified by @var{layout}.
@end deffn

\fmake-subclass-object
@c snarfed from objects.c:455
@deffn primitive make-subclass-object class layout
Create a subclass object of @var{class}, with the slot layout
specified by @var{layout}.
@end deffn

\fobject-properties
@c snarfed from objprop.c:62
@deffn primitive object-properties obj
@deffnx primitive procedure-properties obj
Return @var{obj}'s property list.
@end deffn

\fset-object-properties!
@c snarfed from objprop.c:73
@deffn primitive set-object-properties! obj plist
@deffnx primitive set-procedure-properties! obj alist
Set @var{obj}'s property list to @var{alist}.
@end deffn

\fobject-property
@c snarfed from objprop.c:85
@deffn primitive object-property obj key
@deffnx primitive procedure-property obj key
Return the property of @var{obj} with name @var{key}.
@end deffn

\fset-object-property!
@c snarfed from objprop.c:98
@deffn primitive set-object-property! obj key val
@deffnx primitive set-procedure-property! obj key value
In @var{obj}'s property list, set the property named @var{key} to
@var{value}.
@end deffn

\fcons
@c snarfed from pairs.c:61
@deffn primitive cons x y
Returns a newly allocated pair whose car is @var{x} and whose cdr is
@var{y}.  The pair is guaranteed to be different (in the sense of
@code{eqv?}) from every previously existing object.
@end deffn

\fpair?
@c snarfed from pairs.c:93
@deffn primitive pair? x
Returns @code{#t} if @var{x} is a pair; otherwise returns @code{#f}.
@end deffn

\fset-car!
@c snarfed from pairs.c:104
@deffn primitive set-car! pair value
Stores @var{value} in the car field of @var{pair}.  The value returned
by @code{set-car!} is unspecified.
@end deffn

\fset-cdr!
@c snarfed from pairs.c:117
@deffn primitive set-cdr! pair value
Stores @var{value} in the cdr field of @var{pair}.  The value returned
by @code{set-cdr!} is unspecified.
@end deffn

\fchar-ready?
@c snarfed from ports.c:246
@deffn primitive char-ready? [port]
Returns @code{#t} if a character is ready on input @var{port} and
returns @code{#f} otherwise.  If @code{char-ready?} returns @code{#t}
then the next @code{read-char} operation on @var{port} is
guaranteed not to hang.  If @var{port} is a file port at end of
file then @code{char-ready?} returns @code{#t}.
@footnote{@code{char-ready?} exists to make it possible for a
program to accept characters from interactive ports without getting
stuck waiting for input.  Any input editors associated with such ports
must make sure that characters whose existence has been asserted by
@code{char-ready?} cannot be rubbed out.  If @code{char-ready?} were to
return @code{#f} at end of file, a port at end of file would be
indistinguishable from an interactive port that has no ready
characters.}
@end deffn

\fdrain-input
@c snarfed from ports.c:312
@deffn primitive drain-input port
Drain @var{port}'s read buffers (including any pushed-back
characters) and returns the content as a single string.
@end deffn

\fcurrent-input-port
@c snarfed from ports.c:339
@deffn primitive current-input-port
Return the current input port.  This is the default port used
by many input procedures.  Initially, @code{current-input-port}
returns the @dfn{standard input} in Unix and C terminology.
@end deffn

\fcurrent-output-port
@c snarfed from ports.c:351
@deffn primitive current-output-port
Return the current output port.  This is the default port used
by many output procedures.  Initially,
@code{current-output-port} returns the @dfn{standard output} in
Unix and C terminology.
@end deffn

\fcurrent-error-port
@c snarfed from ports.c:361
@deffn primitive current-error-port
Return the port to which errors and warnings should be sent (the
@dfn{standard error} in Unix and C terminology).
@end deffn

\fcurrent-load-port
@c snarfed from ports.c:371
@deffn primitive current-load-port
Return the current-load-port.
The load port is used internally by @code{primitive-load}.
@end deffn

\fset-current-input-port
@c snarfed from ports.c:384
@deffn primitive set-current-input-port 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.
@end deffn

\fset-current-output-port
@c snarfed from ports.c:397
@deffn primitive set-current-output-port port
Set the current default output port to @var{port}.
@end deffn

\fset-current-error-port
@c snarfed from ports.c:411
@deffn primitive set-current-error-port port
Set the current default error port to @var{port}.
@end deffn

\fport-revealed
@c snarfed from ports.c:556
@deffn primitive port-revealed port
Returns the revealed count for @var{port}.
@end deffn

\fset-port-revealed!
@c snarfed from ports.c:569
@deffn primitive set-port-revealed! port rcount
Sets the revealed count for a port to a given value.
The return value is unspecified.
@end deffn

\fport-mode
@c snarfed from ports.c:612
@deffn primitive port-mode 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.
@end deffn

\fclose-port
@c snarfed from ports.c:649
@deffn primitive close-port 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.
@end deffn

\fclose-input-port
@c snarfed from ports.c:677
@deffn primitive close-input-port port
Close the specified input port object.  The routine has no effect if
the file has already been closed.  An exception may be raised if an
error occurs.  The value returned is unspecified.

See also @ref{Ports and File Descriptors, close}, for a procedure
which can close file descriptors.
@end deffn

\fclose-output-port
@c snarfed from ports.c:692
@deffn primitive close-output-port port
Close the specified output port object.  The routine has no effect if
the file has already been closed.  An exception may be raised if an
error occurs.  The value returned is unspecified.

See also @ref{Ports and File Descriptors, close}, for a procedure
which can close file descriptors.
@end deffn

\fport-for-each
@c snarfed from ports.c:709
@deffn primitive port-for-each proc
Apply @var{proc} to each port in the Guile port table
in turn.  The return value is unspecified.  More specifically,
@var{proc} is applied exactly once to every port that exists
in the system at the time @var{port-for-each} is invoked.
Changes to the port table while @var{port-for-each} is running
have no effect as far as @var{port-for-each} is concerned.
@end deffn

\fclose-all-ports-except
@c snarfed from ports.c:752
@deffn primitive close-all-ports-except . ports
[DEPRECATED] Close all open file ports used by the interpreter
except for those supplied as arguments.  This procedure
was intended to be used before an exec call to close file descriptors
which are not needed in the new process.  However it has the
undesirable side-effect of flushing buffes, so it's deprecated.
Use port-for-each instead.
@end deffn

\finput-port?
@c snarfed from ports.c:791
@deffn primitive input-port? x
Returns @code{#t} if @var{x} is an input port, otherwise returns
@code{#f}.  Any object satisfying this predicate also satisfies
@code{port?}.
@end deffn

\foutput-port?
@c snarfed from ports.c:804
@deffn primitive output-port? x
Returns @code{#t} if @var{x} is an output port, otherwise returns
@code{#f}.  Any object satisfying this predicate also satisfies
@code{port?}.
@end deffn

\fport?
@c snarfed from ports.c:819
@deffn primitive port? x
Returns a boolean indicating whether @var{x} is a port.
Equivalent to @code{(or (input-port? @var{x}) (output-port?
@var{x}))}.
@end deffn

\fport-closed?
@c snarfed from ports.c:828
@deffn primitive port-closed? port
Returns @code{#t} if @var{port} is closed or @code{#f} if it is open.
@end deffn

\feof-object?
@c snarfed from ports.c:839
@deffn primitive eof-object? x
Returns @code{#t} if @var{x} is an end-of-file object; otherwise
returns @code{#f}.
@end deffn

\fforce-output
@c snarfed from ports.c:853
@deffn primitive force-output [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.
@end deffn

\fflush-all-ports
@c snarfed from ports.c:871
@deffn primitive flush-all-ports
Equivalent to calling @code{force-output} on
all open output ports.  The return value is unspecified.
@end deffn

\fread-char
@c snarfed from ports.c:889
@deffn primitive read-char [port]
Returns the next character available from @var{port}, updating
@var{port} to point to the following character.  If no more
characters are available, an end-of-file object is returned.
@end deffn

\fpeek-char
@c snarfed from ports.c:1205
@deffn primitive peek-char [port]
Returns the next character available from @var{port},
@emph{without} updating @var{port} to point to the following
character.  If no more characters are available, an end-of-file object
is returned.@footnote{The value returned by a call to @code{peek-char}
is the same as the value that would have been returned by a call to
@code{read-char} on the same port.  The only difference is that the very
next call to @code{read-char} or @code{peek-char} on that
@var{port} will return the value returned by the preceding call to
@code{peek-char}.  In particular, a call to @code{peek-char} on an
interactive port will hang waiting for input whenever a call to
@code{read-char} would have hung.}
@end deffn

\funread-char
@c snarfed from ports.c:1226
@deffn primitive unread-char cobj [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.
@end deffn

\funread-string
@c snarfed from ports.c:1249
@deffn primitive unread-string str 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.
@end deffn

\fseek
@c snarfed from ports.c:1285
@deffn primitive seek object offset 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
@end deffn

\ftruncate-file
@c snarfed from ports.c:1326
@deffn primitive truncate-file object [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.
@end deffn

\fport-line
@c snarfed from ports.c:1380
@deffn primitive port-line port
Return the current line number for @var{port}.
@end deffn

\fset-port-line!
@c snarfed from ports.c:1391
@deffn primitive set-port-line! port line
Set the current line number for @var{port} to @var{line}.
@end deffn

\fport-column
@c snarfed from ports.c:1412
@deffn primitive port-column port
@deffnx primitive port-line port
Return the current column number or line number of @var{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 recommend 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.)
@end deffn

\fset-port-column!
@c snarfed from ports.c:1425
@deffn primitive set-port-column! port column
@deffnx primitive set-port-line! port line
Set the current column or line number of @var{port}, using the
current input port if none is specified.
@end deffn

\fport-filename
@c snarfed from ports.c:1440
@deffn primitive port-filename 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.
@end deffn

\fset-port-filename!
@c snarfed from ports.c:1454
@deffn primitive set-port-filename! port 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.
@end deffn

\f%make-void-port
@c snarfed from ports.c:1546
@deffn primitive %make-void-port mode
Create and return a new void port.  A void port acts like
/dev/null.  The @var{mode} argument
specifies the input/output modes for this port: see the
documentation for @code{open-file} in @ref{File Ports}.
@end deffn

\fpipe
@c snarfed from posix.c:201
@deffn primitive pipe
Returns a newly created pipe: a pair of ports which are linked
together on the local machine.  The CAR is the input port and
the CDR is the output port.  Data written (and flushed) to the
output port can be read from the input port.
Pipes are commonly used for communication with a newly
forked child process.  The need to flush the output port
can be avoided by making it unbuffered using @code{setvbuf}.

Writes occur atomically provided the size of the data in
bytes is not greater than the value of @code{PIPE_BUF}
Note that the output port is likely to block if too much data
(typically equal to @code{PIPE_BUF}) has been written but not
yet read from the input port
@end deffn

\fgetgroups
@c snarfed from posix.c:221
@deffn primitive getgroups
Returns a vector of integers representing the current supplimentary group IDs.
@end deffn

\fgetpw
@c snarfed from posix.c:254
@deffn primitive getpw [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.
@end deffn

\fsetpw
@c snarfed from posix.c:307
@deffn primitive setpw [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.
@end deffn

\fgetgr
@c snarfed from posix.c:326
@deffn primitive getgr [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.
@end deffn

\fsetgr
@c snarfed from posix.c:367
@deffn primitive setgr [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.
@end deffn

\fkill
@c snarfed from posix.c:403
@deffn primitive kill pid 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
@end deffn

\fwaitpid
@c snarfed from posix.c:451
@deffn primitive waitpid pid [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
@end deffn

\fstatus:exit-val
@c snarfed from posix.c:478
@deffn primitive status:exit-val 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}.
@end deffn

\fstatus:term-sig
@c snarfed from posix.c:498
@deffn primitive status:term-sig status
Returns the signal number which terminated the
process, if any, otherwise @code{#f}.
@end deffn

\fstatus:stop-sig
@c snarfed from posix.c:516
@deffn primitive status:stop-sig status
Returns the signal number which stopped the
process, if any, otherwise @code{#f}.
@end deffn

\fgetppid
@c snarfed from posix.c:533
@deffn primitive getppid
Returns an integer representing the process ID of the parent process.
@end deffn

\fgetuid
@c snarfed from posix.c:544
@deffn primitive getuid
Returns an integer representing the current real user ID.
@end deffn

\fgetgid
@c snarfed from posix.c:555
@deffn primitive getgid
Returns an integer representing the current real group ID.
@end deffn

\fgeteuid
@c snarfed from posix.c:569
@deffn primitive geteuid
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.
@end deffn

\fgetegid
@c snarfed from posix.c:587
@deffn primitive getegid
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.
@end deffn

\fsetuid
@c snarfed from posix.c:603
@deffn primitive setuid 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.
@end deffn

\fsetgid
@c snarfed from posix.c:617
@deffn primitive setgid 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.
@end deffn

\fseteuid
@c snarfed from posix.c:633
@deffn primitive seteuid 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.
@end deffn

\fsetegid
@c snarfed from posix.c:657
@deffn primitive setegid 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.
@end deffn

\fgetpgrp
@c snarfed from posix.c:679
@deffn primitive getpgrp
Returns an integer representing the current process group ID.
This is the POSIX definition, not BSD.
@end deffn

\fsetpgid
@c snarfed from posix.c:695
@deffn primitive setpgid pid 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.
@end deffn

\fsetsid
@c snarfed from posix.c:714
@deffn primitive setsid
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.
@end deffn

\fttyname
@c snarfed from posix.c:728
@deffn primitive ttyname port
Returns a string with the name of the serial terminal device underlying
@var{port}.
@end deffn

\fctermid
@c snarfed from posix.c:751
@deffn primitive ctermid
Returns a string containing the file name of the controlling terminal
for the current process.
@end deffn

\ftcgetpgrp
@c snarfed from posix.c:773
@deffn primitive tcgetpgrp 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.
@end deffn

\ftcsetpgrp
@c snarfed from posix.c:797
@deffn primitive tcsetpgrp port 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.
@end deffn

\fexecl
@c snarfed from posix.c:857
@deffn primitive execl filename . 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.
@end deffn

\fexeclp
@c snarfed from posix.c:878
@deffn primitive execlp filename . 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{execvp} system
call, but we call it @code{execlp} because of its Scheme calling interface.
@end deffn

\fexecle
@c snarfed from posix.c:929
@deffn primitive execle filename env . 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.
@end deffn

\fprimitive-fork
@c snarfed from posix.c:953
@deffn primitive primitive-fork
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.
@end deffn

\funame
@c snarfed from posix.c:968
@deffn primitive uname
Returns an object with some information about the computer system the
program is running on.
@end deffn

\fenviron
@c snarfed from posix.c:997
@deffn primitive environ [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.
@end deffn

\ftmpnam
@c snarfed from posix.c:1035
@deffn primitive tmpnam
tmpnam returns a name in the file system that does not match
any existing file.  However there is no guarantee that
another process will not create the file after tmpnam
is called.  Care should be taken if opening the file,
e.g., use the O_EXCL open flag or use @code{mkstemp!} instead.
@end deffn

\fmkstemp!
@c snarfed from posix.c:1058
@deffn primitive mkstemp! tmpl
mkstemp creates a new unique file in the file system and
returns a new buffered port open for reading and writing to
the file.  @var{tmpl} is a string specifying where the
file should be created: it must end with @code{XXXXXX}
and will be changed in place to return the name of the
temporary file.
@end deffn

\futime
@c snarfed from posix.c:1086
@deffn primitive utime pathname [actime [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.
@end deffn

\faccess?
@c snarfed from posix.c:1135
@deffn primitive access? path 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
@end deffn

\fgetpid
@c snarfed from posix.c:1150
@deffn primitive getpid
Returns an integer representing the current process ID.
@end deffn

\fputenv
@c snarfed from posix.c:1167
@deffn primitive putenv 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.
@end deffn

\fsetlocale
@c snarfed from posix.c:1198
@deffn primitive setlocale category [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.
@end deffn

\fmknod
@c snarfed from posix.c:1239
@deffn primitive mknod path type perms 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.
@end deffn

\fnice
@c snarfed from posix.c:1286
@deffn primitive nice 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.
@end deffn

\fsync
@c snarfed from posix.c:1301
@deffn primitive sync
Flush the operating system disk buffers.
The return value is unspecified.
@end deffn

\fcrypt
@c snarfed from posix.c:1314
@deffn primitive crypt key salt
Encrypt @var{key} using @var{salt} as the salt value to the
crypt(3) library call
@end deffn

\fchroot
@c snarfed from posix.c:1337
@deffn primitive chroot path
Change the root directory to that specified in @var{path}.
This directory will be used for path names beginning with
@file{/}.  The root directory is inherited by all children
of the current process.  Only the superuser may change the
root directory.
@end deffn

\fgetlogin
@c snarfed from posix.c:1355
@deffn primitive getlogin
Return a string containing the name of the user logged in on
the controlling terminal of the process, or @code{#f} if this
information cannot be obtained.
@end deffn

\fcuserid
@c snarfed from posix.c:1373
@deffn primitive cuserid
Return a string containing a user name associated with the
effective user id of the process.  Return @code{#f} if this
information cannot be obtained.
@end deffn

\fgetpriority
@c snarfed from posix.c:1398
@deffn primitive getpriority which who
Return the scheduling priority of the process, process group
or user, as indicated by @var{which} and @var{who}. @var{which}
is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP}
or @code{PRIO_USER}, and @var{who} is interpreted relative to
@var{which} (a process identifier for @code{PRIO_PROCESS},
process group identifier for @code{PRIO_PGRP}, and a user
identifier for @code{PRIO_USER}.  A zero value of @var{who}
denotes the current process, process group, or user.  Return
the highest priority (lowest numerical value) of any of the
specified processes.
@end deffn

\fsetpriority
@c snarfed from posix.c:1432
@deffn primitive setpriority which who prio
Set the scheduling priority of the process, process group
or user, as indicated by @var{which} and @var{who}. @var{which}
is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP}
or @code{PRIO_USER}, and @var{who} is interpreted relative to
@var{which} (a process identifier for @code{PRIO_PROCESS},
process group identifier for @code{PRIO_PGRP}, and a user
identifier for @code{PRIO_USER}.  A zero value of @var{who}
denotes the current process, process group, or user.
@var{prio} is a value in the range -20 and 20, the default
priority is 0; lower priorities cause more favorable
scheduling.  Sets the priority of all of the specified
processes.  Only the super-user may lower priorities.
The return value is not specified.
@end deffn

\fgetpass
@c snarfed from posix.c:1457
@deffn primitive getpass prompt
Display @var{prompt} to the standard error output and read
a password from @file{/dev/tty}.  If this file is not
accessible, it reads from standard input.  The password may be
up to 127 characters in length.  Additional characters and the
terminating newline character are discarded.  While reading
the password, echoing and the generation of signals by special
characters is disabled.
@end deffn

\fflock
@c snarfed from posix.c:1496
@deffn primitive flock file operation
Apply or remove an advisory lock on an open file.
@var{operation} specifies the action to be done:
@table @code
@item LOCK_SH
Shared lock.  More than one process may hold a shared lock
for a given file at a given time.
@item LOCK_EX
Exclusive lock.  Only one process may hold an exclusive lock
for a given file at a given time.
@item LOCK_UN
Unlock the file.
@item LOCK_NB
Don't block when locking.  May be specified by bitwise OR'ing
it to one of the other operations.
@end table
The return value is not specified. @var{file} may be an open
file descriptor or an open file descriptior port.
@end deffn

\fsethostname
@c snarfed from posix.c:1522
@deffn primitive sethostname name
Set the host name of the current processor to @var{name}. May
only be used by the superuser.  The return value is not
specified.
@end deffn

\fgethostname
@c snarfed from posix.c:1538
@deffn primitive gethostname
Return the host name of the current processor.
@end deffn

\fprint-options-interface
@c snarfed from print.c:142
@deffn primitive print-options-interface [setting]
Option interface for the print options. Instead of using
this procedure directly, use the procedures
@code{print-enable}, @code{print-disable}, @code{print-set!}
and @code{print-options}.
@end deffn

\fsimple-format
@c snarfed from print.c:980
@deffn primitive simple-format destination message . args
Write @var{message} to @var{destination}, defaulting to
the current output port.
@var{message} can contain @code{~A} (was @code{%s}) and
@code{~S} (was @code{%S}) escapes.  When printed,
the escapes are replaced with corresponding members of
@var{ARGS}:
@code{~A} formats using @code{display} and @code{~S} formats
using @code{write}.
If @var{destination} is @code{#t}, then use the current output
port, if @var{destination} is @code{#f}, then return a string
containing the formatted text. Does not add a trailing newline.
@end deffn

\fnewline
@c snarfed from print.c:1045
@deffn primitive newline [port]
Send a newline to @var{port}.
@end deffn

\fwrite-char
@c snarfed from print.c:1060
@deffn primitive write-char chr [port]
Send character @var{chr} to @var{port}.
@end deffn

\fport-with-print-state
@c snarfed from print.c:1114
@deffn primitive port-with-print-state port pstate
Create a new port which behaves like @var{port}, but with an
included print state @var{pstate}.
@end deffn

\fget-print-state
@c snarfed from print.c:1129
@deffn primitive get-print-state port
Return the print state of the port @var{port}. If @var{port}
has no associated print state, @code{#f} is returned.
@end deffn

\fprocedure-properties
@c snarfed from procprop.c:180
@deffn primitive procedure-properties proc
Return @var{obj}'s property list.
@end deffn

\fset-procedure-properties!
@c snarfed from procprop.c:193
@deffn primitive set-procedure-properties! proc new_val
Set @var{obj}'s property list to @var{alist}.
@end deffn

\fprocedure-property
@c snarfed from procprop.c:206
@deffn primitive procedure-property p k
Return the property of @var{obj} with name @var{key}.
@end deffn

\fset-procedure-property!
@c snarfed from procprop.c:229
@deffn primitive set-procedure-property! p k v
In @var{obj}'s property list, set the property named @var{key} to
@var{value}.
@end deffn

\fprocedure?
@c snarfed from procs.c:196
@deffn primitive procedure? obj
Return @code{#t} if @var{obj} is a procedure.
@end deffn

\fclosure?
@c snarfed from procs.c:223
@deffn primitive closure? obj
Return @code{#t} if @var{obj} is a closure.
@end deffn

\fthunk?
@c snarfed from procs.c:232
@deffn primitive thunk? obj
Return @code{#t} if @var{obj} is a thunk.
@end deffn

\fprocedure-documentation
@c snarfed from procs.c:283
@deffn primitive procedure-documentation 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.
@end deffn

\fprocedure-with-setter?
@c snarfed from procs.c:319
@deffn primitive procedure-with-setter? obj
Return @code{#t} if @var{obj} is a procedure with an
associated setter procedure.
@end deffn

\fmake-procedure-with-setter
@c snarfed from procs.c:329
@deffn primitive make-procedure-with-setter procedure setter
Create a new procedure which behaves like @var{procedure}, but
with the associated setter @var{setter}.
@end deffn

\fprocedure
@c snarfed from procs.c:348
@deffn primitive procedure proc
Return the procedure of @var{proc}, which must be either a
procedure with setter, or an operator struct.
@end deffn

\fprimitive-make-property
@c snarfed from properties.c:66
@deffn primitive primitive-make-property not_found_proc
Create a @dfn{property token} that can be used with
@code{primitive-property-ref} and @code{primitive-property-set!}.
See @code{primitive-property-ref} for the significance of
@var{not_found_proc}.
@end deffn

\fprimitive-property-ref
@c snarfed from properties.c:83
@deffn primitive primitive-property-ref prop obj
Return the property @var{prop} of @var{obj}.  When no value
has yet been associated with @var{prop} and @var{obj}, call
@var{not-found-proc} instead (see @code{primitive-make-property})
and use its return value.  That value is also associated with
@var{obj} via @code{primitive-property-set!}.  When
@var{not-found-proc} is @code{#f}, use @code{#f} as the
default value of @var{prop}.
@end deffn

\fprimitive-property-set!
@c snarfed from properties.c:111
@deffn primitive primitive-property-set! prop obj val
Associate @var{code} with @var{prop} and @var{obj}.
@end deffn

\fprimitive-property-del!
@c snarfed from properties.c:131
@deffn primitive primitive-property-del! prop obj
Remove any value associated with @var{prop} and @var{obj}.
@end deffn

\farray-fill!
@c snarfed from ramap.c:467
@deffn primitive array-fill! ra fill
Stores @var{fill} in every element of @var{array}.  The value returned
is unspecified.
@end deffn

\farray-copy-in-order!
@c snarfed from ramap.c:832
@deffn primitive array-copy-in-order!
scm_array_copy_x
@end deffn

\farray-copy!
@c snarfed from ramap.c:841
@deffn primitive array-copy! src dst
@deffnx primitive array-copy-in-order! src 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.
@end deffn

\farray-map-in-order!
@c snarfed from ramap.c:1515
@deffn primitive array-map-in-order!
scm_array_map_x
@end deffn

\farray-map!
@c snarfed from ramap.c:1526
@deffn primitive array-map! ra0 proc . lra
@deffnx primitive array-map-in-order! ra0 proc . 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.
@end deffn

\farray-for-each
@c snarfed from ramap.c:1673
@deffn primitive array-for-each proc ra0 . lra
@var{proc} is applied to each tuple of elements of @var{array0} @dots{}
in row-major order.  The value returned is unspecified.
@end deffn

\farray-index-map!
@c snarfed from ramap.c:1701
@deffn primitive array-index-map! ra 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
@end deffn

\frandom
@c snarfed from random.c:370
@deffn primitive random n [state]
Return a number in [0,N).
Accepts a positive integer or real n and returns a
number of the same type between zero (inclusive) and
N (exclusive). The values returned have a uniform
distribution.
The optional argument @var{state} must be of the type produced
by @code{seed->random-state}. It defaults to the value of the
variable @var{*random-state*}. This object is used to maintain
the state of the pseudo-random-number generator and is altered
as a side effect of the random operation.
@end deffn

\fcopy-random-state
@c snarfed from random.c:393
@deffn primitive copy-random-state [state]
Return a copy of the random state @var{state}.
@end deffn

\fseed->random-state
@c snarfed from random.c:405
@deffn primitive seed->random-state seed
Return a new random state using @var{seed}.
@end deffn

\frandom:uniform
@c snarfed from random.c:418
@deffn primitive random:uniform [state]
Returns a uniformly distributed inexact real random number in [0,1).
@end deffn

\frandom:normal
@c snarfed from random.c:433
@deffn primitive random:normal [state]
Returns an inexact real in a normal distribution.
The distribution used has mean 0 and standard deviation 1.
For a normal distribution with mean m and standard deviation
d use @code{(+ m (* d (random:normal)))}.
@end deffn

\frandom:solid-sphere!
@c snarfed from random.c:489
@deffn primitive random:solid-sphere! v [state]
Fills vect with inexact real random numbers
the sum of whose squares is less than 1.0.
Thinking of vect as coordinates in space of
dimension n = (vector-length vect), the coordinates
are uniformly distributed within the unit n-shere.
The sum of the squares of the numbers is returned.
@end deffn

\frandom:hollow-sphere!
@c snarfed from random.c:512
@deffn primitive random:hollow-sphere! v [state]
Fills vect with inexact real random numbers
the sum of whose squares is equal to 1.0.
Thinking of vect as coordinates in space of
dimension n = (vector-length vect), the coordinates
are uniformly distributed over the surface of the
unit n-shere.
@end deffn

\frandom:normal-vector!
@c snarfed from random.c:530
@deffn primitive random:normal-vector! v [state]
Fills vect with inexact real random numbers that are
independent and standard normally distributed
(i.e., with mean 0 and variance 1).
@end deffn

\frandom:exp
@c snarfed from random.c:554
@deffn primitive random:exp [state]
Returns an inexact real in an exponential distribution with mean 1.
For an exponential distribution with mean u use (* u (random:exp)).
@end deffn

\f%read-delimited!
@c snarfed from rdelim.c:78
@deffn primitive %read-delimited! delims str gobble [port [start [end]]]
Read characters from @var{port} into @var{str} until one of the
characters in the @var{delims} string is encountered.  If
@var{gobble} is true, discard the delimiter character;
otherwise, leave it in the input stream for the next read.  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{str}
bounded by @var{start} and @var{end} (which default to the
beginning and end of the string, 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 string was filled without encountering
a delimiter, this value is @code{#f}.
@end deffn

\f%read-line
@c snarfed from rdelim.c:223
@deffn primitive %read-line [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>)}.
@end deffn

\fwrite-line
@c snarfed from rdelim.c:277
@deffn primitive write-line obj [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
@end deffn

\fread-options-interface
@c snarfed from read.c:84
@deffn primitive read-options-interface [setting]
Option interface for the read options. Instead of using
this procedure directly, use the procedures @code{read-enable},
@code{read-disable}, @code{read-set!} and @var{read-options}.
@end deffn

\fread
@c snarfed from read.c:104
@deffn primitive read [port]
Read an s-expression from the input port @var{port}, or from
the current input port if @var{port} is not specified.
Any whitespace before the next token is discarded.
@end deffn

\fread-hash-extend
@c snarfed from read.c:746
@deffn primitive read-hash-extend chr proc
Install the procedure @var{proc} for reading expressions
starting with the character sequence @code{#} and @var{chr}.
@var{proc} will be called with two arguments:  the character
@var{chr} and the port to read further data from. The object
returned will be the return value of @code{read}.
@end deffn

\fregexp?
@c snarfed from regex-posix.c:139
@deffn primitive regexp? x
Return @code{#t} if @var{obj} is a compiled regular expression, or
@code{#f} otherwise.
@end deffn

\fmake-regexp
@c snarfed from regex-posix.c:179
@deffn primitive make-regexp pat . 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
@end deffn

\fregexp-exec
@c snarfed from regex-posix.c:226
@deffn primitive regexp-exec rx str [start [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.
@end deffn

\fcall-with-dynamic-root
@c snarfed from root.c:358
@deffn primitive call-with-dynamic-root thunk handler
Evaluate @code{(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} 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.)
@end deffn

\fdynamic-root
@c snarfed from root.c:371
@deffn primitive dynamic-root
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.
@end deffn

\fsigaction
@c snarfed from scmsigs.c:201
@deffn primitive sigaction signum [handler [flags]]
Install or report the signal handler 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 restartable
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.
@end deffn

\frestore-signals
@c snarfed from scmsigs.c:360
@deffn primitive restore-signals
Return all signal handlers to the values they had before any call to
@code{sigaction} was made.  The return value is unspecified.
@end deffn

\falarm
@c snarfed from scmsigs.c:399
@deffn primitive alarm 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.
@end deffn

\fpause
@c snarfed from scmsigs.c:414
@deffn primitive pause
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.
@end deffn

\fsleep
@c snarfed from scmsigs.c:427
@deffn primitive sleep 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.
@end deffn

\fusleep
@c snarfed from scmsigs.c:445
@deffn primitive usleep i
Sleep for I microseconds.  @code{usleep} is not available on
all platforms.
@end deffn

\fraise
@c snarfed from scmsigs.c:475
@deffn primitive raise sig
Sends a specified signal @var{sig} to the current process, where
@var{sig} is as described for the kill procedure.
@end deffn

\fsystem
@c snarfed from simpos.c:76
@deffn primitive system [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.
@end deffn

\fgetenv
@c snarfed from simpos.c:104
@deffn primitive getenv 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.
@end deffn

\fprimitive-exit
@c snarfed from simpos.c:120
@deffn primitive primitive-exit [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.
@end deffn

\fhtons
@c snarfed from socket.c:89
@deffn primitive htons 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.
@end deffn

\fntohs
@c snarfed from socket.c:106
@deffn primitive ntohs 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.
@end deffn

\fhtonl
@c snarfed from socket.c:123
@deffn primitive htonl 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.
@end deffn

\fntohl
@c snarfed from socket.c:135
@deffn primitive ntohl 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.
@end deffn

\fsocket
@c snarfed from socket.c:158
@deffn primitive socket family style 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.
@end deffn

\fsocketpair
@c snarfed from socket.c:180
@deffn primitive socketpair family style 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}.
@end deffn

\fgetsockopt
@c snarfed from socket.c:209
@deffn primitive getsockopt sock level 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.
@end deffn

\fsetsockopt
@c snarfed from socket.c:277
@deffn primitive setsockopt sock level optname 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.
@end deffn

\fshutdown
@c snarfed from socket.c:381
@deffn primitive shutdown sock 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.
@end deffn

\fconnect
@c snarfed from socket.c:474
@deffn primitive connect sock fam address . 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.
@end deffn

\fbind
@c snarfed from socket.c:528
@deffn primitive bind sock fam address . 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.
@end deffn

\flisten
@c snarfed from socket.c:561
@deffn primitive listen sock 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.
@end deffn

\faccept
@c snarfed from socket.c:637
@deffn primitive accept 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.
@end deffn

\fgetsockname
@c snarfed from socket.c:668
@deffn primitive getsockname 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.
@end deffn

\fgetpeername
@c snarfed from socket.c:695
@deffn primitive getpeername 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.
@end deffn

\frecv!
@c snarfed from socket.c:730
@deffn primitive recv! sock buf [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.
@end deffn

\fsend
@c snarfed from socket.c:759
@deffn primitive send sock message [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.
@end deffn

\frecvfrom!
@c snarfed from socket.c:797
@deffn primitive recvfrom! sock str [flags [start [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{str}, is a string into which
the data will be written.  The size of @var{str} 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{str}
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.
@end deffn

\fsendto
@c snarfed from socket.c:848
@deffn primitive sendto sock message fam address . 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.
@end deffn

\frestricted-vector-sort!
@c snarfed from sort.c:425
@deffn primitive restricted-vector-sort! vec less startpos endpos
Sort the vector @var{vec}, using @var{less} for comparing
the vector elements.  @var{startpos} and @var{endpos} delimit
the range of the vector which gets sorted.  The return value
is not specified.
@end deffn

\fsorted?
@c snarfed from sort.c:456
@deffn primitive sorted? items less
Return @code{#t} iff @var{items} is a list or a vector such that
for all 1 <= i <= m, the predicate @var{less} returns true when
applied to all elements i - 1 and i
@end deffn

\fmerge
@c snarfed from sort.c:528
@deffn primitive merge alist blist less
Takes two lists @var{alist} and @var{blist} such that
@code{(sorted? alist less?)} and @code{(sorted? blist less?)} and
returns a new list in which the elements of @var{alist} and
@var{blist} have been stably interleaved so that
@code{(sorted? (merge alist blist less?) less?)}.
Note:  this does _not_ accept vectors.
@end deffn

\fmerge!
@c snarfed from sort.c:641
@deffn primitive merge! alist blist less
Takes two lists @var{alist} and @var{blist} such that
@code{(sorted? alist less?)} and @code{(sorted? blist less?)} and
returns a new list in which the elements of @var{alist} and
@var{blist} have been stably interleaved so that
 @code{(sorted? (merge alist blist less?) less?)}.
This is the destructive variant of @code{merge}
Note:  this does _not_ accept vectors.
@end deffn

\fsort!
@c snarfed from sort.c:717
@deffn primitive sort! items less
Sort the sequence @var{items}, which may be a list or a
vector.  @var{less} is used for comparing the sequence
elements.  The sorting is destructive, that means that the
input sequence is modified to produce the sorted result.
This is not a stable sort.
@end deffn

\fsort
@c snarfed from sort.c:751
@deffn primitive sort items less
Sort the sequence @var{items}, which may be a list or a
vector.  @var{less} is used for comparing the sequence
elements.  This is not a stable sort.
@end deffn

\fstable-sort!
@c snarfed from sort.c:847
@deffn primitive stable-sort! items less
Sort the sequence @var{items}, which may be a list or a
vector. @var{less} is used for comparing the sequence elements.
The sorting is destructive, that means that the input sequence
is modified to produce the sorted result.
This is a stable sort.
@end deffn

\fstable-sort
@c snarfed from sort.c:887
@deffn primitive stable-sort items less
Sort the sequence @var{items}, which may be a list or a
vector. @var{less} is used for comparing the sequence elements.
This is a stable sort.
@end deffn

\fsort-list!
@c snarfed from sort.c:933
@deffn primitive sort-list! items less
Sort the list @var{items}, using @var{less} for comparing the
list elements. The sorting is destructive, that means that the
input list is modified to produce the sorted result.
This is a stable sort.
@end deffn

\fsort-list
@c snarfed from sort.c:947
@deffn primitive sort-list items less
Sort the list @var{items}, using @var{less} for comparing the
list elements. This is a stable sort.
@end deffn

\fsource-properties
@c snarfed from srcprop.c:171
@deffn primitive source-properties obj
Return the source property association list of @var{obj}.
@end deffn

\fset-source-properties!
@c snarfed from srcprop.c:194
@deffn primitive set-source-properties! obj plist
Install the association list @var{plist} as the source property
list for @var{obj}.
@end deffn

\fsource-property
@c snarfed from srcprop.c:214
@deffn primitive source-property obj key
Return the source property specified by @var{key} from
@var{obj}'s source property list.
@end deffn

\fset-source-property!
@c snarfed from srcprop.c:247
@deffn primitive set-source-property! obj key datum
Set the source property of object @var{obj}, which is specified by
@var{key} to @var{datum}.  Normally, the key will be a symbol.
@end deffn

\fstack?
@c snarfed from stacks.c:407
@deffn primitive stack? obj
Return @code{#t} if @var{obj} is a calling stack.
@end deffn

\fmake-stack
@c snarfed from stacks.c:421
@deffn primitive make-stack obj . args
Create a new stack. If @var{obj} is @code{#t}, the current
evaluation stack is used for creating the stack frames,
otherwise the frames are taken from @var{obj} (which must be
either a debug object or a continuation).
@var{args} must be a list if integers and specifies how the
resulting stack will be narrowed.
@end deffn

\fstack-id
@c snarfed from stacks.c:512
@deffn primitive stack-id stack
Return the identifier given to @var{stack} by @code{start-stack}.
@end deffn

\fstack-ref
@c snarfed from stacks.c:548
@deffn primitive stack-ref stack i
Return the @var{i}'th frame from @var{stack}.
@end deffn

\fstack-length
@c snarfed from stacks.c:562
@deffn primitive stack-length stack
Return the length of @var{stack}.
@end deffn

\fframe?
@c snarfed from stacks.c:575
@deffn primitive frame? obj
Return @code{#t} if @var{obj} is a stack frame.
@end deffn

\flast-stack-frame
@c snarfed from stacks.c:586
@deffn primitive last-stack-frame obj
Return a stack which consists of a single frame, which is the
last stack frame for @var{obj}. @var{obj} must be either a
debug object or a continuation.
@end deffn

\fframe-number
@c snarfed from stacks.c:627
@deffn primitive frame-number frame
Return the frame number of @var{frame}.
@end deffn

\fframe-source
@c snarfed from stacks.c:637
@deffn primitive frame-source frame
Return the source of @var{frame}.
@end deffn

\fframe-procedure
@c snarfed from stacks.c:648
@deffn primitive frame-procedure frame
Return the procedure for @var{frame}, or @code{#f} if no
procedure is associated with @var{frame}.
@end deffn

\fframe-arguments
@c snarfed from stacks.c:660
@deffn primitive frame-arguments frame
Return the arguments of @var{frame}.
@end deffn

\fframe-previous
@c snarfed from stacks.c:671
@deffn primitive frame-previous frame
Return the previous frame of @var{frame}, or @code{#f} if
@var{frame} is the first frame in its stack.
@end deffn

\fframe-next
@c snarfed from stacks.c:687
@deffn primitive frame-next frame
Return the next frame of @var{frame}, or @code{#f} if
@var{frame} is the last frame in its stack.
@end deffn

\fframe-real?
@c snarfed from stacks.c:702
@deffn primitive frame-real? frame
Return @code{#t} if @var{frame} is a real frame.
@end deffn

\fframe-procedure?
@c snarfed from stacks.c:712
@deffn primitive frame-procedure? frame
Return @code{#t} if a procedure is associated with @var{frame}.
@end deffn

\fframe-evaluating-args?
@c snarfed from stacks.c:722
@deffn primitive frame-evaluating-args? frame
Return @code{#t} if @var{frame} contains evaluated arguments.
@end deffn

\fframe-overflow?
@c snarfed from stacks.c:732
@deffn primitive frame-overflow? frame
Return @code{#t} if @var{frame} is an overflow frame.
@end deffn

\fget-internal-real-time
@c snarfed from stime.c:141
@deffn primitive get-internal-real-time
Returns the number of time units since the interpreter was started.
@end deffn

\ftimes
@c snarfed from stime.c:183
@deffn primitive times
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
@end deffn

\fget-internal-run-time
@c snarfed from stime.c:214
@deffn primitive get-internal-run-time
Returns the number of time units of processor time used by the interpreter.
Both "system" and "user" time are included but subprocesses are not.
@end deffn

\fcurrent-time
@c snarfed from stime.c:224
@deffn primitive current-time
Returns the number of seconds since 1970-01-01 00:00:00 UTC, excluding
leap seconds.
@end deffn

\fgettimeofday
@c snarfed from stime.c:241
@deffn primitive gettimeofday
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.
@end deffn

\flocaltime
@c snarfed from stime.c:341
@deffn primitive localtime time [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.
@end deffn

\fgmtime
@c snarfed from stime.c:413
@deffn primitive gmtime 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.
@end deffn

\fmktime
@c snarfed from stime.c:475
@deffn primitive mktime sbd_time [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.
@end deffn

\ftzset
@c snarfed from stime.c:548
@deffn primitive tzset
Initialize the timezone from the TZ environment variable
or the system default.  It's not usually necessary to call this procedure
since it's done automatically by other procedures that depend on the
timezone.
@end deffn

\fstrftime
@c snarfed from stime.c:565
@deffn primitive strftime format 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}.)
@end deffn

\fstrptime
@c snarfed from stime.c:663
@deffn primitive strptime format 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.
@end deffn

\fstring?
@c snarfed from strings.c:62
@deffn primitive string? obj
Returns @code{#t} iff @var{obj} is a string, else returns
@code{#f}.
@end deffn

\fread-only-string?
@c snarfed from strings.c:85
@deffn primitive read-only-string? obj
Return true if @var{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
@end deffn

\flist->string
@c snarfed from strings.c:94
@deffn primitive list->string
scm_string
@end deffn

\fstring
@c snarfed from strings.c:100
@deffn primitive string . chrs
@deffnx primitive list->string chrs
Returns a newly allocated string composed of the arguments,
@var{chrs}.
@end deffn

\fmake-string
@c snarfed from strings.c:253
@deffn primitive make-string k [chr]
Return a newly allocated string of
length @var{k}.  If @var{chr} is given, then all elements of
the string are initialized to @var{chr}, otherwise the contents
of the @var{string} are unspecified.
@end deffn

\fstring-length
@c snarfed from strings.c:286
@deffn primitive string-length string
Return the number of characters in @var{string}.
@end deffn

\fstring-ref
@c snarfed from strings.c:297
@deffn primitive string-ref str k
Return character @var{k} of @var{str} using zero-origin
indexing. @var{k} must be a valid index of @var{str}.
@end deffn

\fstring-set!
@c snarfed from strings.c:314
@deffn primitive string-set! str k chr
Store @var{chr} in element @var{k} of @var{str} and return
an unspecified value. @var{k} must be a valid index of
@var{str}.
@end deffn

\fsubstring
@c snarfed from strings.c:337
@deffn primitive substring str start [end]
Return a newly allocated string formed from the characters
of @var{str} beginning with index @var{start} (inclusive) and
ending with index @var{end} (exclusive).
@var{str} must be a string, @var{start} and @var{end} must be
exact integers satisfying:

0 <= @var{start} <= @var{end} <= (string-length @var{str}).
@end deffn

\fstring-append
@c snarfed from strings.c:360
@deffn primitive string-append . args
Return a newly allocated string whose characters form the
concatenation of the given strings, @var{args}.
@end deffn

\fmake-shared-substring
@c snarfed from strings.c:400
@deffn primitive make-shared-substring str [frm [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}.
@end deffn

\fstring-index
@c snarfed from strop.c:121
@deffn primitive string-index str chr [frm [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.

(qdocs:) Returns
the index of @var{char} in @var{str}, or @code{#f} if the
@var{char} isn't in @var{str}. If @var{frm} is given and not
@code{#f}, it is used as the starting index; if @var{to} is
given and not @code{#f}, it is used as the ending index
(exclusive).

@example
(string-index "weiner" #\e)
@result{} 1

(string-index "weiner" #\e 2)
@result{} 4

(string-index "weiner" #\e 2 4)
@result{} #f
@end example
@end deffn

\fstring-rindex
@c snarfed from strop.c:152
@deffn primitive string-rindex str chr [frm [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.

(qdocs:) The same as @code{string-index}, except it gives the rightmost occurance
of @var{char} in the range [@var{frm}, @var{to}-1], which defaults to
the entire string.

@example
(string-rindex "weiner" #\e)
@result{} 4

(string-rindex "weiner" #\e 2 4)
@result{} #f

(string-rindex "weiner" #\e 2 5)
@result{} 4
@end example
@end deffn

\fsubstring-move-left!
@c snarfed from strop.c:169
@deffn primitive substring-move-left!
scm_substring_move_x
@end deffn

\fsubstring-move-right!
@c snarfed from strop.c:170
@deffn primitive substring-move-right!
scm_substring_move_x
@end deffn

\fsubstring-move!
@c snarfed from strop.c:244
@deffn primitive substring-move! str1 start1 end1 str2 start2
@deffnx primitive substring-move-left! str1 start1 end1 str2 start2
@deffnx primitive substring-move-right! str1 start1 end1 str2 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.
@end deffn

\fsubstring-fill!
@c snarfed from strop.c:280
@deffn primitive substring-fill! str start end fill
Change every character in @var{str} between @var{start} and @var{end} to
@var{fill-char}.

(qdocs:) Destructively fills @var{str}, from @var{start} to @var{end}, with @var{fill}.

@example
(define y "abcdefg")
(substring-fill! y 1 3 #\r)
y
@result{} "arrdefg"
@end example
@end deffn

\fstring-null?
@c snarfed from strop.c:307
@deffn primitive string-null? str
Return @code{#t} if @var{str}'s length is nonzero, and @code{#f}
otherwise.

(qdocs:) Returns @code{#t} if @var{str} is empty, else returns @code{#f}.

@example
(string-null? "")
@result{} #t

(string-null? y)
@result{} #f
@end example
@end deffn

\fstring->list
@c snarfed from strop.c:323
@deffn primitive string->list str
@samp{String->list} returns a newly allocated list of the
characters that make up the given string.  @samp{List->string}
returns a newly allocated string formed from the characters in the list
@var{list}, which must be a list of characters. @samp{String->list}
and @samp{list->string} are
inverses so far as @samp{equal?} is concerned.  (r5rs)
@end deffn

\fstring-copy
@c snarfed from strop.c:348
@deffn primitive string-copy str
Returns a newly allocated copy of the given @var{string}. (r5rs)
@end deffn

\fstring-fill!
@c snarfed from strop.c:361
@deffn primitive string-fill! str chr
Stores @var{char} in every element of the given @var{string} and returns an
unspecified value.  (r5rs)
@end deffn

\fstring-upcase!
@c snarfed from strop.c:397
@deffn primitive string-upcase! str
Destructively upcase every character in @code{str}.

(qdocs:) Converts each element in @var{str} to upper case.

@example
(string-upcase! y)
@result{} "ARRDEFG"

y
@result{} "ARRDEFG"
@end example
@end deffn

\fstring-upcase
@c snarfed from strop.c:409
@deffn primitive string-upcase str
Upcase every character in @code{str}.
@end deffn

\fstring-downcase!
@c snarfed from strop.c:444
@deffn primitive string-downcase! str
Destructively downcase every character in @code{str}.

(qdocs:) Converts each element in @var{str} to lower case.

@example
y
@result{} "ARRDEFG"

(string-downcase! y)
@result{} "arrdefg"

y
@result{} "arrdefg"
@end example
@end deffn

\fstring-downcase
@c snarfed from strop.c:456
@deffn primitive string-downcase str
Downcase every character in @code{str}.
@end deffn

\fstring-capitalize!
@c snarfed from strop.c:493
@deffn primitive string-capitalize! str
Destructively capitalize every character in @code{str}.
@end deffn

\fstring-capitalize
@c snarfed from strop.c:505
@deffn primitive string-capitalize str
Capitalize every character in @code{str}.
@end deffn

\fstring-ci->symbol
@c snarfed from strop.c:517
@deffn primitive string-ci->symbol str
Return the symbol whose name is @var{str}, downcased in necessary(???).
@end deffn

\fstring=?
@c snarfed from strorder.c:64
@deffn primitive string=? s1 s2
Lexicographic equality predicate;
Returns @code{#t} if the two strings are the same length and
contain the same characters in the same positions, otherwise
returns @code{#f}. (r5rs)

The procedure @code{string-ci=?} treats upper and lower case
letters as though they were the same character, but
@code{string=?} treats upper and lower case as distinct
characters.
@end deffn

\fstring-ci=?
@c snarfed from strorder.c:99
@deffn primitive string-ci=? s1 s2
Case-insensitive string equality predicate; returns @code{#t}
if the two strings are the same length and their component
characters match (ignoring case) at each position; otherwise
returns @code{#f}. (r5rs)
@end deffn

\fstring<?
@c snarfed from strorder.c:156
@deffn primitive string<? s1 s2
Lexicographic ordering predicate; returns @code{#t} if
@var{s1} is lexicographically less than @var{s2}.  (r5rs)
@end deffn

\fstring<=?
@c snarfed from strorder.c:171
@deffn primitive string<=? s1 s2
Lexicographic ordering predicate; returns @code{#t} if
@var{s1} is lexicographically less than or equal to @var{s2}.
(r5rs)
@end deffn

\fstring>?
@c snarfed from strorder.c:185
@deffn primitive string>? s1 s2
Lexicographic ordering predicate; returns @code{#t} if
@var{s1} is lexicographically greater than @var{s2}.  (r5rs)
@end deffn

\fstring>=?
@c snarfed from strorder.c:200
@deffn primitive string>=? s1 s2
Lexicographic ordering predicate; returns @code{#t} if
@var{s1} is lexicographically greater than or equal to
@var{s2}.  (r5rs)
@end deffn

\fstring-ci<?
@c snarfed from strorder.c:239
@deffn primitive string-ci<? s1 s2
Case insensitive lexicographic ordering predicate;
returns @code{#t} if @var{s1} is lexicographically less than
@var{s2} regardless of case.  (r5rs)
@end deffn

\fstring-ci<=?
@c snarfed from strorder.c:254
@deffn primitive string-ci<=? s1 s2
Case insensitive lexicographic ordering predicate;
returns @code{#t} if @var{s1} is lexicographically less than
or equal to @var{s2} regardless of case.  (r5rs)
@end deffn

\fstring-ci>?
@c snarfed from strorder.c:269
@deffn primitive string-ci>? s1 s2
Case insensitive lexicographic ordering predicate;
returns @code{#t} if @var{s1} is lexicographically greater
than @var{s2} regardless of case.  (r5rs)
@end deffn

\fstring-ci>=?
@c snarfed from strorder.c:284
@deffn primitive string-ci>=? s1 s2
Case insensitive lexicographic ordering predicate;
returns @code{#t} if @var{s1} is lexicographically greater
than or equal to @var{s2} regardless of case.  (r5rs)
@end deffn

\fobject->string
@c snarfed from strports.c:318
@deffn primitive object->string obj [printer]
Return a Scheme string obtained by printing @var{obj}.
Printing function can be specified by the optional second
argument @var{printer} (default: @code{write}).
@end deffn

\fcall-with-output-string
@c snarfed from strports.c:352
@deffn primitive call-with-output-string 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.
@end deffn

\fcall-with-input-string
@c snarfed from strports.c:371
@deffn primitive call-with-input-string str 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.
@end deffn

\fopen-input-string
@c snarfed from strports.c:384
@deffn primitive open-input-string str
Takes a string and returns an input port that delivers
characters from the string. The port can be closed by
@code{close-input-port}, though its storage will be reclaimed
by the garbage collector if it becomes inaccessible.
@end deffn

\fopen-output-string
@c snarfed from strports.c:398
@deffn primitive open-output-string
Returns an output port that will accumulate characters for
retrieval by @code{get-output-string}. The port can be closed
by the procedure @code{close-output-port}, though its storage
will be reclaimed by the garbage collector if it becomes
inaccessible.
@end deffn

\fget-output-string
@c snarfed from strports.c:415
@deffn primitive get-output-string port
Given an output port created by @code{open-output-string},
returns a string consisting of the characters that have been
output to the port so far.
@end deffn

\feval-string
@c snarfed from strports.c:456
@deffn primitive eval-string string
Evaluate @var{string} as the text representation of a Scheme
form or forms, and return whatever value they produce.
Evaluation takes place in the environment returned by the
procedure @code{interaction-environment}.
@end deffn

\fmake-struct-layout
@c snarfed from struct.c:79
@deffn primitive make-struct-layout fields
Return a new structure layout object.

@var{fields} must be a 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
a field that points 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.
@end deffn

\fstruct?
@c snarfed from struct.c:246
@deffn primitive struct? x
Return @code{#t} iff @var{obj} is a structure object, else
@code{#f}.
@end deffn

\fstruct-vtable?
@c snarfed from struct.c:255
@deffn primitive struct-vtable? x
Return @code{#t} iff obj is a vtable structure.
@end deffn

\fmake-struct
@c snarfed from struct.c:437
@deffn primitive make-struct vtable tail_array_size . init
Create a new structure.

@var{type} must be a vtable structure (@pxref{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{init1}, @dots{} are optional arguments describing how
successive fields of the structure should be initialized.  Only fields
with protection 'r' or 'w' can be initialized, except for fields of
type 's', which are automatically initialized to point to the new
structure itself; fields with protection 'o' can not be initialized by
Scheme programs.

If fewer optional arguments than initializable fields are supplied,
fields of type 'p' get default value #f while fields of type 'u' are
initialized to 0.

Structs are currently the basic representation for record-like data
structures in Guile.  The plan is to eventually replace them with a
new representation which will at the same time be easier to use and
more powerful.

For more information, see the documentation for @code{make-vtable-vtable}.
@end deffn

\fmake-vtable-vtable
@c snarfed from struct.c:523
@deffn primitive make-vtable-vtable user_fields tail_array_size . init
Return a new, self-describing vtable structure.

@var{user-fields} is a string describing user defined fields of the
vtable beginning at index @code{vtable-offset-user}
(see @code{make-struct-layout}).

@var{tail-size} specifies the size of the tail-array (if any) of
this vtable.

@var{init1}, @dots{} are the optional initializers for the fields of
the vtable.

Vtables have one initializable system field---the struct printer.
This field comes before the user fields in the initializers passed
to @code{make-vtable-vtable} and @code{make-struct}, and thus works as
a third optional argument to @code{make-vtable-vtable} and a fourth to
@code{make-struct} when creating vtables:

If the value is a procedure, it will be called instead of the standard
printer whenever a struct described by this vtable is printed.
The procedure will be called with arguments STRUCT and PORT.

The structure of a struct is described by a vtable, so the vtable is
in essence the type of the struct.  The vtable is itself a struct with
a vtable.  This could go on forever if it weren't for the
vtable-vtables which are self-describing vtables, and thus terminate
the chain.

There are several potential ways of using structs, but the standard
one is to use three kinds of structs, together building up a type
sub-system: one vtable-vtable working as the root and one or several
"types", each with a set of "instances".  (The vtable-vtable should be
compared to the class <class> which is the class of itself.)

@example
(define ball-root (make-vtable-vtable "pr" 0))

(define (make-ball-type ball-color)
  (make-struct ball-root 0
               (make-struct-layout "pw")
               (lambda (ball port)
                 (format port "#<a ~A ball owned by ~A>"
                         (color ball)
                         (owner ball)))
               ball-color))
(define (color ball) (struct-ref (struct-vtable ball) vtable-offset-user))
(define (owner ball) (struct-ref ball 0))

(define red (make-ball-type 'red))
(define green (make-ball-type 'green))

(define (make-ball type owner) (make-struct type 0 owner))

(define ball (make-ball green 'Nisse))
ball @result{} #<a green ball owned by Nisse>
@end example
@end deffn

\fstruct-ref
@c snarfed from struct.c:565
@deffn primitive struct-ref handle 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.
@end deffn

\fstruct-set!
@c snarfed from struct.c:643
@deffn primitive struct-set! handle pos val
Set the slot of the structure @var{handle} with index @var{pos}
to @var{val}.  Signal an error if the slot can not be written
to.
@end deffn

\fstruct-vtable
@c snarfed from struct.c:713
@deffn primitive struct-vtable handle
Return the vtable structure that describes the type of @var{struct}.
@end deffn

\fstruct-vtable-tag
@c snarfed from struct.c:724
@deffn primitive struct-vtable-tag handle
Return the vtable tag of the structure @var{handle}.
@end deffn

\fstruct-vtable-name
@c snarfed from struct.c:763
@deffn primitive struct-vtable-name vtable
Return the name of the vtable @var{vtable}.
@end deffn

\fset-struct-vtable-name!
@c snarfed from struct.c:773
@deffn primitive set-struct-vtable-name! vtable name
Set the name of the vtable @var{vtable} to @var{name}.
@end deffn

\fsymbol?
@c snarfed from symbols.c:422
@deffn primitive symbol? obj
Returns @code{#t} if @var{obj} is a symbol, otherwise returns
@code{#f}. (r5rs)
@end deffn

\fsymbol->string
@c snarfed from symbols.c:451
@deffn primitive symbol->string s
Returns the name of @var{symbol} as a string.  If the symbol
was part of an object returned as the value of a literal
expression (section @pxref{Literal expressions,,,r4rs, The
Revised^4 Report on Scheme}) or by a call to the @code{read}
procedure, and its name contains alphabetic characters, then
the string returned will contain characters in the
implementation's preferred standard case---some implementations
will prefer upper case, others lower case.  If the symbol was
returned by @code{string->symbol}, the case of characters in
the string returned will be the same as the case in the string
that was passed to @code{string->symbol}.  It is an error to
apply mutation procedures like @code{string-set!} to strings
returned by this procedure. (r5rs)

The following examples assume that the implementation's
standard case is lower case:

@lisp
(symbol->string 'flying-fish) @result{} "flying-fish"
(symbol->string 'Martin)      @result{}  "martin"
(symbol->string
   (string->symbol "Malvina")) @result{} "Malvina"
@end lisp
@end deffn

\fstring->symbol
@c snarfed from symbols.c:478
@deffn primitive string->symbol s
Returns the symbol whose name is @var{string}. This procedure
can create symbols with names containing special characters or
letters in the non-standard case, but it is usually a bad idea
to create such because in some implementations of Scheme they
cannot be read as themselves.  See @code{symbol->string}.

The following examples assume that the implementation's
standard case is lower case:

@lisp
(eq? 'mISSISSIppi 'mississippi) @result{} #t
(string->symbol "mISSISSIppi") @result{} @r{the symbol with name "mISSISSIppi"}
(eq? 'bitBlt (string->symbol "bitBlt")) @result{} #f
(eq? 'JollyWog
  (string->symbol (symbol->string 'JollyWog))) @result{} #t
(string=? "K. Harper, M.D."
  (symbol->string
    (string->symbol "K. Harper, M.D."))) @result{}#t
@end lisp
@end deffn

\fstring->obarray-symbol
@c snarfed from symbols.c:499
@deffn primitive string->obarray-symbol o s [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}.
@end deffn

\fintern-symbol
@c snarfed from symbols.c:531
@deffn primitive intern-symbol o 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.
@end deffn

\funintern-symbol
@c snarfed from symbols.c:568
@deffn primitive unintern-symbol o 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.
@end deffn

\fsymbol-binding
@c snarfed from symbols.c:609
@deffn primitive symbol-binding o 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.
@end deffn

\fsymbol-interned?
@c snarfed from symbols.c:626
@deffn primitive symbol-interned? o s
Return @code{#t} if @var{obarray} contains a symbol with name
@var{string}, and @code{#f} otherwise.
@end deffn

\fsymbol-bound?
@c snarfed from symbols.c:649
@deffn primitive symbol-bound? o s
Return @code{#t} if @var{obarray} contains a symbol with name
@var{string} bound to a defined value.  This differs from
@var{symbol-interned?} 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.
@end deffn

\fsymbol-set!
@c snarfed from symbols.c:667
@deffn primitive symbol-set! o s 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}.
@end deffn

\fsymbol-fref
@c snarfed from symbols.c:684
@deffn primitive symbol-fref s
Return the contents of @var{symbol}'s @dfn{function slot}.
@end deffn

\fsymbol-pref
@c snarfed from symbols.c:695
@deffn primitive symbol-pref s
Return the @dfn{property list} currently associated with @var{symbol}.
@end deffn

\fsymbol-fset!
@c snarfed from symbols.c:706
@deffn primitive symbol-fset! s val
Change the binding of @var{symbol}'s function slot.
@end deffn

\fsymbol-pset!
@c snarfed from symbols.c:718
@deffn primitive symbol-pset! s val
Change the binding of @var{symbol}'s property slot.
@end deffn

\fsymbol-hash
@c snarfed from symbols.c:732
@deffn primitive symbol-hash symbol
Return a hash value for @var{symbol}.
@end deffn

\fbuiltin-bindings
@c snarfed from symbols.c:769
@deffn primitive builtin-bindings
Create and return a copy of the global symbol table, removing all
unbound symbols.
@end deffn

\fgensym
@c snarfed from symbols.c:790
@deffn primitive gensym [prefix]
Create a new symbol with a name constructed from a prefix and
a counter value. The string @var{prefix} can be specified as
an optional argument. Default prefix is @code{g}.  The counter
is increased by 1 at each call. There is no provision for
resetting the counter.
@end deffn

\fgentemp
@c snarfed from symbols.c:829
@deffn primitive gentemp [prefix [obarray]]
Create a new symbol with a name unique in an obarray.
The name is constructed from an optional string @var{prefix}
and a counter value.  The default prefix is @code{t}.  The
@var{obarray} is specified as a second optional argument.
Default is the system obarray where all normal symbols are
interned.  The counter is increased by 1 at each
call.  There is no provision for resetting the counter.
@end deffn

\ftag
@c snarfed from tag.c:98
@deffn primitive tag x
Return an integer corresponding to the type of X.  Deprecated.
@end deffn

\fcatch
@c snarfed from throw.c:529
@deffn primitive catch tag thunk 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}.
@end deffn

\flazy-catch
@c snarfed from throw.c:556
@deffn primitive lazy-catch tag thunk handler
This behaves exactly like @code{catch}, except that it does
not unwind the stack (this is the major difference), and if
handler returns, its value is returned from the throw.
@end deffn

\fthrow
@c snarfed from throw.c:589
@deffn primitive throw key . 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.
@end deffn

\funiform-vector-length
@c snarfed from unif.c:255
@deffn primitive uniform-vector-length v
Returns the number of elements in @var{uve}.
@end deffn

\farray?
@c snarfed from unif.c:289
@deffn primitive array? v [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.
@end deffn

\farray-rank
@c snarfed from unif.c:360
@deffn primitive array-rank ra
Returns the number of dimensions of @var{obj}.  If @var{obj} is not an
array, @code{0} is returned.
@end deffn

\farray-dimensions
@c snarfed from unif.c:398
@deffn primitive array-dimensions 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
@end deffn

\fshared-array-root
@c snarfed from unif.c:445
@deffn primitive shared-array-root ra
Return the root vector of a shared array.
@end deffn

\fshared-array-offset
@c snarfed from unif.c:456
@deffn primitive shared-array-offset ra
Return the root vector index of the first element in the array.
@end deffn

\fshared-array-increments
@c snarfed from unif.c:467
@deffn primitive shared-array-increments ra
For each dimension, return the distance between elements in the root vector.
@end deffn

\fdimensions->uniform-array
@c snarfed from unif.c:586
@deffn primitive dimensions->uniform-array dims prot [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.
@end deffn

\fmake-shared-array
@c snarfed from unif.c:672
@deffn primitive make-shared-array oldra mapfunc . 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
@end deffn

\ftranspose-array
@c snarfed from unif.c:802
@deffn primitive transpose-array ra . 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
@end deffn

\fenclose-array
@c snarfed from unif.c:911
@deffn primitive enclose-array ra . 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
@end deffn

\farray-in-bounds?
@c snarfed from unif.c:994
@deffn primitive array-in-bounds? v . args
Returns @code{#t} if its arguments would be acceptable to array-ref.
@end deffn

\farray-ref
@c snarfed from unif.c:1073
@deffn primitive array-ref
scm_uniform_vector_ref
@end deffn

\funiform-vector-ref
@c snarfed from unif.c:1079
@deffn primitive uniform-vector-ref v args
@deffnx primitive array-ref v . args
Returns the element at the @code{(index1, index2)} element in @var{array}.
@end deffn

\funiform-array-set1!
@c snarfed from unif.c:1248
@deffn primitive uniform-array-set1!
scm_array_set_x
@end deffn

\farray-set!
@c snarfed from unif.c:1257
@deffn primitive array-set! v obj . args
@deffnx primitive uniform-array-set1! v obj 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.
@end deffn

\farray-contents
@c snarfed from unif.c:1372
@deffn primitive array-contents ra [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.
@end deffn

\funiform-array-read!
@c snarfed from unif.c:1486
@deffn primitive uniform-array-read! ra [port_or_fd [start [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)}.
@end deffn

\funiform-array-write
@c snarfed from unif.c:1649
@deffn primitive uniform-array-write v [port_or_fd [start [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)}.
@end deffn

\fbit-count
@c snarfed from unif.c:1774
@deffn primitive bit-count b bitvector
Returns the number of occurrences of the boolean @var{b} in
@var{bitvector}.
@end deffn

\fbit-position
@c snarfed from unif.c:1813
@deffn primitive bit-position item v 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.
@end deffn

\fbit-set*!
@c snarfed from unif.c:1881
@deffn primitive bit-set*! v kv 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.
@end deffn

\fbit-count*
@c snarfed from unif.c:1935
@deffn primitive bit-count* v kv obj
Returns
@example
(bit-count (bit-set*! (if bool bv (bit-invert! bv)) uve #t) #t).
@end example
@var{bv} is not modified.
@end deffn

\fbit-invert!
@c snarfed from unif.c:1999
@deffn primitive bit-invert! v
Modifies @var{bv} by replacing each element with its negation.
@end deffn

\farray->list
@c snarfed from unif.c:2077
@deffn primitive array->list v
Returns a list consisting of all the elements, in order, of @var{array}.
@end deffn

\flist->uniform-array
@c snarfed from unif.c:2169
@deffn primitive list->uniform-array ndim prot 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.
@end deffn

\farray-prototype
@c snarfed from unif.c:2520
@deffn primitive array-prototype 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}.
@end deffn

\fvalues
@c snarfed from values.c:83
@deffn primitive values . args
Delivers all of its arguments to its continuation.  Except for
continuations created by the @code{call-with-values} procedure,
all continuations take exactly one value.  The effect of
passing no value or more than one value to continuations that
were not created by @code{call-with-values} is unspecified.
@end deffn

\fcall-with-values
@c snarfed from values.c:116
@deffn primitive call-with-values producer consumer
Calls its @var{producer} argument with no values and a
continuation that, when passed some values, calls the
@var{consumer} procedure with those values as arguments.  The
continuation for the call to @var{consumer} is the continuation
of the call to @code{call-with-values}.

@example
(call-with-values (lambda () (values 4 5))
                  (lambda (a b) b))
                                             ==>  5

@end example
@example
(call-with-values * -)                             ==>  -1
@end example
@end deffn

\fmake-variable
@c snarfed from variable.c:100
@deffn primitive make-variable init [name_hint]
Return a variable object initialized to value @var{init}.
If given, uses @var{name-hint} as its internal (debugging)
name, otherwise just treat it as an anonymous variable.
Remember, of course, that multiple bindings to the same
variable may exist, so @var{name-hint} is just that---a hint.
@end deffn

\fmake-undefined-variable
@c snarfed from variable.c:124
@deffn primitive make-undefined-variable [name_hint]
Return a variable object initialized to an undefined value.
If given, uses @var{name-hint} as its internal (debugging)
name, otherwise just treat it as an anonymous variable.
Remember, of course, that multiple bindings to the same
variable may exist, so @var{name-hint} is just that---a hint.
@end deffn

\fvariable?
@c snarfed from variable.c:145
@deffn primitive variable? obj
Return @code{#t} iff @var{obj} is a variable object, else
return @code{#f}
@end deffn

\fvariable-ref
@c snarfed from variable.c:157
@deffn primitive variable-ref var
Dereference @var{var} and return its value.
@var{var} must be a variable object; see @code{make-variable}
and @code{make-undefined-variable}.
@end deffn

\fvariable-set!
@c snarfed from variable.c:171
@deffn primitive variable-set! var val
Set the value of the variable @var{var} to @var{val}.
@var{var} must be a variable object, @var{val} can be any
value. Return an unspecified value.
@end deffn

\fbuiltin-variable
@c snarfed from variable.c:185
@deffn primitive builtin-variable name
Return the built-in variable with the name @var{name}.
@var{name} must be a symbol (not a string).
Then use @code{variable-ref} to access its value.
@end deffn

\fvariable-bound?
@c snarfed from variable.c:213
@deffn primitive variable-bound? var
Return @code{#t} iff @var{var} is bound to a value.
Throws an error if @var{var} is not a variable object.
@end deffn

\fvector?
@c snarfed from vectors.c:142
@deffn primitive vector? obj
Returns @code{#t} if @var{obj} is a vector, otherwise returns
@code{#f}. (r5rs)
@end deffn

\flist->vector
@c snarfed from vectors.c:161
@deffn primitive list->vector
scm_vector
@end deffn

\fvector
@c snarfed from vectors.c:177
@deffn primitive vector . l
@deffnx primitive list->vector l
Returns a newly allocated vector whose elements contain the
given arguments.  Analogous to @code{list}. (r5rs)

@lisp
(vector 'a 'b 'c) @result{}  #(a b c)
@end lisp
@end deffn

\fmake-vector
@c snarfed from vectors.c:255
@deffn primitive make-vector k [fill]
Returns a newly allocated vector of @var{k} elements.  If a second
argument is given, then each element is initialized to @var{fill}.
Otherwise the initial contents of each element is unspecified. (r5rs)
@end deffn

\fvector->list
@c snarfed from vectors.c:311
@deffn primitive vector->list v
@samp{Vector->list} returns a newly allocated list of the
objects contained in the elements of @var{vector}.  (r5rs)

@lisp
(vector->list '#(dah dah didah)) @result{}  (dah dah didah)
(list->vector '(dididit dah)) @result{}  #(dididit dah)
@end lisp
@end deffn

\fvector-fill!
@c snarfed from vectors.c:328
@deffn primitive vector-fill! v fill_x
Stores @var{fill} in every element of @var{vector}.
The value returned by @code{vector-fill!} is unspecified. (r5rs)
@end deffn

\fvector-move-left!
@c snarfed from vectors.c:355
@deffn primitive vector-move-left! vec1 start1 end1 vec2 start2
Vector version of @code{substring-move-left!}.
@end deffn

\fvector-move-right!
@c snarfed from vectors.c:378
@deffn primitive vector-move-right! vec1 start1 end1 vec2 start2
Vector version of @code{substring-move-right!}.
@end deffn

\fmajor-version
@c snarfed from version.c:59
@deffn primitive major-version
Return a string containing Guile's major version number.
E.g., "1".
@end deffn

\fminor-version
@c snarfed from version.c:71
@deffn primitive minor-version
Return a string containing Guile's minor version number.
E.g., "3.5".
@end deffn

\fversion
@c snarfed from version.c:90
@deffn primitive version
@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
@end deffn

\fmake-soft-port
@c snarfed from vports.c:184
@deffn primitive make-soft-port pv 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 8081e20>
@end example
@end deffn

\fmake-weak-vector
@c snarfed from weaks.c:62
@deffn primitive make-weak-vector k [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.
@end deffn

\flist->weak-vector
@c snarfed from weaks.c:79
@deffn primitive list->weak-vector
scm_weak_vector
@end deffn

\fweak-vector
@c snarfed from weaks.c:87
@deffn primitive weak-vector . 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.
@end deffn

\fweak-vector?
@c snarfed from weaks.c:110
@deffn primitive weak-vector? x
Return @code{#t} if @var{obj} is a weak vector. Note that all
weak hashes are also weak vectors.
@end deffn

\fmake-weak-key-hash-table
@c snarfed from weaks.c:130
@deffn primitive make-weak-key-hash-table 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})
@end deffn

\fmake-weak-value-hash-table
@c snarfed from weaks.c:147
@deffn primitive make-weak-value-hash-table k
Return a hash table with weak values with @var{size} buckets.
(@pxref{Hash Tables})
@end deffn

\fmake-doubly-weak-hash-table
@c snarfed from weaks.c:165
@deffn primitive make-doubly-weak-hash-table k
Return a hash table with weak keys and values with @var{size}
buckets.  (@pxref{Hash Tables})
@end deffn

\fweak-key-hash-table?
@c snarfed from weaks.c:184
@deffn primitive weak-key-hash-table? x
@deffnx primitive weak-value-hash-table? obj
@deffnx primitive doubly-weak-hash-table? obj
Return @code{#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.
@end deffn

\fweak-value-hash-table?
@c snarfed from weaks.c:194
@deffn primitive weak-value-hash-table? x
Return @code{#t} if @var{x} is a weak value hash table.
@end deffn

\fdoubly-weak-hash-table?
@c snarfed from weaks.c:204
@deffn primitive doubly-weak-hash-table? x
Return @code{#t} if @var{x} is a doubly weak hash table.
@end deffn