3 @c snarfed from alist.c:36
4 @deffn {Scheme Procedure} acons key value alist
5 @deffnx {C Function} scm_acons (key, value, alist)
6 Add a new key-value pair to @var{alist}. A new pair is
7 created whose car is @var{key} and whose cdr is @var{value}, and the
8 pair is consed onto @var{alist}, and the new list is returned. This
9 function is @emph{not} destructive; @var{alist} is not modified.
13 @c snarfed from alist.c:50
14 @deffn {Scheme Procedure} sloppy-assq key alist
15 @deffnx {C Function} scm_sloppy_assq (key, alist)
16 Behaves like @code{assq} but does not do any error checking.
17 Recommended only for use in Guile internals.
21 @c snarfed from alist.c:68
22 @deffn {Scheme Procedure} sloppy-assv key alist
23 @deffnx {C Function} scm_sloppy_assv (key, alist)
24 Behaves like @code{assv} but does not do any error checking.
25 Recommended only for use in Guile internals.
29 @c snarfed from alist.c:86
30 @deffn {Scheme Procedure} sloppy-assoc key alist
31 @deffnx {C Function} scm_sloppy_assoc (key, alist)
32 Behaves like @code{assoc} but does not do any error checking.
33 Recommended only for use in Guile internals.
37 @c snarfed from alist.c:113
38 @deffn {Scheme Procedure} assq key alist
39 @deffnx {Scheme Procedure} assv key alist
40 @deffnx {Scheme Procedure} assoc key alist
41 @deffnx {C Function} scm_assq (key, alist)
42 Fetch the entry in @var{alist} that is associated with @var{key}. To
43 decide whether the argument @var{key} matches a particular entry in
44 @var{alist}, @code{assq} compares keys with @code{eq?}, @code{assv}
45 uses @code{eqv?} and @code{assoc} uses @code{equal?}. If @var{key}
46 cannot be found in @var{alist} (according to whichever equality
47 predicate is in use), then return @code{#f}. These functions
48 return the entire alist entry found (i.e. both the key and the value).
52 @c snarfed from alist.c:134
53 @deffn {Scheme Procedure} assv key alist
54 @deffnx {C Function} scm_assv (key, alist)
55 Behaves like @code{assq} but uses @code{eqv?} for key comparison.
59 @c snarfed from alist.c:155
60 @deffn {Scheme Procedure} assoc key alist
61 @deffnx {C Function} scm_assoc (key, alist)
62 Behaves like @code{assq} but uses @code{equal?} for key comparison.
66 @c snarfed from alist.c:199
67 @deffn {Scheme Procedure} assq-ref alist key
68 @deffnx {Scheme Procedure} assv-ref alist key
69 @deffnx {Scheme Procedure} assoc-ref alist key
70 @deffnx {C Function} scm_assq_ref (alist, key)
71 Like @code{assq}, @code{assv} and @code{assoc}, except that only the
72 value associated with @var{key} in @var{alist} is returned. These
73 functions are equivalent to
76 (let ((ent (@var{associator} @var{key} @var{alist})))
80 where @var{associator} is one of @code{assq}, @code{assv} or @code{assoc}.
84 @c snarfed from alist.c:216
85 @deffn {Scheme Procedure} assv-ref alist key
86 @deffnx {C Function} scm_assv_ref (alist, key)
87 Behaves like @code{assq-ref} but uses @code{eqv?} for key comparison.
91 @c snarfed from alist.c:233
92 @deffn {Scheme Procedure} assoc-ref alist key
93 @deffnx {C Function} scm_assoc_ref (alist, key)
94 Behaves like @code{assq-ref} but uses @code{equal?} for key comparison.
98 @c snarfed from alist.c:262
99 @deffn {Scheme Procedure} assq-set! alist key val
100 @deffnx {Scheme Procedure} assv-set! alist key value
101 @deffnx {Scheme Procedure} assoc-set! alist key value
102 @deffnx {C Function} scm_assq_set_x (alist, key, val)
103 Reassociate @var{key} in @var{alist} with @var{value}: find any existing
104 @var{alist} entry for @var{key} and associate it with the new
105 @var{value}. If @var{alist} does not contain an entry for @var{key},
106 add a new one. Return the (possibly new) alist.
108 These functions do not attempt to verify the structure of @var{alist},
109 and so may cause unusual results if passed an object that is not an
114 @c snarfed from alist.c:280
115 @deffn {Scheme Procedure} assv-set! alist key val
116 @deffnx {C Function} scm_assv_set_x (alist, key, val)
117 Behaves like @code{assq-set!} but uses @code{eqv?} for key comparison.
121 @c snarfed from alist.c:298
122 @deffn {Scheme Procedure} assoc-set! alist key val
123 @deffnx {C Function} scm_assoc_set_x (alist, key, val)
124 Behaves like @code{assq-set!} but uses @code{equal?} for key comparison.
128 @c snarfed from alist.c:322
129 @deffn {Scheme Procedure} assq-remove! alist key
130 @deffnx {Scheme Procedure} assv-remove! alist key
131 @deffnx {Scheme Procedure} assoc-remove! alist key
132 @deffnx {C Function} scm_assq_remove_x (alist, key)
133 Delete the first entry in @var{alist} associated with @var{key}, and return
138 @c snarfed from alist.c:338
139 @deffn {Scheme Procedure} assv-remove! alist key
140 @deffnx {C Function} scm_assv_remove_x (alist, key)
141 Behaves like @code{assq-remove!} but uses @code{eqv?} for key comparison.
145 @c snarfed from alist.c:354
146 @deffn {Scheme Procedure} assoc-remove! alist key
147 @deffnx {C Function} scm_assoc_remove_x (alist, key)
148 Behaves like @code{assq-remove!} but uses @code{equal?} for key comparison.
152 @c snarfed from arbiters.c:99
153 @deffn {Scheme Procedure} make-arbiter name
154 @deffnx {C Function} scm_make_arbiter (name)
155 Return an arbiter object, initially unlocked. Currently
156 @var{name} is only used for diagnostic output.
160 @c snarfed from arbiters.c:116
161 @deffn {Scheme Procedure} try-arbiter arb
162 @deffnx {C Function} scm_try_arbiter (arb)
163 If @var{arb} is unlocked, then lock it and return @code{#t}.
164 If @var{arb} is already locked, then do nothing and return
169 @c snarfed from arbiters.c:142
170 @deffn {Scheme Procedure} release-arbiter arb
171 @deffnx {C Function} scm_release_arbiter (arb)
172 If @var{arb} is locked, then unlock it and return @code{#t}.
173 If @var{arb} is already unlocked, then do nothing and return
176 Typical usage is for the thread which locked an arbiter to
177 later release it, but that's not required, any thread can
182 @c snarfed from async.c:97
183 @deffn {Scheme Procedure} async thunk
184 @deffnx {C Function} scm_async (thunk)
185 Create a new async for the procedure @var{thunk}.
189 @c snarfed from async.c:106
190 @deffn {Scheme Procedure} async-mark a
191 @deffnx {C Function} scm_async_mark (a)
192 Mark the async @var{a} for future execution.
196 @c snarfed from async.c:117
197 @deffn {Scheme Procedure} run-asyncs list_of_a
198 @deffnx {C Function} scm_run_asyncs (list_of_a)
199 Execute all thunks from the asyncs of the list @var{list_of_a}.
203 @c snarfed from async.c:180
204 @deffn {Scheme Procedure} system-async thunk
205 @deffnx {C Function} scm_system_async (thunk)
206 This function is deprecated. You can use @var{thunk} directly
207 instead of explicitely creating an async object.
212 @c snarfed from async.c:222
213 @deffn {Scheme Procedure} system-async-mark proc [thread]
214 @deffnx {C Function} scm_system_async_mark_for_thread (proc, thread)
215 Mark @var{proc} (a procedure with zero arguments) for future execution
216 in @var{thread}. If @var{proc} has already been marked for
217 @var{thread} but has not been executed yet, this call has no effect.
218 If @var{thread} is omitted, the thread that called
219 @code{system-async-mark} is used.
221 This procedure is not safe to be called from C signal handlers. Use
222 @code{scm_sigaction} or @code{scm_sigaction_for_thread} to install
227 @c snarfed from async.c:253
228 @deffn {Scheme Procedure} noop . args
229 @deffnx {C Function} scm_noop (args)
230 Do nothing. When called without arguments, return @code{#f},
231 otherwise return the first argument.
235 @c snarfed from async.c:268
236 @deffn {Scheme Procedure} unmask-signals
237 @deffnx {C Function} scm_unmask_signals ()
238 Unmask signals. The returned value is not specified.
242 @c snarfed from async.c:286
243 @deffn {Scheme Procedure} mask-signals
244 @deffnx {C Function} scm_mask_signals ()
245 Mask signals. The returned value is not specified.
248 \fcall-with-blocked-asyncs
249 @c snarfed from async.c:319
250 @deffn {Scheme Procedure} call-with-blocked-asyncs proc
251 @deffnx {C Function} scm_call_with_blocked_asyncs (proc)
252 Call @var{proc} with no arguments and block the execution
253 of system asyncs by one level for the current thread while
254 it is running. Return the value returned by @var{proc}.
258 \fcall-with-unblocked-asyncs
259 @c snarfed from async.c:343
260 @deffn {Scheme Procedure} call-with-unblocked-asyncs proc
261 @deffnx {C Function} scm_call_with_unblocked_asyncs (proc)
262 Call @var{proc} with no arguments and unblock the execution
263 of system asyncs by one level for the current thread while
264 it is running. Return the value returned by @var{proc}.
269 @c snarfed from backtrace.c:303
270 @deffn {Scheme Procedure} display-error stack port subr message args rest
271 @deffnx {C Function} scm_display_error (stack, port, subr, message, args, rest)
272 Display an error message to the output port @var{port}.
273 @var{stack} is the saved stack for the error, @var{subr} is
274 the name of the procedure in which the error occurred and
275 @var{message} is the actual error message, which may contain
276 formatting instructions. These will format the arguments in
277 the list @var{args} accordingly. @var{rest} is currently
281 \fdisplay-application
282 @c snarfed from backtrace.c:446
283 @deffn {Scheme Procedure} display-application frame [port [indent]]
284 @deffnx {C Function} scm_display_application (frame, port, indent)
285 Display a procedure application @var{frame} to the output port
286 @var{port}. @var{indent} specifies the indentation of the
291 @c snarfed from backtrace.c:762
292 @deffn {Scheme Procedure} display-backtrace stack port [first [depth [highlights]]]
293 @deffnx {C Function} scm_display_backtrace_with_highlights (stack, port, first, depth, highlights)
294 Display a backtrace to the output port @var{port}. @var{stack}
295 is the stack to take the backtrace from, @var{first} specifies
296 where in the stack to start and @var{depth} how much frames
297 to display. Both @var{first} and @var{depth} can be @code{#f},
298 which means that default values will be used.
299 When @var{highlights} is given,
300 it should be a list and all members of it are highligthed in
305 @c snarfed from backtrace.c:798
306 @deffn {Scheme Procedure} backtrace [highlights]
307 @deffnx {C Function} scm_backtrace_with_highlights (highlights)
308 Display a backtrace of the stack saved by the last error
309 to the current output port. When @var{highlights} is given,
310 it should be a list and all members of it are highligthed in
315 @c snarfed from boolean.c:33
316 @deffn {Scheme Procedure} not x
317 @deffnx {C Function} scm_not (x)
318 Return @code{#t} iff @var{x} is @code{#f}, else return @code{#f}.
322 @c snarfed from boolean.c:43
323 @deffn {Scheme Procedure} boolean? obj
324 @deffnx {C Function} scm_boolean_p (obj)
325 Return @code{#t} iff @var{obj} is either @code{#t} or @code{#f}.
329 @c snarfed from chars.c:33
330 @deffn {Scheme Procedure} char? x
331 @deffnx {C Function} scm_char_p (x)
332 Return @code{#t} iff @var{x} is a character, else @code{#f}.
336 @c snarfed from chars.c:42
337 @deffn {Scheme Procedure} char=? x y
338 Return @code{#t} iff @var{x} is the same character as @var{y}, else @code{#f}.
342 @c snarfed from chars.c:55
343 @deffn {Scheme Procedure} char<? x y
344 Return @code{#t} iff @var{x} is less than @var{y} in the ASCII sequence,
349 @c snarfed from chars.c:67
350 @deffn {Scheme Procedure} char<=? x y
351 Return @code{#t} iff @var{x} is less than or equal to @var{y} in the
352 ASCII sequence, else @code{#f}.
356 @c snarfed from chars.c:79
357 @deffn {Scheme Procedure} char>? x y
358 Return @code{#t} iff @var{x} is greater than @var{y} in the ASCII
359 sequence, else @code{#f}.
363 @c snarfed from chars.c:91
364 @deffn {Scheme Procedure} char>=? x y
365 Return @code{#t} iff @var{x} is greater than or equal to @var{y} in the
366 ASCII sequence, else @code{#f}.
370 @c snarfed from chars.c:103
371 @deffn {Scheme Procedure} char-ci=? x y
372 Return @code{#t} iff @var{x} is the same character as @var{y} ignoring
373 case, else @code{#f}.
377 @c snarfed from chars.c:115
378 @deffn {Scheme Procedure} char-ci<? x y
379 Return @code{#t} iff @var{x} is less than @var{y} in the ASCII sequence
380 ignoring case, else @code{#f}.
384 @c snarfed from chars.c:127
385 @deffn {Scheme Procedure} char-ci<=? x y
386 Return @code{#t} iff @var{x} is less than or equal to @var{y} in the
387 ASCII sequence ignoring case, else @code{#f}.
391 @c snarfed from chars.c:139
392 @deffn {Scheme Procedure} char-ci>? x y
393 Return @code{#t} iff @var{x} is greater than @var{y} in the ASCII
394 sequence ignoring case, else @code{#f}.
398 @c snarfed from chars.c:151
399 @deffn {Scheme Procedure} char-ci>=? x y
400 Return @code{#t} iff @var{x} is greater than or equal to @var{y} in the
401 ASCII sequence ignoring case, else @code{#f}.
405 @c snarfed from chars.c:163
406 @deffn {Scheme Procedure} char-alphabetic? chr
407 @deffnx {C Function} scm_char_alphabetic_p (chr)
408 Return @code{#t} iff @var{chr} is alphabetic, else @code{#f}.
413 @c snarfed from chars.c:172
414 @deffn {Scheme Procedure} char-numeric? chr
415 @deffnx {C Function} scm_char_numeric_p (chr)
416 Return @code{#t} iff @var{chr} is numeric, else @code{#f}.
421 @c snarfed from chars.c:181
422 @deffn {Scheme Procedure} char-whitespace? chr
423 @deffnx {C Function} scm_char_whitespace_p (chr)
424 Return @code{#t} iff @var{chr} is whitespace, else @code{#f}.
429 @c snarfed from chars.c:192
430 @deffn {Scheme Procedure} char-upper-case? chr
431 @deffnx {C Function} scm_char_upper_case_p (chr)
432 Return @code{#t} iff @var{chr} is uppercase, else @code{#f}.
437 @c snarfed from chars.c:202
438 @deffn {Scheme Procedure} char-lower-case? chr
439 @deffnx {C Function} scm_char_lower_case_p (chr)
440 Return @code{#t} iff @var{chr} is lowercase, else @code{#f}.
445 @c snarfed from chars.c:213
446 @deffn {Scheme Procedure} char-is-both? chr
447 @deffnx {C Function} scm_char_is_both_p (chr)
448 Return @code{#t} iff @var{chr} is either uppercase or lowercase, else @code{#f}.
453 @c snarfed from chars.c:228
454 @deffn {Scheme Procedure} char->integer chr
455 @deffnx {C Function} scm_char_to_integer (chr)
456 Return the number corresponding to ordinal position of @var{chr} in the
461 @c snarfed from chars.c:240
462 @deffn {Scheme Procedure} integer->char n
463 @deffnx {C Function} scm_integer_to_char (n)
464 Return the character at position @var{n} in the ASCII sequence.
468 @c snarfed from chars.c:250
469 @deffn {Scheme Procedure} char-upcase chr
470 @deffnx {C Function} scm_char_upcase (chr)
471 Return the uppercase character version of @var{chr}.
475 @c snarfed from chars.c:261
476 @deffn {Scheme Procedure} char-downcase chr
477 @deffnx {C Function} scm_char_downcase (chr)
478 Return the lowercase character version of @var{chr}.
481 \fdebug-options-interface
482 @c snarfed from debug.c:53
483 @deffn {Scheme Procedure} debug-options-interface [setting]
484 @deffnx {C Function} scm_debug_options (setting)
485 Option interface for the debug options. Instead of using
486 this procedure directly, use the procedures @code{debug-enable},
487 @code{debug-disable}, @code{debug-set!} and @code{debug-options}.
491 @c snarfed from debug.c:96
492 @deffn {Scheme Procedure} with-traps thunk
493 @deffnx {C Function} scm_with_traps (thunk)
494 Call @var{thunk} with traps enabled.
498 @c snarfed from debug.c:134
499 @deffn {Scheme Procedure} memoized? obj
500 @deffnx {C Function} scm_memoized_p (obj)
501 Return @code{#t} if @var{obj} is memoized.
505 @c snarfed from debug.c:271
506 @deffn {Scheme Procedure} unmemoize-expr m
507 @deffnx {C Function} scm_i_unmemoize_expr (m)
508 Unmemoize the memoized expression @var{m},
511 \fmemoized-environment
512 @c snarfed from debug.c:281
513 @deffn {Scheme Procedure} memoized-environment m
514 @deffnx {C Function} scm_memoized_environment (m)
515 Return the environment of the memoized expression @var{m}.
519 @c snarfed from debug.c:291
520 @deffn {Scheme Procedure} procedure-name proc
521 @deffnx {C Function} scm_procedure_name (proc)
522 Return the name of the procedure @var{proc}
526 @c snarfed from debug.c:317
527 @deffn {Scheme Procedure} procedure-source proc
528 @deffnx {C Function} scm_procedure_source (proc)
529 Return the source of the procedure @var{proc}.
532 \fprocedure-environment
533 @c snarfed from debug.c:374
534 @deffn {Scheme Procedure} procedure-environment proc
535 @deffnx {C Function} scm_procedure_environment (proc)
536 Return the environment of the procedure @var{proc}.
540 @c snarfed from debug.c:406
541 @deffn {Scheme Procedure} local-eval exp [env]
542 @deffnx {C Function} scm_local_eval (exp, env)
543 Evaluate @var{exp} in its environment. If @var{env} is supplied,
544 it is the environment in which to evaluate @var{exp}. Otherwise,
545 @var{exp} must be a memoized code object (in which case, its environment
550 @c snarfed from debug.c:493
551 @deffn {Scheme Procedure} debug-object? obj
552 @deffnx {C Function} scm_debug_object_p (obj)
553 Return @code{#t} if @var{obj} is a debug object.
556 \fissue-deprecation-warning
557 @c snarfed from deprecation.c:99
558 @deffn {Scheme Procedure} issue-deprecation-warning . msgs
559 @deffnx {C Function} scm_issue_deprecation_warning (msgs)
560 Output @var{msgs} to @code{(current-error-port)} when this is the first call to @code{issue-deprecation-warning} with this specific @var{msgs}. Do nothing otherwise. The argument @var{msgs} should be a list of strings; they are printed in turn, each one followed by a newline.
563 \finclude-deprecated-features
564 @c snarfed from deprecation.c:144
565 @deffn {Scheme Procedure} include-deprecated-features
566 @deffnx {C Function} scm_include_deprecated_features ()
567 Return @code{#t} iff deprecated features should be included in public interfaces.
570 \fsubstring-move-left!
571 @c snarfed from deprecated.c:69
572 @deffn {Scheme Procedure} substring-move-left!
573 implemented by the C function "scm_substring_move_x"
576 \fsubstring-move-right!
577 @c snarfed from deprecated.c:71
578 @deffn {Scheme Procedure} substring-move-right!
579 implemented by the C function "scm_substring_move_x"
582 \fc-registered-modules
583 @c snarfed from deprecated.c:174
584 @deffn {Scheme Procedure} c-registered-modules
585 @deffnx {C Function} scm_registered_modules ()
586 Return a list of the object code modules that have been imported into
587 the current Guile process. Each element of the list is a pair whose
588 car is the name of the module, and whose cdr is the function handle
589 for that module's initializer function. The name is the string that
590 has been passed to scm_register_module_xxx.
593 \fc-clear-registered-modules
594 @c snarfed from deprecated.c:195
595 @deffn {Scheme Procedure} c-clear-registered-modules
596 @deffnx {C Function} scm_clear_registered_modules ()
597 Destroy the list of modules registered with the current Guile process.
598 The return value is unspecified. @strong{Warning:} this function does
599 not actually unlink or deallocate these modules, but only destroys the
600 records of which modules have been loaded. It should therefore be used
601 only by module bookkeeping operations.
604 \fclose-all-ports-except
605 @c snarfed from deprecated.c:338
606 @deffn {Scheme Procedure} close-all-ports-except . ports
607 @deffnx {C Function} scm_close_all_ports_except (ports)
608 [DEPRECATED] Close all open file ports used by the interpreter
609 except for those supplied as arguments. This procedure
610 was intended to be used before an exec call to close file descriptors
611 which are not needed in the new process. However it has the
612 undesirable side effect of flushing buffers, so it's deprecated.
613 Use port-for-each instead.
616 \fvariable-set-name-hint!
617 @c snarfed from deprecated.c:355
618 @deffn {Scheme Procedure} variable-set-name-hint! var hint
619 @deffnx {C Function} scm_variable_set_name_hint (var, hint)
620 Do not use this function.
624 @c snarfed from deprecated.c:368
625 @deffn {Scheme Procedure} builtin-variable name
626 @deffnx {C Function} scm_builtin_variable (name)
627 Do not use this function.
631 @c snarfed from deprecated.c:442
632 @deffn {Scheme Procedure} sloppy-memq x lst
633 @deffnx {C Function} scm_sloppy_memq (x, lst)
634 This procedure behaves like @code{memq}, but does no type or error checking.
635 Its use is recommended only in writing Guile internals,
636 not for high-level Scheme programs.
640 @c snarfed from deprecated.c:462
641 @deffn {Scheme Procedure} sloppy-memv x lst
642 @deffnx {C Function} scm_sloppy_memv (x, lst)
643 This procedure behaves like @code{memv}, but does no type or error checking.
644 Its use is recommended only in writing Guile internals,
645 not for high-level Scheme programs.
649 @c snarfed from deprecated.c:482
650 @deffn {Scheme Procedure} sloppy-member x lst
651 @deffnx {C Function} scm_sloppy_member (x, lst)
652 This procedure behaves like @code{member}, but does no type or error checking.
653 Its use is recommended only in writing Guile internals,
654 not for high-level Scheme programs.
658 @c snarfed from deprecated.c:504
659 @deffn {Scheme Procedure} read-and-eval! [port]
660 @deffnx {C Function} scm_read_and_eval_x (port)
661 Read a form from @var{port} (standard input by default), and evaluate it
662 (memoizing it in the process) in the top-level environment. If no data
663 is left to be read from @var{port}, an @code{end-of-file} error is
667 \fstring->obarray-symbol
668 @c snarfed from deprecated.c:794
669 @deffn {Scheme Procedure} string->obarray-symbol o s [softp]
670 @deffnx {C Function} scm_string_to_obarray_symbol (o, s, softp)
671 Intern a new symbol in @var{obarray}, a symbol table, with name
674 If @var{obarray} is @code{#f}, use the default system symbol table. If
675 @var{obarray} is @code{#t}, the symbol should not be interned in any
676 symbol table; merely return the pair (@var{symbol}
677 . @var{#<undefined>}).
679 The @var{soft?} argument determines whether new symbol table entries
680 should be created when the specified symbol is not already present in
681 @var{obarray}. If @var{soft?} is specified and is a true value, then
682 new entries should not be added for symbols not already present in the
683 table; instead, simply return @code{#f}.
687 @c snarfed from deprecated.c:832
688 @deffn {Scheme Procedure} intern-symbol o s
689 @deffnx {C Function} scm_intern_symbol (o, s)
690 Add a new symbol to @var{obarray} with name @var{string}, bound to an
691 unspecified initial value. The symbol table is not modified if a symbol
692 with this name is already present.
696 @c snarfed from deprecated.c:874
697 @deffn {Scheme Procedure} unintern-symbol o s
698 @deffnx {C Function} scm_unintern_symbol (o, s)
699 Remove the symbol with name @var{string} from @var{obarray}. This
700 function returns @code{#t} if the symbol was present and @code{#f}
705 @c snarfed from deprecated.c:919
706 @deffn {Scheme Procedure} symbol-binding o s
707 @deffnx {C Function} scm_symbol_binding (o, s)
708 Look up in @var{obarray} the symbol whose name is @var{string}, and
709 return the value to which it is bound. If @var{obarray} is @code{#f},
710 use the global symbol table. If @var{string} is not interned in
711 @var{obarray}, an error is signalled.
715 @c snarfed from deprecated.c:972
716 @deffn {Scheme Procedure} symbol-bound? o s
717 @deffnx {C Function} scm_symbol_bound_p (o, s)
718 Return @code{#t} if @var{obarray} contains a symbol with name
719 @var{string} bound to a defined value. This differs from
720 @var{symbol-interned?} in that the mere mention of a symbol
721 usually causes it to be interned; @code{symbol-bound?}
722 determines whether a symbol has been given any meaningful
727 @c snarfed from deprecated.c:999
728 @deffn {Scheme Procedure} symbol-set! o s v
729 @deffnx {C Function} scm_symbol_set_x (o, s, v)
730 Find the symbol in @var{obarray} whose name is @var{string}, and rebind
731 it to @var{value}. An error is signalled if @var{string} is not present
736 @c snarfed from deprecated.c:1032
737 @deffn {Scheme Procedure} gentemp [prefix [obarray]]
738 @deffnx {C Function} scm_gentemp (prefix, obarray)
739 Create a new symbol with a name unique in an obarray.
740 The name is constructed from an optional string @var{prefix}
741 and a counter value. The default prefix is @code{t}. The
742 @var{obarray} is specified as a second optional argument.
743 Default is the system obarray where all normal symbols are
744 interned. The counter is increased by 1 at each
745 call. There is no provision for resetting the counter.
749 @c snarfed from dynl.c:149
750 @deffn {Scheme Procedure} dynamic-link filename
751 @deffnx {C Function} scm_dynamic_link (filename)
752 Find the shared object (shared library) denoted by
753 @var{filename} and link it into the running Guile
754 application. The returned
755 scheme object is a ``handle'' for the library which can
756 be passed to @code{dynamic-func}, @code{dynamic-call} etc.
758 Searching for object files is system dependent. Normally,
759 if @var{filename} does have an explicit directory it will
760 be searched for in locations
761 such as @file{/usr/lib} and @file{/usr/local/lib}.
765 @c snarfed from dynl.c:168
766 @deffn {Scheme Procedure} dynamic-object? obj
767 @deffnx {C Function} scm_dynamic_object_p (obj)
768 Return @code{#t} if @var{obj} is a dynamic object handle,
769 or @code{#f} otherwise.
773 @c snarfed from dynl.c:182
774 @deffn {Scheme Procedure} dynamic-unlink dobj
775 @deffnx {C Function} scm_dynamic_unlink (dobj)
776 Unlink a dynamic object from the application, if possible. The
777 object must have been linked by @code{dynamic-link}, with
778 @var{dobj} the corresponding handle. After this procedure
779 is called, the handle can no longer be used to access the
784 @c snarfed from dynl.c:207
785 @deffn {Scheme Procedure} dynamic-func name dobj
786 @deffnx {C Function} scm_dynamic_func (name, dobj)
787 Return a ``handle'' for the function @var{name} in the
788 shared object referred to by @var{dobj}. The handle
789 can be passed to @code{dynamic-call} to actually
792 Regardless whether your C compiler prepends an underscore
793 @samp{_} to the global names in a program, you should
794 @strong{not} include this underscore in @var{name}
795 since it will be added automatically when necessary.
799 @c snarfed from dynl.c:253
800 @deffn {Scheme Procedure} dynamic-call func dobj
801 @deffnx {C Function} scm_dynamic_call (func, dobj)
802 Call a C function in a dynamic object. Two styles of
803 invocation are supported:
806 @item @var{func} can be a function handle returned by
807 @code{dynamic-func}. In this case @var{dobj} is
809 @item @var{func} can be a string with the name of the
810 function to call, with @var{dobj} the handle of the
811 dynamic object in which to find the function.
812 This is equivalent to
815 (dynamic-call (dynamic-func @var{func} @var{dobj}) #f)
819 In either case, the function is passed no arguments
820 and its return value is ignored.
824 @c snarfed from dynl.c:285
825 @deffn {Scheme Procedure} dynamic-args-call func dobj args
826 @deffnx {C Function} scm_dynamic_args_call (func, dobj, args)
827 Call the C function indicated by @var{func} and @var{dobj},
828 just like @code{dynamic-call}, but pass it some arguments and
829 return its return value. The C function is expected to take
830 two arguments and return an @code{int}, just like @code{main}:
832 int c_func (int argc, char **argv);
835 The parameter @var{args} must be a list of strings and is
836 converted into an array of @code{char *}. The array is passed
837 in @var{argv} and its size in @var{argc}. The return value is
838 converted to a Scheme number and returned from the call to
839 @code{dynamic-args-call}.
843 @c snarfed from dynwind.c:97
844 @deffn {Scheme Procedure} dynamic-wind in_guard thunk out_guard
845 @deffnx {C Function} scm_dynamic_wind (in_guard, thunk, out_guard)
846 All three arguments must be 0-argument procedures.
847 @var{in_guard} is called, then @var{thunk}, then
850 If, any time during the execution of @var{thunk}, the
851 continuation of the @code{dynamic_wind} expression is escaped
852 non-locally, @var{out_guard} is called. If the continuation of
853 the dynamic-wind is re-entered, @var{in_guard} is called. Thus
854 @var{in_guard} and @var{out_guard} may be called any number of
857 (define x 'normal-binding)
859 (define a-cont (call-with-current-continuation
865 (lambda () (set! x 'special-binding))
869 (lambda () (display x) (newline)
870 (call-with-current-continuation escape)
871 (display x) (newline)
876 (lambda () (set! x old-x)))))))
883 @result{} normal-binding
888 @result{} a-cont ;; the value of the (define a-cont...)
890 @result{} normal-binding
892 @result{} special-binding
897 @c snarfed from environments.c:106
898 @deffn {Scheme Procedure} environment? obj
899 @deffnx {C Function} scm_environment_p (obj)
900 Return @code{#t} if @var{obj} is an environment, or @code{#f}
905 @c snarfed from environments.c:117
906 @deffn {Scheme Procedure} environment-bound? env sym
907 @deffnx {C Function} scm_environment_bound_p (env, sym)
908 Return @code{#t} if @var{sym} is bound in @var{env}, or
913 @c snarfed from environments.c:132
914 @deffn {Scheme Procedure} environment-ref env sym
915 @deffnx {C Function} scm_environment_ref (env, sym)
916 Return the value of the location bound to @var{sym} in
917 @var{env}. If @var{sym} is unbound in @var{env}, signal an
918 @code{environment:unbound} error.
922 @c snarfed from environments.c:202
923 @deffn {Scheme Procedure} environment-fold env proc init
924 @deffnx {C Function} scm_environment_fold (env, proc, init)
925 Iterate over all the bindings in @var{env}, accumulating some
927 For each binding in @var{env}, apply @var{proc} to the symbol
928 bound, its value, and the result from the previous application
930 Use @var{init} as @var{proc}'s third argument the first time
931 @var{proc} is applied.
932 If @var{env} contains no bindings, this function simply returns
934 If @var{env} binds the symbol sym1 to the value val1, sym2 to
935 val2, and so on, then this procedure computes:
943 Each binding in @var{env} will be processed exactly once.
944 @code{environment-fold} makes no guarantees about the order in
945 which the bindings are processed.
946 Here is a function which, given an environment, constructs an
947 association list representing that environment's bindings,
948 using environment-fold:
950 (define (environment->alist env)
951 (environment-fold env
952 (lambda (sym val tail)
953 (cons (cons sym val) tail))
959 @c snarfed from environments.c:237
960 @deffn {Scheme Procedure} environment-define env sym val
961 @deffnx {C Function} scm_environment_define (env, sym, val)
962 Bind @var{sym} to a new location containing @var{val} in
963 @var{env}. If @var{sym} is already bound to another location
964 in @var{env} and the binding is mutable, that binding is
965 replaced. The new binding and location are both mutable. The
966 return value is unspecified.
967 If @var{sym} is already bound in @var{env}, and the binding is
968 immutable, signal an @code{environment:immutable-binding} error.
971 \fenvironment-undefine
972 @c snarfed from environments.c:263
973 @deffn {Scheme Procedure} environment-undefine env sym
974 @deffnx {C Function} scm_environment_undefine (env, sym)
975 Remove any binding for @var{sym} from @var{env}. If @var{sym}
976 is unbound in @var{env}, do nothing. The return value is
978 If @var{sym} is already bound in @var{env}, and the binding is
979 immutable, signal an @code{environment:immutable-binding} error.
983 @c snarfed from environments.c:291
984 @deffn {Scheme Procedure} environment-set! env sym val
985 @deffnx {C Function} scm_environment_set_x (env, sym, val)
986 If @var{env} binds @var{sym} to some location, change that
987 location's value to @var{val}. The return value is
989 If @var{sym} is not bound in @var{env}, signal an
990 @code{environment:unbound} error. If @var{env} binds @var{sym}
991 to an immutable location, signal an
992 @code{environment:immutable-location} error.
996 @c snarfed from environments.c:326
997 @deffn {Scheme Procedure} environment-cell env sym for_write
998 @deffnx {C Function} scm_environment_cell (env, sym, for_write)
999 Return the value cell which @var{env} binds to @var{sym}, or
1000 @code{#f} if the binding does not live in a value cell.
1001 The argument @var{for-write} indicates whether the caller
1002 intends to modify the variable's value by mutating the value
1003 cell. If the variable is immutable, then
1004 @code{environment-cell} signals an
1005 @code{environment:immutable-location} error.
1006 If @var{sym} is unbound in @var{env}, signal an
1007 @code{environment:unbound} error.
1008 If you use this function, you should consider using
1009 @code{environment-observe}, to be notified when @var{sym} gets
1010 re-bound to a new value cell, or becomes undefined.
1013 \fenvironment-observe
1014 @c snarfed from environments.c:378
1015 @deffn {Scheme Procedure} environment-observe env proc
1016 @deffnx {C Function} scm_environment_observe (env, proc)
1017 Whenever @var{env}'s bindings change, apply @var{proc} to
1019 This function returns an object, token, which you can pass to
1020 @code{environment-unobserve} to remove @var{proc} from the set
1021 of procedures observing @var{env}. The type and value of
1022 token is unspecified.
1025 \fenvironment-observe-weak
1026 @c snarfed from environments.c:395
1027 @deffn {Scheme Procedure} environment-observe-weak env proc
1028 @deffnx {C Function} scm_environment_observe_weak (env, proc)
1029 This function is the same as environment-observe, except that
1030 the reference @var{env} retains to @var{proc} is a weak
1031 reference. This means that, if there are no other live,
1032 non-weak references to @var{proc}, it will be
1033 garbage-collected, and dropped from @var{env}'s
1034 list of observing procedures.
1037 \fenvironment-unobserve
1038 @c snarfed from environments.c:431
1039 @deffn {Scheme Procedure} environment-unobserve token
1040 @deffnx {C Function} scm_environment_unobserve (token)
1041 Cancel the observation request which returned the value
1042 @var{token}. The return value is unspecified.
1043 If a call @code{(environment-observe env proc)} returns
1044 @var{token}, then the call @code{(environment-unobserve token)}
1045 will cause @var{proc} to no longer be called when @var{env}'s
1049 \fmake-leaf-environment
1050 @c snarfed from environments.c:1015
1051 @deffn {Scheme Procedure} make-leaf-environment
1052 @deffnx {C Function} scm_make_leaf_environment ()
1053 Create a new leaf environment, containing no bindings.
1054 All bindings and locations created in the new environment
1059 @c snarfed from environments.c:1038
1060 @deffn {Scheme Procedure} leaf-environment? object
1061 @deffnx {C Function} scm_leaf_environment_p (object)
1062 Return @code{#t} if object is a leaf environment, or @code{#f}
1066 \fmake-eval-environment
1067 @c snarfed from environments.c:1403
1068 @deffn {Scheme Procedure} make-eval-environment local imported
1069 @deffnx {C Function} scm_make_eval_environment (local, imported)
1070 Return a new environment object eval whose bindings are the
1071 union of the bindings in the environments @var{local} and
1072 @var{imported}, with bindings from @var{local} taking
1073 precedence. Definitions made in eval are placed in @var{local}.
1074 Applying @code{environment-define} or
1075 @code{environment-undefine} to eval has the same effect as
1076 applying the procedure to @var{local}.
1077 Note that eval incorporates @var{local} and @var{imported} by
1079 If, after creating eval, the program changes the bindings of
1080 @var{local} or @var{imported}, those changes will be visible
1082 Since most Scheme evaluation takes place in eval environments,
1083 they transparently cache the bindings received from @var{local}
1084 and @var{imported}. Thus, the first time the program looks up
1085 a symbol in eval, eval may make calls to @var{local} or
1086 @var{imported} to find their bindings, but subsequent
1087 references to that symbol will be as fast as references to
1088 bindings in finite environments.
1089 In typical use, @var{local} will be a finite environment, and
1090 @var{imported} will be an import environment
1094 @c snarfed from environments.c:1440
1095 @deffn {Scheme Procedure} eval-environment? object
1096 @deffnx {C Function} scm_eval_environment_p (object)
1097 Return @code{#t} if object is an eval environment, or @code{#f}
1101 \feval-environment-local
1102 @c snarfed from environments.c:1450
1103 @deffn {Scheme Procedure} eval-environment-local env
1104 @deffnx {C Function} scm_eval_environment_local (env)
1105 Return the local environment of eval environment @var{env}.
1108 \feval-environment-set-local!
1109 @c snarfed from environments.c:1462
1110 @deffn {Scheme Procedure} eval-environment-set-local! env local
1111 @deffnx {C Function} scm_eval_environment_set_local_x (env, local)
1112 Change @var{env}'s local environment to @var{local}.
1115 \feval-environment-imported
1116 @c snarfed from environments.c:1488
1117 @deffn {Scheme Procedure} eval-environment-imported env
1118 @deffnx {C Function} scm_eval_environment_imported (env)
1119 Return the imported environment of eval environment @var{env}.
1122 \feval-environment-set-imported!
1123 @c snarfed from environments.c:1500
1124 @deffn {Scheme Procedure} eval-environment-set-imported! env imported
1125 @deffnx {C Function} scm_eval_environment_set_imported_x (env, imported)
1126 Change @var{env}'s imported environment to @var{imported}.
1129 \fmake-import-environment
1130 @c snarfed from environments.c:1823
1131 @deffn {Scheme Procedure} make-import-environment imports conflict_proc
1132 @deffnx {C Function} scm_make_import_environment (imports, conflict_proc)
1133 Return a new environment @var{imp} whose bindings are the union
1134 of the bindings from the environments in @var{imports};
1135 @var{imports} must be a list of environments. That is,
1136 @var{imp} binds a symbol to a location when some element of
1138 If two different elements of @var{imports} have a binding for
1139 the same symbol, the @var{conflict-proc} is called with the
1140 following parameters: the import environment, the symbol and
1141 the list of the imported environments that bind the symbol.
1142 If the @var{conflict-proc} returns an environment @var{env},
1143 the conflict is considered as resolved and the binding from
1144 @var{env} is used. If the @var{conflict-proc} returns some
1145 non-environment object, the conflict is considered unresolved
1146 and the symbol is treated as unspecified in the import
1148 The checking for conflicts may be performed lazily, i. e. at
1149 the moment when a value or binding for a certain symbol is
1150 requested instead of the moment when the environment is
1151 created or the bindings of the imports change.
1152 All bindings in @var{imp} are immutable. If you apply
1153 @code{environment-define} or @code{environment-undefine} to
1154 @var{imp}, Guile will signal an
1155 @code{environment:immutable-binding} error. However,
1156 notice that the set of bindings in @var{imp} may still change,
1157 if one of its imported environments changes.
1160 \fimport-environment?
1161 @c snarfed from environments.c:1852
1162 @deffn {Scheme Procedure} import-environment? object
1163 @deffnx {C Function} scm_import_environment_p (object)
1164 Return @code{#t} if object is an import environment, or
1165 @code{#f} otherwise.
1168 \fimport-environment-imports
1169 @c snarfed from environments.c:1863
1170 @deffn {Scheme Procedure} import-environment-imports env
1171 @deffnx {C Function} scm_import_environment_imports (env)
1172 Return the list of environments imported by the import
1173 environment @var{env}.
1176 \fimport-environment-set-imports!
1177 @c snarfed from environments.c:1876
1178 @deffn {Scheme Procedure} import-environment-set-imports! env imports
1179 @deffnx {C Function} scm_import_environment_set_imports_x (env, imports)
1180 Change @var{env}'s list of imported environments to
1181 @var{imports}, and check for conflicts.
1184 \fmake-export-environment
1185 @c snarfed from environments.c:2143
1186 @deffn {Scheme Procedure} make-export-environment private signature
1187 @deffnx {C Function} scm_make_export_environment (private, signature)
1188 Return a new environment @var{exp} containing only those
1189 bindings in private whose symbols are present in
1190 @var{signature}. The @var{private} argument must be an
1193 The environment @var{exp} binds symbol to location when
1194 @var{env} does, and symbol is exported by @var{signature}.
1196 @var{signature} is a list specifying which of the bindings in
1197 @var{private} should be visible in @var{exp}. Each element of
1198 @var{signature} should be a list of the form:
1199 (symbol attribute ...)
1200 where each attribute is one of the following:
1202 @item the symbol @code{mutable-location}
1203 @var{exp} should treat the
1204 location bound to symbol as mutable. That is, @var{exp}
1205 will pass calls to @code{environment-set!} or
1206 @code{environment-cell} directly through to private.
1207 @item the symbol @code{immutable-location}
1208 @var{exp} should treat
1209 the location bound to symbol as immutable. If the program
1210 applies @code{environment-set!} to @var{exp} and symbol, or
1211 calls @code{environment-cell} to obtain a writable value
1212 cell, @code{environment-set!} will signal an
1213 @code{environment:immutable-location} error. Note that, even
1214 if an export environment treats a location as immutable, the
1215 underlying environment may treat it as mutable, so its
1218 It is an error for an element of signature to specify both
1219 @code{mutable-location} and @code{immutable-location}. If
1220 neither is specified, @code{immutable-location} is assumed.
1222 As a special case, if an element of signature is a lone
1223 symbol @var{sym}, it is equivalent to an element of the form
1226 All bindings in @var{exp} are immutable. If you apply
1227 @code{environment-define} or @code{environment-undefine} to
1228 @var{exp}, Guile will signal an
1229 @code{environment:immutable-binding} error. However,
1230 notice that the set of bindings in @var{exp} may still change,
1231 if the bindings in private change.
1234 \fexport-environment?
1235 @c snarfed from environments.c:2178
1236 @deffn {Scheme Procedure} export-environment? object
1237 @deffnx {C Function} scm_export_environment_p (object)
1238 Return @code{#t} if object is an export environment, or
1239 @code{#f} otherwise.
1242 \fexport-environment-private
1243 @c snarfed from environments.c:2188
1244 @deffn {Scheme Procedure} export-environment-private env
1245 @deffnx {C Function} scm_export_environment_private (env)
1246 Return the private environment of export environment @var{env}.
1249 \fexport-environment-set-private!
1250 @c snarfed from environments.c:2200
1251 @deffn {Scheme Procedure} export-environment-set-private! env private
1252 @deffnx {C Function} scm_export_environment_set_private_x (env, private)
1253 Change the private environment of export environment @var{env}.
1256 \fexport-environment-signature
1257 @c snarfed from environments.c:2222
1258 @deffn {Scheme Procedure} export-environment-signature env
1259 @deffnx {C Function} scm_export_environment_signature (env)
1260 Return the signature of export environment @var{env}.
1263 \fexport-environment-set-signature!
1264 @c snarfed from environments.c:2296
1265 @deffn {Scheme Procedure} export-environment-set-signature! env signature
1266 @deffnx {C Function} scm_export_environment_set_signature_x (env, signature)
1267 Change the signature of export environment @var{env}.
1271 @c snarfed from eq.c:47
1272 @deffn {Scheme Procedure} eq? x y
1273 Return @code{#t} iff @var{x} references the same object as @var{y}.
1274 @code{eq?} is similar to @code{eqv?} except that in some cases it is
1275 capable of discerning distinctions finer than those detectable by
1280 @c snarfed from eq.c:71
1281 @deffn {Scheme Procedure} eqv? x y
1282 The @code{eqv?} procedure defines a useful equivalence relation on objects.
1283 Briefly, it returns @code{#t} if @var{x} and @var{y} should normally be
1284 regarded as the same object. This relation is left slightly open to
1285 interpretation, but works for comparing immediate integers, characters,
1286 and inexact numbers.
1290 @c snarfed from eq.c:138
1291 @deffn {Scheme Procedure} equal? x y
1292 Return @code{#t} iff @var{x} and @var{y} are recursively @code{eqv?} equivalent.
1293 @code{equal?} recursively compares the contents of pairs,
1294 vectors, and strings, applying @code{eqv?} on other objects such as
1295 numbers and symbols. A rule of thumb is that objects are generally
1296 @code{equal?} if they print the same. @code{equal?} may fail to
1297 terminate if its arguments are circular data structures.
1301 @c snarfed from error.c:83
1302 @deffn {Scheme Procedure} scm-error key subr message args data
1303 @deffnx {C Function} scm_error_scm (key, subr, message, args, data)
1304 Raise an error with key @var{key}. @var{subr} can be a string
1305 naming the procedure associated with the error, or @code{#f}.
1306 @var{message} is the error message string, possibly containing
1307 @code{~S} and @code{~A} escapes. When an error is reported,
1308 these are replaced by formatting the corresponding members of
1309 @var{args}: @code{~A} (was @code{%s} in older versions of
1310 Guile) formats using @code{display} and @code{~S} (was
1311 @code{%S}) formats using @code{write}. @var{data} is a list or
1312 @code{#f} depending on @var{key}: if @var{key} is
1313 @code{system-error} then it should be a list containing the
1314 Unix @code{errno} value; If @var{key} is @code{signal} then it
1315 should be a list containing the Unix signal number; If
1316 @var{key} is @code{out-of-range} or @code{wrong-type-arg},
1317 it is a list containing the bad value; otherwise
1318 it will usually be @code{#f}.
1322 @c snarfed from error.c:130
1323 @deffn {Scheme Procedure} strerror err
1324 @deffnx {C Function} scm_strerror (err)
1325 Return the Unix error message corresponding to @var{err}, which
1326 must be an integer value.
1330 @c snarfed from eval.c:4690
1331 @deffn {Scheme Procedure} apply:nconc2last lst
1332 @deffnx {C Function} scm_nconc2last (lst)
1333 Given a list (@var{arg1} @dots{} @var{args}), this function
1334 conses the @var{arg1} @dots{} arguments onto the front of
1335 @var{args}, and returns the resulting list. Note that
1336 @var{args} is a list; thus, the argument to this function is
1337 a list whose last element is a list.
1338 Note: Rather than do new consing, @code{apply:nconc2last}
1339 destroys its argument, so use with care.
1343 @c snarfed from eval.c:5600
1344 @deffn {Scheme Procedure} force promise
1345 @deffnx {C Function} scm_force (promise)
1346 If the promise @var{x} has not been computed yet, compute and
1347 return @var{x}, otherwise just return the previously computed
1352 @c snarfed from eval.c:5623
1353 @deffn {Scheme Procedure} promise? obj
1354 @deffnx {C Function} scm_promise_p (obj)
1355 Return true if @var{obj} is a promise, i.e. a delayed computation
1356 (@pxref{Delayed evaluation,,,r5rs.info,The Revised^5 Report on Scheme}).
1360 @c snarfed from eval.c:5635
1361 @deffn {Scheme Procedure} cons-source xorig x y
1362 @deffnx {C Function} scm_cons_source (xorig, x, y)
1363 Create and return a new pair whose car and cdr are @var{x} and @var{y}.
1364 Any source properties associated with @var{xorig} are also associated
1369 @c snarfed from eval.c:5792
1370 @deffn {Scheme Procedure} copy-tree obj
1371 @deffnx {C Function} scm_copy_tree (obj)
1372 Recursively copy the data tree that is bound to @var{obj}, and return a
1373 the new data structure. @code{copy-tree} recurses down the
1374 contents of both pairs and vectors (since both cons cells and vector
1375 cells may point to arbitrary objects), and stops recursing when it hits
1380 @c snarfed from eval.c:5878
1381 @deffn {Scheme Procedure} primitive-eval exp
1382 @deffnx {C Function} scm_primitive_eval (exp)
1383 Evaluate @var{exp} in the top-level environment specified by
1388 @c snarfed from eval.c:5947
1389 @deffn {Scheme Procedure} eval exp module
1390 @deffnx {C Function} scm_eval (exp, module)
1391 Evaluate @var{exp}, a list representing a Scheme expression,
1392 in the top-level environment specified by @var{module}.
1393 While @var{exp} is evaluated (using @code{primitive-eval}),
1394 @var{module} is made the current module. The current module
1395 is reset to its previous value when @var{eval} returns.
1398 \feval-options-interface
1399 @c snarfed from eval.c:3090
1400 @deffn {Scheme Procedure} eval-options-interface [setting]
1401 @deffnx {C Function} scm_eval_options_interface (setting)
1402 Option interface for the evaluation options. Instead of using
1403 this procedure directly, use the procedures @code{eval-enable},
1404 @code{eval-disable}, @code{eval-set!} and @code{eval-options}.
1407 \fevaluator-traps-interface
1408 @c snarfed from eval.c:3108
1409 @deffn {Scheme Procedure} evaluator-traps-interface [setting]
1410 @deffnx {C Function} scm_evaluator_traps (setting)
1411 Option interface for the evaluator trap options.
1415 @c snarfed from evalext.c:34
1416 @deffn {Scheme Procedure} defined? sym [env]
1417 @deffnx {C Function} scm_defined_p (sym, env)
1418 Return @code{#t} if @var{sym} is defined in the lexical environment @var{env}. When @var{env} is not specified, look in the top-level environment as defined by the current module.
1422 @c snarfed from evalext.c:80
1423 @deffn {Scheme Procedure} map-in-order
1424 implemented by the C function "scm_map"
1428 @c snarfed from evalext.c:85
1429 @deffn {Scheme Procedure} self-evaluating? obj
1430 @deffnx {C Function} scm_self_evaluating_p (obj)
1431 Return #t for objects which Guile considers self-evaluating
1435 @c snarfed from extensions.c:143
1436 @deffn {Scheme Procedure} load-extension lib init
1437 @deffnx {C Function} scm_load_extension (lib, init)
1438 Load and initialize the extension designated by LIB and INIT.
1439 When there is no pre-registered function for LIB/INIT, this is
1443 (dynamic-call INIT (dynamic-link LIB))
1446 When there is a pre-registered function, that function is called
1449 Normally, there is no pre-registered function. This option exists
1450 only for situations where dynamic linking is unavailable or unwanted.
1451 In that case, you would statically link your program with the desired
1452 library, and register its init function right after Guile has been
1455 LIB should be a string denoting a shared library without any file type
1456 suffix such as ".so". The suffix is provided automatically. It
1457 should also not contain any directory components. Libraries that
1458 implement Guile Extensions should be put into the normal locations for
1459 shared libraries. We recommend to use the naming convention
1460 libguile-bla-blum for a extension related to a module `(bla blum)'.
1462 The normal way for a extension to be used is to write a small Scheme
1463 file that defines a module, and to load the extension into this
1464 module. When the module is auto-loaded, the extension is loaded as
1468 (define-module (bla blum))
1470 (load-extension "libguile-bla-blum" "bla_init_blum")
1475 @c snarfed from feature.c:56
1476 @deffn {Scheme Procedure} program-arguments
1477 @deffnx {Scheme Procedure} command-line
1478 @deffnx {C Function} scm_program_arguments ()
1479 Return the list of command line arguments passed to Guile, as a list of
1480 strings. The list includes the invoked program name, which is usually
1481 @code{"guile"}, but excludes switches and parameters for command line
1482 options like @code{-e} and @code{-l}.
1486 @c snarfed from fluids.c:100
1487 @deffn {Scheme Procedure} make-fluid
1488 @deffnx {C Function} scm_make_fluid ()
1489 Return a newly created fluid.
1490 Fluids are objects of a certain type (a smob) that can hold one SCM
1491 value per dynamic root. That is, modifications to this value are
1492 only visible to code that executes within the same dynamic root as
1493 the modifying code. When a new dynamic root is constructed, it
1494 inherits the values from its parent. Because each thread executes
1495 in its own dynamic root, you can use fluids for thread local storage.
1499 @c snarfed from fluids.c:113
1500 @deffn {Scheme Procedure} fluid? obj
1501 @deffnx {C Function} scm_fluid_p (obj)
1502 Return @code{#t} iff @var{obj} is a fluid; otherwise, return
1507 @c snarfed from fluids.c:124
1508 @deffn {Scheme Procedure} fluid-ref fluid
1509 @deffnx {C Function} scm_fluid_ref (fluid)
1510 Return the value associated with @var{fluid} in the current
1511 dynamic root. If @var{fluid} has not been set, then return
1516 @c snarfed from fluids.c:140
1517 @deffn {Scheme Procedure} fluid-set! fluid value
1518 @deffnx {C Function} scm_fluid_set_x (fluid, value)
1519 Set the value associated with @var{fluid} in the current dynamic root.
1523 @c snarfed from fluids.c:206
1524 @deffn {Scheme Procedure} with-fluids* fluids values thunk
1525 @deffnx {C Function} scm_with_fluids (fluids, values, thunk)
1526 Set @var{fluids} to @var{values} temporary, and call @var{thunk}.
1527 @var{fluids} must be a list of fluids and @var{values} must be the same
1528 number of their values to be applied. Each substitution is done
1529 one after another. @var{thunk} must be a procedure with no argument.
1533 @c snarfed from fluids.c:245
1534 @deffn {Scheme Procedure} with-fluid* fluid value thunk
1535 @deffnx {C Function} scm_with_fluid (fluid, value, thunk)
1536 Set @var{fluid} to @var{value} temporarily, and call @var{thunk}.
1537 @var{thunk} must be a procedure with no argument.
1541 @c snarfed from fports.c:137
1542 @deffn {Scheme Procedure} setvbuf port mode [size]
1543 @deffnx {C Function} scm_setvbuf (port, mode, size)
1544 Set the buffering mode for @var{port}. @var{mode} can be:
1551 block buffered, using a newly allocated buffer of @var{size} bytes.
1552 If @var{size} is omitted, a default size will be used.
1557 @c snarfed from fports.c:230
1558 @deffn {Scheme Procedure} file-port? obj
1559 @deffnx {C Function} scm_file_port_p (obj)
1560 Determine whether @var{obj} is a port that is related to a file.
1564 @c snarfed from fports.c:284
1565 @deffn {Scheme Procedure} open-file filename mode
1566 @deffnx {C Function} scm_open_file (filename, mode)
1567 Open the file whose name is @var{filename}, and return a port
1568 representing that file. The attributes of the port are
1569 determined by the @var{mode} string. The way in which this is
1570 interpreted is similar to C stdio. The first character must be
1571 one of the following:
1574 Open an existing file for input.
1576 Open a file for output, creating it if it doesn't already exist
1577 or removing its contents if it does.
1579 Open a file for output, creating it if it doesn't already
1580 exist. All writes to the port will go to the end of the file.
1581 The "append mode" can be turned off while the port is in use
1582 @pxref{Ports and File Descriptors, fcntl}
1584 The following additional characters can be appended:
1587 Open the port for both input and output. E.g., @code{r+}: open
1588 an existing file for both input and output.
1590 Create an "unbuffered" port. In this case input and output
1591 operations are passed directly to the underlying port
1592 implementation without additional buffering. This is likely to
1593 slow down I/O operations. The buffering mode can be changed
1594 while a port is in use @pxref{Ports and File Descriptors,
1597 Add line-buffering to the port. The port output buffer will be
1598 automatically flushed whenever a newline character is written.
1600 In theory we could create read/write ports which were buffered
1601 in one direction only. However this isn't included in the
1602 current interfaces. If a file cannot be opened with the access
1603 requested, @code{open-file} throws an exception.
1607 @c snarfed from futures.c:89
1608 @deffn {Scheme Procedure} make-future thunk
1609 @deffnx {C Function} scm_make_future (thunk)
1610 Make a future evaluating THUNK.
1614 @c snarfed from futures.c:221
1615 @deffn {Scheme Procedure} future-ref future
1616 @deffnx {C Function} scm_future_ref (future)
1617 If the future @var{x} has not been computed yet, compute and
1618 return @var{x}, otherwise just return the previously computed
1623 @c snarfed from gc.c:283
1624 @deffn {Scheme Procedure} gc-stats
1625 @deffnx {C Function} scm_gc_stats ()
1626 Return an association list of statistics about Guile's current
1632 @c snarfed from gc.c:419
1633 @deffn {Scheme Procedure} object-address obj
1634 @deffnx {C Function} scm_object_address (obj)
1635 Return an integer that for the lifetime of @var{obj} is uniquely
1636 returned by this function for @var{obj}
1640 @c snarfed from gc.c:430
1641 @deffn {Scheme Procedure} gc
1642 @deffnx {C Function} scm_gc ()
1643 Scans all of SCM objects and reclaims for further use those that are
1644 no longer accessible.
1648 @c snarfed from goops.c:265
1649 @deffn {Scheme Procedure} %compute-slots class
1650 @deffnx {C Function} scm_sys_compute_slots (class)
1651 Return a list consisting of the names of all slots belonging to
1652 class @var{class}, i. e. the slots of @var{class} and of all of
1657 @c snarfed from goops.c:356
1658 @deffn {Scheme Procedure} get-keyword key l default_value
1659 @deffnx {C Function} scm_get_keyword (key, l, default_value)
1660 Determine an associated value for the keyword @var{key} from
1661 the list @var{l}. The list @var{l} has to consist of an even
1662 number of elements, where, starting with the first, every
1663 second element is a keyword, followed by its associated value.
1664 If @var{l} does not hold a value for @var{key}, the value
1665 @var{default_value} is returned.
1668 \f%initialize-object
1669 @c snarfed from goops.c:379
1670 @deffn {Scheme Procedure} %initialize-object obj initargs
1671 @deffnx {C Function} scm_sys_initialize_object (obj, initargs)
1672 Initialize the object @var{obj} with the given arguments
1677 @c snarfed from goops.c:477
1678 @deffn {Scheme Procedure} %prep-layout! class
1679 @deffnx {C Function} scm_sys_prep_layout_x (class)
1684 @c snarfed from goops.c:576
1685 @deffn {Scheme Procedure} %inherit-magic! class dsupers
1686 @deffnx {C Function} scm_sys_inherit_magic_x (class, dsupers)
1691 @c snarfed from goops.c:816
1692 @deffn {Scheme Procedure} instance? obj
1693 @deffnx {C Function} scm_instance_p (obj)
1694 Return @code{#t} if @var{obj} is an instance.
1698 @c snarfed from goops.c:831
1699 @deffn {Scheme Procedure} class-name obj
1700 @deffnx {C Function} scm_class_name (obj)
1701 Return the class name of @var{obj}.
1704 \fclass-direct-supers
1705 @c snarfed from goops.c:841
1706 @deffn {Scheme Procedure} class-direct-supers obj
1707 @deffnx {C Function} scm_class_direct_supers (obj)
1708 Return the direct superclasses of the class @var{obj}.
1711 \fclass-direct-slots
1712 @c snarfed from goops.c:851
1713 @deffn {Scheme Procedure} class-direct-slots obj
1714 @deffnx {C Function} scm_class_direct_slots (obj)
1715 Return the direct slots of the class @var{obj}.
1718 \fclass-direct-subclasses
1719 @c snarfed from goops.c:861
1720 @deffn {Scheme Procedure} class-direct-subclasses obj
1721 @deffnx {C Function} scm_class_direct_subclasses (obj)
1722 Return the direct subclasses of the class @var{obj}.
1725 \fclass-direct-methods
1726 @c snarfed from goops.c:871
1727 @deffn {Scheme Procedure} class-direct-methods obj
1728 @deffnx {C Function} scm_class_direct_methods (obj)
1729 Return the direct methods of the class @var{obj}
1732 \fclass-precedence-list
1733 @c snarfed from goops.c:881
1734 @deffn {Scheme Procedure} class-precedence-list obj
1735 @deffnx {C Function} scm_class_precedence_list (obj)
1736 Return the class precedence list of the class @var{obj}.
1740 @c snarfed from goops.c:891
1741 @deffn {Scheme Procedure} class-slots obj
1742 @deffnx {C Function} scm_class_slots (obj)
1743 Return the slot list of the class @var{obj}.
1747 @c snarfed from goops.c:901
1748 @deffn {Scheme Procedure} class-environment obj
1749 @deffnx {C Function} scm_class_environment (obj)
1750 Return the environment of the class @var{obj}.
1753 \fgeneric-function-name
1754 @c snarfed from goops.c:912
1755 @deffn {Scheme Procedure} generic-function-name obj
1756 @deffnx {C Function} scm_generic_function_name (obj)
1757 Return the name of the generic function @var{obj}.
1760 \fgeneric-function-methods
1761 @c snarfed from goops.c:957
1762 @deffn {Scheme Procedure} generic-function-methods obj
1763 @deffnx {C Function} scm_generic_function_methods (obj)
1764 Return the methods of the generic function @var{obj}.
1767 \fmethod-generic-function
1768 @c snarfed from goops.c:970
1769 @deffn {Scheme Procedure} method-generic-function obj
1770 @deffnx {C Function} scm_method_generic_function (obj)
1771 Return the generic function for the method @var{obj}.
1774 \fmethod-specializers
1775 @c snarfed from goops.c:980
1776 @deffn {Scheme Procedure} method-specializers obj
1777 @deffnx {C Function} scm_method_specializers (obj)
1778 Return specializers of the method @var{obj}.
1782 @c snarfed from goops.c:990
1783 @deffn {Scheme Procedure} method-procedure obj
1784 @deffnx {C Function} scm_method_procedure (obj)
1785 Return the procedure of the method @var{obj}.
1788 \faccessor-method-slot-definition
1789 @c snarfed from goops.c:1000
1790 @deffn {Scheme Procedure} accessor-method-slot-definition obj
1791 @deffnx {C Function} scm_accessor_method_slot_definition (obj)
1792 Return the slot definition of the accessor @var{obj}.
1796 @c snarfed from goops.c:1010
1797 @deffn {Scheme Procedure} %tag-body body
1798 @deffnx {C Function} scm_sys_tag_body (body)
1799 Internal GOOPS magic---don't use this function!
1803 @c snarfed from goops.c:1025
1804 @deffn {Scheme Procedure} make-unbound
1805 @deffnx {C Function} scm_make_unbound ()
1806 Return the unbound value.
1810 @c snarfed from goops.c:1034
1811 @deffn {Scheme Procedure} unbound? obj
1812 @deffnx {C Function} scm_unbound_p (obj)
1813 Return @code{#t} if @var{obj} is unbound.
1817 @c snarfed from goops.c:1044
1818 @deffn {Scheme Procedure} assert-bound value obj
1819 @deffnx {C Function} scm_assert_bound (value, obj)
1820 Return @var{value} if it is bound, and invoke the
1821 @var{slot-unbound} method of @var{obj} if it is not.
1824 \f@@assert-bound-ref
1825 @c snarfed from goops.c:1056
1826 @deffn {Scheme Procedure} @@assert-bound-ref obj index
1827 @deffnx {C Function} scm_at_assert_bound_ref (obj, index)
1828 Like @code{assert-bound}, but use @var{index} for accessing
1829 the value from @var{obj}.
1833 @c snarfed from goops.c:1068
1834 @deffn {Scheme Procedure} %fast-slot-ref obj index
1835 @deffnx {C Function} scm_sys_fast_slot_ref (obj, index)
1836 Return the slot value with index @var{index} from @var{obj}.
1840 @c snarfed from goops.c:1082
1841 @deffn {Scheme Procedure} %fast-slot-set! obj index value
1842 @deffnx {C Function} scm_sys_fast_slot_set_x (obj, index, value)
1843 Set the slot with index @var{index} in @var{obj} to
1847 \fslot-ref-using-class
1848 @c snarfed from goops.c:1219
1849 @deffn {Scheme Procedure} slot-ref-using-class class obj slot_name
1850 @deffnx {C Function} scm_slot_ref_using_class (class, obj, slot_name)
1854 \fslot-set-using-class!
1855 @c snarfed from goops.c:1238
1856 @deffn {Scheme Procedure} slot-set-using-class! class obj slot_name value
1857 @deffnx {C Function} scm_slot_set_using_class_x (class, obj, slot_name, value)
1861 \fslot-bound-using-class?
1862 @c snarfed from goops.c:1252
1863 @deffn {Scheme Procedure} slot-bound-using-class? class obj slot_name
1864 @deffnx {C Function} scm_slot_bound_using_class_p (class, obj, slot_name)
1868 \fslot-exists-using-class?
1869 @c snarfed from goops.c:1267
1870 @deffn {Scheme Procedure} slot-exists-using-class? class obj slot_name
1871 @deffnx {C Function} scm_slot_exists_using_class_p (class, obj, slot_name)
1876 @c snarfed from goops.c:1283
1877 @deffn {Scheme Procedure} slot-ref obj slot_name
1878 @deffnx {C Function} scm_slot_ref (obj, slot_name)
1879 Return the value from @var{obj}'s slot with the name
1884 @c snarfed from goops.c:1300
1885 @deffn {Scheme Procedure} slot-set! obj slot_name value
1886 @deffnx {C Function} scm_slot_set_x (obj, slot_name, value)
1887 Set the slot named @var{slot_name} of @var{obj} to @var{value}.
1891 @c snarfed from goops.c:1317
1892 @deffn {Scheme Procedure} slot-bound? obj slot_name
1893 @deffnx {C Function} scm_slot_bound_p (obj, slot_name)
1894 Return @code{#t} if the slot named @var{slot_name} of @var{obj}
1899 @c snarfed from goops.c:1335
1900 @deffn {Scheme Procedure} slot-exists? obj slot_name
1901 @deffnx {C Function} scm_slot_exists_p (obj, slot_name)
1902 Return @code{#t} if @var{obj} has a slot named @var{slot_name}.
1905 \f%allocate-instance
1906 @c snarfed from goops.c:1374
1907 @deffn {Scheme Procedure} %allocate-instance class initargs
1908 @deffnx {C Function} scm_sys_allocate_instance (class, initargs)
1909 Create a new instance of class @var{class} and initialize it
1910 from the arguments @var{initargs}.
1913 \f%set-object-setter!
1914 @c snarfed from goops.c:1444
1915 @deffn {Scheme Procedure} %set-object-setter! obj setter
1916 @deffnx {C Function} scm_sys_set_object_setter_x (obj, setter)
1921 @c snarfed from goops.c:1469
1922 @deffn {Scheme Procedure} %modify-instance old new
1923 @deffnx {C Function} scm_sys_modify_instance (old, new)
1928 @c snarfed from goops.c:1495
1929 @deffn {Scheme Procedure} %modify-class old new
1930 @deffnx {C Function} scm_sys_modify_class (old, new)
1935 @c snarfed from goops.c:1519
1936 @deffn {Scheme Procedure} %invalidate-class class
1937 @deffnx {C Function} scm_sys_invalidate_class (class)
1941 \f%invalidate-method-cache!
1942 @c snarfed from goops.c:1641
1943 @deffn {Scheme Procedure} %invalidate-method-cache! gf
1944 @deffnx {C Function} scm_sys_invalidate_method_cache_x (gf)
1948 \fgeneric-capability?
1949 @c snarfed from goops.c:1667
1950 @deffn {Scheme Procedure} generic-capability? proc
1951 @deffnx {C Function} scm_generic_capability_p (proc)
1955 \fenable-primitive-generic!
1956 @c snarfed from goops.c:1680
1957 @deffn {Scheme Procedure} enable-primitive-generic! . subrs
1958 @deffnx {C Function} scm_enable_primitive_generic_x (subrs)
1962 \fprimitive-generic-generic
1963 @c snarfed from goops.c:1701
1964 @deffn {Scheme Procedure} primitive-generic-generic subr
1965 @deffnx {C Function} scm_primitive_generic_generic (subr)
1970 @c snarfed from goops.c:2069
1971 @deffn {Scheme Procedure} make . args
1972 @deffnx {C Function} scm_make (args)
1973 Make a new object. @var{args} must contain the class and
1974 all necessary initialization information.
1978 @c snarfed from goops.c:2158
1979 @deffn {Scheme Procedure} find-method . l
1980 @deffnx {C Function} scm_find_method (l)
1984 \f%method-more-specific?
1985 @c snarfed from goops.c:2178
1986 @deffn {Scheme Procedure} %method-more-specific? m1 m2 targs
1987 @deffnx {C Function} scm_sys_method_more_specific_p (m1, m2, targs)
1992 @c snarfed from goops.c:2793
1993 @deffn {Scheme Procedure} %goops-loaded
1994 @deffnx {C Function} scm_sys_goops_loaded ()
1995 Announce that GOOPS is loaded and perform initialization
1996 on the C level which depends on the loaded GOOPS modules.
2000 @c snarfed from guardians.c:306
2001 @deffn {Scheme Procedure} make-guardian [greedy_p]
2002 @deffnx {C Function} scm_make_guardian (greedy_p)
2003 Create a new guardian.
2004 A guardian protects a set of objects from garbage collection,
2005 allowing a program to apply cleanup or other actions.
2007 @code{make-guardian} returns a procedure representing the guardian.
2008 Calling the guardian procedure with an argument adds the
2009 argument to the guardian's set of protected objects.
2010 Calling the guardian procedure without an argument returns
2011 one of the protected objects which are ready for garbage
2012 collection, or @code{#f} if no such object is available.
2013 Objects which are returned in this way are removed from
2016 @code{make-guardian} takes one optional argument that says whether the
2017 new guardian should be greedy or sharing. If there is any chance
2018 that any object protected by the guardian may be resurrected,
2019 then you should make the guardian greedy (this is the default).
2021 See R. Kent Dybvig, Carl Bruggeman, and David Eby (1993)
2022 "Guardians in a Generation-Based Garbage Collector".
2023 ACM SIGPLAN Conference on Programming Language Design
2024 and Implementation, June 1993.
2026 (the semantics are slightly different at this point, but the
2027 paper still (mostly) accurately describes the interface).
2030 \fguardian-destroyed?
2031 @c snarfed from guardians.c:334
2032 @deffn {Scheme Procedure} guardian-destroyed? guardian
2033 @deffnx {C Function} scm_guardian_destroyed_p (guardian)
2034 Return @code{#t} if @var{guardian} has been destroyed, otherwise @code{#f}.
2038 @c snarfed from guardians.c:352
2039 @deffn {Scheme Procedure} guardian-greedy? guardian
2040 @deffnx {C Function} scm_guardian_greedy_p (guardian)
2041 Return @code{#t} if @var{guardian} is a greedy guardian, otherwise @code{#f}.
2045 @c snarfed from guardians.c:363
2046 @deffn {Scheme Procedure} destroy-guardian! guardian
2047 @deffnx {C Function} scm_destroy_guardian_x (guardian)
2048 Destroys @var{guardian}, by making it impossible to put any more
2049 objects in it or get any objects from it. It also unguards any
2050 objects guarded by @var{guardian}.
2054 @c snarfed from hash.c:176
2055 @deffn {Scheme Procedure} hashq key size
2056 @deffnx {C Function} scm_hashq (key, size)
2057 Determine a hash value for @var{key} that is suitable for
2058 lookups in a hashtable of size @var{size}, where @code{eq?} is
2059 used as the equality predicate. The function returns an
2060 integer in the range 0 to @var{size} - 1. Note that
2061 @code{hashq} may use internal addresses. Thus two calls to
2062 hashq where the keys are @code{eq?} are not guaranteed to
2063 deliver the same value if the key object gets garbage collected
2064 in between. This can happen, for example with symbols:
2065 @code{(hashq 'foo n) (gc) (hashq 'foo n)} may produce two
2066 different values, since @code{foo} will be garbage collected.
2070 @c snarfed from hash.c:212
2071 @deffn {Scheme Procedure} hashv key size
2072 @deffnx {C Function} scm_hashv (key, size)
2073 Determine a hash value for @var{key} that is suitable for
2074 lookups in a hashtable of size @var{size}, where @code{eqv?} is
2075 used as the equality predicate. The function returns an
2076 integer in the range 0 to @var{size} - 1. Note that
2077 @code{(hashv key)} may use internal addresses. Thus two calls
2078 to hashv where the keys are @code{eqv?} are not guaranteed to
2079 deliver the same value if the key object gets garbage collected
2080 in between. This can happen, for example with symbols:
2081 @code{(hashv 'foo n) (gc) (hashv 'foo n)} may produce two
2082 different values, since @code{foo} will be garbage collected.
2086 @c snarfed from hash.c:235
2087 @deffn {Scheme Procedure} hash key size
2088 @deffnx {C Function} scm_hash (key, size)
2089 Determine a hash value for @var{key} that is suitable for
2090 lookups in a hashtable of size @var{size}, where @code{equal?}
2091 is used as the equality predicate. The function returns an
2092 integer in the range 0 to @var{size} - 1.
2096 @c snarfed from hashtab.c:309
2097 @deffn {Scheme Procedure} make-hash-table [n]
2098 @deffnx {C Function} scm_make_hash_table (n)
2099 Make a hash table with optional minimum number of buckets @var{n}
2103 \fmake-weak-key-hash-table
2104 @c snarfed from hashtab.c:328
2105 @deffn {Scheme Procedure} make-weak-key-hash-table [n]
2106 @deffnx {Scheme Procedure} make-weak-value-hash-table size
2107 @deffnx {Scheme Procedure} make-doubly-weak-hash-table size
2108 @deffnx {C Function} scm_make_weak_key_hash_table (n)
2109 Return a weak hash table with @var{size} buckets. As with any
2110 hash table, choosing a good size for the table requires some
2113 You can modify weak hash tables in exactly the same way you
2114 would modify regular hash tables. (@pxref{Hash Tables})
2117 \fmake-weak-value-hash-table
2118 @c snarfed from hashtab.c:343
2119 @deffn {Scheme Procedure} make-weak-value-hash-table [n]
2120 @deffnx {C Function} scm_make_weak_value_hash_table (n)
2121 Return a hash table with weak values with @var{size} buckets.
2122 (@pxref{Hash Tables})
2125 \fmake-doubly-weak-hash-table
2126 @c snarfed from hashtab.c:360
2127 @deffn {Scheme Procedure} make-doubly-weak-hash-table n
2128 @deffnx {C Function} scm_make_doubly_weak_hash_table (n)
2129 Return a hash table with weak keys and values with @var{size}
2130 buckets. (@pxref{Hash Tables})
2134 @c snarfed from hashtab.c:379
2135 @deffn {Scheme Procedure} hash-table? obj
2136 @deffnx {C Function} scm_hash_table_p (obj)
2137 Return @code{#t} if @var{obj} is a hash table.
2140 \fweak-key-hash-table?
2141 @c snarfed from hashtab.c:393
2142 @deffn {Scheme Procedure} weak-key-hash-table? obj
2143 @deffnx {Scheme Procedure} weak-value-hash-table? obj
2144 @deffnx {Scheme Procedure} doubly-weak-hash-table? obj
2145 @deffnx {C Function} scm_weak_key_hash_table_p (obj)
2146 Return @code{#t} if @var{obj} is the specified weak hash
2147 table. Note that a doubly weak hash table is neither a weak key
2148 nor a weak value hash table.
2151 \fweak-value-hash-table?
2152 @c snarfed from hashtab.c:403
2153 @deffn {Scheme Procedure} weak-value-hash-table? obj
2154 @deffnx {C Function} scm_weak_value_hash_table_p (obj)
2155 Return @code{#t} if @var{obj} is a weak value hash table.
2158 \fdoubly-weak-hash-table?
2159 @c snarfed from hashtab.c:413
2160 @deffn {Scheme Procedure} doubly-weak-hash-table? obj
2161 @deffnx {C Function} scm_doubly_weak_hash_table_p (obj)
2162 Return @code{#t} if @var{obj} is a doubly weak hash table.
2166 @c snarfed from hashtab.c:550
2167 @deffn {Scheme Procedure} hash-clear! table
2168 @deffnx {C Function} scm_hash_clear_x (table)
2169 Remove all items from TABLE (without triggering a resize).
2173 @c snarfed from hashtab.c:567
2174 @deffn {Scheme Procedure} hashq-get-handle table key
2175 @deffnx {C Function} scm_hashq_get_handle (table, key)
2176 This procedure returns the @code{(key . value)} pair from the
2177 hash table @var{table}. If @var{table} does not hold an
2178 associated value for @var{key}, @code{#f} is returned.
2179 Uses @code{eq?} for equality testing.
2182 \fhashq-create-handle!
2183 @c snarfed from hashtab.c:579
2184 @deffn {Scheme Procedure} hashq-create-handle! table key init
2185 @deffnx {C Function} scm_hashq_create_handle_x (table, key, init)
2186 This function looks up @var{key} in @var{table} and returns its handle.
2187 If @var{key} is not already present, a new handle is created which
2188 associates @var{key} with @var{init}.
2192 @c snarfed from hashtab.c:592
2193 @deffn {Scheme Procedure} hashq-ref table key [dflt]
2194 @deffnx {C Function} scm_hashq_ref (table, key, dflt)
2195 Look up @var{key} in the hash table @var{table}, and return the
2196 value (if any) associated with it. If @var{key} is not found,
2197 return @var{default} (or @code{#f} if no @var{default} argument
2198 is supplied). Uses @code{eq?} for equality testing.
2202 @c snarfed from hashtab.c:606
2203 @deffn {Scheme Procedure} hashq-set! table key val
2204 @deffnx {C Function} scm_hashq_set_x (table, key, val)
2205 Find the entry in @var{table} associated with @var{key}, and
2206 store @var{value} there. Uses @code{eq?} for equality testing.
2210 @c snarfed from hashtab.c:618
2211 @deffn {Scheme Procedure} hashq-remove! table key
2212 @deffnx {C Function} scm_hashq_remove_x (table, key)
2213 Remove @var{key} (and any value associated with it) from
2214 @var{table}. Uses @code{eq?} for equality tests.
2218 @c snarfed from hashtab.c:634
2219 @deffn {Scheme Procedure} hashv-get-handle table key
2220 @deffnx {C Function} scm_hashv_get_handle (table, key)
2221 This procedure returns the @code{(key . value)} pair from the
2222 hash table @var{table}. If @var{table} does not hold an
2223 associated value for @var{key}, @code{#f} is returned.
2224 Uses @code{eqv?} for equality testing.
2227 \fhashv-create-handle!
2228 @c snarfed from hashtab.c:646
2229 @deffn {Scheme Procedure} hashv-create-handle! table key init
2230 @deffnx {C Function} scm_hashv_create_handle_x (table, key, init)
2231 This function looks up @var{key} in @var{table} and returns its handle.
2232 If @var{key} is not already present, a new handle is created which
2233 associates @var{key} with @var{init}.
2237 @c snarfed from hashtab.c:660
2238 @deffn {Scheme Procedure} hashv-ref table key [dflt]
2239 @deffnx {C Function} scm_hashv_ref (table, key, dflt)
2240 Look up @var{key} in the hash table @var{table}, and return the
2241 value (if any) associated with it. If @var{key} is not found,
2242 return @var{default} (or @code{#f} if no @var{default} argument
2243 is supplied). Uses @code{eqv?} for equality testing.
2247 @c snarfed from hashtab.c:674
2248 @deffn {Scheme Procedure} hashv-set! table key val
2249 @deffnx {C Function} scm_hashv_set_x (table, key, val)
2250 Find the entry in @var{table} associated with @var{key}, and
2251 store @var{value} there. Uses @code{eqv?} for equality testing.
2255 @c snarfed from hashtab.c:685
2256 @deffn {Scheme Procedure} hashv-remove! table key
2257 @deffnx {C Function} scm_hashv_remove_x (table, key)
2258 Remove @var{key} (and any value associated with it) from
2259 @var{table}. Uses @code{eqv?} for equality tests.
2263 @c snarfed from hashtab.c:700
2264 @deffn {Scheme Procedure} hash-get-handle table key
2265 @deffnx {C Function} scm_hash_get_handle (table, key)
2266 This procedure returns the @code{(key . value)} pair from the
2267 hash table @var{table}. If @var{table} does not hold an
2268 associated value for @var{key}, @code{#f} is returned.
2269 Uses @code{equal?} for equality testing.
2272 \fhash-create-handle!
2273 @c snarfed from hashtab.c:712
2274 @deffn {Scheme Procedure} hash-create-handle! table key init
2275 @deffnx {C Function} scm_hash_create_handle_x (table, key, init)
2276 This function looks up @var{key} in @var{table} and returns its handle.
2277 If @var{key} is not already present, a new handle is created which
2278 associates @var{key} with @var{init}.
2282 @c snarfed from hashtab.c:725
2283 @deffn {Scheme Procedure} hash-ref table key [dflt]
2284 @deffnx {C Function} scm_hash_ref (table, key, dflt)
2285 Look up @var{key} in the hash table @var{table}, and return the
2286 value (if any) associated with it. If @var{key} is not found,
2287 return @var{default} (or @code{#f} if no @var{default} argument
2288 is supplied). Uses @code{equal?} for equality testing.
2292 @c snarfed from hashtab.c:740
2293 @deffn {Scheme Procedure} hash-set! table key val
2294 @deffnx {C Function} scm_hash_set_x (table, key, val)
2295 Find the entry in @var{table} associated with @var{key}, and
2296 store @var{value} there. Uses @code{equal?} for equality
2301 @c snarfed from hashtab.c:752
2302 @deffn {Scheme Procedure} hash-remove! table key
2303 @deffnx {C Function} scm_hash_remove_x (table, key)
2304 Remove @var{key} (and any value associated with it) from
2305 @var{table}. Uses @code{equal?} for equality tests.
2309 @c snarfed from hashtab.c:805
2310 @deffn {Scheme Procedure} hashx-get-handle hash assoc table key
2311 @deffnx {C Function} scm_hashx_get_handle (hash, assoc, table, key)
2312 This behaves the same way as the corresponding
2313 @code{-get-handle} function, but uses @var{hash} as a hash
2314 function and @var{assoc} to compare keys. @code{hash} must be
2315 a function that takes two arguments, a key to be hashed and a
2316 table size. @code{assoc} must be an associator function, like
2317 @code{assoc}, @code{assq} or @code{assv}.
2320 \fhashx-create-handle!
2321 @c snarfed from hashtab.c:824
2322 @deffn {Scheme Procedure} hashx-create-handle! hash assoc table key init
2323 @deffnx {C Function} scm_hashx_create_handle_x (hash, assoc, table, key, init)
2324 This behaves the same way as the corresponding
2325 @code{-create-handle} function, but uses @var{hash} as a hash
2326 function and @var{assoc} to compare keys. @code{hash} must be
2327 a function that takes two arguments, a key to be hashed and a
2328 table size. @code{assoc} must be an associator function, like
2329 @code{assoc}, @code{assq} or @code{assv}.
2333 @c snarfed from hashtab.c:847
2334 @deffn {Scheme Procedure} hashx-ref hash assoc table key [dflt]
2335 @deffnx {C Function} scm_hashx_ref (hash, assoc, table, key, dflt)
2336 This behaves the same way as the corresponding @code{ref}
2337 function, but uses @var{hash} as a hash function and
2338 @var{assoc} to compare keys. @code{hash} must be a function
2339 that takes two arguments, a key to be hashed and a table size.
2340 @code{assoc} must be an associator function, like @code{assoc},
2341 @code{assq} or @code{assv}.
2343 By way of illustration, @code{hashq-ref table key} is
2344 equivalent to @code{hashx-ref hashq assq table key}.
2348 @c snarfed from hashtab.c:873
2349 @deffn {Scheme Procedure} hashx-set! hash assoc table key val
2350 @deffnx {C Function} scm_hashx_set_x (hash, assoc, table, key, val)
2351 This behaves the same way as the corresponding @code{set!}
2352 function, but uses @var{hash} as a hash function and
2353 @var{assoc} to compare keys. @code{hash} must be a function
2354 that takes two arguments, a key to be hashed and a table size.
2355 @code{assoc} must be an associator function, like @code{assoc},
2356 @code{assq} or @code{assv}.
2358 By way of illustration, @code{hashq-set! table key} is
2359 equivalent to @code{hashx-set! hashq assq table key}.
2363 @c snarfed from hashtab.c:975
2364 @deffn {Scheme Procedure} hash-fold proc init table
2365 @deffnx {C Function} scm_hash_fold (proc, init, table)
2366 An iterator over hash-table elements.
2367 Accumulates and returns a result by applying PROC successively.
2368 The arguments to PROC are "(key value prior-result)" where key
2369 and value are successive pairs from the hash table TABLE, and
2370 prior-result is either INIT (for the first application of PROC)
2371 or the return value of the previous application of PROC.
2372 For example, @code{(hash-fold acons '() tab)} will convert a hash
2373 table into an a-list of key-value pairs.
2377 @c snarfed from hashtab.c:996
2378 @deffn {Scheme Procedure} hash-for-each proc table
2379 @deffnx {C Function} scm_hash_for_each (proc, table)
2380 An iterator over hash-table elements.
2381 Applies PROC successively on all hash table items.
2382 The arguments to PROC are "(key value)" where key
2383 and value are successive pairs from the hash table TABLE.
2386 \fhash-for-each-handle
2387 @c snarfed from hashtab.c:1013
2388 @deffn {Scheme Procedure} hash-for-each-handle proc table
2389 @deffnx {C Function} scm_hash_for_each_handle (proc, table)
2390 An iterator over hash-table elements.
2391 Applies PROC successively on all hash table handles.
2395 @c snarfed from hashtab.c:1039
2396 @deffn {Scheme Procedure} hash-map->list proc table
2397 @deffnx {C Function} scm_hash_map_to_list (proc, table)
2398 An iterator over hash-table elements.
2399 Accumulates and returns as a list the results of applying PROC successively.
2400 The arguments to PROC are "(key value)" where key
2401 and value are successive pairs from the hash table TABLE.
2405 @c snarfed from hooks.c:154
2406 @deffn {Scheme Procedure} make-hook [n_args]
2407 @deffnx {C Function} scm_make_hook (n_args)
2408 Create a hook for storing procedure of arity @var{n_args}.
2409 @var{n_args} defaults to zero. The returned value is a hook
2410 object to be used with the other hook procedures.
2414 @c snarfed from hooks.c:171
2415 @deffn {Scheme Procedure} hook? x
2416 @deffnx {C Function} scm_hook_p (x)
2417 Return @code{#t} if @var{x} is a hook, @code{#f} otherwise.
2421 @c snarfed from hooks.c:182
2422 @deffn {Scheme Procedure} hook-empty? hook
2423 @deffnx {C Function} scm_hook_empty_p (hook)
2424 Return @code{#t} if @var{hook} is an empty hook, @code{#f}
2429 @c snarfed from hooks.c:196
2430 @deffn {Scheme Procedure} add-hook! hook proc [append_p]
2431 @deffnx {C Function} scm_add_hook_x (hook, proc, append_p)
2432 Add the procedure @var{proc} to the hook @var{hook}. The
2433 procedure is added to the end if @var{append_p} is true,
2434 otherwise it is added to the front. The return value of this
2435 procedure is not specified.
2439 @c snarfed from hooks.c:223
2440 @deffn {Scheme Procedure} remove-hook! hook proc
2441 @deffnx {C Function} scm_remove_hook_x (hook, proc)
2442 Remove the procedure @var{proc} from the hook @var{hook}. The
2443 return value of this procedure is not specified.
2447 @c snarfed from hooks.c:237
2448 @deffn {Scheme Procedure} reset-hook! hook
2449 @deffnx {C Function} scm_reset_hook_x (hook)
2450 Remove all procedures from the hook @var{hook}. The return
2451 value of this procedure is not specified.
2455 @c snarfed from hooks.c:251
2456 @deffn {Scheme Procedure} run-hook hook . args
2457 @deffnx {C Function} scm_run_hook (hook, args)
2458 Apply all procedures from the hook @var{hook} to the arguments
2459 @var{args}. The order of the procedure application is first to
2460 last. The return value of this procedure is not specified.
2464 @c snarfed from hooks.c:278
2465 @deffn {Scheme Procedure} hook->list hook
2466 @deffnx {C Function} scm_hook_to_list (hook)
2467 Convert the procedure list of @var{hook} to a list.
2471 @c snarfed from i18n.c:90
2472 @deffn {Scheme Procedure} gettext msgid [domain [category]]
2473 @deffnx {C Function} scm_gettext (msgid, domain, category)
2474 Return the translation of @var{msgid} in the message domain @var{domain}. @var{domain} is optional and defaults to the domain set through (textdomain). @var{category} is optional and defaults to LC_MESSAGES.
2478 @c snarfed from i18n.c:146
2479 @deffn {Scheme Procedure} ngettext msgid msgid_plural n [domain [category]]
2480 @deffnx {C Function} scm_ngettext (msgid, msgid_plural, n, domain, category)
2481 Return the translation of @var{msgid}/@var{msgid_plural} in the message domain @var{domain}, with the plural form being chosen appropriately for the number @var{n}. @var{domain} is optional and defaults to the domain set through (textdomain). @var{category} is optional and defaults to LC_MESSAGES.
2485 @c snarfed from i18n.c:209
2486 @deffn {Scheme Procedure} textdomain [domainname]
2487 @deffnx {C Function} scm_textdomain (domainname)
2488 If optional parameter @var{domainname} is supplied, set the textdomain. Return the textdomain.
2492 @c snarfed from i18n.c:241
2493 @deffn {Scheme Procedure} bindtextdomain domainname [directory]
2494 @deffnx {C Function} scm_bindtextdomain (domainname, directory)
2495 If optional parameter @var{directory} is supplied, set message catalogs to directory @var{directory}. Return the directory bound to @var{domainname}.
2498 \fbind-textdomain-codeset
2499 @c snarfed from i18n.c:280
2500 @deffn {Scheme Procedure} bind-textdomain-codeset domainname [encoding]
2501 @deffnx {C Function} scm_bind_textdomain_codeset (domainname, encoding)
2502 If optional parameter @var{encoding} is supplied, set encoding for message catalogs of @var{domainname}. Return the encoding of @var{domainname}.
2506 @c snarfed from ioext.c:54
2507 @deffn {Scheme Procedure} ftell fd_port
2508 @deffnx {C Function} scm_ftell (fd_port)
2509 Return an integer representing the current position of
2510 @var{fd/port}, measured from the beginning. Equivalent to:
2513 (seek port 0 SEEK_CUR)
2518 @c snarfed from ioext.c:72
2519 @deffn {Scheme Procedure} redirect-port old new
2520 @deffnx {C Function} scm_redirect_port (old, new)
2521 This procedure takes two ports and duplicates the underlying file
2522 descriptor from @var{old-port} into @var{new-port}. The
2523 current file descriptor in @var{new-port} will be closed.
2524 After the redirection the two ports will share a file position
2525 and file status flags.
2527 The return value is unspecified.
2529 Unexpected behaviour can result if both ports are subsequently used
2530 and the original and/or duplicate ports are buffered.
2532 This procedure does not have any side effects on other ports or
2537 @c snarfed from ioext.c:111
2538 @deffn {Scheme Procedure} dup->fdes fd_or_port [fd]
2539 @deffnx {C Function} scm_dup_to_fdes (fd_or_port, fd)
2540 Return a new integer file descriptor referring to the open file
2541 designated by @var{fd_or_port}, which must be either an open
2542 file port or a file descriptor.
2546 @c snarfed from ioext.c:158
2547 @deffn {Scheme Procedure} dup2 oldfd newfd
2548 @deffnx {C Function} scm_dup2 (oldfd, newfd)
2549 A simple wrapper for the @code{dup2} system call.
2550 Copies the file descriptor @var{oldfd} to descriptor
2551 number @var{newfd}, replacing the previous meaning
2552 of @var{newfd}. Both @var{oldfd} and @var{newfd} must
2554 Unlike for dup->fdes or primitive-move->fdes, no attempt
2555 is made to move away ports which are using @var{newfd}.
2556 The return value is unspecified.
2560 @c snarfed from ioext.c:177
2561 @deffn {Scheme Procedure} fileno port
2562 @deffnx {C Function} scm_fileno (port)
2563 Return the integer file descriptor underlying @var{port}. Does
2564 not change its revealed count.
2568 @c snarfed from ioext.c:197
2569 @deffn {Scheme Procedure} isatty? port
2570 @deffnx {C Function} scm_isatty_p (port)
2571 Return @code{#t} if @var{port} is using a serial non--file
2572 device, otherwise @code{#f}.
2576 @c snarfed from ioext.c:219
2577 @deffn {Scheme Procedure} fdopen fdes modes
2578 @deffnx {C Function} scm_fdopen (fdes, modes)
2579 Return a new port based on the file descriptor @var{fdes}.
2580 Modes are given by the string @var{modes}. The revealed count
2581 of the port is initialized to zero. The modes string is the
2582 same as that accepted by @ref{File Ports, open-file}.
2585 \fprimitive-move->fdes
2586 @c snarfed from ioext.c:241
2587 @deffn {Scheme Procedure} primitive-move->fdes port fd
2588 @deffnx {C Function} scm_primitive_move_to_fdes (port, fd)
2589 Moves the underlying file descriptor for @var{port} to the integer
2590 value @var{fdes} without changing the revealed count of @var{port}.
2591 Any other ports already using this descriptor will be automatically
2592 shifted to new descriptors and their revealed counts reset to zero.
2593 The return value is @code{#f} if the file descriptor already had the
2594 required value or @code{#t} if it was moved.
2598 @c snarfed from ioext.c:274
2599 @deffn {Scheme Procedure} fdes->ports fd
2600 @deffnx {C Function} scm_fdes_to_ports (fd)
2601 Return a list of existing ports which have @var{fdes} as an
2602 underlying file descriptor, without changing their revealed
2606 \fmake-keyword-from-dash-symbol
2607 @c snarfed from keywords.c:52
2608 @deffn {Scheme Procedure} make-keyword-from-dash-symbol symbol
2609 @deffnx {C Function} scm_make_keyword_from_dash_symbol (symbol)
2610 Make a keyword object from a @var{symbol} that starts with a dash.
2614 @c snarfed from keywords.c:91
2615 @deffn {Scheme Procedure} keyword? obj
2616 @deffnx {C Function} scm_keyword_p (obj)
2617 Return @code{#t} if the argument @var{obj} is a keyword, else
2621 \fkeyword-dash-symbol
2622 @c snarfed from keywords.c:102
2623 @deffn {Scheme Procedure} keyword-dash-symbol keyword
2624 @deffnx {C Function} scm_keyword_dash_symbol (keyword)
2625 Return the dash symbol for @var{keyword}.
2626 This is the inverse of @code{make-keyword-from-dash-symbol}.
2630 @c snarfed from list.c:104
2631 @deffn {Scheme Procedure} list . objs
2632 @deffnx {C Function} scm_list (objs)
2633 Return a list containing @var{objs}, the arguments to
2638 @c snarfed from list.c:119
2639 @deffn {Scheme Procedure} cons* arg . rest
2640 @deffnx {C Function} scm_cons_star (arg, rest)
2641 Like @code{list}, but the last arg provides the tail of the
2642 constructed list, returning @code{(cons @var{arg1} (cons
2643 @var{arg2} (cons @dots{} @var{argn})))}. Requires at least one
2644 argument. If given one argument, that argument is returned as
2645 result. This function is called @code{list*} in some other
2646 Schemes and in Common LISP.
2650 @c snarfed from list.c:143
2651 @deffn {Scheme Procedure} null? x
2652 @deffnx {C Function} scm_null_p (x)
2653 Return @code{#t} iff @var{x} is the empty list, else @code{#f}.
2657 @c snarfed from list.c:153
2658 @deffn {Scheme Procedure} list? x
2659 @deffnx {C Function} scm_list_p (x)
2660 Return @code{#t} iff @var{x} is a proper list, else @code{#f}.
2664 @c snarfed from list.c:194
2665 @deffn {Scheme Procedure} length lst
2666 @deffnx {C Function} scm_length (lst)
2667 Return the number of elements in list @var{lst}.
2671 @c snarfed from list.c:223
2672 @deffn {Scheme Procedure} append . args
2673 @deffnx {C Function} scm_append (args)
2674 Return a list consisting of the elements the lists passed as
2677 (append '(x) '(y)) @result{} (x y)
2678 (append '(a) '(b c d)) @result{} (a b c d)
2679 (append '(a (b)) '((c))) @result{} (a (b) (c))
2681 The resulting list is always newly allocated, except that it
2682 shares structure with the last list argument. The last
2683 argument may actually be any object; an improper list results
2684 if the last argument is not a proper list.
2686 (append '(a b) '(c . d)) @result{} (a b c . d)
2687 (append '() 'a) @result{} a
2692 @c snarfed from list.c:259
2693 @deffn {Scheme Procedure} append! . lists
2694 @deffnx {C Function} scm_append_x (lists)
2695 A destructive version of @code{append} (@pxref{Pairs and
2696 Lists,,,r5rs, The Revised^5 Report on Scheme}). The cdr field
2697 of each list's final pair is changed to point to the head of
2698 the next list, so no consing is performed. Return
2703 @c snarfed from list.c:291
2704 @deffn {Scheme Procedure} last-pair lst
2705 @deffnx {C Function} scm_last_pair (lst)
2706 Return the last pair in @var{lst}, signalling an error if
2707 @var{lst} is circular.
2711 @c snarfed from list.c:321
2712 @deffn {Scheme Procedure} reverse lst
2713 @deffnx {C Function} scm_reverse (lst)
2714 Return a new list that contains the elements of @var{lst} but
2719 @c snarfed from list.c:355
2720 @deffn {Scheme Procedure} reverse! lst [new_tail]
2721 @deffnx {C Function} scm_reverse_x (lst, new_tail)
2722 A destructive version of @code{reverse} (@pxref{Pairs and Lists,,,r5rs,
2723 The Revised^5 Report on Scheme}). The cdr of each cell in @var{lst} is
2724 modified to point to the previous list element. Return the
2727 Caveat: because the list is modified in place, the tail of the original
2728 list now becomes its head, and the head of the original list now becomes
2729 the tail. Therefore, the @var{lst} symbol to which the head of the
2730 original list was bound now points to the tail. To ensure that the head
2731 of the modified list is not lost, it is wise to save the return value of
2736 @c snarfed from list.c:381
2737 @deffn {Scheme Procedure} list-ref list k
2738 @deffnx {C Function} scm_list_ref (list, k)
2739 Return the @var{k}th element from @var{list}.
2743 @c snarfed from list.c:405
2744 @deffn {Scheme Procedure} list-set! list k val
2745 @deffnx {C Function} scm_list_set_x (list, k, val)
2746 Set the @var{k}th element of @var{list} to @var{val}.
2750 @c snarfed from list.c:427
2751 @deffn {Scheme Procedure} list-cdr-ref
2752 implemented by the C function "scm_list_tail"
2756 @c snarfed from list.c:436
2757 @deffn {Scheme Procedure} list-tail lst k
2758 @deffnx {Scheme Procedure} list-cdr-ref lst k
2759 @deffnx {C Function} scm_list_tail (lst, k)
2760 Return the "tail" of @var{lst} beginning with its @var{k}th element.
2761 The first element of the list is considered to be element 0.
2763 @code{list-tail} and @code{list-cdr-ref} are identical. It may help to
2764 think of @code{list-cdr-ref} as accessing the @var{k}th cdr of the list,
2765 or returning the results of cdring @var{k} times down @var{lst}.
2769 @c snarfed from list.c:451
2770 @deffn {Scheme Procedure} list-cdr-set! list k val
2771 @deffnx {C Function} scm_list_cdr_set_x (list, k, val)
2772 Set the @var{k}th cdr of @var{list} to @var{val}.
2776 @c snarfed from list.c:479
2777 @deffn {Scheme Procedure} list-head lst k
2778 @deffnx {C Function} scm_list_head (lst, k)
2779 Copy the first @var{k} elements from @var{lst} into a new list, and
2784 @c snarfed from list.c:530
2785 @deffn {Scheme Procedure} list-copy lst
2786 @deffnx {C Function} scm_list_copy (lst)
2787 Return a (newly-created) copy of @var{lst}.
2791 @c snarfed from list.c:584
2792 @deffn {Scheme Procedure} memq x lst
2793 @deffnx {C Function} scm_memq (x, lst)
2794 Return the first sublist of @var{lst} whose car is @code{eq?}
2795 to @var{x} where the sublists of @var{lst} are the non-empty
2796 lists returned by @code{(list-tail @var{lst} @var{k})} for
2797 @var{k} less than the length of @var{lst}. If @var{x} does not
2798 occur in @var{lst}, then @code{#f} (not the empty list) is
2803 @c snarfed from list.c:600
2804 @deffn {Scheme Procedure} memv x lst
2805 @deffnx {C Function} scm_memv (x, lst)
2806 Return the first sublist of @var{lst} whose car is @code{eqv?}
2807 to @var{x} where the sublists of @var{lst} are the non-empty
2808 lists returned by @code{(list-tail @var{lst} @var{k})} for
2809 @var{k} less than the length of @var{lst}. If @var{x} does not
2810 occur in @var{lst}, then @code{#f} (not the empty list) is
2815 @c snarfed from list.c:621
2816 @deffn {Scheme Procedure} member x lst
2817 @deffnx {C Function} scm_member (x, lst)
2818 Return the first sublist of @var{lst} whose car is
2819 @code{equal?} to @var{x} where the sublists of @var{lst} are
2820 the non-empty lists returned by @code{(list-tail @var{lst}
2821 @var{k})} for @var{k} less than the length of @var{lst}. If
2822 @var{x} does not occur in @var{lst}, then @code{#f} (not the
2823 empty list) is returned.
2827 @c snarfed from list.c:646
2828 @deffn {Scheme Procedure} delq! item lst
2829 @deffnx {Scheme Procedure} delv! item lst
2830 @deffnx {Scheme Procedure} delete! item lst
2831 @deffnx {C Function} scm_delq_x (item, lst)
2832 These procedures are destructive versions of @code{delq}, @code{delv}
2833 and @code{delete}: they modify the existing @var{lst}
2834 rather than creating a new list. Caveat evaluator: Like other
2835 destructive list functions, these functions cannot modify the binding of
2836 @var{lst}, and so cannot be used to delete the first element of
2837 @var{lst} destructively.
2841 @c snarfed from list.c:670
2842 @deffn {Scheme Procedure} delv! item lst
2843 @deffnx {C Function} scm_delv_x (item, lst)
2844 Destructively remove all elements from @var{lst} that are
2845 @code{eqv?} to @var{item}.
2849 @c snarfed from list.c:695
2850 @deffn {Scheme Procedure} delete! item lst
2851 @deffnx {C Function} scm_delete_x (item, lst)
2852 Destructively remove all elements from @var{lst} that are
2853 @code{equal?} to @var{item}.
2857 @c snarfed from list.c:724
2858 @deffn {Scheme Procedure} delq item lst
2859 @deffnx {C Function} scm_delq (item, lst)
2860 Return a newly-created copy of @var{lst} with elements
2861 @code{eq?} to @var{item} removed. This procedure mirrors
2862 @code{memq}: @code{delq} compares elements of @var{lst} against
2863 @var{item} with @code{eq?}.
2867 @c snarfed from list.c:737
2868 @deffn {Scheme Procedure} delv item lst
2869 @deffnx {C Function} scm_delv (item, lst)
2870 Return a newly-created copy of @var{lst} with elements
2871 @code{eqv?} to @var{item} removed. This procedure mirrors
2872 @code{memv}: @code{delv} compares elements of @var{lst} against
2873 @var{item} with @code{eqv?}.
2877 @c snarfed from list.c:750
2878 @deffn {Scheme Procedure} delete item lst
2879 @deffnx {C Function} scm_delete (item, lst)
2880 Return a newly-created copy of @var{lst} with elements
2881 @code{equal?} to @var{item} removed. This procedure mirrors
2882 @code{member}: @code{delete} compares elements of @var{lst}
2883 against @var{item} with @code{equal?}.
2887 @c snarfed from list.c:763
2888 @deffn {Scheme Procedure} delq1! item lst
2889 @deffnx {C Function} scm_delq1_x (item, lst)
2890 Like @code{delq!}, but only deletes the first occurrence of
2891 @var{item} from @var{lst}. Tests for equality using
2892 @code{eq?}. See also @code{delv1!} and @code{delete1!}.
2896 @c snarfed from list.c:791
2897 @deffn {Scheme Procedure} delv1! item lst
2898 @deffnx {C Function} scm_delv1_x (item, lst)
2899 Like @code{delv!}, but only deletes the first occurrence of
2900 @var{item} from @var{lst}. Tests for equality using
2901 @code{eqv?}. See also @code{delq1!} and @code{delete1!}.
2905 @c snarfed from list.c:819
2906 @deffn {Scheme Procedure} delete1! item lst
2907 @deffnx {C Function} scm_delete1_x (item, lst)
2908 Like @code{delete!}, but only deletes the first occurrence of
2909 @var{item} from @var{lst}. Tests for equality using
2910 @code{equal?}. See also @code{delq1!} and @code{delv1!}.
2914 @c snarfed from list.c:851
2915 @deffn {Scheme Procedure} filter pred list
2916 @deffnx {C Function} scm_filter (pred, list)
2917 Return all the elements of 2nd arg @var{list} that satisfy predicate @var{pred}.
2918 The list is not disordered -- elements that appear in the result list occur
2919 in the same order as they occur in the argument list. The returned list may
2920 share a common tail with the argument list. The dynamic order in which the
2921 various applications of pred are made is not specified.
2924 (filter even? '(0 7 8 8 43 -4)) => (0 8 8 -4)
2929 @c snarfed from list.c:878
2930 @deffn {Scheme Procedure} filter! pred list
2931 @deffnx {C Function} scm_filter_x (pred, list)
2932 Linear-update variant of @code{filter}.
2936 @c snarfed from load.c:94
2937 @deffn {Scheme Procedure} primitive-load filename
2938 @deffnx {C Function} scm_primitive_load (filename)
2939 Load the file named @var{filename} and evaluate its contents in
2940 the top-level environment. The load paths are not searched;
2941 @var{filename} must either be a full pathname or be a pathname
2942 relative to the current directory. If the variable
2943 @code{%load-hook} is defined, it should be bound to a procedure
2944 that will be called before any code is loaded. See the
2945 documentation for @code{%load-hook} later in this section.
2949 @c snarfed from load.c:134
2950 @deffn {Scheme Procedure} %package-data-dir
2951 @deffnx {C Function} scm_sys_package_data_dir ()
2952 Return the name of the directory where Scheme packages, modules and
2953 libraries are kept. On most Unix systems, this will be
2954 @samp{/usr/local/share/guile}.
2958 @c snarfed from load.c:146
2959 @deffn {Scheme Procedure} %library-dir
2960 @deffnx {C Function} scm_sys_library_dir ()
2961 Return the directory where the Guile Scheme library files are installed.
2962 E.g., may return "/usr/share/guile/1.3.5".
2966 @c snarfed from load.c:158
2967 @deffn {Scheme Procedure} %site-dir
2968 @deffnx {C Function} scm_sys_site_dir ()
2969 Return the directory where the Guile site files are installed.
2970 E.g., may return "/usr/share/guile/site".
2974 @c snarfed from load.c:183
2975 @deffn {Scheme Procedure} parse-path path [tail]
2976 @deffnx {C Function} scm_parse_path (path, tail)
2977 Parse @var{path}, which is expected to be a colon-separated
2978 string, into a list and return the resulting list with
2979 @var{tail} appended. If @var{path} is @code{#f}, @var{tail}
2984 @c snarfed from load.c:310
2985 @deffn {Scheme Procedure} search-path path filename [extensions]
2986 @deffnx {C Function} scm_search_path (path, filename, extensions)
2987 Search @var{path} for a directory containing a file named
2988 @var{filename}. The file must be readable, and not a directory.
2989 If we find one, return its full filename; otherwise, return
2990 @code{#f}. If @var{filename} is absolute, return it unchanged.
2991 If given, @var{extensions} is a list of strings; for each
2992 directory in @var{path}, we search for @var{filename}
2993 concatenated with each @var{extension}.
2997 @c snarfed from load.c:447
2998 @deffn {Scheme Procedure} %search-load-path filename
2999 @deffnx {C Function} scm_sys_search_load_path (filename)
3000 Search @var{%load-path} for the file named @var{filename},
3001 which must be readable by the current user. If @var{filename}
3002 is found in the list of paths to search or is an absolute
3003 pathname, return its full pathname. Otherwise, return
3004 @code{#f}. Filenames may have any of the optional extensions
3005 in the @code{%load-extensions} list; @code{%search-load-path}
3006 will try each extension automatically.
3009 \fprimitive-load-path
3010 @c snarfed from load.c:468
3011 @deffn {Scheme Procedure} primitive-load-path filename
3012 @deffnx {C Function} scm_primitive_load_path (filename)
3013 Search @var{%load-path} for the file named @var{filename} and
3014 load it into the top-level environment. If @var{filename} is a
3015 relative pathname and is not found in the list of search paths,
3016 an error is signalled.
3019 \fprocedure->memoizing-macro
3020 @c snarfed from macros.c:109
3021 @deffn {Scheme Procedure} procedure->memoizing-macro code
3022 @deffnx {C Function} scm_makmmacro (code)
3023 Return a @dfn{macro} which, when a symbol defined to this value
3024 appears as the first symbol in an expression, evaluates the
3025 result of applying @var{code} to the expression and the
3028 @code{procedure->memoizing-macro} is the same as
3029 @code{procedure->macro}, except that the expression returned by
3030 @var{code} replaces the original macro expression in the memoized
3031 form of the containing code.
3035 @c snarfed from macros.c:123
3036 @deffn {Scheme Procedure} procedure->syntax code
3037 @deffnx {C Function} scm_makacro (code)
3038 Return a @dfn{macro} which, when a symbol defined to this value
3039 appears as the first symbol in an expression, returns the
3040 result of applying @var{code} to the expression and the
3045 @c snarfed from macros.c:146
3046 @deffn {Scheme Procedure} procedure->macro code
3047 @deffnx {C Function} scm_makmacro (code)
3048 Return a @dfn{macro} which, when a symbol defined to this value
3049 appears as the first symbol in an expression, evaluates the
3050 result of applying @var{code} to the expression and the
3051 environment. For example:
3056 (lambda (x env) `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x))))))
3058 (trace @i{foo}) @equiv{} (set! @i{foo} (tracef @i{foo} '@i{foo})).
3063 @c snarfed from macros.c:165
3064 @deffn {Scheme Procedure} macro? obj
3065 @deffnx {C Function} scm_macro_p (obj)
3066 Return @code{#t} if @var{obj} is a regular macro, a memoizing macro or a
3071 @c snarfed from macros.c:186
3072 @deffn {Scheme Procedure} macro-type m
3073 @deffnx {C Function} scm_macro_type (m)
3074 Return one of the symbols @code{syntax}, @code{macro} or
3075 @code{macro!}, depending on whether @var{m} is a syntax
3076 transformer, a regular macro, or a memoizing macro,
3077 respectively. If @var{m} is not a macro, @code{#f} is
3082 @c snarfed from macros.c:207
3083 @deffn {Scheme Procedure} macro-name m
3084 @deffnx {C Function} scm_macro_name (m)
3085 Return the name of the macro @var{m}.
3089 @c snarfed from macros.c:218
3090 @deffn {Scheme Procedure} macro-transformer m
3091 @deffnx {C Function} scm_macro_transformer (m)
3092 Return the transformer of the macro @var{m}.
3096 @c snarfed from modules.c:45
3097 @deffn {Scheme Procedure} current-module
3098 @deffnx {C Function} scm_current_module ()
3099 Return the current module.
3102 \fset-current-module
3103 @c snarfed from modules.c:57
3104 @deffn {Scheme Procedure} set-current-module module
3105 @deffnx {C Function} scm_set_current_module (module)
3106 Set the current module to @var{module} and return
3107 the previous current module.
3110 \finteraction-environment
3111 @c snarfed from modules.c:80
3112 @deffn {Scheme Procedure} interaction-environment
3113 @deffnx {C Function} scm_interaction_environment ()
3114 Return a specifier for the environment that contains
3115 implementation--defined bindings, typically a superset of those
3116 listed in the report. The intent is that this procedure will
3117 return the environment in which the implementation would
3118 evaluate expressions dynamically typed by the user.
3122 @c snarfed from modules.c:261
3123 @deffn {Scheme Procedure} env-module env
3124 @deffnx {C Function} scm_env_module (env)
3125 Return the module of @var{ENV}, a lexical environment.
3128 \fstandard-eval-closure
3129 @c snarfed from modules.c:337
3130 @deffn {Scheme Procedure} standard-eval-closure module
3131 @deffnx {C Function} scm_standard_eval_closure (module)
3132 Return an eval closure for the module @var{module}.
3135 \fstandard-interface-eval-closure
3136 @c snarfed from modules.c:348
3137 @deffn {Scheme Procedure} standard-interface-eval-closure module
3138 @deffnx {C Function} scm_standard_interface_eval_closure (module)
3139 Return a interface eval closure for the module @var{module}. Such a closure does not allow new bindings to be added.
3142 \fmodule-import-interface
3143 @c snarfed from modules.c:394
3144 @deffn {Scheme Procedure} module-import-interface module sym
3145 @deffnx {C Function} scm_module_import_interface (module, sym)
3149 \f%get-pre-modules-obarray
3150 @c snarfed from modules.c:611
3151 @deffn {Scheme Procedure} %get-pre-modules-obarray
3152 @deffnx {C Function} scm_get_pre_modules_obarray ()
3153 Return the obarray that is used for all new bindings before the module system is booted. The first call to @code{set-current-module} will boot the module system.
3157 @c snarfed from numbers.c:460
3158 @deffn {Scheme Procedure} exact? x
3159 @deffnx {C Function} scm_exact_p (x)
3160 Return @code{#t} if @var{x} is an exact number, @code{#f}
3165 @c snarfed from numbers.c:479
3166 @deffn {Scheme Procedure} odd? n
3167 @deffnx {C Function} scm_odd_p (n)
3168 Return @code{#t} if @var{n} is an odd number, @code{#f}
3173 @c snarfed from numbers.c:514
3174 @deffn {Scheme Procedure} even? n
3175 @deffnx {C Function} scm_even_p (n)
3176 Return @code{#t} if @var{n} is an even number, @code{#f}
3181 @c snarfed from numbers.c:548
3182 @deffn {Scheme Procedure} inf? x
3183 @deffnx {C Function} scm_inf_p (x)
3184 Return @code{#t} if @var{x} is either @samp{+inf.0}
3185 or @samp{-inf.0}, @code{#f} otherwise.
3189 @c snarfed from numbers.c:564
3190 @deffn {Scheme Procedure} nan? n
3191 @deffnx {C Function} scm_nan_p (n)
3192 Return @code{#t} if @var{n} is a NaN, @code{#f}
3197 @c snarfed from numbers.c:634
3198 @deffn {Scheme Procedure} inf
3199 @deffnx {C Function} scm_inf ()
3204 @c snarfed from numbers.c:649
3205 @deffn {Scheme Procedure} nan
3206 @deffnx {C Function} scm_nan ()
3211 @c snarfed from numbers.c:665
3212 @deffn {Scheme Procedure} abs x
3213 @deffnx {C Function} scm_abs (x)
3214 Return the absolute value of @var{x}.
3218 @c snarfed from numbers.c:1200
3219 @deffn {Scheme Procedure} logand n1 n2
3220 Return the bitwise AND of the integer arguments.
3223 (logand) @result{} -1
3224 (logand 7) @result{} 7
3225 (logand #b111 #b011 #b001) @result{} 1
3230 @c snarfed from numbers.c:1276
3231 @deffn {Scheme Procedure} logior n1 n2
3232 Return the bitwise OR of the integer arguments.
3235 (logior) @result{} 0
3236 (logior 7) @result{} 7
3237 (logior #b000 #b001 #b011) @result{} 3
3242 @c snarfed from numbers.c:1352
3243 @deffn {Scheme Procedure} logxor n1 n2
3244 Return the bitwise XOR of the integer arguments. A bit is
3245 set in the result if it is set in an odd number of arguments.
3247 (logxor) @result{} 0
3248 (logxor 7) @result{} 7
3249 (logxor #b000 #b001 #b011) @result{} 2
3250 (logxor #b000 #b001 #b011 #b011) @result{} 1
3255 @c snarfed from numbers.c:1423
3256 @deffn {Scheme Procedure} logtest j k
3257 @deffnx {C Function} scm_logtest (j, k)
3259 (logtest j k) @equiv{} (not (zero? (logand j k)))
3261 (logtest #b0100 #b1011) @result{} #f
3262 (logtest #b0100 #b0111) @result{} #t
3267 @c snarfed from numbers.c:1494
3268 @deffn {Scheme Procedure} logbit? index j
3269 @deffnx {C Function} scm_logbit_p (index, j)
3271 (logbit? index j) @equiv{} (logtest (integer-expt 2 index) j)
3273 (logbit? 0 #b1101) @result{} #t
3274 (logbit? 1 #b1101) @result{} #f
3275 (logbit? 2 #b1101) @result{} #t
3276 (logbit? 3 #b1101) @result{} #t
3277 (logbit? 4 #b1101) @result{} #f
3282 @c snarfed from numbers.c:1528
3283 @deffn {Scheme Procedure} lognot n
3284 @deffnx {C Function} scm_lognot (n)
3285 Return the integer which is the ones-complement of the integer
3289 (number->string (lognot #b10000000) 2)
3290 @result{} "-10000001"
3291 (number->string (lognot #b0) 2)
3297 @c snarfed from numbers.c:1573
3298 @deffn {Scheme Procedure} modulo-expt n k m
3299 @deffnx {C Function} scm_modulo_expt (n, k, m)
3300 Return @var{n} raised to the integer exponent
3301 @var{k}, modulo @var{m}.
3310 @c snarfed from numbers.c:1678
3311 @deffn {Scheme Procedure} integer-expt n k
3312 @deffnx {C Function} scm_integer_expt (n, k)
3313 Return @var{n} raised to the exact integer exponent
3325 @c snarfed from numbers.c:1768
3326 @deffn {Scheme Procedure} ash n cnt
3327 @deffnx {C Function} scm_ash (n, cnt)
3328 Return @var{n} shifted left by @var{cnt} bits, or shifted right
3329 if @var{cnt} is negative. This is an ``arithmetic'' shift.
3331 This is effectively a multiplication by 2^@var{cnt}, and when
3332 @var{cnt} is negative it's a division, rounded towards negative
3333 infinity. (Note that this is not the same rounding as
3334 @code{quotient} does.)
3336 With @var{n} viewed as an infinite precision twos complement,
3337 @code{ash} means a left shift introducing zero bits, or a right
3338 shift dropping bits.
3341 (number->string (ash #b1 3) 2) @result{} "1000"
3342 (number->string (ash #b1010 -1) 2) @result{} "101"
3344 ;; -23 is bits ...11101001, -6 is bits ...111010
3345 (ash -23 -2) @result{} -6
3350 @c snarfed from numbers.c:1808
3351 @deffn {Scheme Procedure} bit-extract n start end
3352 @deffnx {C Function} scm_bit_extract (n, start, end)
3353 Return the integer composed of the @var{start} (inclusive)
3354 through @var{end} (exclusive) bits of @var{n}. The
3355 @var{start}th bit becomes the 0-th bit in the result.
3358 (number->string (bit-extract #b1101101010 0 4) 2)
3360 (number->string (bit-extract #b1101101010 4 9) 2)
3366 @c snarfed from numbers.c:1887
3367 @deffn {Scheme Procedure} logcount n
3368 @deffnx {C Function} scm_logcount (n)
3369 Return the number of bits in integer @var{n}. If integer is
3370 positive, the 1-bits in its binary representation are counted.
3371 If negative, the 0-bits in its two's-complement binary
3372 representation are counted. If 0, 0 is returned.
3375 (logcount #b10101010)
3385 @c snarfed from numbers.c:1935
3386 @deffn {Scheme Procedure} integer-length n
3387 @deffnx {C Function} scm_integer_length (n)
3388 Return the number of bits necessary to represent @var{n}.
3391 (integer-length #b10101010)
3395 (integer-length #b1111)
3401 @c snarfed from numbers.c:2258
3402 @deffn {Scheme Procedure} number->string n [radix]
3403 @deffnx {C Function} scm_number_to_string (n, radix)
3404 Return a string holding the external representation of the
3405 number @var{n} in the given @var{radix}. If @var{n} is
3406 inexact, a radix of 10 will be used.
3410 @c snarfed from numbers.c:2941
3411 @deffn {Scheme Procedure} string->number string [radix]
3412 @deffnx {C Function} scm_string_to_number (string, radix)
3413 Return a number of the maximally precise representation
3414 expressed by the given @var{string}. @var{radix} must be an
3415 exact integer, either 2, 8, 10, or 16. If supplied, @var{radix}
3416 is a default radix that may be overridden by an explicit radix
3417 prefix in @var{string} (e.g. "#o177"). If @var{radix} is not
3418 supplied, then the default radix is 10. If string is not a
3419 syntactically valid notation for a number, then
3420 @code{string->number} returns @code{#f}.
3424 @c snarfed from numbers.c:3004
3425 @deffn {Scheme Procedure} number? x
3426 @deffnx {C Function} scm_number_p (x)
3427 Return @code{#t} if @var{x} is a number, @code{#f}
3432 @c snarfed from numbers.c:3017
3433 @deffn {Scheme Procedure} complex? x
3434 @deffnx {C Function} scm_complex_p (x)
3435 Return @code{#t} if @var{x} is a complex number, @code{#f}
3436 otherwise. Note that the sets of real, rational and integer
3437 values form subsets of the set of complex numbers, i. e. the
3438 predicate will also be fulfilled if @var{x} is a real,
3439 rational or integer number.
3443 @c snarfed from numbers.c:3030
3444 @deffn {Scheme Procedure} real? x
3445 @deffnx {C Function} scm_real_p (x)
3446 Return @code{#t} if @var{x} is a real number, @code{#f}
3447 otherwise. Note that the set of integer values forms a subset of
3448 the set of real numbers, i. e. the predicate will also be
3449 fulfilled if @var{x} is an integer number.
3453 @c snarfed from numbers.c:3043
3454 @deffn {Scheme Procedure} rational? x
3455 @deffnx {C Function} scm_rational_p (x)
3456 Return @code{#t} if @var{x} is a rational number, @code{#f}
3457 otherwise. Note that the set of integer values forms a subset of
3458 the set of rational numbers, i. e. the predicate will also be
3459 fulfilled if @var{x} is an integer number.
3463 @c snarfed from numbers.c:3066
3464 @deffn {Scheme Procedure} integer? x
3465 @deffnx {C Function} scm_integer_p (x)
3466 Return @code{#t} if @var{x} is an integer number, @code{#f}
3471 @c snarfed from numbers.c:3092
3472 @deffn {Scheme Procedure} inexact? x
3473 @deffnx {C Function} scm_inexact_p (x)
3474 Return @code{#t} if @var{x} is an inexact number, @code{#f}
3479 @c snarfed from numbers.c:4939
3480 @deffn {Scheme Procedure} truncate x
3481 @deffnx {C Function} scm_truncate_number (x)
3482 Round the number @var{x} towards zero.
3486 @c snarfed from numbers.c:4955
3487 @deffn {Scheme Procedure} round x
3488 @deffnx {C Function} scm_round_number (x)
3489 Round the number @var{x} towards the nearest integer. When it is exactly halfway between two integers, round towards the even one.
3493 @c snarfed from numbers.c:4981
3494 @deffn {Scheme Procedure} floor x
3495 @deffnx {C Function} scm_floor (x)
3496 Round the number @var{x} towards minus infinity.
3500 @c snarfed from numbers.c:5012
3501 @deffn {Scheme Procedure} ceiling x
3502 @deffnx {C Function} scm_ceiling (x)
3503 Round the number @var{x} towards infinity.
3507 @c snarfed from numbers.c:5121
3508 @deffn {Scheme Procedure} $expt x y
3509 @deffnx {C Function} scm_sys_expt (x, y)
3510 Return @var{x} raised to the power of @var{y}. This
3511 procedure does not accept complex arguments.
3515 @c snarfed from numbers.c:5137
3516 @deffn {Scheme Procedure} $atan2 x y
3517 @deffnx {C Function} scm_sys_atan2 (x, y)
3518 Return the arc tangent of the two arguments @var{x} and
3519 @var{y}. This is similar to calculating the arc tangent of
3520 @var{x} / @var{y}, except that the signs of both arguments
3521 are used to determine the quadrant of the result. This
3522 procedure does not accept complex arguments.
3526 @c snarfed from numbers.c:5165
3527 @deffn {Scheme Procedure} make-rectangular real imaginary
3528 @deffnx {C Function} scm_make_rectangular (real, imaginary)
3529 Return a complex number constructed of the given @var{real} and
3530 @var{imaginary} parts.
3534 @c snarfed from numbers.c:5189
3535 @deffn {Scheme Procedure} make-polar x y
3536 @deffnx {C Function} scm_make_polar (x, y)
3537 Return the complex number @var{x} * e^(i * @var{y}).
3541 @c snarfed from numbers.c:5392
3542 @deffn {Scheme Procedure} inexact->exact z
3543 @deffnx {C Function} scm_inexact_to_exact (z)
3544 Return an exact number that is numerically closest to @var{z}.
3548 @c snarfed from numbers.c:5429
3549 @deffn {Scheme Procedure} rationalize x err
3550 @deffnx {C Function} scm_rationalize (x, err)
3551 Return an exact number that is within @var{err} of @var{x}.
3555 @c snarfed from objects.c:62
3556 @deffn {Scheme Procedure} class-of x
3557 @deffnx {C Function} scm_class_of (x)
3558 Return the class of @var{x}.
3562 @c snarfed from objects.c:342
3563 @deffn {Scheme Procedure} entity? obj
3564 @deffnx {C Function} scm_entity_p (obj)
3565 Return @code{#t} if @var{obj} is an entity.
3569 @c snarfed from objects.c:351
3570 @deffn {Scheme Procedure} operator? obj
3571 @deffnx {C Function} scm_operator_p (obj)
3572 Return @code{#t} if @var{obj} is an operator.
3575 \fvalid-object-procedure?
3576 @c snarfed from objects.c:367
3577 @deffn {Scheme Procedure} valid-object-procedure? proc
3578 @deffnx {C Function} scm_valid_object_procedure_p (proc)
3579 Return @code{#t} iff @var{proc} is a procedure that can be used with @code{set-object-procedure}. It is always valid to use a closure constructed by @code{lambda}.
3582 \fset-object-procedure!
3583 @c snarfed from objects.c:389
3584 @deffn {Scheme Procedure} set-object-procedure! obj proc
3585 @deffnx {C Function} scm_set_object_procedure_x (obj, proc)
3586 Set the object procedure of @var{obj} to @var{proc}.
3587 @var{obj} must be either an entity or an operator.
3591 @c snarfed from objects.c:449
3592 @deffn {Scheme Procedure} make-class-object metaclass layout
3593 @deffnx {C Function} scm_make_class_object (metaclass, layout)
3594 Create a new class object of class @var{metaclass}, with the
3595 slot layout specified by @var{layout}.
3598 \fmake-subclass-object
3599 @c snarfed from objects.c:464
3600 @deffn {Scheme Procedure} make-subclass-object class layout
3601 @deffnx {C Function} scm_make_subclass_object (class, layout)
3602 Create a subclass object of @var{class}, with the slot layout
3603 specified by @var{layout}.
3607 @c snarfed from objprop.c:35
3608 @deffn {Scheme Procedure} object-properties obj
3609 @deffnx {C Function} scm_object_properties (obj)
3610 Return @var{obj}'s property list.
3613 \fset-object-properties!
3614 @c snarfed from objprop.c:45
3615 @deffn {Scheme Procedure} set-object-properties! obj alist
3616 @deffnx {C Function} scm_set_object_properties_x (obj, alist)
3617 Set @var{obj}'s property list to @var{alist}.
3621 @c snarfed from objprop.c:56
3622 @deffn {Scheme Procedure} object-property obj key
3623 @deffnx {C Function} scm_object_property (obj, key)
3624 Return the property of @var{obj} with name @var{key}.
3627 \fset-object-property!
3628 @c snarfed from objprop.c:68
3629 @deffn {Scheme Procedure} set-object-property! obj key value
3630 @deffnx {C Function} scm_set_object_property_x (obj, key, value)
3631 In @var{obj}'s property list, set the property named @var{key}
3636 @c snarfed from pairs.c:56
3637 @deffn {Scheme Procedure} cons x y
3638 @deffnx {C Function} scm_cons (x, y)
3639 Return a newly allocated pair whose car is @var{x} and whose
3640 cdr is @var{y}. The pair is guaranteed to be different (in the
3641 sense of @code{eq?}) from every previously existing object.
3645 @c snarfed from pairs.c:74
3646 @deffn {Scheme Procedure} pair? x
3647 @deffnx {C Function} scm_pair_p (x)
3648 Return @code{#t} if @var{x} is a pair; otherwise return
3653 @c snarfed from pairs.c:120
3654 @deffn {Scheme Procedure} set-car! pair value
3655 @deffnx {C Function} scm_set_car_x (pair, value)
3656 Stores @var{value} in the car field of @var{pair}. The value returned
3657 by @code{set-car!} is unspecified.
3661 @c snarfed from pairs.c:133
3662 @deffn {Scheme Procedure} set-cdr! pair value
3663 @deffnx {C Function} scm_set_cdr_x (pair, value)
3664 Stores @var{value} in the cdr field of @var{pair}. The value returned
3665 by @code{set-cdr!} is unspecified.
3669 @c snarfed from ports.c:242
3670 @deffn {Scheme Procedure} char-ready? [port]
3671 @deffnx {C Function} scm_char_ready_p (port)
3672 Return @code{#t} if a character is ready on input @var{port}
3673 and return @code{#f} otherwise. If @code{char-ready?} returns
3674 @code{#t} then the next @code{read-char} operation on
3675 @var{port} is guaranteed not to hang. If @var{port} is a file
3676 port at end of file then @code{char-ready?} returns @code{#t}.
3678 @code{char-ready?} exists to make it possible for a
3679 program to accept characters from interactive ports without
3680 getting stuck waiting for input. Any input editors associated
3681 with such ports must make sure that characters whose existence
3682 has been asserted by @code{char-ready?} cannot be rubbed out.
3683 If @code{char-ready?} were to return @code{#f} at end of file,
3684 a port at end of file would be indistinguishable from an
3685 interactive port that has no ready characters.
3689 @c snarfed from ports.c:319
3690 @deffn {Scheme Procedure} drain-input port
3691 @deffnx {C Function} scm_drain_input (port)
3692 This procedure clears a port's input buffers, similar
3693 to the way that force-output clears the output buffer. The
3694 contents of the buffers are returned as a single string, e.g.,
3697 (define p (open-input-file ...))
3698 (drain-input p) => empty string, nothing buffered yet.
3699 (unread-char (read-char p) p)
3700 (drain-input p) => initial chars from p, up to the buffer size.
3703 Draining the buffers may be useful for cleanly finishing
3704 buffered I/O so that the file descriptor can be used directly
3708 \fcurrent-input-port
3709 @c snarfed from ports.c:347
3710 @deffn {Scheme Procedure} current-input-port
3711 @deffnx {C Function} scm_current_input_port ()
3712 Return the current input port. This is the default port used
3713 by many input procedures. Initially, @code{current-input-port}
3714 returns the @dfn{standard input} in Unix and C terminology.
3717 \fcurrent-output-port
3718 @c snarfed from ports.c:359
3719 @deffn {Scheme Procedure} current-output-port
3720 @deffnx {C Function} scm_current_output_port ()
3721 Return the current output port. This is the default port used
3722 by many output procedures. Initially,
3723 @code{current-output-port} returns the @dfn{standard output} in
3724 Unix and C terminology.
3727 \fcurrent-error-port
3728 @c snarfed from ports.c:369
3729 @deffn {Scheme Procedure} current-error-port
3730 @deffnx {C Function} scm_current_error_port ()
3731 Return the port to which errors and warnings should be sent (the
3732 @dfn{standard error} in Unix and C terminology).
3736 @c snarfed from ports.c:379
3737 @deffn {Scheme Procedure} current-load-port
3738 @deffnx {C Function} scm_current_load_port ()
3739 Return the current-load-port.
3740 The load port is used internally by @code{primitive-load}.
3743 \fset-current-input-port
3744 @c snarfed from ports.c:392
3745 @deffn {Scheme Procedure} set-current-input-port port
3746 @deffnx {Scheme Procedure} set-current-output-port port
3747 @deffnx {Scheme Procedure} set-current-error-port port
3748 @deffnx {C Function} scm_set_current_input_port (port)
3749 Change the ports returned by @code{current-input-port},
3750 @code{current-output-port} and @code{current-error-port}, respectively,
3751 so that they use the supplied @var{port} for input or output.
3754 \fset-current-output-port
3755 @c snarfed from ports.c:405
3756 @deffn {Scheme Procedure} set-current-output-port port
3757 @deffnx {C Function} scm_set_current_output_port (port)
3758 Set the current default output port to @var{port}.
3761 \fset-current-error-port
3762 @c snarfed from ports.c:419
3763 @deffn {Scheme Procedure} set-current-error-port port
3764 @deffnx {C Function} scm_set_current_error_port (port)
3765 Set the current default error port to @var{port}.
3769 @c snarfed from ports.c:639
3770 @deffn {Scheme Procedure} port-revealed port
3771 @deffnx {C Function} scm_port_revealed (port)
3772 Return the revealed count for @var{port}.
3775 \fset-port-revealed!
3776 @c snarfed from ports.c:652
3777 @deffn {Scheme Procedure} set-port-revealed! port rcount
3778 @deffnx {C Function} scm_set_port_revealed_x (port, rcount)
3779 Sets the revealed count for a port to a given value.
3780 The return value is unspecified.
3784 @c snarfed from ports.c:713
3785 @deffn {Scheme Procedure} port-mode port
3786 @deffnx {C Function} scm_port_mode (port)
3787 Return the port modes associated with the open port @var{port}.
3788 These will not necessarily be identical to the modes used when
3789 the port was opened, since modes such as "append" which are
3790 used only during port creation are not retained.
3794 @c snarfed from ports.c:750
3795 @deffn {Scheme Procedure} close-port port
3796 @deffnx {C Function} scm_close_port (port)
3797 Close the specified port object. Return @code{#t} if it
3798 successfully closes a port or @code{#f} if it was already
3799 closed. An exception may be raised if an error occurs, for
3800 example when flushing buffered output. See also @ref{Ports and
3801 File Descriptors, close}, for a procedure which can close file
3806 @c snarfed from ports.c:780
3807 @deffn {Scheme Procedure} close-input-port port
3808 @deffnx {C Function} scm_close_input_port (port)
3809 Close the specified input port object. The routine has no effect if
3810 the file has already been closed. An exception may be raised if an
3811 error occurs. The value returned is unspecified.
3813 See also @ref{Ports and File Descriptors, close}, for a procedure
3814 which can close file descriptors.
3818 @c snarfed from ports.c:795
3819 @deffn {Scheme Procedure} close-output-port port
3820 @deffnx {C Function} scm_close_output_port (port)
3821 Close the specified output port object. The routine has no effect if
3822 the file has already been closed. An exception may be raised if an
3823 error occurs. The value returned is unspecified.
3825 See also @ref{Ports and File Descriptors, close}, for a procedure
3826 which can close file descriptors.
3830 @c snarfed from ports.c:841
3831 @deffn {Scheme Procedure} port-for-each proc
3832 @deffnx {C Function} scm_port_for_each (proc)
3833 Apply @var{proc} to each port in the Guile port table
3834 in turn. The return value is unspecified. More specifically,
3835 @var{proc} is applied exactly once to every port that exists
3836 in the system at the time @var{port-for-each} is invoked.
3837 Changes to the port table while @var{port-for-each} is running
3838 have no effect as far as @var{port-for-each} is concerned.
3842 @c snarfed from ports.c:859
3843 @deffn {Scheme Procedure} input-port? x
3844 @deffnx {C Function} scm_input_port_p (x)
3845 Return @code{#t} if @var{x} is an input port, otherwise return
3846 @code{#f}. Any object satisfying this predicate also satisfies
3851 @c snarfed from ports.c:870
3852 @deffn {Scheme Procedure} output-port? x
3853 @deffnx {C Function} scm_output_port_p (x)
3854 Return @code{#t} if @var{x} is an output port, otherwise return
3855 @code{#f}. Any object satisfying this predicate also satisfies
3860 @c snarfed from ports.c:882
3861 @deffn {Scheme Procedure} port? x
3862 @deffnx {C Function} scm_port_p (x)
3863 Return a boolean indicating whether @var{x} is a port.
3864 Equivalent to @code{(or (input-port? @var{x}) (output-port?
3869 @c snarfed from ports.c:892
3870 @deffn {Scheme Procedure} port-closed? port
3871 @deffnx {C Function} scm_port_closed_p (port)
3872 Return @code{#t} if @var{port} is closed or @code{#f} if it is
3877 @c snarfed from ports.c:903
3878 @deffn {Scheme Procedure} eof-object? x
3879 @deffnx {C Function} scm_eof_object_p (x)
3880 Return @code{#t} if @var{x} is an end-of-file object; otherwise
3885 @c snarfed from ports.c:917
3886 @deffn {Scheme Procedure} force-output [port]
3887 @deffnx {C Function} scm_force_output (port)
3888 Flush the specified output port, or the current output port if @var{port}
3889 is omitted. The current output buffer contents are passed to the
3890 underlying port implementation (e.g., in the case of fports, the
3891 data will be written to the file and the output buffer will be cleared.)
3892 It has no effect on an unbuffered port.
3894 The return value is unspecified.
3898 @c snarfed from ports.c:935
3899 @deffn {Scheme Procedure} flush-all-ports
3900 @deffnx {C Function} scm_flush_all_ports ()
3901 Equivalent to calling @code{force-output} on
3902 all open output ports. The return value is unspecified.
3906 @c snarfed from ports.c:955
3907 @deffn {Scheme Procedure} read-char [port]
3908 @deffnx {C Function} scm_read_char (port)
3909 Return the next character available from @var{port}, updating
3910 @var{port} to point to the following character. If no more
3911 characters are available, the end-of-file object is returned.
3915 @c snarfed from ports.c:1297
3916 @deffn {Scheme Procedure} peek-char [port]
3917 @deffnx {C Function} scm_peek_char (port)
3918 Return the next character available from @var{port},
3919 @emph{without} updating @var{port} to point to the following
3920 character. If no more characters are available, the
3921 end-of-file object is returned.
3923 The value returned by
3924 a call to @code{peek-char} is the same as the value that would
3925 have been returned by a call to @code{read-char} on the same
3926 port. The only difference is that the very next call to
3927 @code{read-char} or @code{peek-char} on that @var{port} will
3928 return the value returned by the preceding call to
3929 @code{peek-char}. In particular, a call to @code{peek-char} on
3930 an interactive port will hang waiting for input whenever a call
3931 to @code{read-char} would have hung.
3935 @c snarfed from ports.c:1320
3936 @deffn {Scheme Procedure} unread-char cobj [port]
3937 @deffnx {C Function} scm_unread_char (cobj, port)
3938 Place @var{char} in @var{port} so that it will be read by the
3939 next read operation. If called multiple times, the unread characters
3940 will be read again in last-in first-out order. If @var{port} is
3941 not supplied, the current input port is used.
3945 @c snarfed from ports.c:1343
3946 @deffn {Scheme Procedure} unread-string str port
3947 @deffnx {C Function} scm_unread_string (str, port)
3948 Place the string @var{str} in @var{port} so that its characters will be
3949 read in subsequent read operations. If called multiple times, the
3950 unread characters will be read again in last-in first-out order. If
3951 @var{port} is not supplied, the current-input-port is used.
3955 @c snarfed from ports.c:1382
3956 @deffn {Scheme Procedure} seek fd_port offset whence
3957 @deffnx {C Function} scm_seek (fd_port, offset, whence)
3958 Sets the current position of @var{fd/port} to the integer
3959 @var{offset}, which is interpreted according to the value of
3962 One of the following variables should be supplied for
3965 Seek from the beginning of the file.
3968 Seek from the current position.
3971 Seek from the end of the file.
3973 If @var{fd/port} is a file descriptor, the underlying system
3974 call is @code{lseek}. @var{port} may be a string port.
3976 The value returned is the new position in the file. This means
3977 that the current position of a port can be obtained using:
3979 (seek port 0 SEEK_CUR)
3984 @c snarfed from ports.c:1440
3985 @deffn {Scheme Procedure} truncate-file object [length]
3986 @deffnx {C Function} scm_truncate_file (object, length)
3987 Truncates the object referred to by @var{object} to at most
3988 @var{length} bytes. @var{object} can be a string containing a
3989 file name or an integer file descriptor or a port.
3990 @var{length} may be omitted if @var{object} is not a file name,
3991 in which case the truncation occurs at the current port
3992 position. The return value is unspecified.
3996 @c snarfed from ports.c:1500
3997 @deffn {Scheme Procedure} port-line port
3998 @deffnx {C Function} scm_port_line (port)
3999 Return the current line number for @var{port}.
4001 The first line of a file is 0. But you might want to add 1
4002 when printing line numbers, since starting from 1 is
4003 traditional in error messages, and likely to be more natural to
4008 @c snarfed from ports.c:1512
4009 @deffn {Scheme Procedure} set-port-line! port line
4010 @deffnx {C Function} scm_set_port_line_x (port, line)
4011 Set the current line number for @var{port} to @var{line}. The
4012 first line of a file is 0.
4016 @c snarfed from ports.c:1531
4017 @deffn {Scheme Procedure} port-column port
4018 @deffnx {C Function} scm_port_column (port)
4019 Return the current column number of @var{port}.
4021 unknown, the result is #f. Otherwise, the result is a 0-origin integer
4022 - i.e. the first character of the first line is line 0, column 0.
4023 (However, when you display a file position, for example in an error
4024 message, we recommend you add 1 to get 1-origin integers. This is
4025 because lines and column numbers traditionally start with 1, and that is
4026 what non-programmers will find most natural.)
4030 @c snarfed from ports.c:1543
4031 @deffn {Scheme Procedure} set-port-column! port column
4032 @deffnx {C Function} scm_set_port_column_x (port, column)
4033 Set the current column of @var{port}. Before reading the first
4034 character on a line the column should be 0.
4038 @c snarfed from ports.c:1557
4039 @deffn {Scheme Procedure} port-filename port
4040 @deffnx {C Function} scm_port_filename (port)
4041 Return the filename associated with @var{port}. This function returns
4042 the strings "standard input", "standard output" and "standard error"
4043 when called on the current input, output and error ports respectively.
4046 \fset-port-filename!
4047 @c snarfed from ports.c:1571
4048 @deffn {Scheme Procedure} set-port-filename! port filename
4049 @deffnx {C Function} scm_set_port_filename_x (port, filename)
4050 Change the filename associated with @var{port}, using the current input
4051 port if none is specified. Note that this does not change the port's
4052 source of data, but only the value that is returned by
4053 @code{port-filename} and reported in diagnostic output.
4057 @c snarfed from ports.c:1665
4058 @deffn {Scheme Procedure} %make-void-port mode
4059 @deffnx {C Function} scm_sys_make_void_port (mode)
4060 Create and return a new void port. A void port acts like
4061 @file{/dev/null}. The @var{mode} argument
4062 specifies the input/output modes for this port: see the
4063 documentation for @code{open-file} in @ref{File Ports}.
4066 \fprint-options-interface
4067 @c snarfed from print.c:83
4068 @deffn {Scheme Procedure} print-options-interface [setting]
4069 @deffnx {C Function} scm_print_options (setting)
4070 Option interface for the print options. Instead of using
4071 this procedure directly, use the procedures
4072 @code{print-enable}, @code{print-disable}, @code{print-set!}
4073 and @code{print-options}.
4077 @c snarfed from print.c:932
4078 @deffn {Scheme Procedure} simple-format destination message . args
4079 @deffnx {C Function} scm_simple_format (destination, message, args)
4080 Write @var{message} to @var{destination}, defaulting to
4081 the current output port.
4082 @var{message} can contain @code{~A} (was @code{%s}) and
4083 @code{~S} (was @code{%S}) escapes. When printed,
4084 the escapes are replaced with corresponding members of
4086 @code{~A} formats using @code{display} and @code{~S} formats
4088 If @var{destination} is @code{#t}, then use the current output
4089 port, if @var{destination} is @code{#f}, then return a string
4090 containing the formatted text. Does not add a trailing newline.
4094 @c snarfed from print.c:1022
4095 @deffn {Scheme Procedure} newline [port]
4096 @deffnx {C Function} scm_newline (port)
4097 Send a newline to @var{port}.
4098 If @var{port} is omitted, send to the current output port.
4102 @c snarfed from print.c:1037
4103 @deffn {Scheme Procedure} write-char chr [port]
4104 @deffnx {C Function} scm_write_char (chr, port)
4105 Send character @var{chr} to @var{port}.
4108 \fport-with-print-state
4109 @c snarfed from print.c:1091
4110 @deffn {Scheme Procedure} port-with-print-state port [pstate]
4111 @deffnx {C Function} scm_port_with_print_state (port, pstate)
4112 Create a new port which behaves like @var{port}, but with an
4113 included print state @var{pstate}. @var{pstate} is optional.
4114 If @var{pstate} isn't supplied and @var{port} already has
4115 a print state, the old print state is reused.
4119 @c snarfed from print.c:1104
4120 @deffn {Scheme Procedure} get-print-state port
4121 @deffnx {C Function} scm_get_print_state (port)
4122 Return the print state of the port @var{port}. If @var{port}
4123 has no associated print state, @code{#f} is returned.
4126 \fprocedure-properties
4127 @c snarfed from procprop.c:160
4128 @deffn {Scheme Procedure} procedure-properties proc
4129 @deffnx {C Function} scm_procedure_properties (proc)
4130 Return @var{obj}'s property list.
4133 \fset-procedure-properties!
4134 @c snarfed from procprop.c:173
4135 @deffn {Scheme Procedure} set-procedure-properties! proc new_val
4136 @deffnx {C Function} scm_set_procedure_properties_x (proc, new_val)
4137 Set @var{obj}'s property list to @var{alist}.
4140 \fprocedure-property
4141 @c snarfed from procprop.c:186
4142 @deffn {Scheme Procedure} procedure-property p k
4143 @deffnx {C Function} scm_procedure_property (p, k)
4144 Return the property of @var{obj} with name @var{key}.
4147 \fset-procedure-property!
4148 @c snarfed from procprop.c:209
4149 @deffn {Scheme Procedure} set-procedure-property! p k v
4150 @deffnx {C Function} scm_set_procedure_property_x (p, k, v)
4151 In @var{obj}'s property list, set the property named @var{key} to
4156 @c snarfed from procs.c:162
4157 @deffn {Scheme Procedure} procedure? obj
4158 @deffnx {C Function} scm_procedure_p (obj)
4159 Return @code{#t} if @var{obj} is a procedure.
4163 @c snarfed from procs.c:189
4164 @deffn {Scheme Procedure} closure? obj
4165 @deffnx {C Function} scm_closure_p (obj)
4166 Return @code{#t} if @var{obj} is a closure.
4170 @c snarfed from procs.c:198
4171 @deffn {Scheme Procedure} thunk? obj
4172 @deffnx {C Function} scm_thunk_p (obj)
4173 Return @code{#t} if @var{obj} is a thunk.
4176 \fprocedure-documentation
4177 @c snarfed from procs.c:248
4178 @deffn {Scheme Procedure} procedure-documentation proc
4179 @deffnx {C Function} scm_procedure_documentation (proc)
4180 Return the documentation string associated with @code{proc}. By
4181 convention, if a procedure contains more than one expression and the
4182 first expression is a string constant, that string is assumed to contain
4183 documentation for that procedure.
4186 \fprocedure-with-setter?
4187 @c snarfed from procs.c:284
4188 @deffn {Scheme Procedure} procedure-with-setter? obj
4189 @deffnx {C Function} scm_procedure_with_setter_p (obj)
4190 Return @code{#t} if @var{obj} is a procedure with an
4191 associated setter procedure.
4194 \fmake-procedure-with-setter
4195 @c snarfed from procs.c:294
4196 @deffn {Scheme Procedure} make-procedure-with-setter procedure setter
4197 @deffnx {C Function} scm_make_procedure_with_setter (procedure, setter)
4198 Create a new procedure which behaves like @var{procedure}, but
4199 with the associated setter @var{setter}.
4203 @c snarfed from procs.c:308
4204 @deffn {Scheme Procedure} procedure proc
4205 @deffnx {C Function} scm_procedure (proc)
4206 Return the procedure of @var{proc}, which must be either a
4207 procedure with setter, or an operator struct.
4210 \fprimitive-make-property
4211 @c snarfed from properties.c:40
4212 @deffn {Scheme Procedure} primitive-make-property not_found_proc
4213 @deffnx {C Function} scm_primitive_make_property (not_found_proc)
4214 Create a @dfn{property token} that can be used with
4215 @code{primitive-property-ref} and @code{primitive-property-set!}.
4216 See @code{primitive-property-ref} for the significance of
4217 @var{not_found_proc}.
4220 \fprimitive-property-ref
4221 @c snarfed from properties.c:59
4222 @deffn {Scheme Procedure} primitive-property-ref prop obj
4223 @deffnx {C Function} scm_primitive_property_ref (prop, obj)
4224 Return the property @var{prop} of @var{obj}.
4226 When no value has yet been associated with @var{prop} and
4227 @var{obj}, the @var{not-found-proc} from @var{prop} is used. A
4228 call @code{(@var{not-found-proc} @var{prop} @var{obj})} is made
4229 and the result set as the property value. If
4230 @var{not-found-proc} is @code{#f} then @code{#f} is the
4234 \fprimitive-property-set!
4235 @c snarfed from properties.c:90
4236 @deffn {Scheme Procedure} primitive-property-set! prop obj val
4237 @deffnx {C Function} scm_primitive_property_set_x (prop, obj, val)
4238 Set the property @var{prop} of @var{obj} to @var{val}.
4241 \fprimitive-property-del!
4242 @c snarfed from properties.c:111
4243 @deffn {Scheme Procedure} primitive-property-del! prop obj
4244 @deffnx {C Function} scm_primitive_property_del_x (prop, obj)
4245 Remove any value associated with @var{prop} and @var{obj}.
4249 @c snarfed from random.c:346
4250 @deffn {Scheme Procedure} random n [state]
4251 @deffnx {C Function} scm_random (n, state)
4252 Return a number in [0, N).
4254 Accepts a positive integer or real n and returns a
4255 number of the same type between zero (inclusive) and
4256 N (exclusive). The values returned have a uniform
4259 The optional argument @var{state} must be of the type produced
4260 by @code{seed->random-state}. It defaults to the value of the
4261 variable @var{*random-state*}. This object is used to maintain
4262 the state of the pseudo-random-number generator and is altered
4263 as a side effect of the random operation.
4267 @c snarfed from random.c:371
4268 @deffn {Scheme Procedure} copy-random-state [state]
4269 @deffnx {C Function} scm_copy_random_state (state)
4270 Return a copy of the random state @var{state}.
4273 \fseed->random-state
4274 @c snarfed from random.c:383
4275 @deffn {Scheme Procedure} seed->random-state seed
4276 @deffnx {C Function} scm_seed_to_random_state (seed)
4277 Return a new random state using @var{seed}.
4281 @c snarfed from random.c:401
4282 @deffn {Scheme Procedure} random:uniform [state]
4283 @deffnx {C Function} scm_random_uniform (state)
4284 Return a uniformly distributed inexact real random number in
4289 @c snarfed from random.c:416
4290 @deffn {Scheme Procedure} random:normal [state]
4291 @deffnx {C Function} scm_random_normal (state)
4292 Return an inexact real in a normal distribution. The
4293 distribution used has mean 0 and standard deviation 1. For a
4294 normal distribution with mean m and standard deviation d use
4295 @code{(+ m (* d (random:normal)))}.
4298 \frandom:solid-sphere!
4299 @c snarfed from random.c:472
4300 @deffn {Scheme Procedure} random:solid-sphere! v [state]
4301 @deffnx {C Function} scm_random_solid_sphere_x (v, state)
4302 Fills vect with inexact real random numbers
4303 the sum of whose squares is less than 1.0.
4304 Thinking of vect as coordinates in space of
4305 dimension n = (vector-length vect), the coordinates
4306 are uniformly distributed within the unit n-sphere.
4307 The sum of the squares of the numbers is returned.
4310 \frandom:hollow-sphere!
4311 @c snarfed from random.c:495
4312 @deffn {Scheme Procedure} random:hollow-sphere! v [state]
4313 @deffnx {C Function} scm_random_hollow_sphere_x (v, state)
4314 Fills vect with inexact real random numbers
4315 the sum of whose squares is equal to 1.0.
4316 Thinking of vect as coordinates in space of
4317 dimension n = (vector-length vect), the coordinates
4318 are uniformly distributed over the surface of the
4322 \frandom:normal-vector!
4323 @c snarfed from random.c:513
4324 @deffn {Scheme Procedure} random:normal-vector! v [state]
4325 @deffnx {C Function} scm_random_normal_vector_x (v, state)
4326 Fills vect with inexact real random numbers that are
4327 independent and standard normally distributed
4328 (i.e., with mean 0 and variance 1).
4332 @c snarfed from random.c:538
4333 @deffn {Scheme Procedure} random:exp [state]
4334 @deffnx {C Function} scm_random_exp (state)
4335 Return an inexact real in an exponential distribution with mean
4336 1. For an exponential distribution with mean u use (* u
4341 @c snarfed from rdelim.c:55
4342 @deffn {Scheme Procedure} %read-delimited! delims str gobble [port [start [end]]]
4343 @deffnx {C Function} scm_read_delimited_x (delims, str, gobble, port, start, end)
4344 Read characters from @var{port} into @var{str} until one of the
4345 characters in the @var{delims} string is encountered. If
4346 @var{gobble} is true, discard the delimiter character;
4347 otherwise, leave it in the input stream for the next read. If
4348 @var{port} is not specified, use the value of
4349 @code{(current-input-port)}. If @var{start} or @var{end} are
4350 specified, store data only into the substring of @var{str}
4351 bounded by @var{start} and @var{end} (which default to the
4352 beginning and end of the string, respectively).
4354 Return a pair consisting of the delimiter that terminated the
4355 string and the number of characters read. If reading stopped
4356 at the end of file, the delimiter returned is the
4357 @var{eof-object}; if the string was filled without encountering
4358 a delimiter, this value is @code{#f}.
4362 @c snarfed from rdelim.c:202
4363 @deffn {Scheme Procedure} %read-line [port]
4364 @deffnx {C Function} scm_read_line (port)
4365 Read a newline-terminated line from @var{port}, allocating storage as
4366 necessary. The newline terminator (if any) is removed from the string,
4367 and a pair consisting of the line and its delimiter is returned. The
4368 delimiter may be either a newline or the @var{eof-object}; if
4369 @code{%read-line} is called at the end of file, it returns the pair
4370 @code{(#<eof> . #<eof>)}.
4374 @c snarfed from rdelim.c:255
4375 @deffn {Scheme Procedure} write-line obj [port]
4376 @deffnx {C Function} scm_write_line (obj, port)
4377 Display @var{obj} and a newline character to @var{port}. If
4378 @var{port} is not specified, @code{(current-output-port)} is
4379 used. This function is equivalent to:
4381 (display obj [port])
4386 \fread-options-interface
4387 @c snarfed from read.c:109
4388 @deffn {Scheme Procedure} read-options-interface [setting]
4389 @deffnx {C Function} scm_read_options (setting)
4390 Option interface for the read options. Instead of using
4391 this procedure directly, use the procedures @code{read-enable},
4392 @code{read-disable}, @code{read-set!} and @code{read-options}.
4396 @c snarfed from read.c:129
4397 @deffn {Scheme Procedure} read [port]
4398 @deffnx {C Function} scm_read (port)
4399 Read an s-expression from the input port @var{port}, or from
4400 the current input port if @var{port} is not specified.
4401 Any whitespace before the next token is discarded.
4405 @c snarfed from read.c:868
4406 @deffn {Scheme Procedure} read-hash-extend chr proc
4407 @deffnx {C Function} scm_read_hash_extend (chr, proc)
4408 Install the procedure @var{proc} for reading expressions
4409 starting with the character sequence @code{#} and @var{chr}.
4410 @var{proc} will be called with two arguments: the character
4411 @var{chr} and the port to read further data from. The object
4412 returned will be the return value of @code{read}.
4415 \fcall-with-dynamic-root
4416 @c snarfed from root.c:320
4417 @deffn {Scheme Procedure} call-with-dynamic-root thunk handler
4418 @deffnx {C Function} scm_call_with_dynamic_root (thunk, handler)
4419 Evaluate @code{(thunk)} in a new dynamic context, returning its value.
4421 If an error occurs during evaluation, apply @var{handler} to the
4422 arguments to the throw, just as @code{throw} would. If this happens,
4423 @var{handler} is called outside the scope of the new root -- it is
4424 called in the same dynamic context in which
4425 @code{call-with-dynamic-root} was evaluated.
4427 If @var{thunk} captures a continuation, the continuation is rooted at
4428 the call to @var{thunk}. In particular, the call to
4429 @code{call-with-dynamic-root} is not captured. Therefore,
4430 @code{call-with-dynamic-root} always returns at most one time.
4432 Before calling @var{thunk}, the dynamic-wind chain is un-wound back to
4433 the root and a new chain started for @var{thunk}. Therefore, this call
4434 may not do what you expect:
4437 ;; Almost certainly a bug:
4438 (with-output-to-port
4442 (call-with-dynamic-root
4446 (lambda (errcode) errcode))))
4449 The problem is, on what port will @samp{fnord} be displayed? You
4450 might expect that because of the @code{with-output-to-port} that
4451 it will be displayed on the port bound to @code{some-port}. But it
4452 probably won't -- before evaluating the thunk, dynamic winds are
4453 unwound, including those created by @code{with-output-to-port}.
4454 So, the standard output port will have been re-set to its default value
4455 before @code{display} is evaluated.
4457 (This function was added to Guile mostly to help calls to functions in C
4458 libraries that can not tolerate non-local exits or calls that return
4459 multiple times. If such functions call back to the interpreter, it should
4460 be under a new dynamic root.)
4464 @c snarfed from root.c:333
4465 @deffn {Scheme Procedure} dynamic-root
4466 @deffnx {C Function} scm_dynamic_root ()
4467 Return an object representing the current dynamic root.
4469 These objects are only useful for comparison using @code{eq?}.
4470 They are currently represented as numbers, but your code should
4471 in no way depend on this.
4474 \fread-string!/partial
4475 @c snarfed from rw.c:101
4476 @deffn {Scheme Procedure} read-string!/partial str [port_or_fdes [start [end]]]
4477 @deffnx {C Function} scm_read_string_x_partial (str, port_or_fdes, start, end)
4478 Read characters from a port or file descriptor into a
4479 string @var{str}. A port must have an underlying file
4480 descriptor --- a so-called fport. This procedure is
4481 scsh-compatible and can efficiently read large strings.
4486 attempt to fill the entire string, unless the @var{start}
4487 and/or @var{end} arguments are supplied. i.e., @var{start}
4488 defaults to 0 and @var{end} defaults to
4489 @code{(string-length str)}
4491 use the current input port if @var{port_or_fdes} is not
4494 return fewer than the requested number of characters in some
4495 cases, e.g., on end of file, if interrupted by a signal, or if
4496 not all the characters are immediately available.
4498 wait indefinitely for some input if no characters are
4499 currently available,
4500 unless the port is in non-blocking mode.
4502 read characters from the port's input buffers if available,
4503 instead from the underlying file descriptor.
4505 return @code{#f} if end-of-file is encountered before reading
4506 any characters, otherwise return the number of characters
4509 return 0 if the port is in non-blocking mode and no characters
4510 are immediately available.
4512 return 0 if the request is for 0 bytes, with no
4517 \fwrite-string/partial
4518 @c snarfed from rw.c:205
4519 @deffn {Scheme Procedure} write-string/partial str [port_or_fdes [start [end]]]
4520 @deffnx {C Function} scm_write_string_partial (str, port_or_fdes, start, end)
4521 Write characters from a string @var{str} to a port or file
4522 descriptor. A port must have an underlying file descriptor
4523 --- a so-called fport. This procedure is
4524 scsh-compatible and can efficiently write large strings.
4529 attempt to write the entire string, unless the @var{start}
4530 and/or @var{end} arguments are supplied. i.e., @var{start}
4531 defaults to 0 and @var{end} defaults to
4532 @code{(string-length str)}
4534 use the current output port if @var{port_of_fdes} is not
4537 in the case of a buffered port, store the characters in the
4538 port's output buffer, if all will fit. If they will not fit
4539 then any existing buffered characters will be flushed
4541 to write the new characters directly to the underlying file
4542 descriptor. If the port is in non-blocking mode and
4543 buffered characters can not be flushed immediately, then an
4544 @code{EAGAIN} system-error exception will be raised (Note:
4545 scsh does not support the use of non-blocking buffered ports.)
4547 write fewer than the requested number of
4548 characters in some cases, e.g., if interrupted by a signal or
4549 if not all of the output can be accepted immediately.
4551 wait indefinitely for at least one character
4552 from @var{str} to be accepted by the port, unless the port is
4553 in non-blocking mode.
4555 return the number of characters accepted by the port.
4557 return 0 if the port is in non-blocking mode and can not accept
4558 at least one character from @var{str} immediately
4560 return 0 immediately if the request size is 0 bytes.
4565 @c snarfed from scmsigs.c:285
4566 @deffn {Scheme Procedure} sigaction signum [handler [flags [thread]]]
4567 @deffnx {C Function} scm_sigaction_for_thread (signum, handler, flags, thread)
4568 Install or report the signal handler for a specified signal.
4570 @var{signum} is the signal number, which can be specified using the value
4571 of variables such as @code{SIGINT}.
4573 If @var{handler} is omitted, @code{sigaction} returns a pair: the
4575 signal hander, which will be either an integer with the value @code{SIG_DFL}
4576 (default action) or @code{SIG_IGN} (ignore), or the Scheme procedure which
4577 handles the signal, or @code{#f} if a non-Scheme procedure handles the
4578 signal. The CDR contains the current @code{sigaction} flags for the handler.
4580 If @var{handler} is provided, it is installed as the new handler for
4581 @var{signum}. @var{handler} can be a Scheme procedure taking one
4582 argument, or the value of @code{SIG_DFL} (default action) or
4583 @code{SIG_IGN} (ignore), or @code{#f} to restore whatever signal handler
4584 was installed before @code{sigaction} was first used. When
4585 a scheme procedure has been specified, that procedure will run
4586 in the given @var{thread}. When no thread has been given, the
4587 thread that made this call to @code{sigaction} is used.
4588 Flags can optionally be specified for the new handler (@code{SA_RESTART} will
4589 always be added if it's available and the system is using restartable
4590 system calls.) The return value is a pair with information about the
4591 old handler as described above.
4593 This interface does not provide access to the "signal blocking"
4594 facility. Maybe this is not needed, since the thread support may
4595 provide solutions to the problem of consistent access to data
4600 @c snarfed from scmsigs.c:456
4601 @deffn {Scheme Procedure} restore-signals
4602 @deffnx {C Function} scm_restore_signals ()
4603 Return all signal handlers to the values they had before any call to
4604 @code{sigaction} was made. The return value is unspecified.
4608 @c snarfed from scmsigs.c:493
4609 @deffn {Scheme Procedure} alarm i
4610 @deffnx {C Function} scm_alarm (i)
4611 Set a timer to raise a @code{SIGALRM} signal after the specified
4612 number of seconds (an integer). It's advisable to install a signal
4614 @code{SIGALRM} beforehand, since the default action is to terminate
4617 The return value indicates the time remaining for the previous alarm,
4618 if any. The new value replaces the previous alarm. If there was
4619 no previous alarm, the return value is zero.
4623 @c snarfed from scmsigs.c:520
4624 @deffn {Scheme Procedure} setitimer which_timer interval_seconds interval_microseconds value_seconds value_microseconds
4625 @deffnx {C Function} scm_setitimer (which_timer, interval_seconds, interval_microseconds, value_seconds, value_microseconds)
4626 Set the timer specified by @var{which_timer} according to the given
4627 @var{interval_seconds}, @var{interval_microseconds},
4628 @var{value_seconds}, and @var{value_microseconds} values.
4630 Return information about the timer's previous setting.
4631 Errors are handled as described in the guile info pages under ``POSIX
4632 Interface Conventions''.
4634 The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL},
4635 and @code{ITIMER_PROF}.
4637 The return value will be a list of two cons pairs representing the
4638 current state of the given timer. The first pair is the seconds and
4639 microseconds of the timer @code{it_interval}, and the second pair is
4640 the seconds and microseconds of the timer @code{it_value}.
4644 @c snarfed from scmsigs.c:561
4645 @deffn {Scheme Procedure} getitimer which_timer
4646 @deffnx {C Function} scm_getitimer (which_timer)
4647 Return information about the timer specified by @var{which_timer}
4648 Errors are handled as described in the guile info pages under ``POSIX
4649 Interface Conventions''.
4651 The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL},
4652 and @code{ITIMER_PROF}.
4654 The return value will be a list of two cons pairs representing the
4655 current state of the given timer. The first pair is the seconds and
4656 microseconds of the timer @code{it_interval}, and the second pair is
4657 the seconds and microseconds of the timer @code{it_value}.
4661 @c snarfed from scmsigs.c:588
4662 @deffn {Scheme Procedure} pause
4663 @deffnx {C Function} scm_pause ()
4664 Pause the current process (thread?) until a signal arrives whose
4665 action is to either terminate the current process or invoke a
4666 handler procedure. The return value is unspecified.
4670 @c snarfed from scmsigs.c:601
4671 @deffn {Scheme Procedure} sleep i
4672 @deffnx {C Function} scm_sleep (i)
4673 Wait for the given number of seconds (an integer) or until a signal
4674 arrives. The return value is zero if the time elapses or the number
4675 of seconds remaining otherwise.
4679 @c snarfed from scmsigs.c:610
4680 @deffn {Scheme Procedure} usleep i
4681 @deffnx {C Function} scm_usleep (i)
4682 Sleep for @var{i} microseconds.
4686 @c snarfed from scmsigs.c:620
4687 @deffn {Scheme Procedure} raise sig
4688 @deffnx {C Function} scm_raise (sig)
4689 Sends a specified signal @var{sig} to the current process, where
4690 @var{sig} is as described for the kill procedure.
4694 @c snarfed from simpos.c:64
4695 @deffn {Scheme Procedure} system [cmd]
4696 @deffnx {C Function} scm_system (cmd)
4697 Execute @var{cmd} using the operating system's "command
4698 processor". Under Unix this is usually the default shell
4699 @code{sh}. The value returned is @var{cmd}'s exit status as
4700 returned by @code{waitpid}, which can be interpreted using
4701 @code{status:exit-val} and friends.
4703 If @code{system} is called without arguments, return a boolean
4704 indicating whether the command processor is available.
4708 @c snarfed from simpos.c:114
4709 @deffn {Scheme Procedure} system* . args
4710 @deffnx {C Function} scm_system_star (args)
4711 Execute the command indicated by @var{args}. The first element must
4712 be a string indicating the command to be executed, and the remaining
4713 items must be strings representing each of the arguments to that
4716 This function returns the exit status of the command as provided by
4717 @code{waitpid}. This value can be handled with @code{status:exit-val}
4718 and the related functions.
4720 @code{system*} is similar to @code{system}, but accepts only one
4721 string per-argument, and performs no shell interpretation. The
4722 command is executed using fork and execlp. Accordingly this function
4723 may be safer than @code{system} in situations where shell
4724 interpretation is not required.
4726 Example: (system* "echo" "foo" "bar")
4730 @c snarfed from simpos.c:184
4731 @deffn {Scheme Procedure} getenv nam
4732 @deffnx {C Function} scm_getenv (nam)
4733 Looks up the string @var{name} in the current environment. The return
4734 value is @code{#f} unless a string of the form @code{NAME=VALUE} is
4735 found, in which case the string @code{VALUE} is returned.
4739 @c snarfed from simpos.c:200
4740 @deffn {Scheme Procedure} primitive-exit [status]
4741 @deffnx {C Function} scm_primitive_exit (status)
4742 Terminate the current process without unwinding the Scheme stack.
4743 This is would typically be useful after a fork. The exit status
4744 is @var{status} if supplied, otherwise zero.
4747 \frestricted-vector-sort!
4748 @c snarfed from sort.c:291
4749 @deffn {Scheme Procedure} restricted-vector-sort! vec less startpos endpos
4750 @deffnx {C Function} scm_restricted_vector_sort_x (vec, less, startpos, endpos)
4751 Sort the vector @var{vec}, using @var{less} for comparing
4752 the vector elements. @var{startpos} and @var{endpos} delimit
4753 the range of the vector which gets sorted. The return value
4758 @c snarfed from sort.c:321
4759 @deffn {Scheme Procedure} sorted? items less
4760 @deffnx {C Function} scm_sorted_p (items, less)
4761 Return @code{#t} iff @var{items} is a list or a vector such that
4762 for all 1 <= i <= m, the predicate @var{less} returns true when
4763 applied to all elements i - 1 and i
4767 @c snarfed from sort.c:393
4768 @deffn {Scheme Procedure} merge alist blist less
4769 @deffnx {C Function} scm_merge (alist, blist, less)
4770 Merge two already sorted lists into one.
4771 Given two lists @var{alist} and @var{blist}, such that
4772 @code{(sorted? alist less?)} and @code{(sorted? blist less?)},
4773 return a new list in which the elements of @var{alist} and
4774 @var{blist} have been stably interleaved so that
4775 @code{(sorted? (merge alist blist less?) less?)}.
4776 Note: this does _not_ accept vectors.
4780 @c snarfed from sort.c:508
4781 @deffn {Scheme Procedure} merge! alist blist less
4782 @deffnx {C Function} scm_merge_x (alist, blist, less)
4783 Takes two lists @var{alist} and @var{blist} such that
4784 @code{(sorted? alist less?)} and @code{(sorted? blist less?)} and
4785 returns a new list in which the elements of @var{alist} and
4786 @var{blist} have been stably interleaved so that
4787 @code{(sorted? (merge alist blist less?) less?)}.
4788 This is the destructive variant of @code{merge}
4789 Note: this does _not_ accept vectors.
4793 @c snarfed from sort.c:577
4794 @deffn {Scheme Procedure} sort! items less
4795 @deffnx {C Function} scm_sort_x (items, less)
4796 Sort the sequence @var{items}, which may be a list or a
4797 vector. @var{less} is used for comparing the sequence
4798 elements. The sorting is destructive, that means that the
4799 input sequence is modified to produce the sorted result.
4800 This is not a stable sort.
4804 @c snarfed from sort.c:609
4805 @deffn {Scheme Procedure} sort items less
4806 @deffnx {C Function} scm_sort (items, less)
4807 Sort the sequence @var{items}, which may be a list or a
4808 vector. @var{less} is used for comparing the sequence
4809 elements. This is not a stable sort.
4813 @c snarfed from sort.c:717
4814 @deffn {Scheme Procedure} stable-sort! items less
4815 @deffnx {C Function} scm_stable_sort_x (items, less)
4816 Sort the sequence @var{items}, which may be a list or a
4817 vector. @var{less} is used for comparing the sequence elements.
4818 The sorting is destructive, that means that the input sequence
4819 is modified to produce the sorted result.
4820 This is a stable sort.
4824 @c snarfed from sort.c:756
4825 @deffn {Scheme Procedure} stable-sort items less
4826 @deffnx {C Function} scm_stable_sort (items, less)
4827 Sort the sequence @var{items}, which may be a list or a
4828 vector. @var{less} is used for comparing the sequence elements.
4829 This is a stable sort.
4833 @c snarfed from sort.c:797
4834 @deffn {Scheme Procedure} sort-list! items less
4835 @deffnx {C Function} scm_sort_list_x (items, less)
4836 Sort the list @var{items}, using @var{less} for comparing the
4837 list elements. The sorting is destructive, that means that the
4838 input list is modified to produce the sorted result.
4839 This is a stable sort.
4843 @c snarfed from sort.c:812
4844 @deffn {Scheme Procedure} sort-list items less
4845 @deffnx {C Function} scm_sort_list (items, less)
4846 Sort the list @var{items}, using @var{less} for comparing the
4847 list elements. This is a stable sort.
4851 @c snarfed from srcprop.c:152
4852 @deffn {Scheme Procedure} source-properties obj
4853 @deffnx {C Function} scm_source_properties (obj)
4854 Return the source property association list of @var{obj}.
4857 \fset-source-properties!
4858 @c snarfed from srcprop.c:175
4859 @deffn {Scheme Procedure} set-source-properties! obj plist
4860 @deffnx {C Function} scm_set_source_properties_x (obj, plist)
4861 Install the association list @var{plist} as the source property
4866 @c snarfed from srcprop.c:193
4867 @deffn {Scheme Procedure} source-property obj key
4868 @deffnx {C Function} scm_source_property (obj, key)
4869 Return the source property specified by @var{key} from
4870 @var{obj}'s source property list.
4873 \fset-source-property!
4874 @c snarfed from srcprop.c:224
4875 @deffn {Scheme Procedure} set-source-property! obj key datum
4876 @deffnx {C Function} scm_set_source_property_x (obj, key, datum)
4877 Set the source property of object @var{obj}, which is specified by
4878 @var{key} to @var{datum}. Normally, the key will be a symbol.
4882 @c snarfed from stacks.c:384
4883 @deffn {Scheme Procedure} stack? obj
4884 @deffnx {C Function} scm_stack_p (obj)
4885 Return @code{#t} if @var{obj} is a calling stack.
4889 @c snarfed from stacks.c:415
4890 @deffn {Scheme Procedure} make-stack obj . args
4891 @deffnx {C Function} scm_make_stack (obj, args)
4892 Create a new stack. If @var{obj} is @code{#t}, the current
4893 evaluation stack is used for creating the stack frames,
4894 otherwise the frames are taken from @var{obj} (which must be
4895 either a debug object or a continuation).
4897 @var{args} should be a list containing any combination of
4898 integer, procedure and @code{#t} values.
4900 These values specify various ways of cutting away uninteresting
4901 stack frames from the top and bottom of the stack that
4902 @code{make-stack} returns. They come in pairs like this:
4903 @code{(@var{inner_cut_1} @var{outer_cut_1} @var{inner_cut_2}
4904 @var{outer_cut_2} @dots{})}.
4906 Each @var{inner_cut_N} can be @code{#t}, an integer, or a
4907 procedure. @code{#t} means to cut away all frames up to but
4908 excluding the first user module frame. An integer means to cut
4909 away exactly that number of frames. A procedure means to cut
4910 away all frames up to but excluding the application frame whose
4911 procedure matches the specified one.
4913 Each @var{outer_cut_N} can be an integer or a procedure. An
4914 integer means to cut away that number of frames. A procedure
4915 means to cut away frames down to but excluding the application
4916 frame whose procedure matches the specified one.
4918 If the @var{outer_cut_N} of the last pair is missing, it is
4923 @c snarfed from stacks.c:507
4924 @deffn {Scheme Procedure} stack-id stack
4925 @deffnx {C Function} scm_stack_id (stack)
4926 Return the identifier given to @var{stack} by @code{start-stack}.
4930 @c snarfed from stacks.c:548
4931 @deffn {Scheme Procedure} stack-ref stack index
4932 @deffnx {C Function} scm_stack_ref (stack, index)
4933 Return the @var{index}'th frame from @var{stack}.
4937 @c snarfed from stacks.c:561
4938 @deffn {Scheme Procedure} stack-length stack
4939 @deffnx {C Function} scm_stack_length (stack)
4940 Return the length of @var{stack}.
4944 @c snarfed from stacks.c:574
4945 @deffn {Scheme Procedure} frame? obj
4946 @deffnx {C Function} scm_frame_p (obj)
4947 Return @code{#t} if @var{obj} is a stack frame.
4951 @c snarfed from stacks.c:585
4952 @deffn {Scheme Procedure} last-stack-frame obj
4953 @deffnx {C Function} scm_last_stack_frame (obj)
4954 Return a stack which consists of a single frame, which is the
4955 last stack frame for @var{obj}. @var{obj} must be either a
4956 debug object or a continuation.
4960 @c snarfed from stacks.c:627
4961 @deffn {Scheme Procedure} frame-number frame
4962 @deffnx {C Function} scm_frame_number (frame)
4963 Return the frame number of @var{frame}.
4967 @c snarfed from stacks.c:637
4968 @deffn {Scheme Procedure} frame-source frame
4969 @deffnx {C Function} scm_frame_source (frame)
4970 Return the source of @var{frame}.
4974 @c snarfed from stacks.c:648
4975 @deffn {Scheme Procedure} frame-procedure frame
4976 @deffnx {C Function} scm_frame_procedure (frame)
4977 Return the procedure for @var{frame}, or @code{#f} if no
4978 procedure is associated with @var{frame}.
4982 @c snarfed from stacks.c:660
4983 @deffn {Scheme Procedure} frame-arguments frame
4984 @deffnx {C Function} scm_frame_arguments (frame)
4985 Return the arguments of @var{frame}.
4989 @c snarfed from stacks.c:671
4990 @deffn {Scheme Procedure} frame-previous frame
4991 @deffnx {C Function} scm_frame_previous (frame)
4992 Return the previous frame of @var{frame}, or @code{#f} if
4993 @var{frame} is the first frame in its stack.
4997 @c snarfed from stacks.c:687
4998 @deffn {Scheme Procedure} frame-next frame
4999 @deffnx {C Function} scm_frame_next (frame)
5000 Return the next frame of @var{frame}, or @code{#f} if
5001 @var{frame} is the last frame in its stack.
5005 @c snarfed from stacks.c:702
5006 @deffn {Scheme Procedure} frame-real? frame
5007 @deffnx {C Function} scm_frame_real_p (frame)
5008 Return @code{#t} if @var{frame} is a real frame.
5012 @c snarfed from stacks.c:712
5013 @deffn {Scheme Procedure} frame-procedure? frame
5014 @deffnx {C Function} scm_frame_procedure_p (frame)
5015 Return @code{#t} if a procedure is associated with @var{frame}.
5018 \fframe-evaluating-args?
5019 @c snarfed from stacks.c:722
5020 @deffn {Scheme Procedure} frame-evaluating-args? frame
5021 @deffnx {C Function} scm_frame_evaluating_args_p (frame)
5022 Return @code{#t} if @var{frame} contains evaluated arguments.
5026 @c snarfed from stacks.c:732
5027 @deffn {Scheme Procedure} frame-overflow? frame
5028 @deffnx {C Function} scm_frame_overflow_p (frame)
5029 Return @code{#t} if @var{frame} is an overflow frame.
5032 \fget-internal-real-time
5033 @c snarfed from stime.c:132
5034 @deffn {Scheme Procedure} get-internal-real-time
5035 @deffnx {C Function} scm_get_internal_real_time ()
5036 Return the number of time units since the interpreter was
5041 @c snarfed from stime.c:179
5042 @deffn {Scheme Procedure} times
5043 @deffnx {C Function} scm_times ()
5044 Return an object with information about real and processor
5045 time. The following procedures accept such an object as an
5046 argument and return a selected component:
5050 The current real time, expressed as time units relative to an
5053 The CPU time units used by the calling process.
5055 The CPU time units used by the system on behalf of the calling
5058 The CPU time units used by terminated child processes of the
5059 calling process, whose status has been collected (e.g., using
5062 Similarly, the CPU times units used by the system on behalf of
5063 terminated child processes.
5067 \fget-internal-run-time
5068 @c snarfed from stime.c:211
5069 @deffn {Scheme Procedure} get-internal-run-time
5070 @deffnx {C Function} scm_get_internal_run_time ()
5071 Return the number of time units of processor time used by the
5072 interpreter. Both @emph{system} and @emph{user} time are
5073 included but subprocesses are not.
5077 @c snarfed from stime.c:228
5078 @deffn {Scheme Procedure} current-time
5079 @deffnx {C Function} scm_current_time ()
5080 Return the number of seconds since 1970-01-01 00:00:00 UTC,
5081 excluding leap seconds.
5085 @c snarfed from stime.c:247
5086 @deffn {Scheme Procedure} gettimeofday
5087 @deffnx {C Function} scm_gettimeofday ()
5088 Return a pair containing the number of seconds and microseconds
5089 since 1970-01-01 00:00:00 UTC, excluding leap seconds. Note:
5090 whether true microsecond resolution is available depends on the
5095 @c snarfed from stime.c:363
5096 @deffn {Scheme Procedure} localtime time [zone]
5097 @deffnx {C Function} scm_localtime (time, zone)
5098 Return an object representing the broken down components of
5099 @var{time}, an integer like the one returned by
5100 @code{current-time}. The time zone for the calculation is
5101 optionally specified by @var{zone} (a string), otherwise the
5102 @code{TZ} environment variable or the system default is used.
5106 @c snarfed from stime.c:448
5107 @deffn {Scheme Procedure} gmtime time
5108 @deffnx {C Function} scm_gmtime (time)
5109 Return an object representing the broken down components of
5110 @var{time}, an integer like the one returned by
5111 @code{current-time}. The values are calculated for UTC.
5115 @c snarfed from stime.c:526
5116 @deffn {Scheme Procedure} mktime sbd_time [zone]
5117 @deffnx {C Function} scm_mktime (sbd_time, zone)
5118 @var{bd-time} is an object representing broken down time and @code{zone}
5119 is an optional time zone specifier (otherwise the TZ environment variable
5120 or the system default is used).
5122 Returns a pair: the car is a corresponding
5123 integer time value like that returned
5124 by @code{current-time}; the cdr is a broken down time object, similar to
5125 as @var{bd-time} but with normalized values.
5129 @c snarfed from stime.c:611
5130 @deffn {Scheme Procedure} tzset
5131 @deffnx {C Function} scm_tzset ()
5132 Initialize the timezone from the TZ environment variable
5133 or the system default. It's not usually necessary to call this procedure
5134 since it's done automatically by other procedures that depend on the
5139 @c snarfed from stime.c:628
5140 @deffn {Scheme Procedure} strftime format stime
5141 @deffnx {C Function} scm_strftime (format, stime)
5142 Formats a time specification @var{time} using @var{template}. @var{time}
5143 is an object with time components in the form returned by @code{localtime}
5144 or @code{gmtime}. @var{template} is a string which can include formatting
5145 specifications introduced by a @code{%} character. The formatting of
5146 month and day names is dependent on the current locale. The value returned
5147 is the formatted string.
5148 @xref{Formatting Date and Time, , , libc, The GNU C Library Reference Manual}.)
5152 @c snarfed from stime.c:726
5153 @deffn {Scheme Procedure} strptime format string
5154 @deffnx {C Function} scm_strptime (format, string)
5155 Performs the reverse action to @code{strftime}, parsing
5156 @var{string} according to the specification supplied in
5157 @var{template}. The interpretation of month and day names is
5158 dependent on the current locale. The value returned is a pair.
5159 The car has an object with time components
5160 in the form returned by @code{localtime} or @code{gmtime},
5161 but the time zone components
5162 are not usefully set.
5163 The cdr reports the number of characters from @var{string}
5164 which were used for the conversion.
5168 @c snarfed from strings.c:526
5169 @deffn {Scheme Procedure} string? obj
5170 @deffnx {C Function} scm_string_p (obj)
5171 Return @code{#t} if @var{obj} is a string, else @code{#f}.
5175 @c snarfed from strings.c:534
5176 @deffn {Scheme Procedure} list->string
5177 implemented by the C function "scm_string"
5181 @c snarfed from strings.c:540
5182 @deffn {Scheme Procedure} string . chrs
5183 @deffnx {Scheme Procedure} list->string chrs
5184 @deffnx {C Function} scm_string (chrs)
5185 Return a newly allocated string composed of the arguments,
5190 @c snarfed from strings.c:578
5191 @deffn {Scheme Procedure} make-string k [chr]
5192 @deffnx {C Function} scm_make_string (k, chr)
5193 Return a newly allocated string of
5194 length @var{k}. If @var{chr} is given, then all elements of
5195 the string are initialized to @var{chr}, otherwise the contents
5196 of the @var{string} are unspecified.
5200 @c snarfed from strings.c:604
5201 @deffn {Scheme Procedure} string-length string
5202 @deffnx {C Function} scm_string_length (string)
5203 Return the number of characters in @var{string}.
5207 @c snarfed from strings.c:623
5208 @deffn {Scheme Procedure} string-ref str k
5209 @deffnx {C Function} scm_string_ref (str, k)
5210 Return character @var{k} of @var{str} using zero-origin
5211 indexing. @var{k} must be a valid index of @var{str}.
5215 @c snarfed from strings.c:646
5216 @deffn {Scheme Procedure} string-set! str k chr
5217 @deffnx {C Function} scm_string_set_x (str, k, chr)
5218 Store @var{chr} in element @var{k} of @var{str} and return
5219 an unspecified value. @var{k} must be a valid index of
5224 @c snarfed from strings.c:682
5225 @deffn {Scheme Procedure} substring str start [end]
5226 @deffnx {C Function} scm_substring (str, start, end)
5227 Return a newly allocated string formed from the characters
5228 of @var{str} beginning with index @var{start} (inclusive) and
5229 ending with index @var{end} (exclusive).
5230 @var{str} must be a string, @var{start} and @var{end} must be
5231 exact integers satisfying:
5233 0 <= @var{start} <= @var{end} <= (string-length @var{str}).
5236 \fsubstring/read-only
5237 @c snarfed from strings.c:708
5238 @deffn {Scheme Procedure} substring/read-only str start [end]
5239 @deffnx {C Function} scm_substring_read_only (str, start, end)
5240 Return a newly allocated string formed from the characters
5241 of @var{str} beginning with index @var{start} (inclusive) and
5242 ending with index @var{end} (exclusive).
5243 @var{str} must be a string, @var{start} and @var{end} must be
5244 exact integers satisfying:
5246 0 <= @var{start} <= @var{end} <= (string-length @var{str}).
5248 The returned string is read-only.
5253 @c snarfed from strings.c:731
5254 @deffn {Scheme Procedure} substring/copy str start [end]
5255 @deffnx {C Function} scm_substring_copy (str, start, end)
5256 Return a newly allocated string formed from the characters
5257 of @var{str} beginning with index @var{start} (inclusive) and
5258 ending with index @var{end} (exclusive).
5259 @var{str} must be a string, @var{start} and @var{end} must be
5260 exact integers satisfying:
5262 0 <= @var{start} <= @var{end} <= (string-length @var{str}).
5266 @c snarfed from strings.c:755
5267 @deffn {Scheme Procedure} substring/shared str start [end]
5268 @deffnx {C Function} scm_substring_shared (str, start, end)
5269 Return string that indirectly refers to the characters
5270 of @var{str} beginning with index @var{start} (inclusive) and
5271 ending with index @var{end} (exclusive).
5272 @var{str} must be a string, @var{start} and @var{end} must be
5273 exact integers satisfying:
5275 0 <= @var{start} <= @var{end} <= (string-length @var{str}).
5279 @c snarfed from strings.c:774
5280 @deffn {Scheme Procedure} string-append . args
5281 @deffnx {C Function} scm_string_append (args)
5282 Return a newly allocated string whose characters form the
5283 concatenation of the given strings, @var{args}.
5287 @c snarfed from srfi-13.c:62
5288 @deffn {Scheme Procedure} string-null? str
5289 @deffnx {C Function} scm_string_null_p (str)
5290 Return @code{#t} if @var{str}'s length is zero, and
5291 @code{#f} otherwise.
5293 (string-null? "") @result{} #t
5295 (string-null? y) @result{} #f
5300 @c snarfed from srfi-13.c:90
5301 @deffn {Scheme Procedure} string-any char_pred s [start [end]]
5302 @deffnx {C Function} scm_string_any (char_pred, s, start, end)
5303 Check if the predicate @var{pred} is true for any character in
5306 Calls to @var{pred} are made from left to right across @var{s}.
5307 When it returns true (ie.@: non-@code{#f}), that return value
5308 is the return from @code{string-any}.
5310 The SRFI-13 specification requires that the call to @var{pred}
5311 on the last character of @var{s} (assuming that point is
5312 reached) be a tail call, but currently in Guile this is not the
5317 @c snarfed from srfi-13.c:153
5318 @deffn {Scheme Procedure} string-every char_pred s [start [end]]
5319 @deffnx {C Function} scm_string_every (char_pred, s, start, end)
5320 Check if the predicate @var{pred} is true for every character
5321 in the string @var{s}.
5323 Calls to @var{pred} are made from left to right across @var{s}.
5324 If the predicate is true for every character then the return
5325 value from the last @var{pred} call is the return from
5326 @code{string-every}.
5328 If there are no characters in @var{s} (ie.@: @var{start} equals
5329 @var{end}) then the return is @code{#t}.
5331 The SRFI-13 specification requires that the call to @var{pred}
5332 on the last character of @var{s} (assuming that point is
5333 reached) be a tail call, but currently in Guile this is not the
5338 @c snarfed from srfi-13.c:209
5339 @deffn {Scheme Procedure} string-tabulate proc len
5340 @deffnx {C Function} scm_string_tabulate (proc, len)
5341 @var{proc} is an integer->char procedure. Construct a string
5342 of size @var{len} by applying @var{proc} to each index to
5343 produce the corresponding string element. The order in which
5344 @var{proc} is applied to the indices is not specified.
5348 @c snarfed from srfi-13.c:241
5349 @deffn {Scheme Procedure} string->list str [start [end]]
5350 @deffnx {C Function} scm_substring_to_list (str, start, end)
5351 Convert the string @var{str} into a list of characters.
5354 \freverse-list->string
5355 @c snarfed from srfi-13.c:280
5356 @deffn {Scheme Procedure} reverse-list->string chrs
5357 @deffnx {C Function} scm_reverse_list_to_string (chrs)
5358 An efficient implementation of @code{(compose string->list
5362 (reverse-list->string '(#\a #\B #\c)) @result{} "cBa"
5367 @c snarfed from srfi-13.c:347
5368 @deffn {Scheme Procedure} string-join ls [delimiter [grammar]]
5369 @deffnx {C Function} scm_string_join (ls, delimiter, grammar)
5370 Append the string in the string list @var{ls}, using the string
5371 @var{delim} as a delimiter between the elements of @var{ls}.
5372 @var{grammar} is a symbol which specifies how the delimiter is
5373 placed between the strings, and defaults to the symbol
5378 Insert the separator between list elements. An empty string
5379 will produce an empty list.
5381 Like @code{infix}, but will raise an error if given the empty
5384 Insert the separator after every list element.
5386 Insert the separator before each list element.
5391 @c snarfed from srfi-13.c:481
5392 @deffn {Scheme Procedure} string-copy str [start [end]]
5393 @deffnx {C Function} scm_srfi13_substring_copy (str, start, end)
5394 Return a freshly allocated copy of the string @var{str}. If
5395 given, @var{start} and @var{end} delimit the portion of
5396 @var{str} which is copied.
5400 @c snarfed from srfi-13.c:508
5401 @deffn {Scheme Procedure} string-copy! target tstart s [start [end]]
5402 @deffnx {C Function} scm_string_copy_x (target, tstart, s, start, end)
5403 Copy the sequence of characters from index range [@var{start},
5404 @var{end}) in string @var{s} to string @var{target}, beginning
5405 at index @var{tstart}. The characters are copied left-to-right
5406 or right-to-left as needed -- the copy is guaranteed to work,
5407 even if @var{target} and @var{s} are the same string. It is an
5408 error if the copy operation runs off the end of the target
5413 @c snarfed from srfi-13.c:538
5414 @deffn {Scheme Procedure} substring-move! str1 start1 end1 str2 start2
5415 @deffnx {C Function} scm_substring_move_x (str1, start1, end1, str2, start2)
5416 Copy the substring of @var{str1} bounded by @var{start1} and @var{end1}
5417 into @var{str2} beginning at position @var{start2}.
5418 @var{str1} and @var{str2} can be the same string.
5422 @c snarfed from srfi-13.c:547
5423 @deffn {Scheme Procedure} string-take s n
5424 @deffnx {C Function} scm_string_take (s, n)
5425 Return the @var{n} first characters of @var{s}.
5429 @c snarfed from srfi-13.c:557
5430 @deffn {Scheme Procedure} string-drop s n
5431 @deffnx {C Function} scm_string_drop (s, n)
5432 Return all but the first @var{n} characters of @var{s}.
5436 @c snarfed from srfi-13.c:567
5437 @deffn {Scheme Procedure} string-take-right s n
5438 @deffnx {C Function} scm_string_take_right (s, n)
5439 Return the @var{n} last characters of @var{s}.
5443 @c snarfed from srfi-13.c:579
5444 @deffn {Scheme Procedure} string-drop-right s n
5445 @deffnx {C Function} scm_string_drop_right (s, n)
5446 Return all but the last @var{n} characters of @var{s}.
5450 @c snarfed from srfi-13.c:594
5451 @deffn {Scheme Procedure} string-pad s len [chr [start [end]]]
5452 @deffnx {C Function} scm_string_pad (s, len, chr, start, end)
5453 Take that characters from @var{start} to @var{end} from the
5454 string @var{s} and return a new string, right-padded by the
5455 character @var{chr} to length @var{len}. If the resulting
5456 string is longer than @var{len}, it is truncated on the right.
5460 @c snarfed from srfi-13.c:634
5461 @deffn {Scheme Procedure} string-pad-right s len [chr [start [end]]]
5462 @deffnx {C Function} scm_string_pad_right (s, len, chr, start, end)
5463 Take that characters from @var{start} to @var{end} from the
5464 string @var{s} and return a new string, left-padded by the
5465 character @var{chr} to length @var{len}. If the resulting
5466 string is longer than @var{len}, it is truncated on the left.
5470 @c snarfed from srfi-13.c:687
5471 @deffn {Scheme Procedure} string-trim s [char_pred [start [end]]]
5472 @deffnx {C Function} scm_string_trim (s, char_pred, start, end)
5473 Trim @var{s} by skipping over all characters on the left
5474 that satisfy the parameter @var{char_pred}:
5478 if it is the character @var{ch}, characters equal to
5479 @var{ch} are trimmed,
5482 if it is a procedure @var{pred} characters that
5483 satisfy @var{pred} are trimmed,
5486 if it is a character set, characters in that set are trimmed.
5489 If called without a @var{char_pred} argument, all whitespace is
5494 @c snarfed from srfi-13.c:763
5495 @deffn {Scheme Procedure} string-trim-right s [char_pred [start [end]]]
5496 @deffnx {C Function} scm_string_trim_right (s, char_pred, start, end)
5497 Trim @var{s} by skipping over all characters on the rightt
5498 that satisfy the parameter @var{char_pred}:
5502 if it is the character @var{ch}, characters equal to @var{ch}
5506 if it is a procedure @var{pred} characters that satisfy
5507 @var{pred} are trimmed,
5510 if it is a character sets, all characters in that set are
5514 If called without a @var{char_pred} argument, all whitespace is
5519 @c snarfed from srfi-13.c:839
5520 @deffn {Scheme Procedure} string-trim-both s [char_pred [start [end]]]
5521 @deffnx {C Function} scm_string_trim_both (s, char_pred, start, end)
5522 Trim @var{s} by skipping over all characters on both sides of
5523 the string that satisfy the parameter @var{char_pred}:
5527 if it is the character @var{ch}, characters equal to @var{ch}
5531 if it is a procedure @var{pred} characters that satisfy
5532 @var{pred} are trimmed,
5535 if it is a character set, the characters in the set are
5539 If called without a @var{char_pred} argument, all whitespace is
5544 @c snarfed from srfi-13.c:926
5545 @deffn {Scheme Procedure} string-fill! str chr [start [end]]
5546 @deffnx {C Function} scm_substring_fill_x (str, chr, start, end)
5547 Stores @var{chr} in every element of the given @var{str} and
5548 returns an unspecified value.
5552 @c snarfed from srfi-13.c:978
5553 @deffn {Scheme Procedure} string-compare s1 s2 proc_lt proc_eq proc_gt [start1 [end1 [start2 [end2]]]]
5554 @deffnx {C Function} scm_string_compare (s1, s2, proc_lt, proc_eq, proc_gt, start1, end1, start2, end2)
5555 Apply @var{proc_lt}, @var{proc_eq}, @var{proc_gt} to the
5556 mismatch index, depending upon whether @var{s1} is less than,
5557 equal to, or greater than @var{s2}. The mismatch index is the
5558 largest index @var{i} such that for every 0 <= @var{j} <
5559 @var{i}, @var{s1}[@var{j}] = @var{s2}[@var{j}] -- that is,
5560 @var{i} is the first position that does not match.
5564 @c snarfed from srfi-13.c:1032
5565 @deffn {Scheme Procedure} string-compare-ci s1 s2 proc_lt proc_eq proc_gt [start1 [end1 [start2 [end2]]]]
5566 @deffnx {C Function} scm_string_compare_ci (s1, s2, proc_lt, proc_eq, proc_gt, start1, end1, start2, end2)
5567 Apply @var{proc_lt}, @var{proc_eq}, @var{proc_gt} to the
5568 mismatch index, depending upon whether @var{s1} is less than,
5569 equal to, or greater than @var{s2}. The mismatch index is the
5570 largest index @var{i} such that for every 0 <= @var{j} <
5571 @var{i}, @var{s1}[@var{j}] = @var{s2}[@var{j}] -- that is,
5572 @var{i} is the first position that does not match. The
5573 character comparison is done case-insensitively.
5577 @c snarfed from srfi-13.c:1083
5578 @deffn {Scheme Procedure} string= s1 s2 [start1 [end1 [start2 [end2]]]]
5579 @deffnx {C Function} scm_string_eq (s1, s2, start1, end1, start2, end2)
5580 Return @code{#f} if @var{s1} and @var{s2} are not equal, a true
5585 @c snarfed from srfi-13.c:1122
5586 @deffn {Scheme Procedure} string<> s1 s2 [start1 [end1 [start2 [end2]]]]
5587 @deffnx {C Function} scm_string_neq (s1, s2, start1, end1, start2, end2)
5588 Return @code{#f} if @var{s1} and @var{s2} are equal, a true
5593 @c snarfed from srfi-13.c:1165
5594 @deffn {Scheme Procedure} string< s1 s2 [start1 [end1 [start2 [end2]]]]
5595 @deffnx {C Function} scm_string_lt (s1, s2, start1, end1, start2, end2)
5596 Return @code{#f} if @var{s1} is greater or equal to @var{s2}, a
5597 true value otherwise.
5601 @c snarfed from srfi-13.c:1208
5602 @deffn {Scheme Procedure} string> s1 s2 [start1 [end1 [start2 [end2]]]]
5603 @deffnx {C Function} scm_string_gt (s1, s2, start1, end1, start2, end2)
5604 Return @code{#f} if @var{s1} is less or equal to @var{s2}, a
5605 true value otherwise.
5609 @c snarfed from srfi-13.c:1251
5610 @deffn {Scheme Procedure} string<= s1 s2 [start1 [end1 [start2 [end2]]]]
5611 @deffnx {C Function} scm_string_le (s1, s2, start1, end1, start2, end2)
5612 Return @code{#f} if @var{s1} is greater to @var{s2}, a true
5617 @c snarfed from srfi-13.c:1294
5618 @deffn {Scheme Procedure} string>= s1 s2 [start1 [end1 [start2 [end2]]]]
5619 @deffnx {C Function} scm_string_ge (s1, s2, start1, end1, start2, end2)
5620 Return @code{#f} if @var{s1} is less to @var{s2}, a true value
5625 @c snarfed from srfi-13.c:1338
5626 @deffn {Scheme Procedure} string-ci= s1 s2 [start1 [end1 [start2 [end2]]]]
5627 @deffnx {C Function} scm_string_ci_eq (s1, s2, start1, end1, start2, end2)
5628 Return @code{#f} if @var{s1} and @var{s2} are not equal, a true
5629 value otherwise. The character comparison is done
5634 @c snarfed from srfi-13.c:1382
5635 @deffn {Scheme Procedure} string-ci<> s1 s2 [start1 [end1 [start2 [end2]]]]
5636 @deffnx {C Function} scm_string_ci_neq (s1, s2, start1, end1, start2, end2)
5637 Return @code{#f} if @var{s1} and @var{s2} are equal, a true
5638 value otherwise. The character comparison is done
5643 @c snarfed from srfi-13.c:1426
5644 @deffn {Scheme Procedure} string-ci< s1 s2 [start1 [end1 [start2 [end2]]]]
5645 @deffnx {C Function} scm_string_ci_lt (s1, s2, start1, end1, start2, end2)
5646 Return @code{#f} if @var{s1} is greater or equal to @var{s2}, a
5647 true value otherwise. The character comparison is done
5652 @c snarfed from srfi-13.c:1470
5653 @deffn {Scheme Procedure} string-ci> s1 s2 [start1 [end1 [start2 [end2]]]]
5654 @deffnx {C Function} scm_string_ci_gt (s1, s2, start1, end1, start2, end2)
5655 Return @code{#f} if @var{s1} is less or equal to @var{s2}, a
5656 true value otherwise. The character comparison is done
5661 @c snarfed from srfi-13.c:1514
5662 @deffn {Scheme Procedure} string-ci<= s1 s2 [start1 [end1 [start2 [end2]]]]
5663 @deffnx {C Function} scm_string_ci_le (s1, s2, start1, end1, start2, end2)
5664 Return @code{#f} if @var{s1} is greater to @var{s2}, a true
5665 value otherwise. The character comparison is done
5670 @c snarfed from srfi-13.c:1558
5671 @deffn {Scheme Procedure} string-ci>= s1 s2 [start1 [end1 [start2 [end2]]]]
5672 @deffnx {C Function} scm_string_ci_ge (s1, s2, start1, end1, start2, end2)
5673 Return @code{#f} if @var{s1} is less to @var{s2}, a true value
5674 otherwise. The character comparison is done
5679 @c snarfed from srfi-13.c:1603
5680 @deffn {Scheme Procedure} string-hash s [bound [start [end]]]
5681 @deffnx {C Function} scm_substring_hash (s, bound, start, end)
5682 Compute a hash value for @var{S}. the optional argument @var{bound} is a non-negative exact integer specifying the range of the hash function. A positive value restricts the return value to the range [0,bound).
5686 @c snarfed from srfi-13.c:1620
5687 @deffn {Scheme Procedure} string-hash-ci s [bound [start [end]]]
5688 @deffnx {C Function} scm_substring_hash_ci (s, bound, start, end)
5689 Compute a hash value for @var{S}. the optional argument @var{bound} is a non-negative exact integer specifying the range of the hash function. A positive value restricts the return value to the range [0,bound).
5692 \fstring-prefix-length
5693 @c snarfed from srfi-13.c:1632
5694 @deffn {Scheme Procedure} string-prefix-length s1 s2 [start1 [end1 [start2 [end2]]]]
5695 @deffnx {C Function} scm_string_prefix_length (s1, s2, start1, end1, start2, end2)
5696 Return the length of the longest common prefix of the two
5700 \fstring-prefix-length-ci
5701 @c snarfed from srfi-13.c:1664
5702 @deffn {Scheme Procedure} string-prefix-length-ci s1 s2 [start1 [end1 [start2 [end2]]]]
5703 @deffnx {C Function} scm_string_prefix_length_ci (s1, s2, start1, end1, start2, end2)
5704 Return the length of the longest common prefix of the two
5705 strings, ignoring character case.
5708 \fstring-suffix-length
5709 @c snarfed from srfi-13.c:1696
5710 @deffn {Scheme Procedure} string-suffix-length s1 s2 [start1 [end1 [start2 [end2]]]]
5711 @deffnx {C Function} scm_string_suffix_length (s1, s2, start1, end1, start2, end2)
5712 Return the length of the longest common suffix of the two
5716 \fstring-suffix-length-ci
5717 @c snarfed from srfi-13.c:1728
5718 @deffn {Scheme Procedure} string-suffix-length-ci s1 s2 [start1 [end1 [start2 [end2]]]]
5719 @deffnx {C Function} scm_string_suffix_length_ci (s1, s2, start1, end1, start2, end2)
5720 Return the length of the longest common suffix of the two
5721 strings, ignoring character case.
5725 @c snarfed from srfi-13.c:1759
5726 @deffn {Scheme Procedure} string-prefix? s1 s2 [start1 [end1 [start2 [end2]]]]
5727 @deffnx {C Function} scm_string_prefix_p (s1, s2, start1, end1, start2, end2)
5728 Is @var{s1} a prefix of @var{s2}?
5732 @c snarfed from srfi-13.c:1791
5733 @deffn {Scheme Procedure} string-prefix-ci? s1 s2 [start1 [end1 [start2 [end2]]]]
5734 @deffnx {C Function} scm_string_prefix_ci_p (s1, s2, start1, end1, start2, end2)
5735 Is @var{s1} a prefix of @var{s2}, ignoring character case?
5739 @c snarfed from srfi-13.c:1823
5740 @deffn {Scheme Procedure} string-suffix? s1 s2 [start1 [end1 [start2 [end2]]]]
5741 @deffnx {C Function} scm_string_suffix_p (s1, s2, start1, end1, start2, end2)
5742 Is @var{s1} a suffix of @var{s2}?
5746 @c snarfed from srfi-13.c:1855
5747 @deffn {Scheme Procedure} string-suffix-ci? s1 s2 [start1 [end1 [start2 [end2]]]]
5748 @deffnx {C Function} scm_string_suffix_ci_p (s1, s2, start1, end1, start2, end2)
5749 Is @var{s1} a suffix of @var{s2}, ignoring character case?
5753 @c snarfed from srfi-13.c:1899
5754 @deffn {Scheme Procedure} string-index s char_pred [start [end]]
5755 @deffnx {C Function} scm_string_index (s, char_pred, start, end)
5756 Search through the string @var{s} from left to right, returning
5757 the index of the first occurence of a character which
5761 equals @var{char_pred}, if it is character,
5764 satisifies the predicate @var{char_pred}, if it is a procedure,
5767 is in the set @var{char_pred}, if it is a character set.
5771 \fstring-index-right
5772 @c snarfed from srfi-13.c:1964
5773 @deffn {Scheme Procedure} string-index-right s char_pred [start [end]]
5774 @deffnx {C Function} scm_string_index_right (s, char_pred, start, end)
5775 Search through the string @var{s} from right to left, returning
5776 the index of the last occurence of a character which
5780 equals @var{char_pred}, if it is character,
5783 satisifies the predicate @var{char_pred}, if it is a procedure,
5786 is in the set if @var{char_pred} is a character set.
5791 @c snarfed from srfi-13.c:2029
5792 @deffn {Scheme Procedure} string-rindex s char_pred [start [end]]
5793 @deffnx {C Function} scm_string_rindex (s, char_pred, start, end)
5794 Search through the string @var{s} from right to left, returning
5795 the index of the last occurence of a character which
5799 equals @var{char_pred}, if it is character,
5802 satisifies the predicate @var{char_pred}, if it is a procedure,
5805 is in the set if @var{char_pred} is a character set.
5810 @c snarfed from srfi-13.c:2051
5811 @deffn {Scheme Procedure} string-skip s char_pred [start [end]]
5812 @deffnx {C Function} scm_string_skip (s, char_pred, start, end)
5813 Search through the string @var{s} from left to right, returning
5814 the index of the first occurence of a character which
5818 does not equal @var{char_pred}, if it is character,
5821 does not satisify the predicate @var{char_pred}, if it is a
5825 is not in the set if @var{char_pred} is a character set.
5830 @c snarfed from srfi-13.c:2118
5831 @deffn {Scheme Procedure} string-skip-right s char_pred [start [end]]
5832 @deffnx {C Function} scm_string_skip_right (s, char_pred, start, end)
5833 Search through the string @var{s} from right to left, returning
5834 the index of the last occurence of a character which
5838 does not equal @var{char_pred}, if it is character,
5841 does not satisfy the predicate @var{char_pred}, if it is a
5845 is not in the set if @var{char_pred} is a character set.
5850 @c snarfed from srfi-13.c:2185
5851 @deffn {Scheme Procedure} string-count s char_pred [start [end]]
5852 @deffnx {C Function} scm_string_count (s, char_pred, start, end)
5853 Return the count of the number of characters in the string
5858 equals @var{char_pred}, if it is character,
5861 satisifies the predicate @var{char_pred}, if it is a procedure.
5864 is in the set @var{char_pred}, if it is a character set.
5869 @c snarfed from srfi-13.c:2242
5870 @deffn {Scheme Procedure} string-contains s1 s2 [start1 [end1 [start2 [end2]]]]
5871 @deffnx {C Function} scm_string_contains (s1, s2, start1, end1, start2, end2)
5872 Does string @var{s1} contain string @var{s2}? Return the index
5873 in @var{s1} where @var{s2} occurs as a substring, or false.
5874 The optional start/end indices restrict the operation to the
5875 indicated substrings.
5878 \fstring-contains-ci
5879 @c snarfed from srfi-13.c:2289
5880 @deffn {Scheme Procedure} string-contains-ci s1 s2 [start1 [end1 [start2 [end2]]]]
5881 @deffnx {C Function} scm_string_contains_ci (s1, s2, start1, end1, start2, end2)
5882 Does string @var{s1} contain string @var{s2}? Return the index
5883 in @var{s1} where @var{s2} occurs as a substring, or false.
5884 The optional start/end indices restrict the operation to the
5885 indicated substrings. Character comparison is done
5890 @c snarfed from srfi-13.c:2354
5891 @deffn {Scheme Procedure} string-upcase! str [start [end]]
5892 @deffnx {C Function} scm_substring_upcase_x (str, start, end)
5893 Destructively upcase every character in @code{str}.
5904 @c snarfed from srfi-13.c:2375
5905 @deffn {Scheme Procedure} string-upcase str [start [end]]
5906 @deffnx {C Function} scm_substring_upcase (str, start, end)
5907 Upcase every character in @code{str}.
5911 @c snarfed from srfi-13.c:2422
5912 @deffn {Scheme Procedure} string-downcase! str [start [end]]
5913 @deffnx {C Function} scm_substring_downcase_x (str, start, end)
5914 Destructively downcase every character in @var{str}.
5919 (string-downcase! y)
5927 @c snarfed from srfi-13.c:2443
5928 @deffn {Scheme Procedure} string-downcase str [start [end]]
5929 @deffnx {C Function} scm_substring_downcase (str, start, end)
5930 Downcase every character in @var{str}.
5934 @c snarfed from srfi-13.c:2499
5935 @deffn {Scheme Procedure} string-titlecase! str [start [end]]
5936 @deffnx {C Function} scm_string_titlecase_x (str, start, end)
5937 Destructively titlecase every first character in a word in
5942 @c snarfed from srfi-13.c:2515
5943 @deffn {Scheme Procedure} string-titlecase str [start [end]]
5944 @deffnx {C Function} scm_string_titlecase (str, start, end)
5945 Titlecase every first character in a word in @var{str}.
5948 \fstring-capitalize!
5949 @c snarfed from srfi-13.c:2537
5950 @deffn {Scheme Procedure} string-capitalize! str
5951 @deffnx {C Function} scm_string_capitalize_x (str)
5952 Upcase the first character of every word in @var{str}
5953 destructively and return @var{str}.
5956 y @result{} "hello world"
5957 (string-capitalize! y) @result{} "Hello World"
5958 y @result{} "Hello World"
5963 @c snarfed from srfi-13.c:2549
5964 @deffn {Scheme Procedure} string-capitalize str
5965 @deffnx {C Function} scm_string_capitalize (str)
5966 Return a freshly allocated string with the characters in
5967 @var{str}, where the first character of every word is
5972 @c snarfed from srfi-13.c:2583
5973 @deffn {Scheme Procedure} string-reverse str [start [end]]
5974 @deffnx {C Function} scm_string_reverse (str, start, end)
5975 Reverse the string @var{str}. The optional arguments
5976 @var{start} and @var{end} delimit the region of @var{str} to
5981 @c snarfed from srfi-13.c:2608
5982 @deffn {Scheme Procedure} string-reverse! str [start [end]]
5983 @deffnx {C Function} scm_string_reverse_x (str, start, end)
5984 Reverse the string @var{str} in-place. The optional arguments
5985 @var{start} and @var{end} delimit the region of @var{str} to
5986 operate on. The return value is unspecified.
5989 \fstring-append/shared
5990 @c snarfed from srfi-13.c:2630
5991 @deffn {Scheme Procedure} string-append/shared . ls
5992 @deffnx {C Function} scm_string_append_shared (ls)
5993 Like @code{string-append}, but the result may share memory
5994 with the argument strings.
5997 \fstring-concatenate
5998 @c snarfed from srfi-13.c:2651
5999 @deffn {Scheme Procedure} string-concatenate ls
6000 @deffnx {C Function} scm_string_concatenate (ls)
6001 Append the elements of @var{ls} (which must be strings)
6002 together into a single string. Guaranteed to return a freshly
6006 \fstring-concatenate-reverse
6007 @c snarfed from srfi-13.c:2673
6008 @deffn {Scheme Procedure} string-concatenate-reverse ls [final_string [end]]
6009 @deffnx {C Function} scm_string_concatenate_reverse (ls, final_string, end)
6010 Without optional arguments, this procedure is equivalent to
6013 (string-concatenate (reverse ls))
6016 If the optional argument @var{final_string} is specified, it is
6017 consed onto the beginning to @var{ls} before performing the
6018 list-reverse and string-concatenate operations. If @var{end}
6019 is given, only the characters of @var{final_string} up to index
6022 Guaranteed to return a freshly allocated string.
6025 \fstring-concatenate/shared
6026 @c snarfed from srfi-13.c:2690
6027 @deffn {Scheme Procedure} string-concatenate/shared ls
6028 @deffnx {C Function} scm_string_concatenate_shared (ls)
6029 Like @code{string-concatenate}, but the result may share memory
6030 with the strings in the list @var{ls}.
6033 \fstring-concatenate-reverse/shared
6034 @c snarfed from srfi-13.c:2701
6035 @deffn {Scheme Procedure} string-concatenate-reverse/shared ls [final_string [end]]
6036 @deffnx {C Function} scm_string_concatenate_reverse_shared (ls, final_string, end)
6037 Like @code{string-concatenate-reverse}, but the result may
6038 share memory with the the strings in the @var{ls} arguments.
6042 @c snarfed from srfi-13.c:2714
6043 @deffn {Scheme Procedure} string-map proc s [start [end]]
6044 @deffnx {C Function} scm_string_map (proc, s, start, end)
6045 @var{proc} is a char->char procedure, it is mapped over
6046 @var{s}. The order in which the procedure is applied to the
6047 string elements is not specified.
6051 @c snarfed from srfi-13.c:2744
6052 @deffn {Scheme Procedure} string-map! proc s [start [end]]
6053 @deffnx {C Function} scm_string_map_x (proc, s, start, end)
6054 @var{proc} is a char->char procedure, it is mapped over
6055 @var{s}. The order in which the procedure is applied to the
6056 string elements is not specified. The string @var{s} is
6057 modified in-place, the return value is not specified.
6061 @c snarfed from srfi-13.c:2771
6062 @deffn {Scheme Procedure} string-fold kons knil s [start [end]]
6063 @deffnx {C Function} scm_string_fold (kons, knil, s, start, end)
6064 Fold @var{kons} over the characters of @var{s}, with @var{knil}
6065 as the terminating element, from left to right. @var{kons}
6066 must expect two arguments: The actual character and the last
6067 result of @var{kons}' application.
6071 @c snarfed from srfi-13.c:2802
6072 @deffn {Scheme Procedure} string-fold-right kons knil s [start [end]]
6073 @deffnx {C Function} scm_string_fold_right (kons, knil, s, start, end)
6074 Fold @var{kons} over the characters of @var{s}, with @var{knil}
6075 as the terminating element, from right to left. @var{kons}
6076 must expect two arguments: The actual character and the last
6077 result of @var{kons}' application.
6081 @c snarfed from srfi-13.c:2847
6082 @deffn {Scheme Procedure} string-unfold p f g seed [base [make_final]]
6083 @deffnx {C Function} scm_string_unfold (p, f, g, seed, base, make_final)
6085 @item @var{g} is used to generate a series of @emph{seed}
6086 values from the initial @var{seed}: @var{seed}, (@var{g}
6087 @var{seed}), (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}),
6089 @item @var{p} tells us when to stop -- when it returns true
6090 when applied to one of these seed values.
6091 @item @var{f} maps each seed value to the corresponding
6092 character in the result string. These chars are assembled
6093 into the string in a left-to-right order.
6094 @item @var{base} is the optional initial/leftmost portion
6095 of the constructed string; it default to the empty
6097 @item @var{make_final} is applied to the terminal seed
6098 value (on which @var{p} returns true) to produce
6099 the final/rightmost portion of the constructed string.
6100 It defaults to @code{(lambda (x) )}.
6104 \fstring-unfold-right
6105 @c snarfed from srfi-13.c:2910
6106 @deffn {Scheme Procedure} string-unfold-right p f g seed [base [make_final]]
6107 @deffnx {C Function} scm_string_unfold_right (p, f, g, seed, base, make_final)
6109 @item @var{g} is used to generate a series of @emph{seed}
6110 values from the initial @var{seed}: @var{seed}, (@var{g}
6111 @var{seed}), (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}),
6113 @item @var{p} tells us when to stop -- when it returns true
6114 when applied to one of these seed values.
6115 @item @var{f} maps each seed value to the corresponding
6116 character in the result string. These chars are assembled
6117 into the string in a right-to-left order.
6118 @item @var{base} is the optional initial/rightmost portion
6119 of the constructed string; it default to the empty
6121 @item @var{make_final} is applied to the terminal seed
6122 value (on which @var{p} returns true) to produce
6123 the final/leftmost portion of the constructed string.
6124 It defaults to @code{(lambda (x) )}.
6129 @c snarfed from srfi-13.c:2957
6130 @deffn {Scheme Procedure} string-for-each proc s [start [end]]
6131 @deffnx {C Function} scm_string_for_each (proc, s, start, end)
6132 @var{proc} is mapped over @var{s} in left-to-right order. The
6133 return value is not specified.
6136 \fstring-for-each-index
6137 @c snarfed from srfi-13.c:2983
6138 @deffn {Scheme Procedure} string-for-each-index proc s [start [end]]
6139 @deffnx {C Function} scm_string_for_each_index (proc, s, start, end)
6140 @var{proc} is mapped over @var{s} in left-to-right order. The
6141 return value is not specified.
6145 @c snarfed from srfi-13.c:3015
6146 @deffn {Scheme Procedure} xsubstring s from [to [start [end]]]
6147 @deffnx {C Function} scm_xsubstring (s, from, to, start, end)
6148 This is the @emph{extended substring} procedure that implements
6149 replicated copying of a substring of some string.
6151 @var{s} is a string, @var{start} and @var{end} are optional
6152 arguments that demarcate a substring of @var{s}, defaulting to
6153 0 and the length of @var{s}. Replicate this substring up and
6154 down index space, in both the positive and negative directions.
6155 @code{xsubstring} returns the substring of this string
6156 beginning at index @var{from}, and ending at @var{to}, which
6157 defaults to @var{from} + (@var{end} - @var{start}).
6161 @c snarfed from srfi-13.c:3062
6162 @deffn {Scheme Procedure} string-xcopy! target tstart s sfrom [sto [start [end]]]
6163 @deffnx {C Function} scm_string_xcopy_x (target, tstart, s, sfrom, sto, start, end)
6164 Exactly the same as @code{xsubstring}, but the extracted text
6165 is written into the string @var{target} starting at index
6166 @var{tstart}. The operation is not defined if @code{(eq?
6167 @var{target} @var{s})} or these arguments share storage -- you
6168 cannot copy a string on top of itself.
6172 @c snarfed from srfi-13.c:3112
6173 @deffn {Scheme Procedure} string-replace s1 s2 [start1 [end1 [start2 [end2]]]]
6174 @deffnx {C Function} scm_string_replace (s1, s2, start1, end1, start2, end2)
6175 Return the string @var{s1}, but with the characters
6176 @var{start1} @dots{} @var{end1} replaced by the characters
6177 @var{start2} @dots{} @var{end2} from @var{s2}.
6181 @c snarfed from srfi-13.c:3149
6182 @deffn {Scheme Procedure} string-tokenize s [token_set [start [end]]]
6183 @deffnx {C Function} scm_string_tokenize (s, token_set, start, end)
6184 Split the string @var{s} into a list of substrings, where each
6185 substring is a maximal non-empty contiguous sequence of
6186 characters from the character set @var{token_set}, which
6187 defaults to @code{char-set:graphic}.
6188 If @var{start} or @var{end} indices are provided, they restrict
6189 @code{string-tokenize} to operating on the indicated substring
6194 @c snarfed from srfi-13.c:3215
6195 @deffn {Scheme Procedure} string-split str chr
6196 @deffnx {C Function} scm_string_split (str, chr)
6197 Split the string @var{str} into the a list of the substrings delimited
6198 by appearances of the character @var{chr}. Note that an empty substring
6199 between separator characters will result in an empty string in the
6203 (string-split "root:x:0:0:root:/root:/bin/bash" #\:)
6205 ("root" "x" "0" "0" "root" "/root" "/bin/bash")
6207 (string-split "::" #\:)
6211 (string-split "" #\:)
6218 @c snarfed from srfi-13.c:3253
6219 @deffn {Scheme Procedure} string-filter s char_pred [start [end]]
6220 @deffnx {C Function} scm_string_filter (s, char_pred, start, end)
6221 Filter the string @var{s}, retaining only those characters that
6222 satisfy the @var{char_pred} argument. If the argument is a
6223 procedure, it is applied to each character as a predicate, if
6224 it is a character, it is tested for equality and if it is a
6225 character set, it is tested for membership.
6229 @c snarfed from srfi-13.c:3325
6230 @deffn {Scheme Procedure} string-delete s char_pred [start [end]]
6231 @deffnx {C Function} scm_string_delete (s, char_pred, start, end)
6232 Filter the string @var{s}, retaining only those characters that
6233 do not satisfy the @var{char_pred} argument. If the argument
6234 is a procedure, it is applied to each character as a predicate,
6235 if it is a character, it is tested for equality and if it is a
6236 character set, it is tested for membership.
6240 @c snarfed from srfi-14.c:85
6241 @deffn {Scheme Procedure} char-set? obj
6242 @deffnx {C Function} scm_char_set_p (obj)
6243 Return @code{#t} if @var{obj} is a character set, @code{#f}
6248 @c snarfed from srfi-14.c:95
6249 @deffn {Scheme Procedure} char-set= . char_sets
6250 @deffnx {C Function} scm_char_set_eq (char_sets)
6251 Return @code{#t} if all given character sets are equal.
6255 @c snarfed from srfi-14.c:125
6256 @deffn {Scheme Procedure} char-set<= . char_sets
6257 @deffnx {C Function} scm_char_set_leq (char_sets)
6258 Return @code{#t} if every character set @var{cs}i is a subset
6259 of character set @var{cs}i+1.
6263 @c snarfed from srfi-14.c:163
6264 @deffn {Scheme Procedure} char-set-hash cs [bound]
6265 @deffnx {C Function} scm_char_set_hash (cs, bound)
6266 Compute a hash value for the character set @var{cs}. If
6267 @var{bound} is given and non-zero, it restricts the
6268 returned value to the range 0 @dots{} @var{bound - 1}.
6272 @c snarfed from srfi-14.c:196
6273 @deffn {Scheme Procedure} char-set-cursor cs
6274 @deffnx {C Function} scm_char_set_cursor (cs)
6275 Return a cursor into the character set @var{cs}.
6279 @c snarfed from srfi-14.c:216
6280 @deffn {Scheme Procedure} char-set-ref cs cursor
6281 @deffnx {C Function} scm_char_set_ref (cs, cursor)
6282 Return the character at the current cursor position
6283 @var{cursor} in the character set @var{cs}. It is an error to
6284 pass a cursor for which @code{end-of-char-set?} returns true.
6287 \fchar-set-cursor-next
6288 @c snarfed from srfi-14.c:233
6289 @deffn {Scheme Procedure} char-set-cursor-next cs cursor
6290 @deffnx {C Function} scm_char_set_cursor_next (cs, cursor)
6291 Advance the character set cursor @var{cursor} to the next
6292 character in the character set @var{cs}. It is an error if the
6293 cursor given satisfies @code{end-of-char-set?}.
6297 @c snarfed from srfi-14.c:254
6298 @deffn {Scheme Procedure} end-of-char-set? cursor
6299 @deffnx {C Function} scm_end_of_char_set_p (cursor)
6300 Return @code{#t} if @var{cursor} has reached the end of a
6301 character set, @code{#f} otherwise.
6305 @c snarfed from srfi-14.c:266
6306 @deffn {Scheme Procedure} char-set-fold kons knil cs
6307 @deffnx {C Function} scm_char_set_fold (kons, knil, cs)
6308 Fold the procedure @var{kons} over the character set @var{cs},
6309 initializing it with @var{knil}.
6313 @c snarfed from srfi-14.c:296
6314 @deffn {Scheme Procedure} char-set-unfold p f g seed [base_cs]
6315 @deffnx {C Function} scm_char_set_unfold (p, f, g, seed, base_cs)
6316 This is a fundamental constructor for character sets.
6318 @item @var{g} is used to generate a series of ``seed'' values
6319 from the initial seed: @var{seed}, (@var{g} @var{seed}),
6320 (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}), @dots{}
6321 @item @var{p} tells us when to stop -- when it returns true
6322 when applied to one of the seed values.
6323 @item @var{f} maps each seed value to a character. These
6324 characters are added to the base character set @var{base_cs} to
6325 form the result; @var{base_cs} defaults to the empty set.
6330 @c snarfed from srfi-14.c:340
6331 @deffn {Scheme Procedure} char-set-unfold! p f g seed base_cs
6332 @deffnx {C Function} scm_char_set_unfold_x (p, f, g, seed, base_cs)
6333 This is a fundamental constructor for character sets.
6335 @item @var{g} is used to generate a series of ``seed'' values
6336 from the initial seed: @var{seed}, (@var{g} @var{seed}),
6337 (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}), @dots{}
6338 @item @var{p} tells us when to stop -- when it returns true
6339 when applied to one of the seed values.
6340 @item @var{f} maps each seed value to a character. These
6341 characters are added to the base character set @var{base_cs} to
6342 form the result; @var{base_cs} defaults to the empty set.
6347 @c snarfed from srfi-14.c:369
6348 @deffn {Scheme Procedure} char-set-for-each proc cs
6349 @deffnx {C Function} scm_char_set_for_each (proc, cs)
6350 Apply @var{proc} to every character in the character set
6351 @var{cs}. The return value is not specified.
6355 @c snarfed from srfi-14.c:388
6356 @deffn {Scheme Procedure} char-set-map proc cs
6357 @deffnx {C Function} scm_char_set_map (proc, cs)
6358 Map the procedure @var{proc} over every character in @var{cs}.
6359 @var{proc} must be a character -> character procedure.
6363 @c snarfed from srfi-14.c:414
6364 @deffn {Scheme Procedure} char-set-copy cs
6365 @deffnx {C Function} scm_char_set_copy (cs)
6366 Return a newly allocated character set containing all
6367 characters in @var{cs}.
6371 @c snarfed from srfi-14.c:434
6372 @deffn {Scheme Procedure} char-set . rest
6373 @deffnx {C Function} scm_char_set (rest)
6374 Return a character set containing all given characters.
6378 @c snarfed from srfi-14.c:462
6379 @deffn {Scheme Procedure} list->char-set list [base_cs]
6380 @deffnx {C Function} scm_list_to_char_set (list, base_cs)
6381 Convert the character list @var{list} to a character set. If
6382 the character set @var{base_cs} is given, the character in this
6383 set are also included in the result.
6387 @c snarfed from srfi-14.c:496
6388 @deffn {Scheme Procedure} list->char-set! list base_cs
6389 @deffnx {C Function} scm_list_to_char_set_x (list, base_cs)
6390 Convert the character list @var{list} to a character set. The
6391 characters are added to @var{base_cs} and @var{base_cs} is
6396 @c snarfed from srfi-14.c:523
6397 @deffn {Scheme Procedure} string->char-set str [base_cs]
6398 @deffnx {C Function} scm_string_to_char_set (str, base_cs)
6399 Convert the string @var{str} to a character set. If the
6400 character set @var{base_cs} is given, the characters in this
6401 set are also included in the result.
6405 @c snarfed from srfi-14.c:557
6406 @deffn {Scheme Procedure} string->char-set! str base_cs
6407 @deffnx {C Function} scm_string_to_char_set_x (str, base_cs)
6408 Convert the string @var{str} to a character set. The
6409 characters from the string are added to @var{base_cs}, and
6410 @var{base_cs} is returned.
6414 @c snarfed from srfi-14.c:584
6415 @deffn {Scheme Procedure} char-set-filter pred cs [base_cs]
6416 @deffnx {C Function} scm_char_set_filter (pred, cs, base_cs)
6417 Return a character set containing every character from @var{cs}
6418 so that it satisfies @var{pred}. If provided, the characters
6419 from @var{base_cs} are added to the result.
6423 @c snarfed from srfi-14.c:620
6424 @deffn {Scheme Procedure} char-set-filter! pred cs base_cs
6425 @deffnx {C Function} scm_char_set_filter_x (pred, cs, base_cs)
6426 Return a character set containing every character from @var{cs}
6427 so that it satisfies @var{pred}. The characters are added to
6428 @var{base_cs} and @var{base_cs} is returned.
6431 \fucs-range->char-set
6432 @c snarfed from srfi-14.c:658
6433 @deffn {Scheme Procedure} ucs-range->char-set lower upper [error [base_cs]]
6434 @deffnx {C Function} scm_ucs_range_to_char_set (lower, upper, error, base_cs)
6435 Return a character set containing all characters whose
6436 character codes lie in the half-open range
6437 [@var{lower},@var{upper}).
6439 If @var{error} is a true value, an error is signalled if the
6440 specified range contains characters which are not contained in
6441 the implemented character range. If @var{error} is @code{#f},
6442 these characters are silently left out of the resultung
6445 The characters in @var{base_cs} are added to the result, if
6449 \fucs-range->char-set!
6450 @c snarfed from srfi-14.c:711
6451 @deffn {Scheme Procedure} ucs-range->char-set! lower upper error base_cs
6452 @deffnx {C Function} scm_ucs_range_to_char_set_x (lower, upper, error, base_cs)
6453 Return a character set containing all characters whose
6454 character codes lie in the half-open range
6455 [@var{lower},@var{upper}).
6457 If @var{error} is a true value, an error is signalled if the
6458 specified range contains characters which are not contained in
6459 the implemented character range. If @var{error} is @code{#f},
6460 these characters are silently left out of the resultung
6463 The characters are added to @var{base_cs} and @var{base_cs} is
6468 @c snarfed from srfi-14.c:741
6469 @deffn {Scheme Procedure} ->char-set x
6470 @deffnx {C Function} scm_to_char_set (x)
6471 Coerces x into a char-set. @var{x} may be a string, character or char-set. A string is converted to the set of its constituent characters; a character is converted to a singleton set; a char-set is returned as-is.
6475 @c snarfed from srfi-14.c:757
6476 @deffn {Scheme Procedure} char-set-size cs
6477 @deffnx {C Function} scm_char_set_size (cs)
6478 Return the number of elements in character set @var{cs}.
6482 @c snarfed from srfi-14.c:774
6483 @deffn {Scheme Procedure} char-set-count pred cs
6484 @deffnx {C Function} scm_char_set_count (pred, cs)
6485 Return the number of the elements int the character set
6486 @var{cs} which satisfy the predicate @var{pred}.
6490 @c snarfed from srfi-14.c:797
6491 @deffn {Scheme Procedure} char-set->list cs
6492 @deffnx {C Function} scm_char_set_to_list (cs)
6493 Return a list containing the elements of the character set
6498 @c snarfed from srfi-14.c:816
6499 @deffn {Scheme Procedure} char-set->string cs
6500 @deffnx {C Function} scm_char_set_to_string (cs)
6501 Return a string containing the elements of the character set
6502 @var{cs}. The order in which the characters are placed in the
6503 string is not defined.
6506 \fchar-set-contains?
6507 @c snarfed from srfi-14.c:841
6508 @deffn {Scheme Procedure} char-set-contains? cs ch
6509 @deffnx {C Function} scm_char_set_contains_p (cs, ch)
6510 Return @code{#t} iff the character @var{ch} is contained in the
6511 character set @var{cs}.
6515 @c snarfed from srfi-14.c:854
6516 @deffn {Scheme Procedure} char-set-every pred cs
6517 @deffnx {C Function} scm_char_set_every (pred, cs)
6518 Return a true value if every character in the character set
6519 @var{cs} satisfies the predicate @var{pred}.
6523 @c snarfed from srfi-14.c:878
6524 @deffn {Scheme Procedure} char-set-any pred cs
6525 @deffnx {C Function} scm_char_set_any (pred, cs)
6526 Return a true value if any character in the character set
6527 @var{cs} satisfies the predicate @var{pred}.
6531 @c snarfed from srfi-14.c:901
6532 @deffn {Scheme Procedure} char-set-adjoin cs . rest
6533 @deffnx {C Function} scm_char_set_adjoin (cs, rest)
6534 Add all character arguments to the first argument, which must
6539 @c snarfed from srfi-14.c:929
6540 @deffn {Scheme Procedure} char-set-delete cs . rest
6541 @deffnx {C Function} scm_char_set_delete (cs, rest)
6542 Delete all character arguments from the first argument, which
6543 must be a character set.
6547 @c snarfed from srfi-14.c:957
6548 @deffn {Scheme Procedure} char-set-adjoin! cs . rest
6549 @deffnx {C Function} scm_char_set_adjoin_x (cs, rest)
6550 Add all character arguments to the first argument, which must
6555 @c snarfed from srfi-14.c:984
6556 @deffn {Scheme Procedure} char-set-delete! cs . rest
6557 @deffnx {C Function} scm_char_set_delete_x (cs, rest)
6558 Delete all character arguments from the first argument, which
6559 must be a character set.
6562 \fchar-set-complement
6563 @c snarfed from srfi-14.c:1010
6564 @deffn {Scheme Procedure} char-set-complement cs
6565 @deffnx {C Function} scm_char_set_complement (cs)
6566 Return the complement of the character set @var{cs}.
6570 @c snarfed from srfi-14.c:1031
6571 @deffn {Scheme Procedure} char-set-union . rest
6572 @deffnx {C Function} scm_char_set_union (rest)
6573 Return the union of all argument character sets.
6576 \fchar-set-intersection
6577 @c snarfed from srfi-14.c:1060
6578 @deffn {Scheme Procedure} char-set-intersection . rest
6579 @deffnx {C Function} scm_char_set_intersection (rest)
6580 Return the intersection of all argument character sets.
6583 \fchar-set-difference
6584 @c snarfed from srfi-14.c:1100
6585 @deffn {Scheme Procedure} char-set-difference cs1 . rest
6586 @deffnx {C Function} scm_char_set_difference (cs1, rest)
6587 Return the difference of all argument character sets.
6591 @c snarfed from srfi-14.c:1130
6592 @deffn {Scheme Procedure} char-set-xor . rest
6593 @deffnx {C Function} scm_char_set_xor (rest)
6594 Return the exclusive-or of all argument character sets.
6597 \fchar-set-diff+intersection
6598 @c snarfed from srfi-14.c:1171
6599 @deffn {Scheme Procedure} char-set-diff+intersection cs1 . rest
6600 @deffnx {C Function} scm_char_set_diff_plus_intersection (cs1, rest)
6601 Return the difference and the intersection of all argument
6605 \fchar-set-complement!
6606 @c snarfed from srfi-14.c:1209
6607 @deffn {Scheme Procedure} char-set-complement! cs
6608 @deffnx {C Function} scm_char_set_complement_x (cs)
6609 Return the complement of the character set @var{cs}.
6613 @c snarfed from srfi-14.c:1226
6614 @deffn {Scheme Procedure} char-set-union! cs1 . rest
6615 @deffnx {C Function} scm_char_set_union_x (cs1, rest)
6616 Return the union of all argument character sets.
6619 \fchar-set-intersection!
6620 @c snarfed from srfi-14.c:1254
6621 @deffn {Scheme Procedure} char-set-intersection! cs1 . rest
6622 @deffnx {C Function} scm_char_set_intersection_x (cs1, rest)
6623 Return the intersection of all argument character sets.
6626 \fchar-set-difference!
6627 @c snarfed from srfi-14.c:1282
6628 @deffn {Scheme Procedure} char-set-difference! cs1 . rest
6629 @deffnx {C Function} scm_char_set_difference_x (cs1, rest)
6630 Return the difference of all argument character sets.
6634 @c snarfed from srfi-14.c:1310
6635 @deffn {Scheme Procedure} char-set-xor! cs1 . rest
6636 @deffnx {C Function} scm_char_set_xor_x (cs1, rest)
6637 Return the exclusive-or of all argument character sets.
6640 \fchar-set-diff+intersection!
6641 @c snarfed from srfi-14.c:1349
6642 @deffn {Scheme Procedure} char-set-diff+intersection! cs1 cs2 . rest
6643 @deffnx {C Function} scm_char_set_diff_plus_intersection_x (cs1, cs2, rest)
6644 Return the difference and the intersection of all argument
6649 @c snarfed from strorder.c:50
6650 @deffn {Scheme Procedure} string=? s1 s2
6651 Lexicographic equality predicate; return @code{#t} if the two
6652 strings are the same length and contain the same characters in
6653 the same positions, otherwise return @code{#f}.
6655 The procedure @code{string-ci=?} treats upper and lower case
6656 letters as though they were the same character, but
6657 @code{string=?} treats upper and lower case as distinct
6662 @c snarfed from strorder.c:62
6663 @deffn {Scheme Procedure} string-ci=? s1 s2
6664 Case-insensitive string equality predicate; return @code{#t} if
6665 the two strings are the same length and their component
6666 characters match (ignoring case) at each position; otherwise
6671 @c snarfed from strorder.c:72
6672 @deffn {Scheme Procedure} string<? s1 s2
6673 Lexicographic ordering predicate; return @code{#t} if @var{s1}
6674 is lexicographically less than @var{s2}.
6678 @c snarfed from strorder.c:82
6679 @deffn {Scheme Procedure} string<=? s1 s2
6680 Lexicographic ordering predicate; return @code{#t} if @var{s1}
6681 is lexicographically less than or equal to @var{s2}.
6685 @c snarfed from strorder.c:92
6686 @deffn {Scheme Procedure} string>? s1 s2
6687 Lexicographic ordering predicate; return @code{#t} if @var{s1}
6688 is lexicographically greater than @var{s2}.
6692 @c snarfed from strorder.c:102
6693 @deffn {Scheme Procedure} string>=? s1 s2
6694 Lexicographic ordering predicate; return @code{#t} if @var{s1}
6695 is lexicographically greater than or equal to @var{s2}.
6699 @c snarfed from strorder.c:113
6700 @deffn {Scheme Procedure} string-ci<? s1 s2
6701 Case insensitive lexicographic ordering predicate; return
6702 @code{#t} if @var{s1} is lexicographically less than @var{s2}
6707 @c snarfed from strorder.c:124
6708 @deffn {Scheme Procedure} string-ci<=? s1 s2
6709 Case insensitive lexicographic ordering predicate; return
6710 @code{#t} if @var{s1} is lexicographically less than or equal
6711 to @var{s2} regardless of case.
6715 @c snarfed from strorder.c:135
6716 @deffn {Scheme Procedure} string-ci>? s1 s2
6717 Case insensitive lexicographic ordering predicate; return
6718 @code{#t} if @var{s1} is lexicographically greater than
6719 @var{s2} regardless of case.
6723 @c snarfed from strorder.c:146
6724 @deffn {Scheme Procedure} string-ci>=? s1 s2
6725 Case insensitive lexicographic ordering predicate; return
6726 @code{#t} if @var{s1} is lexicographically greater than or
6727 equal to @var{s2} regardless of case.
6731 @c snarfed from strports.c:332
6732 @deffn {Scheme Procedure} object->string obj [printer]
6733 @deffnx {C Function} scm_object_to_string (obj, printer)
6734 Return a Scheme string obtained by printing @var{obj}.
6735 Printing function can be specified by the optional second
6736 argument @var{printer} (default: @code{write}).
6739 \fcall-with-output-string
6740 @c snarfed from strports.c:356
6741 @deffn {Scheme Procedure} call-with-output-string proc
6742 @deffnx {C Function} scm_call_with_output_string (proc)
6743 Calls the one-argument procedure @var{proc} with a newly created output
6744 port. When the function returns, the string composed of the characters
6745 written into the port is returned.
6748 \fcall-with-input-string
6749 @c snarfed from strports.c:375
6750 @deffn {Scheme Procedure} call-with-input-string string proc
6751 @deffnx {C Function} scm_call_with_input_string (string, proc)
6752 Calls the one-argument procedure @var{proc} with a newly
6753 created input port from which @var{string}'s contents may be
6754 read. The value yielded by the @var{proc} is returned.
6758 @c snarfed from strports.c:388
6759 @deffn {Scheme Procedure} open-input-string str
6760 @deffnx {C Function} scm_open_input_string (str)
6761 Take a string and return an input port that delivers characters
6762 from the string. The port can be closed by
6763 @code{close-input-port}, though its storage will be reclaimed
6764 by the garbage collector if it becomes inaccessible.
6767 \fopen-output-string
6768 @c snarfed from strports.c:402
6769 @deffn {Scheme Procedure} open-output-string
6770 @deffnx {C Function} scm_open_output_string ()
6771 Return an output port that will accumulate characters for
6772 retrieval by @code{get-output-string}. The port can be closed
6773 by the procedure @code{close-output-port}, though its storage
6774 will be reclaimed by the garbage collector if it becomes
6779 @c snarfed from strports.c:419
6780 @deffn {Scheme Procedure} get-output-string port
6781 @deffnx {C Function} scm_get_output_string (port)
6782 Given an output port created by @code{open-output-string},
6783 return a string consisting of the characters that have been
6784 output to the port so far.
6788 @c snarfed from strports.c:488
6789 @deffn {Scheme Procedure} eval-string string [module]
6790 @deffnx {C Function} scm_eval_string_in_module (string, module)
6791 Evaluate @var{string} as the text representation of a Scheme
6792 form or forms, and return whatever value they produce.
6793 Evaluation takes place in the given module, or the current
6794 module when no module is given.
6795 While the code is evaluated, the given module is made the
6796 current one. The current module is restored when this
6800 \fmake-struct-layout
6801 @c snarfed from struct.c:55
6802 @deffn {Scheme Procedure} make-struct-layout fields
6803 @deffnx {C Function} scm_make_struct_layout (fields)
6804 Return a new structure layout object.
6806 @var{fields} must be a string made up of pairs of characters
6807 strung together. The first character of each pair describes a field
6808 type, the second a field protection. Allowed types are 'p' for
6809 GC-protected Scheme data, 'u' for unprotected binary data, and 's' for
6810 a field that points to the structure itself. Allowed protections
6811 are 'w' for mutable fields, 'r' for read-only fields, and 'o' for opaque
6812 fields. The last field protection specification may be capitalized to
6813 indicate that the field is a tail-array.
6817 @c snarfed from struct.c:222
6818 @deffn {Scheme Procedure} struct? x
6819 @deffnx {C Function} scm_struct_p (x)
6820 Return @code{#t} iff @var{x} is a structure object, else
6825 @c snarfed from struct.c:231
6826 @deffn {Scheme Procedure} struct-vtable? x
6827 @deffnx {C Function} scm_struct_vtable_p (x)
6828 Return @code{#t} iff @var{x} is a vtable structure.
6832 @c snarfed from struct.c:417
6833 @deffn {Scheme Procedure} make-struct vtable tail_array_size . init
6834 @deffnx {C Function} scm_make_struct (vtable, tail_array_size, init)
6835 Create a new structure.
6837 @var{type} must be a vtable structure (@pxref{Vtables}).
6839 @var{tail-elts} must be a non-negative integer. If the layout
6840 specification indicated by @var{type} includes a tail-array,
6841 this is the number of elements allocated to that array.
6843 The @var{init1}, @dots{} are optional arguments describing how
6844 successive fields of the structure should be initialized. Only fields
6845 with protection 'r' or 'w' can be initialized, except for fields of
6846 type 's', which are automatically initialized to point to the new
6847 structure itself; fields with protection 'o' can not be initialized by
6850 If fewer optional arguments than initializable fields are supplied,
6851 fields of type 'p' get default value #f while fields of type 'u' are
6854 Structs are currently the basic representation for record-like data
6855 structures in Guile. The plan is to eventually replace them with a
6856 new representation which will at the same time be easier to use and
6859 For more information, see the documentation for @code{make-vtable-vtable}.
6862 \fmake-vtable-vtable
6863 @c snarfed from struct.c:501
6864 @deffn {Scheme Procedure} make-vtable-vtable user_fields tail_array_size . init
6865 @deffnx {C Function} scm_make_vtable_vtable (user_fields, tail_array_size, init)
6866 Return a new, self-describing vtable structure.
6868 @var{user-fields} is a string describing user defined fields of the
6869 vtable beginning at index @code{vtable-offset-user}
6870 (see @code{make-struct-layout}).
6872 @var{tail-size} specifies the size of the tail-array (if any) of
6875 @var{init1}, @dots{} are the optional initializers for the fields of
6878 Vtables have one initializable system field---the struct printer.
6879 This field comes before the user fields in the initializers passed
6880 to @code{make-vtable-vtable} and @code{make-struct}, and thus works as
6881 a third optional argument to @code{make-vtable-vtable} and a fourth to
6882 @code{make-struct} when creating vtables:
6884 If the value is a procedure, it will be called instead of the standard
6885 printer whenever a struct described by this vtable is printed.
6886 The procedure will be called with arguments STRUCT and PORT.
6888 The structure of a struct is described by a vtable, so the vtable is
6889 in essence the type of the struct. The vtable is itself a struct with
6890 a vtable. This could go on forever if it weren't for the
6891 vtable-vtables which are self-describing vtables, and thus terminate
6894 There are several potential ways of using structs, but the standard
6895 one is to use three kinds of structs, together building up a type
6896 sub-system: one vtable-vtable working as the root and one or several
6897 "types", each with a set of "instances". (The vtable-vtable should be
6898 compared to the class <class> which is the class of itself.)
6901 (define ball-root (make-vtable-vtable "pr" 0))
6903 (define (make-ball-type ball-color)
6904 (make-struct ball-root 0
6905 (make-struct-layout "pw")
6907 (format port "#<a ~A ball owned by ~A>"
6911 (define (color ball) (struct-ref (struct-vtable ball) vtable-offset-user))
6912 (define (owner ball) (struct-ref ball 0))
6914 (define red (make-ball-type 'red))
6915 (define green (make-ball-type 'green))
6917 (define (make-ball type owner) (make-struct type 0 owner))
6919 (define ball (make-ball green 'Nisse))
6920 ball @result{} #<a green ball owned by Nisse>
6925 @c snarfed from struct.c:541
6926 @deffn {Scheme Procedure} struct-ref handle pos
6927 @deffnx {Scheme Procedure} struct-set! struct n value
6928 @deffnx {C Function} scm_struct_ref (handle, pos)
6929 Access (or modify) the @var{n}th field of @var{struct}.
6931 If the field is of type 'p', then it can be set to an arbitrary value.
6933 If the field is of type 'u', then it can only be set to a non-negative
6934 integer value small enough to fit in one machine word.
6938 @c snarfed from struct.c:620
6939 @deffn {Scheme Procedure} struct-set! handle pos val
6940 @deffnx {C Function} scm_struct_set_x (handle, pos, val)
6941 Set the slot of the structure @var{handle} with index @var{pos}
6942 to @var{val}. Signal an error if the slot can not be written
6947 @c snarfed from struct.c:691
6948 @deffn {Scheme Procedure} struct-vtable handle
6949 @deffnx {C Function} scm_struct_vtable (handle)
6950 Return the vtable structure that describes the type of @var{struct}.
6954 @c snarfed from struct.c:702
6955 @deffn {Scheme Procedure} struct-vtable-tag handle
6956 @deffnx {C Function} scm_struct_vtable_tag (handle)
6957 Return the vtable tag of the structure @var{handle}.
6960 \fstruct-vtable-name
6961 @c snarfed from struct.c:741
6962 @deffn {Scheme Procedure} struct-vtable-name vtable
6963 @deffnx {C Function} scm_struct_vtable_name (vtable)
6964 Return the name of the vtable @var{vtable}.
6967 \fset-struct-vtable-name!
6968 @c snarfed from struct.c:751
6969 @deffn {Scheme Procedure} set-struct-vtable-name! vtable name
6970 @deffnx {C Function} scm_set_struct_vtable_name_x (vtable, name)
6971 Set the name of the vtable @var{vtable} to @var{name}.
6975 @c snarfed from symbols.c:156
6976 @deffn {Scheme Procedure} symbol? obj
6977 @deffnx {C Function} scm_symbol_p (obj)
6978 Return @code{#t} if @var{obj} is a symbol, otherwise return
6983 @c snarfed from symbols.c:166
6984 @deffn {Scheme Procedure} symbol-interned? symbol
6985 @deffnx {C Function} scm_symbol_interned_p (symbol)
6986 Return @code{#t} if @var{symbol} is interned, otherwise return
6991 @c snarfed from symbols.c:178
6992 @deffn {Scheme Procedure} make-symbol name
6993 @deffnx {C Function} scm_make_symbol (name)
6994 Return a new uninterned symbol with the name @var{name}. The returned symbol is guaranteed to be unique and future calls to @code{string->symbol} will not return it.
6998 @c snarfed from symbols.c:210
6999 @deffn {Scheme Procedure} symbol->string s
7000 @deffnx {C Function} scm_symbol_to_string (s)
7001 Return the name of @var{symbol} as a string. If the symbol was
7002 part of an object returned as the value of a literal expression
7003 (section @pxref{Literal expressions,,,r5rs, The Revised^5
7004 Report on Scheme}) or by a call to the @code{read} procedure,
7005 and its name contains alphabetic characters, then the string
7006 returned will contain characters in the implementation's
7007 preferred standard case---some implementations will prefer
7008 upper case, others lower case. If the symbol was returned by
7009 @code{string->symbol}, the case of characters in the string
7010 returned will be the same as the case in the string that was
7011 passed to @code{string->symbol}. It is an error to apply
7012 mutation procedures like @code{string-set!} to strings returned
7015 The following examples assume that the implementation's
7016 standard case is lower case:
7019 (symbol->string 'flying-fish) @result{} "flying-fish"
7020 (symbol->string 'Martin) @result{} "martin"
7022 (string->symbol "Malvina")) @result{} "Malvina"
7027 @c snarfed from symbols.c:240
7028 @deffn {Scheme Procedure} string->symbol string
7029 @deffnx {C Function} scm_string_to_symbol (string)
7030 Return the symbol whose name is @var{string}. This procedure
7031 can create symbols with names containing special characters or
7032 letters in the non-standard case, but it is usually a bad idea
7033 to create such symbols because in some implementations of
7034 Scheme they cannot be read as themselves. See
7035 @code{symbol->string}.
7037 The following examples assume that the implementation's
7038 standard case is lower case:
7041 (eq? 'mISSISSIppi 'mississippi) @result{} #t
7042 (string->symbol "mISSISSIppi") @result{} @r{the symbol with name "mISSISSIppi"}
7043 (eq? 'bitBlt (string->symbol "bitBlt")) @result{} #f
7045 (string->symbol (symbol->string 'JollyWog))) @result{} #t
7046 (string=? "K. Harper, M.D."
7048 (string->symbol "K. Harper, M.D."))) @result{}#t
7053 @c snarfed from symbols.c:252
7054 @deffn {Scheme Procedure} string-ci->symbol str
7055 @deffnx {C Function} scm_string_ci_to_symbol (str)
7056 Return the symbol whose name is @var{str}. @var{str} is
7057 converted to lowercase before the conversion is done, if Guile
7058 is currently reading symbols case-insensitively.
7062 @c snarfed from symbols.c:269
7063 @deffn {Scheme Procedure} gensym [prefix]
7064 @deffnx {C Function} scm_gensym (prefix)
7065 Create a new symbol with a name constructed from a prefix and
7066 a counter value. The string @var{prefix} can be specified as
7067 an optional argument. Default prefix is @code{ g}. The counter
7068 is increased by 1 at each call. There is no provision for
7069 resetting the counter.
7073 @c snarfed from symbols.c:295
7074 @deffn {Scheme Procedure} symbol-hash symbol
7075 @deffnx {C Function} scm_symbol_hash (symbol)
7076 Return a hash value for @var{symbol}.
7080 @c snarfed from symbols.c:305
7081 @deffn {Scheme Procedure} symbol-fref s
7082 @deffnx {C Function} scm_symbol_fref (s)
7083 Return the contents of @var{symbol}'s @dfn{function slot}.
7087 @c snarfed from symbols.c:316
7088 @deffn {Scheme Procedure} symbol-pref s
7089 @deffnx {C Function} scm_symbol_pref (s)
7090 Return the @dfn{property list} currently associated with @var{symbol}.
7094 @c snarfed from symbols.c:327
7095 @deffn {Scheme Procedure} symbol-fset! s val
7096 @deffnx {C Function} scm_symbol_fset_x (s, val)
7097 Change the binding of @var{symbol}'s function slot.
7101 @c snarfed from symbols.c:339
7102 @deffn {Scheme Procedure} symbol-pset! s val
7103 @deffnx {C Function} scm_symbol_pset_x (s, val)
7104 Change the binding of @var{symbol}'s property slot.
7107 \fcall-with-new-thread
7108 @c snarfed from threads.c:428
7109 @deffn {Scheme Procedure} call-with-new-thread thunk handler
7110 @deffnx {C Function} scm_call_with_new_thread (thunk, handler)
7111 Evaluate @code{(@var{thunk})} in a new thread, and new dynamic context, returning a new thread object representing the thread. If an error occurs during evaluation, call error-thunk, passing it an error code describing the condition. If this happens, the error-thunk is called outside the scope of the new root -- it is called in the same dynamic context in which with-new-thread was evaluated, but not in the callers thread. All the evaluation rules for dynamic roots apply to threads.
7115 @c snarfed from threads.c:443
7116 @deffn {Scheme Procedure} yield
7117 @deffnx {C Function} scm_yield ()
7118 Move the calling thread to the end of the scheduling queue.
7122 @c snarfed from threads.c:453
7123 @deffn {Scheme Procedure} join-thread thread
7124 @deffnx {C Function} scm_join_thread (thread)
7125 Suspend execution of the calling thread until the target @var{thread} terminates, unless the target @var{thread} has already terminated.
7129 @c snarfed from threads.c:508
7130 @deffn {Scheme Procedure} make-fair-mutex
7131 @deffnx {C Function} scm_make_fair_mutex ()
7132 Create a new fair mutex object.
7135 \fmake-fair-condition-variable
7136 @c snarfed from threads.c:628
7137 @deffn {Scheme Procedure} make-fair-condition-variable
7138 @deffnx {C Function} scm_make_fair_condition_variable ()
7139 Make a new fair condition variable.
7143 @c snarfed from threads.c:691
7144 @deffn {Scheme Procedure} make-mutex
7145 @deffnx {C Function} scm_make_mutex ()
7146 Create a new mutex object.
7150 @c snarfed from threads.c:707
7151 @deffn {Scheme Procedure} lock-mutex mx
7152 @deffnx {C Function} scm_lock_mutex (mx)
7153 Lock @var{mutex}. If the mutex is already locked, the calling thread blocks until the mutex becomes available. The function returns when the calling thread owns the lock on @var{mutex}. Locking a mutex that a thread already owns will succeed right away and will not block the thread. That is, Guile's mutexes are @emph{recursive}.
7157 @c snarfed from threads.c:733
7158 @deffn {Scheme Procedure} try-mutex mx
7159 @deffnx {C Function} scm_try_mutex (mx)
7160 Try to lock @var{mutex}. If the mutex is already locked by someone else, return @code{#f}. Else lock the mutex and return @code{#t}.
7164 @c snarfed from threads.c:768
7165 @deffn {Scheme Procedure} unlock-mutex mx
7166 @deffnx {C Function} scm_unlock_mutex (mx)
7167 Unlocks @var{mutex} if the calling thread owns the lock on @var{mutex}. Calling unlock-mutex on a mutex not owned by the current thread results in undefined behaviour. Once a mutex has been unlocked, one thread blocked on @var{mutex} is awakened and grabs the mutex lock. Every call to @code{lock-mutex} by this thread must be matched with a call to @code{unlock-mutex}. Only the last call to @code{unlock-mutex} will actually unlock the mutex.
7170 \fmake-condition-variable
7171 @c snarfed from threads.c:808
7172 @deffn {Scheme Procedure} make-condition-variable
7173 @deffnx {C Function} scm_make_condition_variable ()
7174 Make a new condition variable.
7177 \fwait-condition-variable
7178 @c snarfed from threads.c:827
7179 @deffn {Scheme Procedure} wait-condition-variable cv mx [t]
7180 @deffnx {C Function} scm_timed_wait_condition_variable (cv, mx, t)
7181 Wait until @var{cond-var} has been signalled. While waiting, @var{mutex} is atomically unlocked (as with @code{unlock-mutex}) and is locked again when this function returns. When @var{time} is given, it specifies a point in time where the waiting should be aborted. It can be either a integer as returned by @code{current-time} or a pair as returned by @code{gettimeofday}. When the waiting is aborted the mutex is locked and @code{#f} is returned. When the condition variable is in fact signalled, the mutex is also locked and @code{#t} is returned.
7184 \fsignal-condition-variable
7185 @c snarfed from threads.c:884
7186 @deffn {Scheme Procedure} signal-condition-variable cv
7187 @deffnx {C Function} scm_signal_condition_variable (cv)
7188 Wake up one thread that is waiting for @var{cv}
7191 \fbroadcast-condition-variable
7192 @c snarfed from threads.c:901
7193 @deffn {Scheme Procedure} broadcast-condition-variable cv
7194 @deffnx {C Function} scm_broadcast_condition_variable (cv)
7195 Wake up all threads that are waiting for @var{cv}.
7199 @c snarfed from threads.c:1105
7200 @deffn {Scheme Procedure} current-thread
7201 @deffnx {C Function} scm_current_thread ()
7202 Return the thread that called this function.
7206 @c snarfed from threads.c:1114
7207 @deffn {Scheme Procedure} all-threads
7208 @deffnx {C Function} scm_all_threads ()
7209 Return a list of all threads.
7213 @c snarfed from threads.c:1129
7214 @deffn {Scheme Procedure} thread-exited? thread
7215 @deffnx {C Function} scm_thread_exited_p (thread)
7216 Return @code{#t} iff @var{thread} has exited.
7221 @c snarfed from throw.c:510
7222 @deffn {Scheme Procedure} catch key thunk handler
7223 @deffnx {C Function} scm_catch (key, thunk, handler)
7224 Invoke @var{thunk} in the dynamic context of @var{handler} for
7225 exceptions matching @var{key}. If thunk throws to the symbol
7226 @var{key}, then @var{handler} is invoked this way:
7228 (handler key args ...)
7231 @var{key} is a symbol or @code{#t}.
7233 @var{thunk} takes no arguments. If @var{thunk} returns
7234 normally, that is the return value of @code{catch}.
7236 Handler is invoked outside the scope of its own @code{catch}.
7237 If @var{handler} again throws to the same key, a new handler
7238 from further up the call chain is invoked.
7240 If the key is @code{#t}, then a throw to @emph{any} symbol will
7241 match this call to @code{catch}.
7245 @c snarfed from throw.c:538
7246 @deffn {Scheme Procedure} lazy-catch key thunk handler
7247 @deffnx {C Function} scm_lazy_catch (key, thunk, handler)
7248 This behaves exactly like @code{catch}, except that it does
7249 not unwind the stack before invoking @var{handler}.
7250 The @var{handler} procedure is not allowed to return:
7251 it must throw to another catch, or otherwise exit non-locally.
7255 @c snarfed from throw.c:571
7256 @deffn {Scheme Procedure} throw key . args
7257 @deffnx {C Function} scm_throw (key, args)
7258 Invoke the catch form matching @var{key}, passing @var{args} to the
7261 @var{key} is a symbol. It will match catches of the same symbol or of
7264 If there is no handler at all, Guile prints an error and then exits.
7268 @c snarfed from values.c:53
7269 @deffn {Scheme Procedure} values . args
7270 @deffnx {C Function} scm_values (args)
7271 Delivers all of its arguments to its continuation. Except for
7272 continuations created by the @code{call-with-values} procedure,
7273 all continuations take exactly one value. The effect of
7274 passing no value or more than one value to continuations that
7275 were not created by @code{call-with-values} is unspecified.
7279 @c snarfed from variable.c:52
7280 @deffn {Scheme Procedure} make-variable init
7281 @deffnx {C Function} scm_make_variable (init)
7282 Return a variable initialized to value @var{init}.
7285 \fmake-undefined-variable
7286 @c snarfed from variable.c:62
7287 @deffn {Scheme Procedure} make-undefined-variable
7288 @deffnx {C Function} scm_make_undefined_variable ()
7289 Return a variable that is initially unbound.
7293 @c snarfed from variable.c:73
7294 @deffn {Scheme Procedure} variable? obj
7295 @deffnx {C Function} scm_variable_p (obj)
7296 Return @code{#t} iff @var{obj} is a variable object, else
7301 @c snarfed from variable.c:85
7302 @deffn {Scheme Procedure} variable-ref var
7303 @deffnx {C Function} scm_variable_ref (var)
7304 Dereference @var{var} and return its value.
7305 @var{var} must be a variable object; see @code{make-variable}
7306 and @code{make-undefined-variable}.
7310 @c snarfed from variable.c:101
7311 @deffn {Scheme Procedure} variable-set! var val
7312 @deffnx {C Function} scm_variable_set_x (var, val)
7313 Set the value of the variable @var{var} to @var{val}.
7314 @var{var} must be a variable object, @var{val} can be any
7315 value. Return an unspecified value.
7319 @c snarfed from variable.c:113
7320 @deffn {Scheme Procedure} variable-bound? var
7321 @deffnx {C Function} scm_variable_bound_p (var)
7322 Return @code{#t} iff @var{var} is bound to a value.
7323 Throws an error if @var{var} is not a variable object.
7327 @c snarfed from vectors.c:35
7328 @deffn {Scheme Procedure} vector? obj
7329 @deffnx {C Function} scm_vector_p (obj)
7330 Return @code{#t} if @var{obj} is a vector, otherwise return
7335 @c snarfed from vectors.c:52
7336 @deffn {Scheme Procedure} list->vector
7337 implemented by the C function "scm_vector"
7341 @c snarfed from vectors.c:69
7342 @deffn {Scheme Procedure} vector . l
7343 @deffnx {Scheme Procedure} list->vector l
7344 @deffnx {C Function} scm_vector (l)
7345 Return a newly allocated vector composed of the
7346 given arguments. Analogous to @code{list}.
7349 (vector 'a 'b 'c) @result{} #(a b c)
7354 @c snarfed from vectors.c:163
7355 @deffn {Scheme Procedure} make-vector k [fill]
7356 @deffnx {C Function} scm_make_vector (k, fill)
7357 Return a newly allocated vector of @var{k} elements. If a
7358 second argument is given, then each position is initialized to
7359 @var{fill}. Otherwise the initial contents of each position is
7364 @c snarfed from vectors.c:211
7365 @deffn {Scheme Procedure} vector->list v
7366 @deffnx {C Function} scm_vector_to_list (v)
7367 Return a newly allocated list composed of the elements of @var{v}.
7370 (vector->list '#(dah dah didah)) @result{} (dah dah didah)
7371 (list->vector '(dididit dah)) @result{} #(dididit dah)
7376 @c snarfed from vectors.c:228
7377 @deffn {Scheme Procedure} vector-fill! v fill
7378 @deffnx {C Function} scm_vector_fill_x (v, fill)
7379 Store @var{fill} in every position of @var{vector}. The value
7380 returned by @code{vector-fill!} is unspecified.
7384 @c snarfed from vectors.c:260
7385 @deffn {Scheme Procedure} vector-move-left! vec1 start1 end1 vec2 start2
7386 @deffnx {C Function} scm_vector_move_left_x (vec1, start1, end1, vec2, start2)
7387 Copy elements from @var{vec1}, positions @var{start1} to @var{end1},
7388 to @var{vec2} starting at position @var{start2}. @var{start1} and
7389 @var{start2} are inclusive indices; @var{end1} is exclusive.
7391 @code{vector-move-left!} copies elements in leftmost order.
7392 Therefore, in the case where @var{vec1} and @var{vec2} refer to the
7393 same vector, @code{vector-move-left!} is usually appropriate when
7394 @var{start1} is greater than @var{start2}.
7397 \fvector-move-right!
7398 @c snarfed from vectors.c:290
7399 @deffn {Scheme Procedure} vector-move-right! vec1 start1 end1 vec2 start2
7400 @deffnx {C Function} scm_vector_move_right_x (vec1, start1, end1, vec2, start2)
7401 Copy elements from @var{vec1}, positions @var{start1} to @var{end1},
7402 to @var{vec2} starting at position @var{start2}. @var{start1} and
7403 @var{start2} are inclusive indices; @var{end1} is exclusive.
7405 @code{vector-move-right!} copies elements in rightmost order.
7406 Therefore, in the case where @var{vec1} and @var{vec2} refer to the
7407 same vector, @code{vector-move-right!} is usually appropriate when
7408 @var{start1} is less than @var{start2}.
7412 @c snarfed from version.c:35
7413 @deffn {Scheme Procedure} major-version
7414 @deffnx {C Function} scm_major_version ()
7415 Return a string containing Guile's major version number.
7416 E.g., the 1 in "1.6.5".
7420 @c snarfed from version.c:48
7421 @deffn {Scheme Procedure} minor-version
7422 @deffnx {C Function} scm_minor_version ()
7423 Return a string containing Guile's minor version number.
7424 E.g., the 6 in "1.6.5".
7428 @c snarfed from version.c:61
7429 @deffn {Scheme Procedure} micro-version
7430 @deffnx {C Function} scm_micro_version ()
7431 Return a string containing Guile's micro version number.
7432 E.g., the 5 in "1.6.5".
7436 @c snarfed from version.c:83
7437 @deffn {Scheme Procedure} version
7438 @deffnx {Scheme Procedure} major-version
7439 @deffnx {Scheme Procedure} minor-version
7440 @deffnx {Scheme Procedure} micro-version
7441 @deffnx {C Function} scm_version ()
7442 Return a string describing Guile's version number, or its major, minor
7443 or micro version number, respectively.
7446 (version) @result{} "1.6.0"
7447 (major-version) @result{} "1"
7448 (minor-version) @result{} "6"
7449 (micro-version) @result{} "0"
7454 @c snarfed from version.c:113
7455 @deffn {Scheme Procedure} effective-version
7456 @deffnx {C Function} scm_effective_version ()
7457 Return a string describing Guile's effective version number.
7459 (version) @result{} "1.6.0"
7460 (effective-version) @result{} "1.6"
7461 (major-version) @result{} "1"
7462 (minor-version) @result{} "6"
7463 (micro-version) @result{} "0"
7468 @c snarfed from vports.c:183
7469 @deffn {Scheme Procedure} make-soft-port pv modes
7470 @deffnx {C Function} scm_make_soft_port (pv, modes)
7471 Return a port capable of receiving or delivering characters as
7472 specified by the @var{modes} string (@pxref{File Ports,
7473 open-file}). @var{pv} must be a vector of length 5 or 6. Its
7474 components are as follows:
7478 procedure accepting one character for output
7480 procedure accepting a string for output
7482 thunk for flushing output
7484 thunk for getting one character
7486 thunk for closing port (not by garbage collection)
7488 (if present and not @code{#f}) thunk for computing the number of
7489 characters that can be read from the port without blocking.
7492 For an output-only port only elements 0, 1, 2, and 4 need be
7493 procedures. For an input-only port only elements 3 and 4 need
7494 be procedures. Thunks 2 and 4 can instead be @code{#f} if
7495 there is no useful operation for them to perform.
7497 If thunk 3 returns @code{#f} or an @code{eof-object}
7498 (@pxref{Input, eof-object?, ,r5rs, The Revised^5 Report on
7499 Scheme}) it indicates that the port has reached end-of-file.
7503 (define stdout (current-output-port))
7504 (define p (make-soft-port
7506 (lambda (c) (write c stdout))
7507 (lambda (s) (display s stdout))
7508 (lambda () (display "." stdout))
7509 (lambda () (char-upcase (read-char)))
7510 (lambda () (display "@@" stdout)))
7513 (write p p) @result{} #<input-output: soft 8081e20>
7518 @c snarfed from weaks.c:117
7519 @deffn {Scheme Procedure} make-weak-vector size [fill]
7520 @deffnx {C Function} scm_make_weak_vector (size, fill)
7521 Return a weak vector with @var{size} elements. If the optional
7522 argument @var{fill} is given, all entries in the vector will be
7523 set to @var{fill}. The default value for @var{fill} is the
7528 @c snarfed from weaks.c:125
7529 @deffn {Scheme Procedure} list->weak-vector
7530 implemented by the C function "scm_weak_vector"
7534 @c snarfed from weaks.c:133
7535 @deffn {Scheme Procedure} weak-vector . l
7536 @deffnx {Scheme Procedure} list->weak-vector l
7537 @deffnx {C Function} scm_weak_vector (l)
7538 Construct a weak vector from a list: @code{weak-vector} uses
7539 the list of its arguments while @code{list->weak-vector} uses
7540 its only argument @var{l} (a list) to construct a weak vector
7541 the same way @code{list->vector} would.
7545 @c snarfed from weaks.c:164
7546 @deffn {Scheme Procedure} weak-vector? obj
7547 @deffnx {C Function} scm_weak_vector_p (obj)
7548 Return @code{#t} if @var{obj} is a weak vector. Note that all
7549 weak hashes are also weak vectors.
7552 \fmake-weak-key-alist-vector
7553 @c snarfed from weaks.c:182
7554 @deffn {Scheme Procedure} make-weak-key-alist-vector [size]
7555 @deffnx {Scheme Procedure} make-weak-value-alist-vector size
7556 @deffnx {Scheme Procedure} make-doubly-weak-alist-vector size
7557 @deffnx {C Function} scm_make_weak_key_alist_vector (size)
7558 Return a weak hash table with @var{size} buckets. As with any
7559 hash table, choosing a good size for the table requires some
7562 You can modify weak hash tables in exactly the same way you
7563 would modify regular hash tables. (@pxref{Hash Tables})
7566 \fmake-weak-value-alist-vector
7567 @c snarfed from weaks.c:194
7568 @deffn {Scheme Procedure} make-weak-value-alist-vector [size]
7569 @deffnx {C Function} scm_make_weak_value_alist_vector (size)
7570 Return a hash table with weak values with @var{size} buckets.
7571 (@pxref{Hash Tables})
7574 \fmake-doubly-weak-alist-vector
7575 @c snarfed from weaks.c:206
7576 @deffn {Scheme Procedure} make-doubly-weak-alist-vector size
7577 @deffnx {C Function} scm_make_doubly_weak_alist_vector (size)
7578 Return a hash table with weak keys and values with @var{size}
7579 buckets. (@pxref{Hash Tables})
7582 \fweak-key-alist-vector?
7583 @c snarfed from weaks.c:221
7584 @deffn {Scheme Procedure} weak-key-alist-vector? obj
7585 @deffnx {Scheme Procedure} weak-value-alist-vector? obj
7586 @deffnx {Scheme Procedure} doubly-weak-alist-vector? obj
7587 @deffnx {C Function} scm_weak_key_alist_vector_p (obj)
7588 Return @code{#t} if @var{obj} is the specified weak hash
7589 table. Note that a doubly weak hash table is neither a weak key
7590 nor a weak value hash table.
7593 \fweak-value-alist-vector?
7594 @c snarfed from weaks.c:231
7595 @deffn {Scheme Procedure} weak-value-alist-vector? obj
7596 @deffnx {C Function} scm_weak_value_alist_vector_p (obj)
7597 Return @code{#t} if @var{obj} is a weak value hash table.
7600 \fdoubly-weak-alist-vector?
7601 @c snarfed from weaks.c:241
7602 @deffn {Scheme Procedure} doubly-weak-alist-vector? obj
7603 @deffnx {C Function} scm_doubly_weak_alist_vector_p (obj)
7604 Return @code{#t} if @var{obj} is a doubly weak hash table.
7608 @c snarfed from dynl.c:149
7609 @deffn {Scheme Procedure} dynamic-link filename
7610 @deffnx {C Function} scm_dynamic_link (filename)
7611 Find the shared object (shared library) denoted by
7612 @var{filename} and link it into the running Guile
7613 application. The returned
7614 scheme object is a ``handle'' for the library which can
7615 be passed to @code{dynamic-func}, @code{dynamic-call} etc.
7617 Searching for object files is system dependent. Normally,
7618 if @var{filename} does have an explicit directory it will
7619 be searched for in locations
7620 such as @file{/usr/lib} and @file{/usr/local/lib}.
7624 @c snarfed from dynl.c:168
7625 @deffn {Scheme Procedure} dynamic-object? obj
7626 @deffnx {C Function} scm_dynamic_object_p (obj)
7627 Return @code{#t} if @var{obj} is a dynamic object handle,
7628 or @code{#f} otherwise.
7632 @c snarfed from dynl.c:182
7633 @deffn {Scheme Procedure} dynamic-unlink dobj
7634 @deffnx {C Function} scm_dynamic_unlink (dobj)
7635 Unlink a dynamic object from the application, if possible. The
7636 object must have been linked by @code{dynamic-link}, with
7637 @var{dobj} the corresponding handle. After this procedure
7638 is called, the handle can no longer be used to access the
7643 @c snarfed from dynl.c:207
7644 @deffn {Scheme Procedure} dynamic-func name dobj
7645 @deffnx {C Function} scm_dynamic_func (name, dobj)
7646 Return a ``handle'' for the function @var{name} in the
7647 shared object referred to by @var{dobj}. The handle
7648 can be passed to @code{dynamic-call} to actually
7651 Regardless whether your C compiler prepends an underscore
7652 @samp{_} to the global names in a program, you should
7653 @strong{not} include this underscore in @var{name}
7654 since it will be added automatically when necessary.
7658 @c snarfed from dynl.c:253
7659 @deffn {Scheme Procedure} dynamic-call func dobj
7660 @deffnx {C Function} scm_dynamic_call (func, dobj)
7661 Call a C function in a dynamic object. Two styles of
7662 invocation are supported:
7665 @item @var{func} can be a function handle returned by
7666 @code{dynamic-func}. In this case @var{dobj} is
7668 @item @var{func} can be a string with the name of the
7669 function to call, with @var{dobj} the handle of the
7670 dynamic object in which to find the function.
7671 This is equivalent to
7674 (dynamic-call (dynamic-func @var{func} @var{dobj}) #f)
7678 In either case, the function is passed no arguments
7679 and its return value is ignored.
7683 @c snarfed from dynl.c:285
7684 @deffn {Scheme Procedure} dynamic-args-call func dobj args
7685 @deffnx {C Function} scm_dynamic_args_call (func, dobj, args)
7686 Call the C function indicated by @var{func} and @var{dobj},
7687 just like @code{dynamic-call}, but pass it some arguments and
7688 return its return value. The C function is expected to take
7689 two arguments and return an @code{int}, just like @code{main}:
7691 int c_func (int argc, char **argv);
7694 The parameter @var{args} must be a list of strings and is
7695 converted into an array of @code{char *}. The array is passed
7696 in @var{argv} and its size in @var{argc}. The return value is
7697 converted to a Scheme number and returned from the call to
7698 @code{dynamic-args-call}.
7702 @c snarfed from ramap.c:438
7703 @deffn {Scheme Procedure} array-fill! ra fill
7704 @deffnx {C Function} scm_array_fill_x (ra, fill)
7705 Store @var{fill} in every element of @var{array}. The value returned
7709 \farray-copy-in-order!
7710 @c snarfed from ramap.c:810
7711 @deffn {Scheme Procedure} array-copy-in-order!
7712 implemented by the C function "scm_array_copy_x"
7716 @c snarfed from ramap.c:819
7717 @deffn {Scheme Procedure} array-copy! src dst
7718 @deffnx {Scheme Procedure} array-copy-in-order! src dst
7719 @deffnx {C Function} scm_array_copy_x (src, dst)
7720 Copy every element from vector or array @var{source} to the
7721 corresponding element of @var{destination}. @var{destination} must have
7722 the same rank as @var{source}, and be at least as large in each
7723 dimension. The order is unspecified.
7726 \farray-map-in-order!
7727 @c snarfed from ramap.c:1494
7728 @deffn {Scheme Procedure} array-map-in-order!
7729 implemented by the C function "scm_array_map_x"
7733 @c snarfed from ramap.c:1505
7734 @deffn {Scheme Procedure} array-map! ra0 proc . lra
7735 @deffnx {Scheme Procedure} array-map-in-order! ra0 proc . lra
7736 @deffnx {C Function} scm_array_map_x (ra0, proc, lra)
7737 @var{array1}, @dots{} must have the same number of dimensions as
7738 @var{array0} and have a range for each index which includes the range
7739 for the corresponding index in @var{array0}. @var{proc} is applied to
7740 each tuple of elements of @var{array1} @dots{} and the result is stored
7741 as the corresponding element in @var{array0}. The value returned is
7742 unspecified. The order of application is unspecified.
7746 @c snarfed from ramap.c:1651
7747 @deffn {Scheme Procedure} array-for-each proc ra0 . lra
7748 @deffnx {C Function} scm_array_for_each (proc, ra0, lra)
7749 Apply @var{proc} to each tuple of elements of @var{array0} @dots{}
7750 in row-major order. The value returned is unspecified.
7754 @c snarfed from ramap.c:1679
7755 @deffn {Scheme Procedure} array-index-map! ra proc
7756 @deffnx {C Function} scm_array_index_map_x (ra, proc)
7757 Apply @var{proc} to the indices of each element of @var{array} in
7758 turn, storing the result in the corresponding element. The value
7759 returned and the order of application are unspecified.
7761 One can implement @var{array-indexes} as
7763 (define (array-indexes array)
7764 (let ((ra (apply make-array #f (array-shape array))))
7765 (array-index-map! ra (lambda x x))
7770 (define (apl:index-generator n)
7771 (let ((v (make-uniform-vector n 1)))
7772 (array-index-map! v (lambda (i) i))
7777 \funiform-vector-length
7778 @c snarfed from unif.c:211
7779 @deffn {Scheme Procedure} uniform-vector-length v
7780 @deffnx {C Function} scm_uniform_vector_length (v)
7781 Return the number of elements in @var{uve}.
7785 @c snarfed from unif.c:245
7786 @deffn {Scheme Procedure} array? v [prot]
7787 @deffnx {C Function} scm_array_p (v, prot)
7788 Return @code{#t} if the @var{obj} is an array, and @code{#f} if
7789 not. The @var{prototype} argument is used with uniform arrays
7790 and is described elsewhere.
7794 @c snarfed from unif.c:328
7795 @deffn {Scheme Procedure} array-rank ra
7796 @deffnx {C Function} scm_array_rank (ra)
7797 Return the number of dimensions of @var{obj}. If @var{obj} is
7798 not an array, @code{0} is returned.
7802 @c snarfed from unif.c:366
7803 @deffn {Scheme Procedure} array-dimensions ra
7804 @deffnx {C Function} scm_array_dimensions (ra)
7805 @code{Array-dimensions} is similar to @code{array-shape} but replaces
7806 elements with a @code{0} minimum with one greater than the maximum. So:
7808 (array-dimensions (make-array 'foo '(-1 3) 5)) @result{} ((-1 3) 5)
7813 @c snarfed from unif.c:413
7814 @deffn {Scheme Procedure} shared-array-root ra
7815 @deffnx {C Function} scm_shared_array_root (ra)
7816 Return the root vector of a shared array.
7819 \fshared-array-offset
7820 @c snarfed from unif.c:424
7821 @deffn {Scheme Procedure} shared-array-offset ra
7822 @deffnx {C Function} scm_shared_array_offset (ra)
7823 Return the root vector index of the first element in the array.
7826 \fshared-array-increments
7827 @c snarfed from unif.c:435
7828 @deffn {Scheme Procedure} shared-array-increments ra
7829 @deffnx {C Function} scm_shared_array_increments (ra)
7830 For each dimension, return the distance between elements in the root vector.
7833 \fdimensions->uniform-array
7834 @c snarfed from unif.c:554
7835 @deffn {Scheme Procedure} dimensions->uniform-array dims prot [fill]
7836 @deffnx {Scheme Procedure} make-uniform-vector length prototype [fill]
7837 @deffnx {C Function} scm_dimensions_to_uniform_array (dims, prot, fill)
7838 Create and return a uniform array or vector of type
7839 corresponding to @var{prototype} with dimensions @var{dims} or
7840 length @var{length}. If @var{fill} is supplied, it's used to
7841 fill the array, otherwise @var{prototype} is used.
7845 @c snarfed from unif.c:643
7846 @deffn {Scheme Procedure} make-shared-array oldra mapfunc . dims
7847 @deffnx {C Function} scm_make_shared_array (oldra, mapfunc, dims)
7848 @code{make-shared-array} can be used to create shared subarrays of other
7849 arrays. The @var{mapper} is a function that translates coordinates in
7850 the new array into coordinates in the old array. A @var{mapper} must be
7851 linear, and its range must stay within the bounds of the old array, but
7852 it can be otherwise arbitrary. A simple example:
7854 (define fred (make-array #f 8 8))
7855 (define freds-diagonal
7856 (make-shared-array fred (lambda (i) (list i i)) 8))
7857 (array-set! freds-diagonal 'foo 3)
7858 (array-ref fred 3 3) @result{} foo
7859 (define freds-center
7860 (make-shared-array fred (lambda (i j) (list (+ 3 i) (+ 3 j))) 2 2))
7861 (array-ref freds-center 0 0) @result{} foo
7866 @c snarfed from unif.c:774
7867 @deffn {Scheme Procedure} transpose-array ra . args
7868 @deffnx {C Function} scm_transpose_array (ra, args)
7869 Return an array sharing contents with @var{array}, but with
7870 dimensions arranged in a different order. There must be one
7871 @var{dim} argument for each dimension of @var{array}.
7872 @var{dim0}, @var{dim1}, @dots{} should be integers between 0
7873 and the rank of the array to be returned. Each integer in that
7874 range must appear at least once in the argument list.
7876 The values of @var{dim0}, @var{dim1}, @dots{} correspond to
7877 dimensions in the array to be returned, their positions in the
7878 argument list to dimensions of @var{array}. Several @var{dim}s
7879 may have the same value, in which case the returned array will
7880 have smaller rank than @var{array}.
7883 (transpose-array '#2((a b) (c d)) 1 0) @result{} #2((a c) (b d))
7884 (transpose-array '#2((a b) (c d)) 0 0) @result{} #1(a d)
7885 (transpose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 1 0) @result{}
7886 #2((a 4) (b 5) (c 6))
7891 @c snarfed from unif.c:879
7892 @deffn {Scheme Procedure} enclose-array ra . axes
7893 @deffnx {C Function} scm_enclose_array (ra, axes)
7894 @var{dim0}, @var{dim1} @dots{} should be nonnegative integers less than
7895 the rank of @var{array}. @var{enclose-array} returns an array
7896 resembling an array of shared arrays. The dimensions of each shared
7897 array are the same as the @var{dim}th dimensions of the original array,
7898 the dimensions of the outer array are the same as those of the original
7899 array that did not match a @var{dim}.
7901 An enclosed array is not a general Scheme array. Its elements may not
7902 be set using @code{array-set!}. Two references to the same element of
7903 an enclosed array will be @code{equal?} but will not in general be
7904 @code{eq?}. The value returned by @var{array-prototype} when given an
7905 enclosed array is unspecified.
7909 (enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1) @result{}
7910 #<enclosed-array (#1(a d) #1(b e) #1(c f)) (#1(1 4) #1(2 5) #1(3 6))>
7912 (enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 0) @result{}
7913 #<enclosed-array #2((a 1) (d 4)) #2((b 2) (e 5)) #2((c 3) (f 6))>
7918 @c snarfed from unif.c:966
7919 @deffn {Scheme Procedure} array-in-bounds? v . args
7920 @deffnx {C Function} scm_array_in_bounds_p (v, args)
7921 Return @code{#t} if its arguments would be acceptable to
7926 @c snarfed from unif.c:1044
7927 @deffn {Scheme Procedure} array-ref
7928 implemented by the C function "scm_uniform_vector_ref"
7931 \funiform-vector-ref
7932 @c snarfed from unif.c:1051
7933 @deffn {Scheme Procedure} uniform-vector-ref v args
7934 @deffnx {Scheme Procedure} array-ref v . args
7935 @deffnx {C Function} scm_uniform_vector_ref (v, args)
7936 Return the element at the @code{(index1, index2)} element in
7940 \funiform-array-set1!
7941 @c snarfed from unif.c:1219
7942 @deffn {Scheme Procedure} uniform-array-set1!
7943 implemented by the C function "scm_array_set_x"
7947 @c snarfed from unif.c:1228
7948 @deffn {Scheme Procedure} array-set! v obj . args
7949 @deffnx {Scheme Procedure} uniform-array-set1! v obj args
7950 @deffnx {C Function} scm_array_set_x (v, obj, args)
7951 Set the element at the @code{(index1, index2)} element in @var{array} to
7952 @var{new-value}. The value returned by array-set! is unspecified.
7956 @c snarfed from unif.c:1335
7957 @deffn {Scheme Procedure} array-contents ra [strict]
7958 @deffnx {C Function} scm_array_contents (ra, strict)
7959 If @var{array} may be @dfn{unrolled} into a one dimensional shared array
7960 without changing their order (last subscript changing fastest), then
7961 @code{array-contents} returns that shared array, otherwise it returns
7962 @code{#f}. All arrays made by @var{make-array} and
7963 @var{make-uniform-array} may be unrolled, some arrays made by
7964 @var{make-shared-array} may not be.
7966 If the optional argument @var{strict} is provided, a shared array will
7967 be returned only if its elements are stored internally contiguous in
7971 \funiform-array-read!
7972 @c snarfed from unif.c:1449
7973 @deffn {Scheme Procedure} uniform-array-read! ra [port_or_fd [start [end]]]
7974 @deffnx {Scheme Procedure} uniform-vector-read! uve [port-or-fdes] [start] [end]
7975 @deffnx {C Function} scm_uniform_array_read_x (ra, port_or_fd, start, end)
7976 Attempt to read all elements of @var{ura}, in lexicographic order, as
7977 binary objects from @var{port-or-fdes}.
7978 If an end of file is encountered,
7979 the objects up to that point are put into @var{ura}
7980 (starting at the beginning) and the remainder of the array is
7983 The optional arguments @var{start} and @var{end} allow
7984 a specified region of a vector (or linearized array) to be read,
7985 leaving the remainder of the vector unchanged.
7987 @code{uniform-array-read!} returns the number of objects read.
7988 @var{port-or-fdes} may be omitted, in which case it defaults to the value
7989 returned by @code{(current-input-port)}.
7992 \funiform-array-write
7993 @c snarfed from unif.c:1632
7994 @deffn {Scheme Procedure} uniform-array-write v [port_or_fd [start [end]]]
7995 @deffnx {Scheme Procedure} uniform-vector-write uve [port-or-fdes] [start] [end]
7996 @deffnx {C Function} scm_uniform_array_write (v, port_or_fd, start, end)
7997 Writes all elements of @var{ura} as binary objects to
8000 The optional arguments @var{start}
8002 a specified region of a vector (or linearized array) to be written.
8004 The number of objects actually written is returned.
8005 @var{port-or-fdes} may be
8006 omitted, in which case it defaults to the value returned by
8007 @code{(current-output-port)}.
8011 @c snarfed from unif.c:1759
8012 @deffn {Scheme Procedure} bit-count b bitvector
8013 @deffnx {C Function} scm_bit_count (b, bitvector)
8014 Return the number of occurrences of the boolean @var{b} in
8019 @c snarfed from unif.c:1804
8020 @deffn {Scheme Procedure} bit-position item v k
8021 @deffnx {C Function} scm_bit_position (item, v, k)
8022 Return the index of the first occurrance of @var{item} in bit
8023 vector @var{v}, starting from @var{k}. If there is no
8024 @var{item} entry between @var{k} and the end of
8025 @var{bitvector}, then return @code{#f}. For example,
8028 (bit-position #t #*000101 0) @result{} 3
8029 (bit-position #f #*0001111 3) @result{} #f
8034 @c snarfed from unif.c:1890
8035 @deffn {Scheme Procedure} bit-set*! v kv obj
8036 @deffnx {C Function} scm_bit_set_star_x (v, kv, obj)
8037 Set entries of bit vector @var{v} to @var{obj}, with @var{kv}
8038 selecting the entries to change. The return value is
8041 If @var{kv} is a bit vector, then those entries where it has
8042 @code{#t} are the ones in @var{v} which are set to @var{obj}.
8043 @var{kv} and @var{v} must be the same length. When @var{obj}
8044 is @code{#t} it's like @var{kv} is OR'ed into @var{v}. Or when
8045 @var{obj} is @code{#f} it can be seen as an ANDNOT.
8048 (define bv #*01000010)
8049 (bit-set*! bv #*10010001 #t)
8051 @result{} #*11010011
8054 If @var{kv} is a uniform vector of unsigned long integers, then
8055 they're indexes into @var{v} which are set to @var{obj}.
8058 (define bv #*01000010)
8059 (bit-set*! bv #u(5 2 7) #t)
8061 @result{} #*01100111
8066 @c snarfed from unif.c:1956
8067 @deffn {Scheme Procedure} bit-count* v kv obj
8068 @deffnx {C Function} scm_bit_count_star (v, kv, obj)
8069 Return a count of how many entries in bit vector @var{v} are
8070 equal to @var{obj}, with @var{kv} selecting the entries to
8073 If @var{kv} is a bit vector, then those entries where it has
8074 @code{#t} are the ones in @var{v} which are considered.
8075 @var{kv} and @var{v} must be the same length.
8077 If @var{kv} is a uniform vector of unsigned long integers, then
8078 it's the indexes in @var{v} to consider.
8083 (bit-count* #*01110111 #*11001101 #t) @result{} 3
8084 (bit-count* #*01110111 #u(7 0 4) #f) @result{} 2
8089 @c snarfed from unif.c:2021
8090 @deffn {Scheme Procedure} bit-invert! v
8091 @deffnx {C Function} scm_bit_invert_x (v)
8092 Modify the bit vector @var{v} by replacing each element with
8097 @c snarfed from unif.c:2103
8098 @deffn {Scheme Procedure} array->list v
8099 @deffnx {C Function} scm_array_to_list (v)
8100 Return a list consisting of all the elements, in order, of
8104 \flist->uniform-array
8105 @c snarfed from unif.c:2205
8106 @deffn {Scheme Procedure} list->uniform-array ndim prot lst
8107 @deffnx {Scheme Procedure} list->uniform-vector prot lst
8108 @deffnx {C Function} scm_list_to_uniform_array (ndim, prot, lst)
8109 Return a uniform array of the type indicated by prototype
8110 @var{prot} with elements the same as those of @var{lst}.
8111 Elements must be of the appropriate type, no coercions are
8116 @c snarfed from unif.c:2562
8117 @deffn {Scheme Procedure} array-prototype ra
8118 @deffnx {C Function} scm_array_prototype (ra)
8119 Return an object that would produce an array of the same type
8120 as @var{array}, if used as the @var{prototype} for
8121 @code{make-uniform-array}.
8125 @c snarfed from filesys.c:224
8126 @deffn {Scheme Procedure} chown object owner group
8127 @deffnx {C Function} scm_chown (object, owner, group)
8128 Change the ownership and group of the file referred to by @var{object} to
8129 the integer values @var{owner} and @var{group}. @var{object} can be
8130 a string containing a file name or, if the platform
8131 supports fchown, a port or integer file descriptor
8132 which is open on the file. The return value
8135 If @var{object} is a symbolic link, either the
8136 ownership of the link or the ownership of the referenced file will be
8137 changed depending on the operating system (lchown is
8138 unsupported at present). If @var{owner} or @var{group} is specified
8139 as @code{-1}, then that ID is not changed.
8143 @c snarfed from filesys.c:262
8144 @deffn {Scheme Procedure} chmod object mode
8145 @deffnx {C Function} scm_chmod (object, mode)
8146 Changes the permissions of the file referred to by @var{obj}.
8147 @var{obj} can be a string containing a file name or a port or integer file
8148 descriptor which is open on a file (in which case @code{fchmod} is used
8149 as the underlying system call).
8150 @var{mode} specifies
8151 the new permissions as a decimal number, e.g., @code{(chmod "foo" #o755)}.
8152 The return value is unspecified.
8156 @c snarfed from filesys.c:294
8157 @deffn {Scheme Procedure} umask [mode]
8158 @deffnx {C Function} scm_umask (mode)
8159 If @var{mode} is omitted, returns a decimal number representing the current
8160 file creation mask. Otherwise the file creation mask is set to
8161 @var{mode} and the previous value is returned.
8163 E.g., @code{(umask #o022)} sets the mask to octal 22, decimal 18.
8167 @c snarfed from filesys.c:316
8168 @deffn {Scheme Procedure} open-fdes path flags [mode]
8169 @deffnx {C Function} scm_open_fdes (path, flags, mode)
8170 Similar to @code{open} but return a file descriptor instead of
8175 @c snarfed from filesys.c:357
8176 @deffn {Scheme Procedure} open path flags [mode]
8177 @deffnx {C Function} scm_open (path, flags, mode)
8178 Open the file named by @var{path} for reading and/or writing.
8179 @var{flags} is an integer specifying how the file should be opened.
8180 @var{mode} is an integer specifying the permission bits of the file, if
8181 it needs to be created, before the umask is applied. The default is 666
8182 (Unix itself has no default).
8184 @var{flags} can be constructed by combining variables using @code{logior}.
8188 Open the file read-only.
8191 Open the file write-only.
8194 Open the file read/write.
8197 Append to the file instead of truncating.
8200 Create the file if it does not already exist.
8203 See the Unix documentation of the @code{open} system call
8204 for additional flags.
8208 @c snarfed from filesys.c:395
8209 @deffn {Scheme Procedure} close fd_or_port
8210 @deffnx {C Function} scm_close (fd_or_port)
8211 Similar to close-port (@pxref{Closing, close-port}),
8212 but also works on file descriptors. A side
8213 effect of closing a file descriptor is that any ports using that file
8214 descriptor are moved to a different file descriptor and have
8215 their revealed counts set to zero.
8219 @c snarfed from filesys.c:422
8220 @deffn {Scheme Procedure} close-fdes fd
8221 @deffnx {C Function} scm_close_fdes (fd)
8222 A simple wrapper for the @code{close} system call.
8223 Close file descriptor @var{fd}, which must be an integer.
8224 Unlike close (@pxref{Ports and File Descriptors, close}),
8225 the file descriptor will be closed even if a port is using it.
8226 The return value is unspecified.
8230 @c snarfed from filesys.c:624
8231 @deffn {Scheme Procedure} stat object
8232 @deffnx {C Function} scm_stat (object)
8233 Return an object containing various information about the file
8234 determined by @var{obj}. @var{obj} can be a string containing
8235 a file name or a port or integer file descriptor which is open
8236 on a file (in which case @code{fstat} is used as the underlying
8239 The object returned by @code{stat} can be passed as a single
8240 parameter to the following procedures, all of which return
8245 The device containing the file.
8247 The file serial number, which distinguishes this file from all
8248 other files on the same device.
8250 The mode of the file. This includes file type information and
8251 the file permission bits. See @code{stat:type} and
8252 @code{stat:perms} below.
8254 The number of hard links to the file.
8256 The user ID of the file's owner.
8258 The group ID of the file.
8260 Device ID; this entry is defined only for character or block
8263 The size of a regular file in bytes.
8265 The last access time for the file.
8267 The last modification time for the file.
8269 The last modification time for the attributes of the file.
8271 The optimal block size for reading or writing the file, in
8274 The amount of disk space that the file occupies measured in
8275 units of 512 byte blocks.
8278 In addition, the following procedures return the information
8279 from stat:mode in a more convenient form:
8283 A symbol representing the type of file. Possible values are
8284 regular, directory, symlink, block-special, char-special, fifo,
8287 An integer representing the access permission bits.
8292 @c snarfed from filesys.c:686
8293 @deffn {Scheme Procedure} link oldpath newpath
8294 @deffnx {C Function} scm_link (oldpath, newpath)
8295 Creates a new name @var{newpath} in the file system for the
8296 file named by @var{oldpath}. If @var{oldpath} is a symbolic
8297 link, the link may or may not be followed depending on the
8302 @c snarfed from filesys.c:724
8303 @deffn {Scheme Procedure} rename-file oldname newname
8304 @deffnx {C Function} scm_rename (oldname, newname)
8305 Renames the file specified by @var{oldname} to @var{newname}.
8306 The return value is unspecified.
8310 @c snarfed from filesys.c:741
8311 @deffn {Scheme Procedure} delete-file str
8312 @deffnx {C Function} scm_delete_file (str)
8313 Deletes (or "unlinks") the file specified by @var{path}.
8317 @c snarfed from filesys.c:758
8318 @deffn {Scheme Procedure} mkdir path [mode]
8319 @deffnx {C Function} scm_mkdir (path, mode)
8320 Create a new directory named by @var{path}. If @var{mode} is omitted
8321 then the permissions of the directory file are set using the current
8322 umask. Otherwise they are set to the decimal value specified with
8323 @var{mode}. The return value is unspecified.
8327 @c snarfed from filesys.c:785
8328 @deffn {Scheme Procedure} rmdir path
8329 @deffnx {C Function} scm_rmdir (path)
8330 Remove the existing directory named by @var{path}. The directory must
8331 be empty for this to succeed. The return value is unspecified.
8335 @c snarfed from filesys.c:809
8336 @deffn {Scheme Procedure} directory-stream? obj
8337 @deffnx {C Function} scm_directory_stream_p (obj)
8338 Return a boolean indicating whether @var{object} is a directory
8339 stream as returned by @code{opendir}.
8343 @c snarfed from filesys.c:820
8344 @deffn {Scheme Procedure} opendir dirname
8345 @deffnx {C Function} scm_opendir (dirname)
8346 Open the directory specified by @var{path} and return a directory
8351 @c snarfed from filesys.c:841
8352 @deffn {Scheme Procedure} readdir port
8353 @deffnx {C Function} scm_readdir (port)
8354 Return (as a string) the next directory entry from the directory stream
8355 @var{stream}. If there is no remaining entry to be read then the
8356 end of file object is returned.
8360 @c snarfed from filesys.c:880
8361 @deffn {Scheme Procedure} rewinddir port
8362 @deffnx {C Function} scm_rewinddir (port)
8363 Reset the directory port @var{stream} so that the next call to
8364 @code{readdir} will return the first directory entry.
8368 @c snarfed from filesys.c:897
8369 @deffn {Scheme Procedure} closedir port
8370 @deffnx {C Function} scm_closedir (port)
8371 Close the directory stream @var{stream}.
8372 The return value is unspecified.
8376 @c snarfed from filesys.c:947
8377 @deffn {Scheme Procedure} chdir str
8378 @deffnx {C Function} scm_chdir (str)
8379 Change the current working directory to @var{path}.
8380 The return value is unspecified.
8384 @c snarfed from filesys.c:962
8385 @deffn {Scheme Procedure} getcwd
8386 @deffnx {C Function} scm_getcwd ()
8387 Return the name of the current working directory.
8391 @c snarfed from filesys.c:1163
8392 @deffn {Scheme Procedure} select reads writes excepts [secs [usecs]]
8393 @deffnx {C Function} scm_select (reads, writes, excepts, secs, usecs)
8394 This procedure has a variety of uses: waiting for the ability
8395 to provide input, accept output, or the existence of
8396 exceptional conditions on a collection of ports or file
8397 descriptors, or waiting for a timeout to occur.
8398 It also returns if interrupted by a signal.
8400 @var{reads}, @var{writes} and @var{excepts} can be lists or
8401 vectors, with each member a port or a file descriptor.
8402 The value returned is a list of three corresponding
8403 lists or vectors containing only the members which meet the
8404 specified requirement. The ability of port buffers to
8405 provide input or accept output is taken into account.
8406 Ordering of the input lists or vectors is not preserved.
8408 The optional arguments @var{secs} and @var{usecs} specify the
8409 timeout. Either @var{secs} can be specified alone, as
8410 either an integer or a real number, or both @var{secs} and
8411 @var{usecs} can be specified as integers, in which case
8412 @var{usecs} is an additional timeout expressed in
8413 microseconds. If @var{secs} is omitted or is @code{#f} then
8414 select will wait for as long as it takes for one of the other
8415 conditions to be satisfied.
8417 The scsh version of @code{select} differs as follows:
8418 Only vectors are accepted for the first three arguments.
8419 The @var{usecs} argument is not supported.
8420 Multiple values are returned instead of a list.
8421 Duplicates in the input vectors appear only once in output.
8422 An additional @code{select!} interface is provided.
8426 @c snarfed from filesys.c:1301
8427 @deffn {Scheme Procedure} fcntl object cmd [value]
8428 @deffnx {C Function} scm_fcntl (object, cmd, value)
8429 Apply @var{command} to the specified file descriptor or the underlying
8430 file descriptor of the specified port. @var{value} is an optional
8433 Values for @var{command} are:
8437 Duplicate a file descriptor
8439 Get flags associated with the file descriptor.
8441 Set flags associated with the file descriptor to @var{value}.
8443 Get flags associated with the open file.
8445 Set flags associated with the open file to @var{value}
8447 Get the process ID of a socket's owner, for @code{SIGIO} signals.
8449 Set the process that owns a socket to @var{value}, for @code{SIGIO} signals.
8451 The value used to indicate the "close on exec" flag with @code{F_GETFL} or
8457 @c snarfed from filesys.c:1333
8458 @deffn {Scheme Procedure} fsync object
8459 @deffnx {C Function} scm_fsync (object)
8460 Copies any unwritten data for the specified output file descriptor to disk.
8461 If @var{port/fd} is a port, its buffer is flushed before the underlying
8462 file descriptor is fsync'd.
8463 The return value is unspecified.
8467 @c snarfed from filesys.c:1358
8468 @deffn {Scheme Procedure} symlink oldpath newpath
8469 @deffnx {C Function} scm_symlink (oldpath, newpath)
8470 Create a symbolic link named @var{path-to} with the value (i.e., pointing to)
8471 @var{path-from}. The return value is unspecified.
8475 @c snarfed from filesys.c:1377
8476 @deffn {Scheme Procedure} readlink path
8477 @deffnx {C Function} scm_readlink (path)
8478 Return the value of the symbolic link named by @var{path} (a
8479 string), i.e., the file that the link points to.
8483 @c snarfed from filesys.c:1419
8484 @deffn {Scheme Procedure} lstat str
8485 @deffnx {C Function} scm_lstat (str)
8486 Similar to @code{stat}, but does not follow symbolic links, i.e.,
8487 it will return information about a symbolic link itself, not the
8488 file it points to. @var{path} must be a string.
8492 @c snarfed from filesys.c:1442
8493 @deffn {Scheme Procedure} copy-file oldfile newfile
8494 @deffnx {C Function} scm_copy_file (oldfile, newfile)
8495 Copy the file specified by @var{path-from} to @var{path-to}.
8496 The return value is unspecified.
8500 @c snarfed from filesys.c:1505
8501 @deffn {Scheme Procedure} dirname filename
8502 @deffnx {C Function} scm_dirname (filename)
8503 Return the directory name component of the file name
8504 @var{filename}. If @var{filename} does not contain a directory
8505 component, @code{.} is returned.
8509 @c snarfed from filesys.c:1548
8510 @deffn {Scheme Procedure} basename filename [suffix]
8511 @deffnx {C Function} scm_basename (filename, suffix)
8512 Return the base name of the file name @var{filename}. The
8513 base name is the file name without any directory components.
8514 If @var{suffix} is provided, and is equal to the end of
8515 @var{basename}, it is removed also.
8519 @c snarfed from posix.c:232
8520 @deffn {Scheme Procedure} pipe
8521 @deffnx {C Function} scm_pipe ()
8522 Return a newly created pipe: a pair of ports which are linked
8523 together on the local machine. The @emph{car} is the input
8524 port and the @emph{cdr} is the output port. Data written (and
8525 flushed) to the output port can be read from the input port.
8526 Pipes are commonly used for communication with a newly forked
8527 child process. The need to flush the output port can be
8528 avoided by making it unbuffered using @code{setvbuf}.
8530 Writes occur atomically provided the size of the data in bytes
8531 is not greater than the value of @code{PIPE_BUF}. Note that
8532 the output port is likely to block if too much data (typically
8533 equal to @code{PIPE_BUF}) has been written but not yet read
8534 from the input port.
8538 @c snarfed from posix.c:253
8539 @deffn {Scheme Procedure} getgroups
8540 @deffnx {C Function} scm_getgroups ()
8541 Return a vector of integers representing the current
8542 supplementary group IDs.
8546 @c snarfed from posix.c:286
8547 @deffn {Scheme Procedure} setgroups group_vec
8548 @deffnx {C Function} scm_setgroups (group_vec)
8549 Set the current set of supplementary group IDs to the integers
8550 in the given vector @var{vec}. The return value is
8553 Generally only the superuser can set the process group IDs.
8557 @c snarfed from posix.c:334
8558 @deffn {Scheme Procedure} getpw [user]
8559 @deffnx {C Function} scm_getpwuid (user)
8560 Look up an entry in the user database. @var{obj} can be an integer,
8561 a string, or omitted, giving the behaviour of getpwuid, getpwnam
8562 or getpwent respectively.
8566 @c snarfed from posix.c:384
8567 @deffn {Scheme Procedure} setpw [arg]
8568 @deffnx {C Function} scm_setpwent (arg)
8569 If called with a true argument, initialize or reset the password data
8570 stream. Otherwise, close the stream. The @code{setpwent} and
8571 @code{endpwent} procedures are implemented on top of this.
8575 @c snarfed from posix.c:403
8576 @deffn {Scheme Procedure} getgr [name]
8577 @deffnx {C Function} scm_getgrgid (name)
8578 Look up an entry in the group database. @var{obj} can be an integer,
8579 a string, or omitted, giving the behaviour of getgrgid, getgrnam
8580 or getgrent respectively.
8584 @c snarfed from posix.c:439
8585 @deffn {Scheme Procedure} setgr [arg]
8586 @deffnx {C Function} scm_setgrent (arg)
8587 If called with a true argument, initialize or reset the group data
8588 stream. Otherwise, close the stream. The @code{setgrent} and
8589 @code{endgrent} procedures are implemented on top of this.
8593 @c snarfed from posix.c:475
8594 @deffn {Scheme Procedure} kill pid sig
8595 @deffnx {C Function} scm_kill (pid, sig)
8596 Sends a signal to the specified process or group of processes.
8598 @var{pid} specifies the processes to which the signal is sent:
8601 @item @var{pid} greater than 0
8602 The process whose identifier is @var{pid}.
8603 @item @var{pid} equal to 0
8604 All processes in the current process group.
8605 @item @var{pid} less than -1
8606 The process group whose identifier is -@var{pid}
8607 @item @var{pid} equal to -1
8608 If the process is privileged, all processes except for some special
8609 system processes. Otherwise, all processes with the current effective
8613 @var{sig} should be specified using a variable corresponding to
8614 the Unix symbolic name, e.g.,
8626 @c snarfed from posix.c:526
8627 @deffn {Scheme Procedure} waitpid pid [options]
8628 @deffnx {C Function} scm_waitpid (pid, options)
8629 This procedure collects status information from a child process which
8630 has terminated or (optionally) stopped. Normally it will
8631 suspend the calling process until this can be done. If more than one
8632 child process is eligible then one will be chosen by the operating system.
8634 The value of @var{pid} determines the behaviour:
8637 @item @var{pid} greater than 0
8638 Request status information from the specified child process.
8639 @item @var{pid} equal to -1 or WAIT_ANY
8640 Request status information for any child process.
8641 @item @var{pid} equal to 0 or WAIT_MYPGRP
8642 Request status information for any child process in the current process
8644 @item @var{pid} less than -1
8645 Request status information for any child process whose process group ID
8649 The @var{options} argument, if supplied, should be the bitwise OR of the
8650 values of zero or more of the following variables:
8653 Return immediately even if there are no child processes to be collected.
8657 Report status information for stopped processes as well as terminated
8661 The return value is a pair containing:
8665 The process ID of the child process, or 0 if @code{WNOHANG} was
8666 specified and no process was collected.
8668 The integer status value.
8673 @c snarfed from posix.c:552
8674 @deffn {Scheme Procedure} status:exit-val status
8675 @deffnx {C Function} scm_status_exit_val (status)
8676 Return the exit status value, as would be set if a process
8677 ended normally through a call to @code{exit} or @code{_exit},
8678 if any, otherwise @code{#f}.
8682 @c snarfed from posix.c:570
8683 @deffn {Scheme Procedure} status:term-sig status
8684 @deffnx {C Function} scm_status_term_sig (status)
8685 Return the signal number which terminated the process, if any,
8686 otherwise @code{#f}.
8690 @c snarfed from posix.c:586
8691 @deffn {Scheme Procedure} status:stop-sig status
8692 @deffnx {C Function} scm_status_stop_sig (status)
8693 Return the signal number which stopped the process, if any,
8694 otherwise @code{#f}.
8698 @c snarfed from posix.c:604
8699 @deffn {Scheme Procedure} getppid
8700 @deffnx {C Function} scm_getppid ()
8701 Return an integer representing the process ID of the parent
8706 @c snarfed from posix.c:616
8707 @deffn {Scheme Procedure} getuid
8708 @deffnx {C Function} scm_getuid ()
8709 Return an integer representing the current real user ID.
8713 @c snarfed from posix.c:627
8714 @deffn {Scheme Procedure} getgid
8715 @deffnx {C Function} scm_getgid ()
8716 Return an integer representing the current real group ID.
8720 @c snarfed from posix.c:641
8721 @deffn {Scheme Procedure} geteuid
8722 @deffnx {C Function} scm_geteuid ()
8723 Return an integer representing the current effective user ID.
8724 If the system does not support effective IDs, then the real ID
8725 is returned. @code{(provided? 'EIDs)} reports whether the
8726 system supports effective IDs.
8730 @c snarfed from posix.c:658
8731 @deffn {Scheme Procedure} getegid
8732 @deffnx {C Function} scm_getegid ()
8733 Return an integer representing the current effective group ID.
8734 If the system does not support effective IDs, then the real ID
8735 is returned. @code{(provided? 'EIDs)} reports whether the
8736 system supports effective IDs.
8740 @c snarfed from posix.c:674
8741 @deffn {Scheme Procedure} setuid id
8742 @deffnx {C Function} scm_setuid (id)
8743 Sets both the real and effective user IDs to the integer @var{id}, provided
8744 the process has appropriate privileges.
8745 The return value is unspecified.
8749 @c snarfed from posix.c:687
8750 @deffn {Scheme Procedure} setgid id
8751 @deffnx {C Function} scm_setgid (id)
8752 Sets both the real and effective group IDs to the integer @var{id}, provided
8753 the process has appropriate privileges.
8754 The return value is unspecified.
8758 @c snarfed from posix.c:702
8759 @deffn {Scheme Procedure} seteuid id
8760 @deffnx {C Function} scm_seteuid (id)
8761 Sets the effective user ID to the integer @var{id}, provided the process
8762 has appropriate privileges. If effective IDs are not supported, the
8763 real ID is set instead -- @code{(provided? 'EIDs)} reports whether the
8764 system supports effective IDs.
8765 The return value is unspecified.
8769 @c snarfed from posix.c:727
8770 @deffn {Scheme Procedure} setegid id
8771 @deffnx {C Function} scm_setegid (id)
8772 Sets the effective group ID to the integer @var{id}, provided the process
8773 has appropriate privileges. If effective IDs are not supported, the
8774 real ID is set instead -- @code{(provided? 'EIDs)} reports whether the
8775 system supports effective IDs.
8776 The return value is unspecified.
8780 @c snarfed from posix.c:750
8781 @deffn {Scheme Procedure} getpgrp
8782 @deffnx {C Function} scm_getpgrp ()
8783 Return an integer representing the current process group ID.
8784 This is the POSIX definition, not BSD.
8788 @c snarfed from posix.c:768
8789 @deffn {Scheme Procedure} setpgid pid pgid
8790 @deffnx {C Function} scm_setpgid (pid, pgid)
8791 Move the process @var{pid} into the process group @var{pgid}. @var{pid} or
8792 @var{pgid} must be integers: they can be zero to indicate the ID of the
8794 Fails on systems that do not support job control.
8795 The return value is unspecified.
8799 @c snarfed from posix.c:785
8800 @deffn {Scheme Procedure} setsid
8801 @deffnx {C Function} scm_setsid ()
8802 Creates a new session. The current process becomes the session leader
8803 and is put in a new process group. The process will be detached
8804 from its controlling terminal if it has one.
8805 The return value is an integer representing the new process group ID.
8809 @c snarfed from posix.c:809
8810 @deffn {Scheme Procedure} ttyname port
8811 @deffnx {C Function} scm_ttyname (port)
8812 Return a string with the name of the serial terminal device
8813 underlying @var{port}.
8817 @c snarfed from posix.c:848
8818 @deffn {Scheme Procedure} ctermid
8819 @deffnx {C Function} scm_ctermid ()
8820 Return a string containing the file name of the controlling
8821 terminal for the current process.
8825 @c snarfed from posix.c:872
8826 @deffn {Scheme Procedure} tcgetpgrp port
8827 @deffnx {C Function} scm_tcgetpgrp (port)
8828 Return the process group ID of the foreground process group
8829 associated with the terminal open on the file descriptor
8830 underlying @var{port}.
8832 If there is no foreground process group, the return value is a
8833 number greater than 1 that does not match the process group ID
8834 of any existing process group. This can happen if all of the
8835 processes in the job that was formerly the foreground job have
8836 terminated, and no other job has yet been moved into the
8841 @c snarfed from posix.c:896
8842 @deffn {Scheme Procedure} tcsetpgrp port pgid
8843 @deffnx {C Function} scm_tcsetpgrp (port, pgid)
8844 Set the foreground process group ID for the terminal used by the file
8845 descriptor underlying @var{port} to the integer @var{pgid}.
8847 must be a member of the same session as @var{pgid} and must have the same
8848 controlling terminal. The return value is unspecified.
8852 @c snarfed from posix.c:928
8853 @deffn {Scheme Procedure} execl filename . args
8854 @deffnx {C Function} scm_execl (filename, args)
8855 Executes the file named by @var{path} as a new process image.
8856 The remaining arguments are supplied to the process; from a C program
8857 they are accessible as the @code{argv} argument to @code{main}.
8858 Conventionally the first @var{arg} is the same as @var{path}.
8859 All arguments must be strings.
8861 If @var{arg} is missing, @var{path} is executed with a null
8862 argument list, which may have system-dependent side-effects.
8864 This procedure is currently implemented using the @code{execv} system
8865 call, but we call it @code{execl} because of its Scheme calling interface.
8869 @c snarfed from posix.c:959
8870 @deffn {Scheme Procedure} execlp filename . args
8871 @deffnx {C Function} scm_execlp (filename, args)
8872 Similar to @code{execl}, however if
8873 @var{filename} does not contain a slash
8874 then the file to execute will be located by searching the
8875 directories listed in the @code{PATH} environment variable.
8877 This procedure is currently implemented using the @code{execvp} system
8878 call, but we call it @code{execlp} because of its Scheme calling interface.
8882 @c snarfed from posix.c:993
8883 @deffn {Scheme Procedure} execle filename env . args
8884 @deffnx {C Function} scm_execle (filename, env, args)
8885 Similar to @code{execl}, but the environment of the new process is
8886 specified by @var{env}, which must be a list of strings as returned by the
8887 @code{environ} procedure.
8889 This procedure is currently implemented using the @code{execve} system
8890 call, but we call it @code{execle} because of its Scheme calling interface.
8894 @c snarfed from posix.c:1029
8895 @deffn {Scheme Procedure} primitive-fork
8896 @deffnx {C Function} scm_fork ()
8897 Creates a new "child" process by duplicating the current "parent" process.
8898 In the child the return value is 0. In the parent the return value is
8899 the integer process ID of the child.
8901 This procedure has been renamed from @code{fork} to avoid a naming conflict
8906 @c snarfed from posix.c:1049
8907 @deffn {Scheme Procedure} uname
8908 @deffnx {C Function} scm_uname ()
8909 Return an object with some information about the computer
8910 system the program is running on.
8914 @c snarfed from posix.c:1078
8915 @deffn {Scheme Procedure} environ [env]
8916 @deffnx {C Function} scm_environ (env)
8917 If @var{env} is omitted, return the current environment (in the
8918 Unix sense) as a list of strings. Otherwise set the current
8919 environment, which is also the default environment for child
8920 processes, to the supplied list of strings. Each member of
8921 @var{env} should be of the form @code{NAME=VALUE} and values of
8922 @code{NAME} should not be duplicated. If @var{env} is supplied
8923 then the return value is unspecified.
8927 @c snarfed from posix.c:1111
8928 @deffn {Scheme Procedure} tmpnam
8929 @deffnx {C Function} scm_tmpnam ()
8930 Return a name in the file system that does not match any
8931 existing file. However there is no guarantee that another
8932 process will not create the file after @code{tmpnam} is called.
8933 Care should be taken if opening the file, e.g., use the
8934 @code{O_EXCL} open flag or use @code{mkstemp!} instead.
8938 @c snarfed from posix.c:1137
8939 @deffn {Scheme Procedure} mkstemp! tmpl
8940 @deffnx {C Function} scm_mkstemp (tmpl)
8941 Create a new unique file in the file system and returns a new
8942 buffered port open for reading and writing to the file.
8943 @var{tmpl} is a string specifying where the file should be
8944 created: it must end with @code{XXXXXX} and will be changed in
8945 place to return the name of the temporary file.
8949 @c snarfed from posix.c:1172
8950 @deffn {Scheme Procedure} utime pathname [actime [modtime]]
8951 @deffnx {C Function} scm_utime (pathname, actime, modtime)
8952 @code{utime} sets the access and modification times for the
8953 file named by @var{path}. If @var{actime} or @var{modtime} is
8954 not supplied, then the current time is used. @var{actime} and
8955 @var{modtime} must be integer time values as returned by the
8956 @code{current-time} procedure.
8958 (utime "foo" (- (current-time) 3600))
8960 will set the access time to one hour in the past and the
8961 modification time to the current time.
8965 @c snarfed from posix.c:1237
8966 @deffn {Scheme Procedure} access? path how
8967 @deffnx {C Function} scm_access (path, how)
8968 Test accessibility of a file under the real UID and GID of the
8969 calling process. The return is @code{#t} if @var{path} exists
8970 and the permissions requested by @var{how} are all allowed, or
8973 @var{how} is an integer which is one of the following values,
8974 or a bitwise-OR (@code{logior}) of multiple values.
8977 Test for read permission.
8980 Test for write permission.
8983 Test for execute permission.
8986 Test for existence of the file. This is implied by each of the
8987 other tests, so there's no need to combine it with them.
8990 It's important to note that @code{access?} does not simply
8991 indicate what will happen on attempting to read or write a
8992 file. In normal circumstances it does, but in a set-UID or
8993 set-GID program it doesn't because @code{access?} tests the
8994 real ID, whereas an open or execute attempt uses the effective
8997 A program which will never run set-UID/GID can ignore the
8998 difference between real and effective IDs, but for maximum
8999 generality, especially in library functions, it's best not to
9000 use @code{access?} to predict the result of an open or execute,
9001 instead simply attempt that and catch any exception.
9003 The main use for @code{access?} is to let a set-UID/GID program
9004 determine what the invoking user would have been allowed to do,
9005 without the greater (or perhaps lesser) privileges afforded by
9006 the effective ID. For more on this, see ``Testing File
9007 Access'' in The GNU C Library Reference Manual.
9011 @c snarfed from posix.c:1250
9012 @deffn {Scheme Procedure} getpid
9013 @deffnx {C Function} scm_getpid ()
9014 Return an integer representing the current process ID.
9018 @c snarfed from posix.c:1267
9019 @deffn {Scheme Procedure} putenv str
9020 @deffnx {C Function} scm_putenv (str)
9021 Modifies the environment of the current process, which is
9022 also the default environment inherited by child processes.
9024 If @var{string} is of the form @code{NAME=VALUE} then it will be written
9025 directly into the environment, replacing any existing environment string
9027 name matching @code{NAME}. If @var{string} does not contain an equal
9028 sign, then any existing string with name matching @var{string} will
9031 The return value is unspecified.
9035 @c snarfed from posix.c:1351
9036 @deffn {Scheme Procedure} setlocale category [locale]
9037 @deffnx {C Function} scm_setlocale (category, locale)
9038 If @var{locale} is omitted, return the current value of the
9039 specified locale category as a system-dependent string.
9040 @var{category} should be specified using the values
9041 @code{LC_COLLATE}, @code{LC_ALL} etc.
9043 Otherwise the specified locale category is set to the string
9044 @var{locale} and the new value is returned as a
9045 system-dependent string. If @var{locale} is an empty string,
9046 the locale will be set using environment variables.
9050 @c snarfed from posix.c:1394
9051 @deffn {Scheme Procedure} mknod path type perms dev
9052 @deffnx {C Function} scm_mknod (path, type, perms, dev)
9053 Creates a new special file, such as a file corresponding to a device.
9054 @var{path} specifies the name of the file. @var{type} should
9055 be one of the following symbols:
9056 regular, directory, symlink, block-special, char-special,
9057 fifo, or socket. @var{perms} (an integer) specifies the file permissions.
9058 @var{dev} (an integer) specifies which device the special file refers
9059 to. Its exact interpretation depends on the kind of special file
9064 (mknod "/dev/fd0" 'block-special #o660 (+ (* 2 256) 2))
9067 The return value is unspecified.
9071 @c snarfed from posix.c:1440
9072 @deffn {Scheme Procedure} nice incr
9073 @deffnx {C Function} scm_nice (incr)
9074 Increment the priority of the current process by @var{incr}. A higher
9075 priority value means that the process runs less often.
9076 The return value is unspecified.
9080 @c snarfed from posix.c:1458
9081 @deffn {Scheme Procedure} sync
9082 @deffnx {C Function} scm_sync ()
9083 Flush the operating system disk buffers.
9084 The return value is unspecified.
9088 @c snarfed from posix.c:1489
9089 @deffn {Scheme Procedure} crypt key salt
9090 @deffnx {C Function} scm_crypt (key, salt)
9091 Encrypt @var{key} using @var{salt} as the salt value to the
9092 crypt(3) library call.
9096 @c snarfed from posix.c:1521
9097 @deffn {Scheme Procedure} chroot path
9098 @deffnx {C Function} scm_chroot (path)
9099 Change the root directory to that specified in @var{path}.
9100 This directory will be used for path names beginning with
9101 @file{/}. The root directory is inherited by all children
9102 of the current process. Only the superuser may change the
9107 @c snarfed from posix.c:1555
9108 @deffn {Scheme Procedure} getlogin
9109 @deffnx {C Function} scm_getlogin ()
9110 Return a string containing the name of the user logged in on
9111 the controlling terminal of the process, or @code{#f} if this
9112 information cannot be obtained.
9116 @c snarfed from posix.c:1573
9117 @deffn {Scheme Procedure} cuserid
9118 @deffnx {C Function} scm_cuserid ()
9119 Return a string containing a user name associated with the
9120 effective user id of the process. Return @code{#f} if this
9121 information cannot be obtained.
9125 @c snarfed from posix.c:1599
9126 @deffn {Scheme Procedure} getpriority which who
9127 @deffnx {C Function} scm_getpriority (which, who)
9128 Return the scheduling priority of the process, process group
9129 or user, as indicated by @var{which} and @var{who}. @var{which}
9130 is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP}
9131 or @code{PRIO_USER}, and @var{who} is interpreted relative to
9132 @var{which} (a process identifier for @code{PRIO_PROCESS},
9133 process group identifier for @code{PRIO_PGRP}, and a user
9134 identifier for @code{PRIO_USER}. A zero value of @var{who}
9135 denotes the current process, process group, or user. Return
9136 the highest priority (lowest numerical value) of any of the
9137 specified processes.
9141 @c snarfed from posix.c:1633
9142 @deffn {Scheme Procedure} setpriority which who prio
9143 @deffnx {C Function} scm_setpriority (which, who, prio)
9144 Set the scheduling priority of the process, process group
9145 or user, as indicated by @var{which} and @var{who}. @var{which}
9146 is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP}
9147 or @code{PRIO_USER}, and @var{who} is interpreted relative to
9148 @var{which} (a process identifier for @code{PRIO_PROCESS},
9149 process group identifier for @code{PRIO_PGRP}, and a user
9150 identifier for @code{PRIO_USER}. A zero value of @var{who}
9151 denotes the current process, process group, or user.
9152 @var{prio} is a value in the range -20 and 20, the default
9153 priority is 0; lower priorities cause more favorable
9154 scheduling. Sets the priority of all of the specified
9155 processes. Only the super-user may lower priorities.
9156 The return value is not specified.
9160 @c snarfed from posix.c:1658
9161 @deffn {Scheme Procedure} getpass prompt
9162 @deffnx {C Function} scm_getpass (prompt)
9163 Display @var{prompt} to the standard error output and read
9164 a password from @file{/dev/tty}. If this file is not
9165 accessible, it reads from standard input. The password may be
9166 up to 127 characters in length. Additional characters and the
9167 terminating newline character are discarded. While reading
9168 the password, echoing and the generation of signals by special
9169 characters is disabled.
9173 @c snarfed from posix.c:1763
9174 @deffn {Scheme Procedure} flock file operation
9175 @deffnx {C Function} scm_flock (file, operation)
9176 Apply or remove an advisory lock on an open file.
9177 @var{operation} specifies the action to be done:
9180 Shared lock. More than one process may hold a shared lock
9181 for a given file at a given time.
9183 Exclusive lock. Only one process may hold an exclusive lock
9184 for a given file at a given time.
9188 Don't block when locking. May be specified by bitwise OR'ing
9189 it to one of the other operations.
9191 The return value is not specified. @var{file} may be an open
9192 file descriptor or an open file descriptor port.
9196 @c snarfed from posix.c:1788
9197 @deffn {Scheme Procedure} sethostname name
9198 @deffnx {C Function} scm_sethostname (name)
9199 Set the host name of the current processor to @var{name}. May
9200 only be used by the superuser. The return value is not
9205 @c snarfed from posix.c:1806
9206 @deffn {Scheme Procedure} gethostname
9207 @deffnx {C Function} scm_gethostname ()
9208 Return the host name of the current processor.
9212 @c snarfed from net_db.c:134
9213 @deffn {Scheme Procedure} gethost [host]
9214 @deffnx {Scheme Procedure} gethostbyname hostname
9215 @deffnx {Scheme Procedure} gethostbyaddr address
9216 @deffnx {C Function} scm_gethost (host)
9217 Look up a host by name or address, returning a host object. The
9218 @code{gethost} procedure will accept either a string name or an integer
9219 address; if given no arguments, it behaves like @code{gethostent} (see
9220 below). If a name or address is supplied but the address can not be
9221 found, an error will be thrown to one of the keys:
9222 @code{host-not-found}, @code{try-again}, @code{no-recovery} or
9223 @code{no-data}, corresponding to the equivalent @code{h_error} values.
9224 Unusual conditions may result in errors thrown to the
9225 @code{system-error} or @code{misc_error} keys.
9229 @c snarfed from net_db.c:216
9230 @deffn {Scheme Procedure} getnet [net]
9231 @deffnx {Scheme Procedure} getnetbyname net-name
9232 @deffnx {Scheme Procedure} getnetbyaddr net-number
9233 @deffnx {C Function} scm_getnet (net)
9234 Look up a network by name or net number in the network database. The
9235 @var{net-name} argument must be a string, and the @var{net-number}
9236 argument must be an integer. @code{getnet} will accept either type of
9237 argument, behaving like @code{getnetent} (see below) if no arguments are
9242 @c snarfed from net_db.c:268
9243 @deffn {Scheme Procedure} getproto [protocol]
9244 @deffnx {Scheme Procedure} getprotobyname name
9245 @deffnx {Scheme Procedure} getprotobynumber number
9246 @deffnx {C Function} scm_getproto (protocol)
9247 Look up a network protocol by name or by number. @code{getprotobyname}
9248 takes a string argument, and @code{getprotobynumber} takes an integer
9249 argument. @code{getproto} will accept either type, behaving like
9250 @code{getprotoent} (see below) if no arguments are supplied.
9254 @c snarfed from net_db.c:334
9255 @deffn {Scheme Procedure} getserv [name [protocol]]
9256 @deffnx {Scheme Procedure} getservbyname name protocol
9257 @deffnx {Scheme Procedure} getservbyport port protocol
9258 @deffnx {C Function} scm_getserv (name, protocol)
9259 Look up a network service by name or by service number, and return a
9260 network service object. The @var{protocol} argument specifies the name
9261 of the desired protocol; if the protocol found in the network service
9262 database does not match this name, a system error is signalled.
9264 The @code{getserv} procedure will take either a service name or number
9265 as its first argument; if given no arguments, it behaves like
9266 @code{getservent} (see below).
9270 @c snarfed from net_db.c:385
9271 @deffn {Scheme Procedure} sethost [stayopen]
9272 @deffnx {C Function} scm_sethost (stayopen)
9273 If @var{stayopen} is omitted, this is equivalent to @code{endhostent}.
9274 Otherwise it is equivalent to @code{sethostent stayopen}.
9278 @c snarfed from net_db.c:401
9279 @deffn {Scheme Procedure} setnet [stayopen]
9280 @deffnx {C Function} scm_setnet (stayopen)
9281 If @var{stayopen} is omitted, this is equivalent to @code{endnetent}.
9282 Otherwise it is equivalent to @code{setnetent stayopen}.
9286 @c snarfed from net_db.c:417
9287 @deffn {Scheme Procedure} setproto [stayopen]
9288 @deffnx {C Function} scm_setproto (stayopen)
9289 If @var{stayopen} is omitted, this is equivalent to @code{endprotoent}.
9290 Otherwise it is equivalent to @code{setprotoent stayopen}.
9294 @c snarfed from net_db.c:433
9295 @deffn {Scheme Procedure} setserv [stayopen]
9296 @deffnx {C Function} scm_setserv (stayopen)
9297 If @var{stayopen} is omitted, this is equivalent to @code{endservent}.
9298 Otherwise it is equivalent to @code{setservent stayopen}.
9302 @c snarfed from socket.c:80
9303 @deffn {Scheme Procedure} htons value
9304 @deffnx {C Function} scm_htons (value)
9305 Convert a 16 bit quantity from host to network byte ordering.
9306 @var{value} is packed into 2 bytes, which are then converted
9307 and returned as a new integer.
9311 @c snarfed from socket.c:91
9312 @deffn {Scheme Procedure} ntohs value
9313 @deffnx {C Function} scm_ntohs (value)
9314 Convert a 16 bit quantity from network to host byte ordering.
9315 @var{value} is packed into 2 bytes, which are then converted
9316 and returned as a new integer.
9320 @c snarfed from socket.c:102
9321 @deffn {Scheme Procedure} htonl value
9322 @deffnx {C Function} scm_htonl (value)
9323 Convert a 32 bit quantity from host to network byte ordering.
9324 @var{value} is packed into 4 bytes, which are then converted
9325 and returned as a new integer.
9329 @c snarfed from socket.c:115
9330 @deffn {Scheme Procedure} ntohl value
9331 @deffnx {C Function} scm_ntohl (value)
9332 Convert a 32 bit quantity from network to host byte ordering.
9333 @var{value} is packed into 4 bytes, which are then converted
9334 and returned as a new integer.
9338 @c snarfed from socket.c:135
9339 @deffn {Scheme Procedure} inet-aton address
9340 @deffnx {C Function} scm_inet_aton (address)
9341 Convert an IPv4 Internet address from printable string
9342 (dotted decimal notation) to an integer. E.g.,
9345 (inet-aton "127.0.0.1") @result{} 2130706433
9350 @c snarfed from socket.c:158
9351 @deffn {Scheme Procedure} inet-ntoa inetid
9352 @deffnx {C Function} scm_inet_ntoa (inetid)
9353 Convert an IPv4 Internet address to a printable
9354 (dotted decimal notation) string. E.g.,
9357 (inet-ntoa 2130706433) @result{} "127.0.0.1"
9362 @c snarfed from socket.c:178
9363 @deffn {Scheme Procedure} inet-netof address
9364 @deffnx {C Function} scm_inet_netof (address)
9365 Return the network number part of the given IPv4
9366 Internet address. E.g.,
9369 (inet-netof 2130706433) @result{} 127
9374 @c snarfed from socket.c:196
9375 @deffn {Scheme Procedure} inet-lnaof address
9376 @deffnx {C Function} scm_lnaof (address)
9377 Return the local-address-with-network part of the given
9378 IPv4 Internet address, using the obsolete class A/B/C system.
9382 (inet-lnaof 2130706433) @result{} 1
9387 @c snarfed from socket.c:214
9388 @deffn {Scheme Procedure} inet-makeaddr net lna
9389 @deffnx {C Function} scm_inet_makeaddr (net, lna)
9390 Make an IPv4 Internet address by combining the network number
9391 @var{net} with the local-address-within-network number
9395 (inet-makeaddr 127 1) @result{} 2130706433
9400 @c snarfed from socket.c:399
9401 @deffn {Scheme Procedure} inet-pton family address
9402 @deffnx {C Function} scm_inet_pton (family, address)
9403 Convert a string containing a printable network address to
9404 an integer address. Note that unlike the C version of this
9406 the result is an integer with normal host byte ordering.
9407 @var{family} can be @code{AF_INET} or @code{AF_INET6}. E.g.,
9410 (inet-pton AF_INET "127.0.0.1") @result{} 2130706433
9411 (inet-pton AF_INET6 "::1") @result{} 1
9416 @c snarfed from socket.c:437
9417 @deffn {Scheme Procedure} inet-ntop family address
9418 @deffnx {C Function} scm_inet_ntop (family, address)
9419 Convert a network address into a printable string.
9420 Note that unlike the C version of this function,
9421 the input is an integer with normal host byte ordering.
9422 @var{family} can be @code{AF_INET} or @code{AF_INET6}. E.g.,
9425 (inet-ntop AF_INET 2130706433) @result{} "127.0.0.1"
9426 (inet-ntop AF_INET6 (- (expt 2 128) 1)) @result{}
9427 ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff
9432 @c snarfed from socket.c:479
9433 @deffn {Scheme Procedure} socket family style proto
9434 @deffnx {C Function} scm_socket (family, style, proto)
9435 Return a new socket port of the type specified by @var{family},
9436 @var{style} and @var{proto}. All three parameters are
9437 integers. Supported values for @var{family} are
9438 @code{AF_UNIX}, @code{AF_INET} and @code{AF_INET6}.
9439 Typical values for @var{style} are @code{SOCK_STREAM},
9440 @code{SOCK_DGRAM} and @code{SOCK_RAW}.
9442 @var{proto} can be obtained from a protocol name using
9443 @code{getprotobyname}. A value of zero specifies the default
9444 protocol, which is usually right.
9446 A single socket port cannot by used for communication until it
9447 has been connected to another socket.
9451 @c snarfed from socket.c:500
9452 @deffn {Scheme Procedure} socketpair family style proto
9453 @deffnx {C Function} scm_socketpair (family, style, proto)
9454 Return a pair of connected (but unnamed) socket ports of the
9455 type specified by @var{family}, @var{style} and @var{proto}.
9456 Many systems support only socket pairs of the @code{AF_UNIX}
9457 family. Zero is likely to be the only meaningful value for
9462 @c snarfed from socket.c:525
9463 @deffn {Scheme Procedure} getsockopt sock level optname
9464 @deffnx {C Function} scm_getsockopt (sock, level, optname)
9465 Return the value of a particular socket option for the socket
9466 port @var{sock}. @var{level} is an integer code for type of
9467 option being requested, e.g., @code{SOL_SOCKET} for
9468 socket-level options. @var{optname} is an integer code for the
9469 option required and should be specified using one of the
9470 symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc.
9472 The returned value is typically an integer but @code{SO_LINGER}
9473 returns a pair of integers.
9477 @c snarfed from socket.c:593
9478 @deffn {Scheme Procedure} setsockopt sock level optname value
9479 @deffnx {C Function} scm_setsockopt (sock, level, optname, value)
9480 Set the value of a particular socket option for the socket
9481 port @var{sock}. @var{level} is an integer code for type of option
9482 being set, e.g., @code{SOL_SOCKET} for socket-level options.
9484 integer code for the option to set and should be specified using one of
9485 the symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc.
9486 @var{value} is the value to which the option should be set. For
9487 most options this must be an integer, but for @code{SO_LINGER} it must
9490 The return value is unspecified.
9494 @c snarfed from socket.c:697
9495 @deffn {Scheme Procedure} shutdown sock how
9496 @deffnx {C Function} scm_shutdown (sock, how)
9497 Sockets can be closed simply by using @code{close-port}. The
9498 @code{shutdown} procedure allows reception or transmission on a
9499 connection to be shut down individually, according to the parameter
9504 Stop receiving data for this socket. If further data arrives, reject it.
9506 Stop trying to transmit data from this socket. Discard any
9507 data waiting to be sent. Stop looking for acknowledgement of
9508 data already sent; don't retransmit it if it is lost.
9510 Stop both reception and transmission.
9513 The return value is unspecified.
9517 @c snarfed from socket.c:840
9518 @deffn {Scheme Procedure} connect sock fam address . args
9519 @deffnx {C Function} scm_connect (sock, fam, address, args)
9520 Initiate a connection from a socket using a specified address
9521 family to the address
9522 specified by @var{address} and possibly @var{args}.
9523 The format required for @var{address}
9524 and @var{args} depends on the family of the socket.
9526 For a socket of family @code{AF_UNIX},
9527 only @var{address} is specified and must be a string with the
9528 filename where the socket is to be created.
9530 For a socket of family @code{AF_INET},
9531 @var{address} must be an integer IPv4 host address and
9532 @var{args} must be a single integer port number.
9534 For a socket of family @code{AF_INET6},
9535 @var{address} must be an integer IPv6 host address and
9536 @var{args} may be up to three integers:
9537 port [flowinfo] [scope_id],
9538 where flowinfo and scope_id default to zero.
9540 The return value is unspecified.
9544 @c snarfed from socket.c:899
9545 @deffn {Scheme Procedure} bind sock fam address . args
9546 @deffnx {C Function} scm_bind (sock, fam, address, args)
9547 Assign an address to the socket port @var{sock}.
9548 Generally this only needs to be done for server sockets,
9549 so they know where to look for incoming connections. A socket
9550 without an address will be assigned one automatically when it
9551 starts communicating.
9553 The format of @var{address} and @var{args} depends
9554 on the family of the socket.
9556 For a socket of family @code{AF_UNIX}, only @var{address}
9557 is specified and must be a string with the filename where
9558 the socket is to be created.
9560 For a socket of family @code{AF_INET}, @var{address}
9561 must be an integer IPv4 address and @var{args}
9562 must be a single integer port number.
9564 The values of the following variables can also be used for
9568 Allow connections from any address.
9571 @defvar INADDR_LOOPBACK
9572 The address of the local host using the loopback device.
9575 @defvar INADDR_BROADCAST
9576 The broadcast address on the local network.
9583 For a socket of family @code{AF_INET6}, @var{address}
9584 must be an integer IPv6 address and @var{args}
9585 may be up to three integers:
9586 port [flowinfo] [scope_id],
9587 where flowinfo and scope_id default to zero.
9589 The return value is unspecified.
9593 @c snarfed from socket.c:932
9594 @deffn {Scheme Procedure} listen sock backlog
9595 @deffnx {C Function} scm_listen (sock, backlog)
9596 Enable @var{sock} to accept connection
9597 requests. @var{backlog} is an integer specifying
9598 the maximum length of the queue for pending connections.
9599 If the queue fills, new clients will fail to connect until
9600 the server calls @code{accept} to accept a connection from
9603 The return value is unspecified.
9607 @c snarfed from socket.c:1044
9608 @deffn {Scheme Procedure} accept sock
9609 @deffnx {C Function} scm_accept (sock)
9610 Accept a connection on a bound, listening socket.
9612 are no pending connections in the queue, wait until
9613 one is available unless the non-blocking option has been
9616 The return value is a
9617 pair in which the @emph{car} is a new socket port for the
9619 the @emph{cdr} is an object with address information about the
9620 client which initiated the connection.
9622 @var{sock} does not become part of the
9623 connection and will continue to accept new requests.
9627 @c snarfed from socket.c:1071
9628 @deffn {Scheme Procedure} getsockname sock
9629 @deffnx {C Function} scm_getsockname (sock)
9630 Return the address of @var{sock}, in the same form as the
9631 object returned by @code{accept}. On many systems the address
9632 of a socket in the @code{AF_FILE} namespace cannot be read.
9636 @c snarfed from socket.c:1093
9637 @deffn {Scheme Procedure} getpeername sock
9638 @deffnx {C Function} scm_getpeername (sock)
9639 Return the address that @var{sock}
9640 is connected to, in the same form as the object returned by
9641 @code{accept}. On many systems the address of a socket in the
9642 @code{AF_FILE} namespace cannot be read.
9646 @c snarfed from socket.c:1128
9647 @deffn {Scheme Procedure} recv! sock buf [flags]
9648 @deffnx {C Function} scm_recv (sock, buf, flags)
9649 Receive data from a socket port.
9650 @var{sock} must already
9651 be bound to the address from which data is to be received.
9652 @var{buf} is a string into which
9653 the data will be written. The size of @var{buf} limits
9655 data which can be received: in the case of packet
9656 protocols, if a packet larger than this limit is encountered
9658 will be irrevocably lost.
9660 The optional @var{flags} argument is a value or
9661 bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc.
9663 The value returned is the number of bytes read from the
9666 Note that the data is read directly from the socket file
9668 any unread buffered port data is ignored.
9672 @c snarfed from socket.c:1171
9673 @deffn {Scheme Procedure} send sock message [flags]
9674 @deffnx {C Function} scm_send (sock, message, flags)
9675 Transmit the string @var{message} on a socket port @var{sock}.
9676 @var{sock} must already be bound to a destination address. The
9677 value returned is the number of bytes transmitted --
9679 this to be less than the length of @var{message}
9681 set to be non-blocking. The optional @var{flags} argument
9683 bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc.
9685 Note that the data is written directly to the socket
9687 any unflushed buffered port data is ignored.
9691 @c snarfed from socket.c:1222
9692 @deffn {Scheme Procedure} recvfrom! sock str [flags [start [end]]]
9693 @deffnx {C Function} scm_recvfrom (sock, str, flags, start, end)
9694 Return data from the socket port @var{sock} and also
9695 information about where the data was received from.
9696 @var{sock} must already be bound to the address from which
9697 data is to be received. @code{str}, is a string into which the
9698 data will be written. The size of @var{str} limits the amount
9699 of data which can be received: in the case of packet protocols,
9700 if a packet larger than this limit is encountered then some
9701 data will be irrevocably lost.
9703 The optional @var{flags} argument is a value or bitwise OR of
9704 @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
9706 The value returned is a pair: the @emph{car} is the number of
9707 bytes read from the socket and the @emph{cdr} an address object
9708 in the same form as returned by @code{accept}. The address
9709 will given as @code{#f} if not available, as is usually the
9710 case for stream sockets.
9712 The @var{start} and @var{end} arguments specify a substring of
9713 @var{str} to which the data should be written.
9715 Note that the data is read directly from the socket file
9716 descriptor: any unread buffered port data is ignored.
9720 @c snarfed from socket.c:1287
9721 @deffn {Scheme Procedure} sendto sock message fam address . args_and_flags
9722 @deffnx {C Function} scm_sendto (sock, message, fam, address, args_and_flags)
9723 Transmit the string @var{message} on the socket port
9725 destination address is specified using the @var{fam},
9727 @var{args_and_flags} arguments, in a similar way to the
9728 @code{connect} procedure. @var{args_and_flags} contains
9729 the usual connection arguments optionally followed by
9730 a flags argument, which is a value or
9731 bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc.
9733 The value returned is the number of bytes transmitted --
9735 this to be less than the length of @var{message} if the
9737 set to be non-blocking.
9738 Note that the data is written directly to the socket
9740 any unflushed buffered port data is ignored.
9744 @c snarfed from regex-posix.c:105
9745 @deffn {Scheme Procedure} regexp? obj
9746 @deffnx {C Function} scm_regexp_p (obj)
9747 Return @code{#t} if @var{obj} is a compiled regular expression,
9748 or @code{#f} otherwise.
9752 @c snarfed from regex-posix.c:150
9753 @deffn {Scheme Procedure} make-regexp pat . flags
9754 @deffnx {C Function} scm_make_regexp (pat, flags)
9755 Compile the regular expression described by @var{pat}, and
9756 return the compiled regexp structure. If @var{pat} does not
9757 describe a legal regular expression, @code{make-regexp} throws
9758 a @code{regular-expression-syntax} error.
9760 The @var{flags} arguments change the behavior of the compiled
9761 regular expression. The following flags may be supplied:
9765 Consider uppercase and lowercase letters to be the same when
9767 @item regexp/newline
9768 If a newline appears in the target string, then permit the
9769 @samp{^} and @samp{$} operators to match immediately after or
9770 immediately before the newline, respectively. Also, the
9771 @samp{.} and @samp{[^...]} operators will never match a newline
9772 character. The intent of this flag is to treat the target
9773 string as a buffer containing many lines of text, and the
9774 regular expression as a pattern that may match a single one of
9777 Compile a basic (``obsolete'') regexp instead of the extended
9778 (``modern'') regexps that are the default. Basic regexps do
9779 not consider @samp{|}, @samp{+} or @samp{?} to be special
9780 characters, and require the @samp{@{...@}} and @samp{(...)}
9781 metacharacters to be backslash-escaped (@pxref{Backslash
9782 Escapes}). There are several other differences between basic
9783 and extended regular expressions, but these are the most
9785 @item regexp/extended
9786 Compile an extended regular expression rather than a basic
9787 regexp. This is the default behavior; this flag will not
9788 usually be needed. If a call to @code{make-regexp} includes
9789 both @code{regexp/basic} and @code{regexp/extended} flags, the
9790 one which comes last will override the earlier one.
9795 @c snarfed from regex-posix.c:216
9796 @deffn {Scheme Procedure} regexp-exec rx str [start [flags]]
9797 @deffnx {C Function} scm_regexp_exec (rx, str, start, flags)
9798 Match the compiled regular expression @var{rx} against
9799 @code{str}. If the optional integer @var{start} argument is
9800 provided, begin matching from that position in the string.
9801 Return a match structure describing the results of the match,
9802 or @code{#f} if no match could be found.
9804 The @var{flags} arguments change the matching behavior.
9805 The following flags may be supplied:
9809 Operator @samp{^} always fails (unless @code{regexp/newline}
9810 is used). Use this when the beginning of the string should
9811 not be considered the beginning of a line.
9813 Operator @samp{$} always fails (unless @code{regexp/newline}
9814 is used). Use this when the end of the string should not be
9815 considered the end of a line.