Commit | Line | Data |
---|---|---|
780ee65e NJ |
1 | @paragraphindent 0 |
2 | ||
3 | \facons | |
4 | @c snarfed from alist.c:60 | |
5 | @deffn primitive acons key value alist | |
6 | Adds 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. | |
10 | @end deffn | |
11 | ||
12 | \fsloppy-assq | |
13 | @c snarfed from alist.c:83 | |
14 | @deffn primitive sloppy-assq key alist | |
15 | Behaves like @code{assq} but does not do any error checking. | |
16 | Recommended only for use in Guile internals. | |
17 | @end deffn | |
18 | ||
19 | \fsloppy-assv | |
20 | @c snarfed from alist.c:101 | |
21 | @deffn primitive sloppy-assv key alist | |
22 | Behaves like @code{assv} but does not do any error checking. | |
23 | Recommended only for use in Guile internals. | |
24 | @end deffn | |
25 | ||
26 | \fsloppy-assoc | |
27 | @c snarfed from alist.c:119 | |
28 | @deffn primitive sloppy-assoc key alist | |
29 | Behaves like @code{assoc} but does not do any error checking. | |
30 | Recommended only for use in Guile internals. | |
31 | @end deffn | |
32 | ||
33 | \fassq | |
34 | @c snarfed from alist.c:146 | |
35 | @deffn primitive assq key alist | |
36 | @deffnx primitive assv key alist | |
37 | @deffnx primitive assoc key alist | |
38 | Fetches the entry in @var{alist} that is associated with @var{key}. To | |
39 | decide whether the argument @var{key} matches a particular entry in | |
40 | @var{alist}, @code{assq} compares keys with @code{eq?}, @code{assv} | |
41 | uses @code{eqv?} and @code{assoc} uses @code{equal?}. If @var{key} | |
42 | cannot be found in @var{alist} (according to whichever equality | |
43 | predicate is in use), then @code{#f} is returned. These functions | |
44 | return the entire alist entry found (i.e. both the key and the value). | |
45 | @end deffn | |
46 | ||
47 | \fassv | |
48 | @c snarfed from alist.c:167 | |
49 | @deffn primitive assv key alist | |
50 | Behaves like @code{assq} but uses @code{eqv?} for key comparison. | |
51 | @end deffn | |
52 | ||
53 | \fassoc | |
54 | @c snarfed from alist.c:188 | |
55 | @deffn primitive assoc key alist | |
56 | Behaves like @code{assq} but uses @code{equal?} for key comparison. | |
57 | @end deffn | |
58 | ||
59 | \fassq-ref | |
60 | @c snarfed from alist.c:232 | |
61 | @deffn primitive assq-ref alist key | |
62 | @deffnx primitive assv-ref alist key | |
63 | @deffnx primitive assoc-ref alist key | |
64 | Like @code{assq}, @code{assv} and @code{assoc}, except that only the | |
65 | value associated with @var{key} in @var{alist} is returned. These | |
66 | functions are equivalent to | |
67 | ||
68 | @lisp | |
69 | (let ((ent (@var{associator} @var{key} @var{alist}))) | |
70 | (and ent (cdr ent))) | |
71 | @end lisp | |
72 | ||
73 | where @var{associator} is one of @code{assq}, @code{assv} or @code{assoc}. | |
74 | @end deffn | |
75 | ||
76 | \fassv-ref | |
77 | @c snarfed from alist.c:249 | |
78 | @deffn primitive assv-ref alist key | |
79 | Behaves like @code{assq-ref} but uses @code{eqv?} for key comparison. | |
80 | @end deffn | |
81 | ||
82 | \fassoc-ref | |
83 | @c snarfed from alist.c:266 | |
84 | @deffn primitive assoc-ref alist key | |
85 | Behaves like @code{assq-ref} but uses @code{equal?} for key comparison. | |
86 | @end deffn | |
87 | ||
88 | \fassq-set! | |
89 | @c snarfed from alist.c:295 | |
90 | @deffn primitive assq-set! alist key val | |
91 | @deffnx primitive assv-set! alist key value | |
92 | @deffnx primitive assoc-set! alist key value | |
93 | Reassociate @var{key} in @var{alist} with @var{value}: find any existing | |
94 | @var{alist} entry for @var{key} and associate it with the new | |
95 | @var{value}. If @var{alist} does not contain an entry for @var{key}, | |
96 | add a new one. Return the (possibly new) alist. | |
97 | ||
98 | These functions do not attempt to verify the structure of @var{alist}, | |
99 | and so may cause unusual results if passed an object that is not an | |
100 | association list. | |
101 | @end deffn | |
102 | ||
103 | \fassv-set! | |
104 | @c snarfed from alist.c:313 | |
105 | @deffn primitive assv-set! alist key val | |
106 | Behaves like @code{assq-set!} but uses @code{eqv?} for key comparison. | |
107 | @end deffn | |
108 | ||
109 | \fassoc-set! | |
110 | @c snarfed from alist.c:331 | |
111 | @deffn primitive assoc-set! alist key val | |
112 | Behaves like @code{assq-set!} but uses @code{equal?} for key comparison. | |
113 | @end deffn | |
114 | ||
115 | \fassq-remove! | |
116 | @c snarfed from alist.c:355 | |
117 | @deffn primitive assq-remove! alist key | |
118 | @deffnx primitive assv-remove! alist key | |
119 | @deffnx primitive assoc-remove! alist key | |
120 | Delete the first entry in @var{alist} associated with @var{key}, and return | |
121 | the resulting alist. | |
122 | @end deffn | |
123 | ||
124 | \fassv-remove! | |
125 | @c snarfed from alist.c:371 | |
126 | @deffn primitive assv-remove! alist key | |
127 | Behaves like @code{assq-remove!} but uses @code{eqv?} for key comparison. | |
128 | @end deffn | |
129 | ||
130 | \fassoc-remove! | |
131 | @c snarfed from alist.c:387 | |
132 | @deffn primitive assoc-remove! alist key | |
133 | Behaves like @code{assq-remove!} but uses @code{equal?} for key comparison. | |
134 | @end deffn | |
135 | ||
136 | \fmake-arbiter | |
137 | @c snarfed from arbiters.c:84 | |
138 | @deffn primitive make-arbiter name | |
139 | Return an object of type arbiter and name @var{name}. Its | |
140 | state is initially unlocked. Arbiters are a way to achieve | |
141 | process synchronization. | |
142 | @end deffn | |
143 | ||
144 | \ftry-arbiter | |
145 | @c snarfed from arbiters.c:94 | |
146 | @deffn primitive try-arbiter arb | |
147 | Return @code{#t} and lock the arbiter @var{arb} if the arbiter | |
148 | was unlocked. Otherwise, return @code{#f}. | |
149 | @end deffn | |
150 | ||
151 | \frelease-arbiter | |
152 | @c snarfed from arbiters.c:115 | |
153 | @deffn primitive release-arbiter arb | |
154 | Return @code{#t} and unlock the arbiter @var{arb} if the | |
155 | arbiter was locked. Otherwise, return @code{#f}. | |
156 | @end deffn | |
157 | ||
158 | \fasync | |
159 | @c snarfed from async.c:290 | |
160 | @deffn primitive async thunk | |
161 | Create a new async for the procedure @var{thunk}. | |
162 | @end deffn | |
163 | ||
164 | \fsystem-async | |
165 | @c snarfed from async.c:300 | |
166 | @deffn primitive system-async thunk | |
167 | Create a new async for the procedure @var{thunk}. Also | |
168 | add it to the system's list of active async objects. | |
169 | @end deffn | |
170 | ||
171 | \fasync-mark | |
89d04205 | 172 | @c snarfed from async.c:311 |
780ee65e NJ |
173 | @deffn primitive async-mark a |
174 | Mark the async @var{a} for future execution. | |
175 | @end deffn | |
176 | ||
177 | \fsystem-async-mark | |
89d04205 | 178 | @c snarfed from async.c:327 |
780ee65e NJ |
179 | @deffn primitive system-async-mark a |
180 | Mark the async @var{a} for future execution. | |
181 | @end deffn | |
182 | ||
183 | \frun-asyncs | |
89d04205 | 184 | @c snarfed from async.c:347 |
780ee65e NJ |
185 | @deffn primitive run-asyncs list_of_a |
186 | Execute all thunks from the asyncs of the list @var{list_of_a}. | |
187 | @end deffn | |
188 | ||
189 | \fnoop | |
89d04205 | 190 | @c snarfed from async.c:381 |
780ee65e NJ |
191 | @deffn primitive noop . args |
192 | Do nothing. When called without arguments, return @code{#f}, | |
193 | otherwise return the first argument. | |
194 | @end deffn | |
195 | ||
196 | \funmask-signals | |
89d04205 | 197 | @c snarfed from async.c:433 |
780ee65e NJ |
198 | @deffn primitive unmask-signals |
199 | Unmask signals. The returned value is not specified. | |
200 | @end deffn | |
201 | ||
202 | \fmask-signals | |
89d04205 | 203 | @c snarfed from async.c:444 |
780ee65e NJ |
204 | @deffn primitive mask-signals |
205 | Mask signals. The returned value is not specified. | |
206 | @end deffn | |
207 | ||
208 | \fdisplay-error | |
209 | @c snarfed from backtrace.c:262 | |
210 | @deffn primitive display-error stack port subr message args rest | |
211 | Display an error message to the output port @var{port}. | |
212 | @var{stack} is the saved stack for the error, @var{subr} is | |
213 | the name of the procedure in which the error occured and | |
214 | @var{message} is the actual error message, which may contain | |
215 | formatting instructions. These will format the arguments in | |
216 | the list @var{args} accordingly. @var{rest} is currently | |
217 | ignored. | |
218 | @end deffn | |
219 | ||
220 | \fdisplay-application | |
221 | @c snarfed from backtrace.c:399 | |
222 | @deffn primitive display-application frame [port [indent]] | |
223 | Display a procedure application @var{frame} to the output port | |
224 | @var{port}. @var{indent} specifies the indentation of the | |
225 | output. | |
226 | @end deffn | |
227 | ||
228 | \fdisplay-backtrace | |
89d04205 | 229 | @c snarfed from backtrace.c:619 |
780ee65e NJ |
230 | @deffn primitive display-backtrace stack port [first [depth]] |
231 | Display a backtrace to the output port @var{port}. @var{stack} | |
232 | is the stack to take the backtrace from, @var{first} specifies | |
233 | where in the stack to start and @var{depth} how much frames | |
234 | to display. Both @var{first} and @var{depth} can be @code{#f}, | |
235 | which means that default values will be used. | |
236 | @end deffn | |
237 | ||
238 | \fbacktrace | |
89d04205 | 239 | @c snarfed from backtrace.c:642 |
780ee65e NJ |
240 | @deffn primitive backtrace |
241 | Display a backtrace of the stack saved by the last error | |
242 | to the current output port. | |
243 | @end deffn | |
244 | ||
245 | \fnot | |
246 | @c snarfed from boolean.c:56 | |
247 | @deffn primitive not x | |
248 | Return @code{#t} iff @var{x} is @code{#f}, else return @code{#f}. | |
249 | @end deffn | |
250 | ||
251 | \fboolean? | |
252 | @c snarfed from boolean.c:66 | |
253 | @deffn primitive boolean? obj | |
254 | Return @code{#t} iff @var{obj} is either @code{#t} or @code{#f}. | |
255 | @end deffn | |
256 | ||
257 | \fchar? | |
258 | @c snarfed from chars.c:56 | |
259 | @deffn primitive char? x | |
260 | Return @code{#t} iff @var{x} is a character, else @code{#f}. | |
261 | @end deffn | |
262 | ||
263 | \fchar=? | |
264 | @c snarfed from chars.c:65 | |
265 | @deffn primitive char=? x y | |
266 | Return @code{#t} iff @var{x} is the same character as @var{y}, else @code{#f}. | |
267 | @end deffn | |
268 | ||
269 | \fchar<? | |
270 | @c snarfed from chars.c:78 | |
271 | @deffn primitive char<? x y | |
272 | Return @code{#t} iff @var{x} is less than @var{y} in the ASCII sequence, | |
273 | else @code{#f}. | |
274 | @end deffn | |
275 | ||
276 | \fchar<=? | |
277 | @c snarfed from chars.c:90 | |
278 | @deffn primitive char<=? x y | |
279 | Return @code{#t} iff @var{x} is less than or equal to @var{y} in the | |
280 | ASCII sequence, else @code{#f}. | |
281 | @end deffn | |
282 | ||
283 | \fchar>? | |
284 | @c snarfed from chars.c:102 | |
285 | @deffn primitive char>? x y | |
286 | Return @code{#t} iff @var{x} is greater than @var{y} in the ASCII | |
287 | sequence, else @code{#f}. | |
288 | @end deffn | |
289 | ||
290 | \fchar>=? | |
291 | @c snarfed from chars.c:114 | |
292 | @deffn primitive char>=? x y | |
293 | Return @code{#t} iff @var{x} is greater than or equal to @var{y} in the | |
294 | ASCII sequence, else @code{#f}. | |
295 | @end deffn | |
296 | ||
297 | \fchar-ci=? | |
298 | @c snarfed from chars.c:126 | |
299 | @deffn primitive char-ci=? x y | |
300 | Return @code{#t} iff @var{x} is the same character as @var{y} ignoring | |
301 | case, else @code{#f}. | |
302 | @end deffn | |
303 | ||
304 | \fchar-ci<? | |
305 | @c snarfed from chars.c:138 | |
306 | @deffn primitive char-ci<? x y | |
307 | Return @code{#t} iff @var{x} is less than @var{y} in the ASCII sequence | |
308 | ignoring case, else @code{#f}. | |
309 | @end deffn | |
310 | ||
311 | \fchar-ci<=? | |
312 | @c snarfed from chars.c:150 | |
313 | @deffn primitive char-ci<=? x y | |
314 | Return @code{#t} iff @var{x} is less than or equal to @var{y} in the | |
315 | ASCII sequence ignoring case, else @code{#f}. | |
316 | @end deffn | |
317 | ||
318 | \fchar-ci>? | |
319 | @c snarfed from chars.c:162 | |
320 | @deffn primitive char-ci>? x y | |
321 | Return @code{#t} iff @var{x} is greater than @var{y} in the ASCII | |
322 | sequence ignoring case, else @code{#f}. | |
323 | @end deffn | |
324 | ||
325 | \fchar-ci>=? | |
326 | @c snarfed from chars.c:174 | |
327 | @deffn primitive char-ci>=? x y | |
328 | Return @code{#t} iff @var{x} is greater than or equal to @var{y} in the | |
329 | ASCII sequence ignoring case, else @code{#f}. | |
330 | @end deffn | |
331 | ||
332 | \fchar-alphabetic? | |
333 | @c snarfed from chars.c:187 | |
334 | @deffn primitive char-alphabetic? chr | |
335 | Return @code{#t} iff @var{chr} is alphabetic, else @code{#f}. | |
336 | Alphabetic means the same thing as the isalpha C library function. | |
337 | @end deffn | |
338 | ||
339 | \fchar-numeric? | |
340 | @c snarfed from chars.c:198 | |
341 | @deffn primitive char-numeric? chr | |
342 | Return @code{#t} iff @var{chr} is numeric, else @code{#f}. | |
343 | Numeric means the same thing as the isdigit C library function. | |
344 | @end deffn | |
345 | ||
346 | \fchar-whitespace? | |
347 | @c snarfed from chars.c:209 | |
348 | @deffn primitive char-whitespace? chr | |
349 | Return @code{#t} iff @var{chr} is whitespace, else @code{#f}. | |
350 | Whitespace means the same thing as the isspace C library function. | |
351 | @end deffn | |
352 | ||
353 | \fchar-upper-case? | |
354 | @c snarfed from chars.c:222 | |
355 | @deffn primitive char-upper-case? chr | |
356 | Return @code{#t} iff @var{chr} is uppercase, else @code{#f}. | |
357 | Uppercase means the same thing as the isupper C library function. | |
358 | @end deffn | |
359 | ||
360 | \fchar-lower-case? | |
361 | @c snarfed from chars.c:234 | |
362 | @deffn primitive char-lower-case? chr | |
363 | Return @code{#t} iff @var{chr} is lowercase, else @code{#f}. | |
364 | Lowercase means the same thing as the islower C library function. | |
365 | @end deffn | |
366 | ||
367 | \fchar-is-both? | |
368 | @c snarfed from chars.c:248 | |
369 | @deffn primitive char-is-both? chr | |
370 | Return @code{#t} iff @var{chr} is either uppercase or lowercase, else @code{#f}. | |
371 | Uppercase and lowercase are as defined by the isupper and islower | |
372 | C library functions. | |
373 | @end deffn | |
374 | ||
375 | \fchar->integer | |
376 | @c snarfed from chars.c:262 | |
377 | @deffn primitive char->integer chr | |
378 | Return the number corresponding to ordinal position of @var{chr} in the | |
379 | ASCII sequence. | |
380 | @end deffn | |
381 | ||
382 | \finteger->char | |
383 | @c snarfed from chars.c:274 | |
384 | @deffn primitive integer->char n | |
385 | Return the character at position @var{n} in the ASCII sequence. | |
386 | @end deffn | |
387 | ||
388 | \fchar-upcase | |
389 | @c snarfed from chars.c:285 | |
390 | @deffn primitive char-upcase chr | |
391 | Return the uppercase character version of @var{chr}. | |
392 | @end deffn | |
393 | ||
394 | \fchar-downcase | |
395 | @c snarfed from chars.c:296 | |
396 | @deffn primitive char-downcase chr | |
397 | Return the lowercase character version of @var{chr}. | |
398 | @end deffn | |
399 | ||
400 | \fdebug-options-interface | |
401 | @c snarfed from debug.c:80 | |
402 | @deffn primitive debug-options-interface [setting] | |
403 | Option interface for the debug options. Instead of using | |
404 | this procedure directly, use the procedures @code{debug-enable}, | |
405 | @code{debug-disable}, @code{debug-set!} and @var{debug-options}. | |
406 | @end deffn | |
407 | ||
408 | \fwith-traps | |
409 | @c snarfed from debug.c:128 | |
410 | @deffn primitive with-traps thunk | |
411 | Call @var{thunk} with traps enabled. | |
412 | @end deffn | |
413 | ||
414 | \fmemoized? | |
415 | @c snarfed from debug.c:170 | |
416 | @deffn primitive memoized? obj | |
417 | Return @code{#t} if @var{obj} is memoized. | |
418 | @end deffn | |
419 | ||
420 | \funmemoize | |
421 | @c snarfed from debug.c:376 | |
422 | @deffn primitive unmemoize m | |
423 | Unmemoize the memoized expression @var{m}, | |
424 | @end deffn | |
425 | ||
426 | \fmemoized-environment | |
427 | @c snarfed from debug.c:386 | |
428 | @deffn primitive memoized-environment m | |
429 | Return the environment of the memoized expression @var{m}. | |
430 | @end deffn | |
431 | ||
432 | \fprocedure-name | |
433 | @c snarfed from debug.c:396 | |
434 | @deffn primitive procedure-name proc | |
435 | Return the name of the procedure @var{proc} | |
436 | @end deffn | |
437 | ||
438 | \fprocedure-source | |
439 | @c snarfed from debug.c:422 | |
440 | @deffn primitive procedure-source proc | |
441 | Return the source of the procedure @var{proc}. | |
442 | @end deffn | |
443 | ||
444 | \fprocedure-environment | |
72ad43dc | 445 | @c snarfed from debug.c:455 |
780ee65e NJ |
446 | @deffn primitive procedure-environment proc |
447 | Return the environment of the procedure @var{proc}. | |
448 | @end deffn | |
449 | ||
450 | \flocal-eval | |
72ad43dc | 451 | @c snarfed from debug.c:487 |
780ee65e NJ |
452 | @deffn primitive local-eval exp [env] |
453 | Evaluate @var{exp} in its environment. If @var{env} is supplied, | |
454 | it is the environment in which to evaluate @var{exp}. Otherwise, | |
455 | @var{exp} must be a memoized code object (in which case, its environment | |
456 | is implicit). | |
457 | @end deffn | |
458 | ||
459 | \fdebug-object? | |
72ad43dc | 460 | @c snarfed from debug.c:574 |
780ee65e NJ |
461 | @deffn primitive debug-object? obj |
462 | Return @code{#t} if @var{obj} is a debug object. | |
463 | @end deffn | |
464 | ||
7a095584 NJ |
465 | \fissue-deprecation-warning |
466 | @c snarfed from deprecation.c:78 | |
467 | @deffn primitive issue-deprecation-warning . msgs | |
468 | Output @var{msgs} to @code{(current-error-port)} when this | |
469 | is the first call to @code{issue-deprecation-warning} with | |
470 | this specific @var{msg}. Do nothing otherwise. | |
471 | The argument @var{msgs} should be a list of strings; | |
472 | they are printed in turn, each one followed by a newline. | |
473 | @end deffn | |
474 | ||
475 | \finclude-deprecated-features | |
476 | @c snarfed from deprecation.c:120 | |
477 | @deffn primitive include-deprecated-features | |
478 | Return @code{#t} iff deprecated features should be included | |
479 | in public interfaces. | |
480 | @end deffn | |
481 | ||
780ee65e NJ |
482 | \fc-registered-modules |
483 | @c snarfed from dynl.c:183 | |
484 | @deffn primitive c-registered-modules | |
485 | Return a list of the object code modules that have been imported into | |
486 | the current Guile process. Each element of the list is a pair whose | |
487 | car is the name of the module, and whose cdr is the function handle | |
488 | for that module's initializer function. The name is the string that | |
489 | has been passed to scm_register_module_xxx. | |
490 | @end deffn | |
491 | ||
492 | \fc-clear-registered-modules | |
493 | @c snarfed from dynl.c:204 | |
494 | @deffn primitive c-clear-registered-modules | |
495 | Destroy the list of modules registered with the current Guile process. | |
496 | The return value is unspecified. @strong{Warning:} this function does | |
497 | not actually unlink or deallocate these modules, but only destroys the | |
498 | records of which modules have been loaded. It should therefore be used | |
499 | only by module bookkeeping operations. | |
500 | @end deffn | |
501 | ||
502 | \fdynamic-link | |
89d04205 | 503 | @c snarfed from dynl.c:357 |
ae9f3a15 MG |
504 | @deffn primitive dynamic-link filename |
505 | Open the dynamic library called @var{filename}. A library | |
506 | handle representing the opened library is returned; this handle | |
507 | should be used as the @var{dobj} argument to the following | |
508 | functions. | |
780ee65e NJ |
509 | @end deffn |
510 | ||
511 | \fdynamic-object? | |
89d04205 | 512 | @c snarfed from dynl.c:373 |
780ee65e NJ |
513 | @deffn primitive dynamic-object? obj |
514 | Return @code{#t} if @var{obj} is a dynamic library handle, or @code{#f} | |
515 | otherwise. | |
516 | @end deffn | |
517 | ||
518 | \fdynamic-unlink | |
89d04205 | 519 | @c snarfed from dynl.c:386 |
780ee65e | 520 | @deffn primitive dynamic-unlink dobj |
780ee65e | 521 | Unlink the indicated object file from the application. The |
ae9f3a15 | 522 | argument @var{dobj} must have been obtained by a call to |
780ee65e | 523 | @code{dynamic-link}. After @code{dynamic-unlink} has been |
ae9f3a15 | 524 | called on @var{dobj}, its content is no longer accessible. |
780ee65e NJ |
525 | @end deffn |
526 | ||
527 | \fdynamic-func | |
89d04205 | 528 | @c snarfed from dynl.c:413 |
780ee65e NJ |
529 | @deffn primitive dynamic-func name dobj |
530 | Search the dynamic object @var{dobj} for the C function | |
531 | indicated by the string @var{name} and return some Scheme | |
532 | handle that can later be used with @code{dynamic-call} to | |
533 | actually call the function. | |
534 | ||
535 | Regardless whether your C compiler prepends an underscore @samp{_} to | |
536 | the global names in a program, you should @strong{not} include this | |
537 | underscore in @var{function}. Guile knows whether the underscore is | |
538 | needed or not and will add it when necessary. | |
539 | @end deffn | |
540 | ||
541 | \fdynamic-call | |
89d04205 | 542 | @c snarfed from dynl.c:453 |
780ee65e | 543 | @deffn primitive dynamic-call func dobj |
ae9f3a15 MG |
544 | Call the C function indicated by @var{func} and @var{dobj}. |
545 | The function is passed no arguments and its return value is | |
546 | ignored. When @var{function} is something returned by | |
547 | @code{dynamic-func}, call that function and ignore @var{dobj}. | |
548 | When @var{func} is a string , look it up in @var{dynobj}; this | |
549 | is equivalent to | |
780ee65e | 550 | @smallexample |
ae9f3a15 | 551 | (dynamic-call (dynamic-func @var{func} @var{dobj} #f)) |
780ee65e NJ |
552 | @end smallexample |
553 | ||
554 | Interrupts are deferred while the C function is executing (with | |
555 | @code{SCM_DEFER_INTS}/@code{SCM_ALLOW_INTS}). | |
556 | @end deffn | |
557 | ||
558 | \fdynamic-args-call | |
89d04205 | 559 | @c snarfed from dynl.c:481 |
780ee65e | 560 | @deffn primitive dynamic-args-call func dobj args |
ae9f3a15 MG |
561 | Call the C function indicated by @var{func} and @var{dobj}, |
562 | just like @code{dynamic-call}, but pass it some arguments and | |
563 | return its return value. The C function is expected to take | |
564 | two arguments and return an @code{int}, just like @code{main}: | |
780ee65e NJ |
565 | @smallexample |
566 | int c_func (int argc, char **argv); | |
567 | @end smallexample | |
568 | ||
ae9f3a15 MG |
569 | The parameter @var{args} must be a list of strings and is |
570 | converted into an array of @code{char *}. The array is passed | |
571 | in @var{argv} and its size in @var{argc}. The return value is | |
572 | converted to a Scheme number and returned from the call to | |
573 | @code{dynamic-args-call}. | |
780ee65e NJ |
574 | @end deffn |
575 | ||
576 | \fdynamic-wind | |
89d04205 | 577 | @c snarfed from dynwind.c:121 |
ae9f3a15 | 578 | @deffn primitive dynamic-wind in_guard thunk out_guard |
780ee65e | 579 | All three arguments must be 0-argument procedures. |
ae9f3a15 MG |
580 | @var{in_guard} is called, then @var{thunk}, then |
581 | @var{out_guard}. | |
7a095584 | 582 | |
ae9f3a15 MG |
583 | If, any time during the execution of @var{thunk}, the |
584 | continuation of the @code{dynamic_wind} expression is escaped | |
585 | non-locally, @var{out_guard} is called. If the continuation of | |
586 | the dynamic-wind is re-entered, @var{in_guard} is called. Thus | |
587 | @var{in_guard} and @var{out_guard} may be called any number of | |
588 | times. | |
589 | @lisp | |
780ee65e NJ |
590 | (define x 'normal-binding) |
591 | @result{} x | |
780ee65e NJ |
592 | (define a-cont (call-with-current-continuation |
593 | (lambda (escape) | |
594 | (let ((old-x x)) | |
595 | (dynamic-wind | |
596 | ;; in-guard: | |
597 | ;; | |
598 | (lambda () (set! x 'special-binding)) | |
7a095584 | 599 | |
780ee65e NJ |
600 | ;; thunk |
601 | ;; | |
602 | (lambda () (display x) (newline) | |
603 | (call-with-current-continuation escape) | |
604 | (display x) (newline) | |
605 | x) | |
7a095584 | 606 | |
780ee65e NJ |
607 | ;; out-guard: |
608 | ;; | |
609 | (lambda () (set! x old-x))))))) | |
7a095584 | 610 | |
780ee65e NJ |
611 | ;; Prints: |
612 | special-binding | |
613 | ;; Evaluates to: | |
614 | @result{} a-cont | |
780ee65e NJ |
615 | x |
616 | @result{} normal-binding | |
780ee65e NJ |
617 | (a-cont #f) |
618 | ;; Prints: | |
619 | special-binding | |
620 | ;; Evaluates to: | |
621 | @result{} a-cont ;; the value of the (define a-cont...) | |
780ee65e NJ |
622 | x |
623 | @result{} normal-binding | |
780ee65e NJ |
624 | a-cont |
625 | @result{} special-binding | |
ae9f3a15 | 626 | @end lisp |
780ee65e NJ |
627 | @end deffn |
628 | ||
629 | \fenvironment? | |
630 | @c snarfed from environments.c:135 | |
631 | @deffn primitive environment? obj | |
632 | Return @code{#t} if @var{obj} is an environment, or @code{#f} | |
633 | otherwise. | |
634 | @end deffn | |
635 | ||
636 | \fenvironment-bound? | |
637 | @c snarfed from environments.c:146 | |
638 | @deffn primitive environment-bound? env sym | |
639 | Return @code{#t} if @var{sym} is bound in @var{env}, or | |
640 | @code{#f} otherwise. | |
641 | @end deffn | |
642 | ||
643 | \fenvironment-ref | |
644 | @c snarfed from environments.c:161 | |
645 | @deffn primitive environment-ref env sym | |
646 | Return the value of the location bound to @var{sym} in | |
647 | @var{env}. If @var{sym} is unbound in @var{env}, signal an | |
648 | @code{environment:unbound} error. | |
649 | @end deffn | |
650 | ||
651 | \fenvironment-fold | |
652 | @c snarfed from environments.c:231 | |
653 | @deffn primitive environment-fold env proc init | |
654 | Iterate over all the bindings in @var{env}, accumulating some | |
655 | value. | |
656 | For each binding in @var{env}, apply @var{proc} to the symbol | |
657 | bound, its value, and the result from the previous application | |
658 | of @var{proc}. | |
659 | Use @var{init} as @var{proc}'s third argument the first time | |
660 | @var{proc} is applied. | |
661 | If @var{env} contains no bindings, this function simply returns | |
662 | @var{init}. | |
663 | If @var{env} binds the symbol sym1 to the value val1, sym2 to | |
664 | val2, and so on, then this procedure computes: | |
ae9f3a15 | 665 | @lisp |
780ee65e NJ |
666 | (proc sym1 val1 |
667 | (proc sym2 val2 | |
668 | ... | |
669 | (proc symn valn | |
670 | init))) | |
ae9f3a15 | 671 | @end lisp |
780ee65e NJ |
672 | Each binding in @var{env} will be processed exactly once. |
673 | @code{environment-fold} makes no guarantees about the order in | |
674 | which the bindings are processed. | |
675 | Here is a function which, given an environment, constructs an | |
676 | association list representing that environment's bindings, | |
677 | using environment-fold: | |
ae9f3a15 | 678 | @lisp |
780ee65e NJ |
679 | (define (environment->alist env) |
680 | (environment-fold env | |
681 | (lambda (sym val tail) | |
682 | (cons (cons sym val) tail)) | |
683 | '())) | |
ae9f3a15 | 684 | @end lisp |
780ee65e NJ |
685 | @end deffn |
686 | ||
687 | \fenvironment-define | |
688 | @c snarfed from environments.c:266 | |
689 | @deffn primitive environment-define env sym val | |
690 | Bind @var{sym} to a new location containing @var{val} in | |
691 | @var{env}. If @var{sym} is already bound to another location | |
692 | in @var{env} and the binding is mutable, that binding is | |
693 | replaced. The new binding and location are both mutable. The | |
694 | return value is unspecified. | |
695 | If @var{sym} is already bound in @var{env}, and the binding is | |
696 | immutable, signal an @code{environment:immutable-binding} error. | |
697 | @end deffn | |
698 | ||
699 | \fenvironment-undefine | |
700 | @c snarfed from environments.c:292 | |
701 | @deffn primitive environment-undefine env sym | |
702 | Remove any binding for @var{sym} from @var{env}. If @var{sym} | |
703 | is unbound in @var{env}, do nothing. The return value is | |
704 | unspecified. | |
705 | If @var{sym} is already bound in @var{env}, and the binding is | |
706 | immutable, signal an @code{environment:immutable-binding} error. | |
707 | @end deffn | |
708 | ||
709 | \fenvironment-set! | |
710 | @c snarfed from environments.c:320 | |
711 | @deffn primitive environment-set! env sym val | |
712 | If @var{env} binds @var{sym} to some location, change that | |
713 | location's value to @var{val}. The return value is | |
714 | unspecified. | |
715 | If @var{sym} is not bound in @var{env}, signal an | |
716 | @code{environment:unbound} error. If @var{env} binds @var{sym} | |
717 | to an immutable location, signal an | |
718 | @code{environment:immutable-location} error. | |
719 | @end deffn | |
720 | ||
721 | \fenvironment-cell | |
722 | @c snarfed from environments.c:355 | |
723 | @deffn primitive environment-cell env sym for_write | |
724 | Return the value cell which @var{env} binds to @var{sym}, or | |
725 | @code{#f} if the binding does not live in a value cell. | |
726 | The argument @var{for-write} indicates whether the caller | |
727 | intends to modify the variable's value by mutating the value | |
728 | cell. If the variable is immutable, then | |
729 | @code{environment-cell} signals an | |
730 | @code{environment:immutable-location} error. | |
731 | If @var{sym} is unbound in @var{env}, signal an | |
732 | @code{environment:unbound} error. | |
733 | If you use this function, you should consider using | |
734 | @code{environment-observe}, to be notified when @var{sym} gets | |
735 | re-bound to a new value cell, or becomes undefined. | |
736 | @end deffn | |
737 | ||
738 | \fenvironment-observe | |
739 | @c snarfed from environments.c:407 | |
740 | @deffn primitive environment-observe env proc | |
741 | Whenever @var{env}'s bindings change, apply @var{proc} to | |
742 | @var{env}. | |
743 | This function returns an object, token, which you can pass to | |
744 | @code{environment-unobserve} to remove @var{proc} from the set | |
745 | of procedures observing @var{env}. The type and value of | |
746 | token is unspecified. | |
747 | @end deffn | |
748 | ||
749 | \fenvironment-observe-weak | |
750 | @c snarfed from environments.c:424 | |
751 | @deffn primitive environment-observe-weak env proc | |
752 | This function is the same as environment-observe, except that | |
753 | the reference @var{env} retains to @var{proc} is a weak | |
754 | reference. This means that, if there are no other live, | |
755 | non-weak references to @var{proc}, it will be | |
756 | garbage-collected, and dropped from @var{env}'s | |
757 | list of observing procedures. | |
758 | @end deffn | |
759 | ||
760 | \fenvironment-unobserve | |
761 | @c snarfed from environments.c:460 | |
762 | @deffn primitive environment-unobserve token | |
763 | Cancel the observation request which returned the value | |
764 | @var{token}. The return value is unspecified. | |
765 | If a call @code{(environment-observe env proc)} returns | |
766 | @var{token}, then the call @code{(environment-unobserve token)} | |
767 | will cause @var{proc} to no longer be called when @var{env}'s | |
768 | bindings change. | |
769 | @end deffn | |
770 | ||
771 | \fmake-leaf-environment | |
772 | @c snarfed from environments.c:1040 | |
773 | @deffn primitive make-leaf-environment | |
774 | Create a new leaf environment, containing no bindings. | |
775 | All bindings and locations created in the new environment | |
776 | will be mutable. | |
777 | @end deffn | |
778 | ||
779 | \fleaf-environment? | |
780 | @c snarfed from environments.c:1063 | |
781 | @deffn primitive leaf-environment? object | |
782 | Return @code{#t} if object is a leaf environment, or @code{#f} | |
783 | otherwise. | |
784 | @end deffn | |
785 | ||
786 | \fmake-eval-environment | |
787 | @c snarfed from environments.c:1429 | |
788 | @deffn primitive make-eval-environment local imported | |
789 | Return a new environment object eval whose bindings are the | |
790 | union of the bindings in the environments @var{local} and | |
791 | @var{imported}, with bindings from @var{local} taking | |
792 | precedence. Definitions made in eval are placed in @var{local}. | |
793 | Applying @code{environment-define} or | |
794 | @code{environment-undefine} to eval has the same effect as | |
795 | applying the procedure to @var{local}. | |
796 | Note that eval incorporates @var{local} and @var{imported} by | |
797 | reference: | |
798 | If, after creating eval, the program changes the bindings of | |
799 | @var{local} or @var{imported}, those changes will be visible | |
800 | in eval. | |
801 | Since most Scheme evaluation takes place in eval environments, | |
802 | they transparently cache the bindings received from @var{local} | |
803 | and @var{imported}. Thus, the first time the program looks up | |
804 | a symbol in eval, eval may make calls to @var{local} or | |
805 | @var{imported} to find their bindings, but subsequent | |
806 | references to that symbol will be as fast as references to | |
807 | bindings in finite environments. | |
808 | In typical use, @var{local} will be a finite environment, and | |
809 | @var{imported} will be an import environment | |
810 | @end deffn | |
811 | ||
812 | \feval-environment? | |
813 | @c snarfed from environments.c:1466 | |
814 | @deffn primitive eval-environment? object | |
815 | Return @code{#t} if object is an eval environment, or @code{#f} | |
816 | otherwise. | |
817 | @end deffn | |
818 | ||
819 | \feval-environment-local | |
820 | @c snarfed from environments.c:1476 | |
821 | @deffn primitive eval-environment-local env | |
822 | Return the local environment of eval environment @var{env}. | |
823 | @end deffn | |
824 | ||
825 | \feval-environment-set-local! | |
826 | @c snarfed from environments.c:1488 | |
827 | @deffn primitive eval-environment-set-local! env local | |
828 | Change @var{env}'s local environment to @var{local}. | |
829 | @end deffn | |
830 | ||
831 | \feval-environment-imported | |
832 | @c snarfed from environments.c:1514 | |
833 | @deffn primitive eval-environment-imported env | |
834 | Return the imported environment of eval environment @var{env}. | |
835 | @end deffn | |
836 | ||
837 | \feval-environment-set-imported! | |
838 | @c snarfed from environments.c:1526 | |
839 | @deffn primitive eval-environment-set-imported! env imported | |
840 | Change @var{env}'s imported environment to @var{imported}. | |
841 | @end deffn | |
842 | ||
843 | \fmake-import-environment | |
844 | @c snarfed from environments.c:1846 | |
845 | @deffn primitive make-import-environment imports conflict_proc | |
846 | Return a new environment @var{imp} whose bindings are the union | |
847 | of the bindings from the environments in @var{imports}; | |
848 | @var{imports} must be a list of environments. That is, | |
849 | @var{imp} binds a symbol to a location when some element of | |
850 | @var{imports} does. | |
851 | If two different elements of @var{imports} have a binding for | |
852 | the same symbol, the @var{conflict-proc} is called with the | |
853 | following parameters: the import environment, the symbol and | |
854 | the list of the imported environments that bind the symbol. | |
855 | If the @var{conflict-proc} returns an environment @var{env}, | |
856 | the conflict is considered as resolved and the binding from | |
857 | @var{env} is used. If the @var{conflict-proc} returns some | |
858 | non-environment object, the conflict is considered unresolved | |
859 | and the symbol is treated as unspecified in the import | |
860 | environment. | |
861 | The checking for conflicts may be performed lazily, i. e. at | |
862 | the moment when a value or binding for a certain symbol is | |
863 | requested instead of the moment when the environment is | |
864 | created or the bindings of the imports change. | |
865 | All bindings in @var{imp} are immutable. If you apply | |
866 | @code{environment-define} or @code{environment-undefine} to | |
867 | @var{imp}, Guile will signal an | |
868 | @code{environment:immutable-binding} error. However, | |
869 | notice that the set of bindings in @var{imp} may still change, | |
870 | if one of its imported environments changes. | |
871 | @end deffn | |
872 | ||
873 | \fimport-environment? | |
874 | @c snarfed from environments.c:1875 | |
875 | @deffn primitive import-environment? object | |
876 | Return @code{#t} if object is an import environment, or | |
877 | @code{#f} otherwise. | |
878 | @end deffn | |
879 | ||
880 | \fimport-environment-imports | |
881 | @c snarfed from environments.c:1886 | |
882 | @deffn primitive import-environment-imports env | |
883 | Return the list of environments imported by the import | |
884 | environment @var{env}. | |
885 | @end deffn | |
886 | ||
887 | \fimport-environment-set-imports! | |
888 | @c snarfed from environments.c:1899 | |
889 | @deffn primitive import-environment-set-imports! env imports | |
890 | Change @var{env}'s list of imported environments to | |
891 | @var{imports}, and check for conflicts. | |
892 | @end deffn | |
893 | ||
894 | \fmake-export-environment | |
895 | @c snarfed from environments.c:2164 | |
896 | @deffn primitive make-export-environment private signature | |
897 | Return a new environment @var{exp} containing only those | |
898 | bindings in private whose symbols are present in | |
899 | @var{signature}. The @var{private} argument must be an | |
900 | environment. | |
901 | ||
902 | The environment @var{exp} binds symbol to location when | |
903 | @var{env} does, and symbol is exported by @var{signature}. | |
904 | ||
905 | @var{signature} is a list specifying which of the bindings in | |
906 | @var{private} should be visible in @var{exp}. Each element of | |
907 | @var{signature} should be a list of the form: | |
908 | (symbol attribute ...) | |
909 | where each attribute is one of the following: | |
910 | @table @asis | |
911 | @item the symbol @code{mutable-location} | |
912 | @var{exp} should treat the | |
913 | location bound to symbol as mutable. That is, @var{exp} | |
914 | will pass calls to @code{environment-set!} or | |
915 | @code{environment-cell} directly through to private. | |
916 | @item the symbol @code{immutable-location} | |
917 | @var{exp} should treat | |
918 | the location bound to symbol as immutable. If the program | |
919 | applies @code{environment-set!} to @var{exp} and symbol, or | |
920 | calls @code{environment-cell} to obtain a writable value | |
921 | cell, @code{environment-set!} will signal an | |
922 | @code{environment:immutable-location} error. Note that, even | |
923 | if an export environment treats a location as immutable, the | |
924 | underlying environment may treat it as mutable, so its | |
925 | value may change. | |
926 | @end table | |
927 | It is an error for an element of signature to specify both | |
928 | @code{mutable-location} and @code{immutable-location}. If | |
929 | neither is specified, @code{immutable-location} is assumed. | |
930 | ||
931 | As a special case, if an element of signature is a lone | |
932 | symbol @var{sym}, it is equivalent to an element of the form | |
933 | @code{(sym)}. | |
934 | ||
935 | All bindings in @var{exp} are immutable. If you apply | |
936 | @code{environment-define} or @code{environment-undefine} to | |
937 | @var{exp}, Guile will signal an | |
938 | @code{environment:immutable-binding} error. However, | |
939 | notice that the set of bindings in @var{exp} may still change, | |
940 | if the bindings in private change. | |
941 | @end deffn | |
942 | ||
943 | \fexport-environment? | |
944 | @c snarfed from environments.c:2199 | |
945 | @deffn primitive export-environment? object | |
946 | Return @code{#t} if object is an export environment, or | |
947 | @code{#f} otherwise. | |
948 | @end deffn | |
949 | ||
950 | \fexport-environment-private | |
951 | @c snarfed from environments.c:2209 | |
952 | @deffn primitive export-environment-private env | |
953 | Return the private environment of export environment @var{env}. | |
954 | @end deffn | |
955 | ||
956 | \fexport-environment-set-private! | |
957 | @c snarfed from environments.c:2221 | |
958 | @deffn primitive export-environment-set-private! env private | |
959 | Change the private environment of export environment @var{env}. | |
960 | @end deffn | |
961 | ||
962 | \fexport-environment-signature | |
963 | @c snarfed from environments.c:2243 | |
964 | @deffn primitive export-environment-signature env | |
965 | Return the signature of export environment @var{env}. | |
966 | @end deffn | |
967 | ||
968 | \fexport-environment-set-signature! | |
969 | @c snarfed from environments.c:2317 | |
970 | @deffn primitive export-environment-set-signature! env signature | |
971 | Change the signature of export environment @var{env}. | |
972 | @end deffn | |
973 | ||
974 | \feq? | |
975 | @c snarfed from eq.c:64 | |
976 | @deffn primitive eq? x y | |
977 | Return @code{#t} iff @var{x} references the same object as @var{y}. | |
978 | @code{eq?} is similar to @code{eqv?} except that in some cases it is | |
979 | capable of discerning distinctions finer than those detectable by | |
980 | @code{eqv?}. | |
981 | @end deffn | |
982 | ||
983 | \feqv? | |
984 | @c snarfed from eq.c:78 | |
985 | @deffn primitive eqv? x y | |
986 | The @code{eqv?} procedure defines a useful equivalence relation on objects. | |
987 | Briefly, it returns @code{#t} if @var{x} and @var{y} should normally be | |
988 | regarded as the same object. This relation is left slightly open to | |
989 | interpretation, but works for comparing immediate integers, characters, | |
990 | and inexact numbers. | |
991 | @end deffn | |
992 | ||
993 | \fequal? | |
994 | @c snarfed from eq.c:127 | |
995 | @deffn primitive equal? x y | |
996 | Return @code{#t} iff @var{x} and @var{y} are recursively @code{eqv?} equivalent. | |
997 | @code{equal?} recursively compares the contents of pairs, | |
998 | vectors, and strings, applying @code{eqv?} on other objects such as | |
999 | numbers and symbols. A rule of thumb is that objects are generally | |
1000 | @code{equal?} if they print the same. @code{equal?} may fail to | |
1001 | terminate if its arguments are circular data structures. | |
1002 | @end deffn | |
1003 | ||
1004 | \fscm-error | |
89d04205 | 1005 | @c snarfed from error.c:114 |
ae9f3a15 MG |
1006 | @deffn primitive scm-error key subr message args data |
1007 | Raise an error with key @var{key}. @var{subr} can be a string | |
1008 | naming the procedure associated with the error, or @code{#f}. | |
1009 | @var{message} is the error message string, possibly containing | |
1010 | @code{~S} and @code{~A} escapes. When an error is reported, | |
1011 | these are replaced by formatting the corresponding members of | |
1012 | @var{args}: @code{~A} (was @code{%s} in older versions of | |
1013 | Guile) formats using @code{display} and @code{~S} (was | |
1014 | @code{%S}) formats using @code{write}. @var{data} is a list or | |
1015 | @code{#f} depending on @var{key}: if @var{key} is | |
1016 | @code{system-error} then it should be a list containing the | |
1017 | Unix @code{errno} value; If @var{key} is @code{signal} then it | |
1018 | should be a list containing the Unix signal number; otherwise | |
1019 | it will usually be @code{#f}. | |
780ee65e NJ |
1020 | @end deffn |
1021 | ||
1022 | \fstrerror | |
89d04205 | 1023 | @c snarfed from error.c:156 |
780ee65e | 1024 | @deffn primitive strerror err |
ae9f3a15 MG |
1025 | Return the Unix error message corresponding to @var{err}, which |
1026 | must be an integer value. | |
780ee65e NJ |
1027 | @end deffn |
1028 | ||
1029 | \fapply:nconc2last | |
89d04205 | 1030 | @c snarfed from eval.c:3256 |
780ee65e NJ |
1031 | @deffn primitive apply:nconc2last lst |
1032 | Given a list (@var{arg1} @dots{} @var{args}), this function | |
1033 | conses the @var{arg1} @dots{} arguments onto the front of | |
1034 | @var{args}, and returns the resulting list. Note that | |
1035 | @var{args} is a list; thus, the argument to this function is | |
1036 | a list whose last element is a list. | |
1037 | Note: Rather than do new consing, @code{apply:nconc2last} | |
1038 | destroys its argument, so use with care. | |
1039 | @end deffn | |
1040 | ||
1041 | \fforce | |
89d04205 | 1042 | @c snarfed from eval.c:3789 |
780ee65e NJ |
1043 | @deffn primitive force x |
1044 | If the promise @var{x} has not been computed yet, compute and | |
1045 | return @var{x}, otherwise just return the previously computed | |
1046 | value. | |
1047 | @end deffn | |
1048 | ||
1049 | \fpromise? | |
89d04205 | 1050 | @c snarfed from eval.c:3812 |
780ee65e NJ |
1051 | @deffn primitive promise? obj |
1052 | Return true if @var{obj} is a promise, i.e. a delayed computation | |
1053 | (@pxref{Delayed evaluation,,,r4rs.info,The Revised^4 Report on Scheme}). | |
1054 | @end deffn | |
1055 | ||
1056 | \fcons-source | |
89d04205 | 1057 | @c snarfed from eval.c:3824 |
780ee65e NJ |
1058 | @deffn primitive cons-source xorig x y |
1059 | Create and return a new pair whose car and cdr are @var{x} and @var{y}. | |
1060 | Any source properties associated with @var{xorig} are also associated | |
1061 | with the new pair. | |
1062 | @end deffn | |
1063 | ||
1064 | \fcopy-tree | |
89d04205 | 1065 | @c snarfed from eval.c:3846 |
780ee65e NJ |
1066 | @deffn primitive copy-tree obj |
1067 | Recursively copy the data tree that is bound to @var{obj}, and return a | |
1068 | pointer to the new data structure. @code{copy-tree} recurses down the | |
1069 | contents of both pairs and vectors (since both cons cells and vector | |
1070 | cells may point to arbitrary objects), and stops recursing when it hits | |
1071 | any other object. | |
1072 | @end deffn | |
1073 | ||
1074 | \fprimitive-eval | |
7a095584 | 1075 | @c snarfed from eval.c:3938 |
780ee65e NJ |
1076 | @deffn primitive primitive-eval exp |
1077 | Evaluate @var{exp} in the top-level environment specified by | |
1078 | the current module. | |
1079 | @end deffn | |
1080 | ||
1081 | \feval | |
7a095584 | 1082 | @c snarfed from eval.c:4007 |
780ee65e NJ |
1083 | @deffn primitive eval exp module |
1084 | Evaluate @var{exp}, a list representing a Scheme expression, | |
1085 | in the top-level environment specified by @var{module}. | |
1086 | While @var{exp} is evaluated (using @var{primitive-eval}), | |
1087 | @var{module} is made the current module. The current module | |
1088 | is reset to its previous value when @var{eval} returns. | |
1089 | @end deffn | |
1090 | ||
1091 | \feval2 | |
7a095584 | 1092 | @c snarfed from eval.c:4051 |
780ee65e NJ |
1093 | @deffn primitive eval2 obj env_thunk |
1094 | Evaluate @var{exp}, a Scheme expression, in the environment | |
7a095584 | 1095 | designated by @var{lookup}, a symbol-lookup function. |
780ee65e NJ |
1096 | Do not use this version of eval, it does not play well |
1097 | with the module system. Use @code{eval} or | |
1098 | @code{primitive-eval} instead. | |
1099 | @end deffn | |
1100 | ||
1101 | \feval-options-interface | |
89d04205 | 1102 | @c snarfed from eval.c:1697 |
780ee65e NJ |
1103 | @deffn primitive eval-options-interface [setting] |
1104 | Option interface for the evaluation options. Instead of using | |
1105 | this procedure directly, use the procedures @code{eval-enable}, | |
1106 | @code{eval-disable}, @code{eval-set!} and @var{eval-options}. | |
1107 | @end deffn | |
1108 | ||
1109 | \fevaluator-traps-interface | |
89d04205 | 1110 | @c snarfed from eval.c:1714 |
780ee65e NJ |
1111 | @deffn primitive evaluator-traps-interface [setting] |
1112 | Option interface for the evaluator trap options. | |
1113 | @end deffn | |
1114 | ||
1115 | \fdefined? | |
1116 | @c snarfed from evalext.c:74 | |
1117 | @deffn primitive defined? sym [env] | |
1118 | Return @code{#t} if @var{sym} is defined in the top-level environment. | |
1119 | @end deffn | |
1120 | ||
1121 | \fmap-in-order | |
1122 | @c snarfed from evalext.c:146 | |
1123 | @deffn primitive map-in-order | |
1124 | scm_map | |
1125 | @end deffn | |
1126 | ||
1127 | \fprogram-arguments | |
1128 | @c snarfed from feature.c:79 | |
1129 | @deffn primitive program-arguments | |
1130 | @deffnx procedure command-line | |
1131 | Return the list of command line arguments passed to Guile, as a list of | |
1132 | strings. The list includes the invoked program name, which is usually | |
1133 | @code{"guile"}, but excludes switches and parameters for command line | |
1134 | options like @code{-e} and @code{-l}. | |
1135 | @end deffn | |
1136 | ||
1137 | \fchown | |
1138 | @c snarfed from filesys.c:140 | |
1139 | @deffn primitive chown object owner group | |
1140 | Change the ownership and group of the file referred to by @var{object} to | |
1141 | the integer values @var{owner} and @var{group}. @var{object} can be | |
1142 | a string containing a file name or, if the platform | |
1143 | supports fchown, a port or integer file descriptor | |
1144 | which is open on the file. The return value | |
1145 | is unspecified. | |
1146 | ||
1147 | If @var{object} is a symbolic link, either the | |
1148 | ownership of the link or the ownership of the referenced file will be | |
1149 | changed depending on the operating system (lchown is | |
1150 | unsupported at present). If @var{owner} or @var{group} is specified | |
1151 | as @code{-1}, then that ID is not changed. | |
1152 | @end deffn | |
1153 | ||
1154 | \fchmod | |
1155 | @c snarfed from filesys.c:180 | |
1156 | @deffn primitive chmod object mode | |
1157 | Changes the permissions of the file referred to by @var{obj}. | |
1158 | @var{obj} can be a string containing a file name or a port or integer file | |
1159 | descriptor which is open on a file (in which case @code{fchmod} is used | |
1160 | as the underlying system call). | |
1161 | @var{mode} specifies | |
1162 | the new permissions as a decimal number, e.g., @code{(chmod "foo" #o755)}. | |
1163 | The return value is unspecified. | |
1164 | @end deffn | |
1165 | ||
1166 | \fumask | |
1167 | @c snarfed from filesys.c:214 | |
1168 | @deffn primitive umask [mode] | |
1169 | If @var{mode} is omitted, retuns a decimal number representing the current | |
1170 | file creation mask. Otherwise the file creation mask is set to | |
1171 | @var{mode} and the previous value is returned. | |
1172 | ||
1173 | E.g., @code{(umask #o022)} sets the mask to octal 22, decimal 18. | |
1174 | @end deffn | |
1175 | ||
1176 | \fopen-fdes | |
1177 | @c snarfed from filesys.c:237 | |
1178 | @deffn primitive open-fdes path flags [mode] | |
ae9f3a15 MG |
1179 | Similar to @code{open} but return a file descriptor instead of |
1180 | a port. | |
780ee65e NJ |
1181 | @end deffn |
1182 | ||
1183 | \fopen | |
1184 | @c snarfed from filesys.c:280 | |
1185 | @deffn primitive open path flags [mode] | |
1186 | Open the file named by @var{path} for reading and/or writing. | |
1187 | @var{flags} is an integer specifying how the file should be opened. | |
1188 | @var{mode} is an integer specifying the permission bits of the file, if | |
1189 | it needs to be created, before the umask is applied. The default is 666 | |
1190 | (Unix itself has no default). | |
1191 | ||
1192 | @var{flags} can be constructed by combining variables using @code{logior}. | |
1193 | Basic flags are: | |
1194 | ||
1195 | @defvar O_RDONLY | |
1196 | Open the file read-only. | |
1197 | @end defvar | |
1198 | @defvar O_WRONLY | |
1199 | Open the file write-only. | |
1200 | @end defvar | |
1201 | @defvar O_RDWR | |
1202 | Open the file read/write. | |
1203 | @end defvar | |
1204 | @defvar O_APPEND | |
1205 | Append to the file instead of truncating. | |
1206 | @end defvar | |
1207 | @defvar O_CREAT | |
1208 | Create the file if it does not already exist. | |
1209 | @end defvar | |
1210 | ||
1211 | See the Unix documentation of the @code{open} system call | |
1212 | for additional flags. | |
1213 | @end deffn | |
1214 | ||
1215 | \fclose | |
1216 | @c snarfed from filesys.c:318 | |
1217 | @deffn primitive close fd_or_port | |
1218 | Similar to close-port (@pxref{Generic Port Operations, close-port}), | |
1219 | but also works on file descriptors. A side | |
1220 | effect of closing a file descriptor is that any ports using that file | |
1221 | descriptor are moved to a different file descriptor and have | |
1222 | their revealed counts set to zero. | |
1223 | @end deffn | |
1224 | ||
1225 | \fclose-fdes | |
1226 | @c snarfed from filesys.c:346 | |
1227 | @deffn primitive close-fdes fd | |
1228 | A simple wrapper for the @code{close} system call. | |
1229 | Close file descriptor @var{fd}, which must be an integer. | |
1230 | Unlike close (@pxref{Ports and File Descriptors, close}), | |
1231 | the file descriptor will be closed even if a port is using it. | |
1232 | The return value is unspecified. | |
1233 | @end deffn | |
1234 | ||
1235 | \fstat | |
89d04205 | 1236 | @c snarfed from filesys.c:524 |
780ee65e | 1237 | @deffn primitive stat object |
ae9f3a15 MG |
1238 | Return an object containing various information about the file |
1239 | determined by @var{obj}. @var{obj} can be a string containing | |
1240 | a file name or a port or integer file descriptor which is open | |
1241 | on a file (in which case @code{fstat} is used as the underlying | |
1242 | system call). | |
7a095584 | 1243 | |
ae9f3a15 MG |
1244 | The object returned by @code{stat} can be passed as a single |
1245 | parameter to the following procedures, all of which return | |
1246 | integers: | |
7a095584 | 1247 | |
780ee65e NJ |
1248 | @table @code |
1249 | @item stat:dev | |
1250 | The device containing the file. | |
1251 | @item stat:ino | |
ae9f3a15 MG |
1252 | The file serial number, which distinguishes this file from all |
1253 | other files on the same device. | |
780ee65e | 1254 | @item stat:mode |
ae9f3a15 MG |
1255 | The mode of the file. This includes file type information and |
1256 | the file permission bits. See @code{stat:type} and | |
1257 | @code{stat:perms} below. | |
780ee65e NJ |
1258 | @item stat:nlink |
1259 | The number of hard links to the file. | |
1260 | @item stat:uid | |
1261 | The user ID of the file's owner. | |
1262 | @item stat:gid | |
1263 | The group ID of the file. | |
1264 | @item stat:rdev | |
1265 | Device ID; this entry is defined only for character or block | |
1266 | special files. | |
1267 | @item stat:size | |
1268 | The size of a regular file in bytes. | |
1269 | @item stat:atime | |
1270 | The last access time for the file. | |
1271 | @item stat:mtime | |
1272 | The last modification time for the file. | |
1273 | @item stat:ctime | |
1274 | The last modification time for the attributes of the file. | |
1275 | @item stat:blksize | |
ae9f3a15 MG |
1276 | The optimal block size for reading or writing the file, in |
1277 | bytes. | |
780ee65e | 1278 | @item stat:blocks |
ae9f3a15 MG |
1279 | The amount of disk space that the file occupies measured in |
1280 | units of 512 byte blocks. | |
780ee65e | 1281 | @end table |
7a095584 | 1282 | |
780ee65e NJ |
1283 | In addition, the following procedures return the information |
1284 | from stat:mode in a more convenient form: | |
7a095584 | 1285 | |
780ee65e NJ |
1286 | @table @code |
1287 | @item stat:type | |
1288 | A symbol representing the type of file. Possible values are | |
ae9f3a15 MG |
1289 | regular, directory, symlink, block-special, char-special, fifo, |
1290 | socket and unknown | |
780ee65e NJ |
1291 | @item stat:perms |
1292 | An integer representing the access permission bits. | |
1293 | @end table | |
1294 | @end deffn | |
1295 | ||
1296 | \flink | |
89d04205 | 1297 | @c snarfed from filesys.c:570 |
780ee65e NJ |
1298 | @deffn primitive link oldpath newpath |
1299 | Creates a new name @var{newpath} in the file system for the | |
1300 | file named by @var{oldpath}. If @var{oldpath} is a symbolic | |
1301 | link, the link may or may not be followed depending on the | |
1302 | system. | |
1303 | @end deffn | |
1304 | ||
1305 | \frename-file | |
89d04205 | 1306 | @c snarfed from filesys.c:592 |
780ee65e NJ |
1307 | @deffn primitive rename-file oldname newname |
1308 | Renames the file specified by @var{oldname} to @var{newname}. | |
1309 | The return value is unspecified. | |
1310 | @end deffn | |
1311 | ||
1312 | \fdelete-file | |
89d04205 | 1313 | @c snarfed from filesys.c:621 |
780ee65e NJ |
1314 | @deffn primitive delete-file str |
1315 | Deletes (or "unlinks") the file specified by @var{path}. | |
1316 | @end deffn | |
1317 | ||
1318 | \fmkdir | |
89d04205 | 1319 | @c snarfed from filesys.c:640 |
780ee65e NJ |
1320 | @deffn primitive mkdir path [mode] |
1321 | Create a new directory named by @var{path}. If @var{mode} is omitted | |
1322 | then the permissions of the directory file are set using the current | |
1323 | umask. Otherwise they are set to the decimal value specified with | |
1324 | @var{mode}. The return value is unspecified. | |
1325 | @end deffn | |
1326 | ||
1327 | \frmdir | |
89d04205 | 1328 | @c snarfed from filesys.c:669 |
780ee65e NJ |
1329 | @deffn primitive rmdir path |
1330 | Remove the existing directory named by @var{path}. The directory must | |
1331 | be empty for this to succeed. The return value is unspecified. | |
1332 | @end deffn | |
1333 | ||
1334 | \fdirectory-stream? | |
89d04205 | 1335 | @c snarfed from filesys.c:695 |
780ee65e | 1336 | @deffn primitive directory-stream? obj |
ae9f3a15 MG |
1337 | Return a boolean indicating whether @var{object} is a directory |
1338 | stream as returned by @code{opendir}. | |
780ee65e NJ |
1339 | @end deffn |
1340 | ||
1341 | \fopendir | |
89d04205 | 1342 | @c snarfed from filesys.c:706 |
780ee65e NJ |
1343 | @deffn primitive opendir dirname |
1344 | Open the directory specified by @var{path} and return a directory | |
1345 | stream. | |
1346 | @end deffn | |
1347 | ||
1348 | \freaddir | |
89d04205 | 1349 | @c snarfed from filesys.c:724 |
780ee65e NJ |
1350 | @deffn primitive readdir port |
1351 | Return (as a string) the next directory entry from the directory stream | |
1352 | @var{stream}. If there is no remaining entry to be read then the | |
1353 | end of file object is returned. | |
1354 | @end deffn | |
1355 | ||
1356 | \frewinddir | |
89d04205 | 1357 | @c snarfed from filesys.c:747 |
780ee65e NJ |
1358 | @deffn primitive rewinddir port |
1359 | Reset the directory port @var{stream} so that the next call to | |
1360 | @code{readdir} will return the first directory entry. | |
1361 | @end deffn | |
1362 | ||
1363 | \fclosedir | |
89d04205 | 1364 | @c snarfed from filesys.c:764 |
780ee65e NJ |
1365 | @deffn primitive closedir port |
1366 | Close the directory stream @var{stream}. | |
1367 | The return value is unspecified. | |
1368 | @end deffn | |
1369 | ||
1370 | \fchdir | |
89d04205 | 1371 | @c snarfed from filesys.c:814 |
780ee65e NJ |
1372 | @deffn primitive chdir str |
1373 | Change the current working directory to @var{path}. | |
1374 | The return value is unspecified. | |
1375 | @end deffn | |
1376 | ||
1377 | \fgetcwd | |
89d04205 | 1378 | @c snarfed from filesys.c:831 |
780ee65e | 1379 | @deffn primitive getcwd |
ae9f3a15 | 1380 | Return the name of the current working directory. |
780ee65e NJ |
1381 | @end deffn |
1382 | ||
1383 | \fselect | |
89d04205 | 1384 | @c snarfed from filesys.c:1028 |
780ee65e NJ |
1385 | @deffn primitive select reads writes excepts [secs [usecs]] |
1386 | This procedure has a variety of uses: waiting for the ability | |
1387 | to provide input, accept output, or the existance of | |
1388 | exceptional conditions on a collection of ports or file | |
1389 | descriptors, or waiting for a timeout to occur. | |
1390 | It also returns if interrupted by a signal. | |
1391 | ||
1392 | @var{reads}, @var{writes} and @var{excepts} can be lists or | |
1393 | vectors, with each member a port or a file descriptor. | |
1394 | The value returned is a list of three corresponding | |
1395 | lists or vectors containing only the members which meet the | |
1396 | specified requirement. The ability of port buffers to | |
1397 | provide input or accept output is taken into account. | |
1398 | Ordering of the input lists or vectors is not preserved. | |
1399 | ||
1400 | The optional arguments @var{secs} and @var{usecs} specify the | |
1401 | timeout. Either @var{secs} can be specified alone, as | |
1402 | either an integer or a real number, or both @var{secs} and | |
1403 | @var{usecs} can be specified as integers, in which case | |
1404 | @var{usecs} is an additional timeout expressed in | |
1405 | microseconds. If @var{secs} is omitted or is @code{#f} then | |
1406 | select will wait for as long as it takes for one of the other | |
1407 | conditions to be satisfied. | |
1408 | ||
1409 | The scsh version of @code{select} differs as follows: | |
1410 | Only vectors are accepted for the first three arguments. | |
1411 | The @var{usecs} argument is not supported. | |
1412 | Multiple values are returned instead of a list. | |
1413 | Duplicates in the input vectors appear only once in output. | |
1414 | An additional @code{select!} interface is provided. | |
1415 | @end deffn | |
1416 | ||
1417 | \ffcntl | |
89d04205 | 1418 | @c snarfed from filesys.c:1173 |
780ee65e NJ |
1419 | @deffn primitive fcntl object cmd [value] |
1420 | Apply @var{command} to the specified file descriptor or the underlying | |
1421 | file descriptor of the specified port. @var{value} is an optional | |
1422 | integer argument. | |
1423 | ||
1424 | Values for @var{command} are: | |
1425 | ||
1426 | @table @code | |
1427 | @item F_DUPFD | |
1428 | Duplicate a file descriptor | |
1429 | @item F_GETFD | |
1430 | Get flags associated with the file descriptor. | |
1431 | @item F_SETFD | |
1432 | Set flags associated with the file descriptor to @var{value}. | |
1433 | @item F_GETFL | |
1434 | Get flags associated with the open file. | |
1435 | @item F_SETFL | |
1436 | Set flags associated with the open file to @var{value} | |
1437 | @item F_GETOWN | |
1438 | Get the process ID of a socket's owner, for @code{SIGIO} signals. | |
1439 | @item F_SETOWN | |
1440 | Set the process that owns a socket to @var{value}, for @code{SIGIO} signals. | |
1441 | @item FD_CLOEXEC | |
1442 | The value used to indicate the "close on exec" flag with @code{F_GETFL} or | |
1443 | @code{F_SETFL}. | |
1444 | @end table | |
1445 | @end deffn | |
1446 | ||
1447 | \ffsync | |
89d04205 | 1448 | @c snarfed from filesys.c:1209 |
780ee65e NJ |
1449 | @deffn primitive fsync object |
1450 | Copies any unwritten data for the specified output file descriptor to disk. | |
1451 | If @var{port/fd} is a port, its buffer is flushed before the underlying | |
1452 | file descriptor is fsync'd. | |
1453 | The return value is unspecified. | |
1454 | @end deffn | |
1455 | ||
1456 | \fsymlink | |
89d04205 | 1457 | @c snarfed from filesys.c:1236 |
780ee65e NJ |
1458 | @deffn primitive symlink oldpath newpath |
1459 | Create a symbolic link named @var{path-to} with the value (i.e., pointing to) | |
1460 | @var{path-from}. The return value is unspecified. | |
1461 | @end deffn | |
1462 | ||
1463 | \freadlink | |
89d04205 | 1464 | @c snarfed from filesys.c:1257 |
780ee65e | 1465 | @deffn primitive readlink path |
ae9f3a15 MG |
1466 | Return the value of the symbolic link named by @var{path} (a |
1467 | string), i.e., the file that the link points to. | |
780ee65e NJ |
1468 | @end deffn |
1469 | ||
1470 | \flstat | |
89d04205 | 1471 | @c snarfed from filesys.c:1287 |
780ee65e NJ |
1472 | @deffn primitive lstat str |
1473 | Similar to @code{stat}, but does not follow symbolic links, i.e., | |
1474 | it will return information about a symbolic link itself, not the | |
1475 | file it points to. @var{path} must be a string. | |
1476 | @end deffn | |
1477 | ||
1478 | \fcopy-file | |
89d04205 | 1479 | @c snarfed from filesys.c:1312 |
780ee65e NJ |
1480 | @deffn primitive copy-file oldfile newfile |
1481 | Copy the file specified by @var{path-from} to @var{path-to}. | |
1482 | The return value is unspecified. | |
1483 | @end deffn | |
1484 | ||
1485 | \fdirname | |
89d04205 | 1486 | @c snarfed from filesys.c:1359 |
780ee65e NJ |
1487 | @deffn primitive dirname filename |
1488 | Return the directory name component of the file name | |
1489 | @var{filename}. If @var{filename} does not contain a directory | |
1490 | component, @code{.} is returned. | |
1491 | @end deffn | |
1492 | ||
1493 | \fbasename | |
89d04205 | 1494 | @c snarfed from filesys.c:1392 |
780ee65e NJ |
1495 | @deffn primitive basename filename [suffix] |
1496 | Return the base name of the file name @var{filename}. The | |
1497 | base name is the file name without any directory components. | |
1498 | If @var{suffix} is privided, and is equal to the end of | |
1499 | @var{basename}, it is removed also. | |
1500 | @end deffn | |
1501 | ||
1502 | \fmake-fluid | |
72ad43dc | 1503 | @c snarfed from fluids.c:124 |
780ee65e NJ |
1504 | @deffn primitive make-fluid |
1505 | Return a newly created fluid. | |
1506 | Fluids are objects of a certain type (a smob) that can hold one SCM | |
1507 | value per dynamic root. That is, modifications to this value are | |
1508 | only visible to code that executes within the same dynamic root as | |
1509 | the modifying code. When a new dynamic root is constructed, it | |
1510 | inherits the values from its parent. Because each thread executes | |
1511 | in its own dynamic root, you can use fluids for thread local storage. | |
1512 | @end deffn | |
1513 | ||
1514 | \ffluid? | |
72ad43dc | 1515 | @c snarfed from fluids.c:137 |
780ee65e | 1516 | @deffn primitive fluid? obj |
ae9f3a15 MG |
1517 | Return @code{#t} iff @var{obj} is a fluid; otherwise, return |
1518 | @code{#f}. | |
780ee65e NJ |
1519 | @end deffn |
1520 | ||
1521 | \ffluid-ref | |
72ad43dc | 1522 | @c snarfed from fluids.c:148 |
780ee65e | 1523 | @deffn primitive fluid-ref fluid |
ae9f3a15 MG |
1524 | Return the value associated with @var{fluid} in the current |
1525 | dynamic root. If @var{fluid} has not been set, then return | |
1526 | @code{#f}. | |
780ee65e NJ |
1527 | @end deffn |
1528 | ||
1529 | \ffluid-set! | |
72ad43dc | 1530 | @c snarfed from fluids.c:165 |
780ee65e NJ |
1531 | @deffn primitive fluid-set! fluid value |
1532 | Set the value associated with @var{fluid} in the current dynamic root. | |
1533 | @end deffn | |
1534 | ||
1535 | \fwith-fluids* | |
72ad43dc | 1536 | @c snarfed from fluids.c:224 |
780ee65e NJ |
1537 | @deffn primitive with-fluids* fluids values thunk |
1538 | Set @var{fluids} to @var{values} temporary, and call @var{thunk}. | |
1539 | @var{fluids} must be a list of fluids and @var{values} must be the same | |
1540 | number of their values to be applied. Each substitution is done | |
1541 | one after another. @var{thunk} must be a procedure with no argument. | |
1542 | @end deffn | |
1543 | ||
1544 | \fsetvbuf | |
1545 | @c snarfed from fports.c:148 | |
1546 | @deffn primitive setvbuf port mode [size] | |
1547 | Set the buffering mode for @var{port}. @var{mode} can be: | |
1548 | @table @code | |
1549 | @item _IONBF | |
1550 | non-buffered | |
1551 | @item _IOLBF | |
1552 | line buffered | |
1553 | @item _IOFBF | |
1554 | block buffered, using a newly allocated buffer of @var{size} bytes. | |
1555 | If @var{size} is omitted, a default size will be used. | |
1556 | @end table | |
1557 | @end deffn | |
1558 | ||
1559 | \ffile-port? | |
1560 | @c snarfed from fports.c:229 | |
1561 | @deffn primitive file-port? obj | |
1562 | Determine whether @var{obj} is a port that is related to a file. | |
1563 | @end deffn | |
1564 | ||
1565 | \fopen-file | |
89d04205 | 1566 | @c snarfed from fports.c:283 |
ae9f3a15 MG |
1567 | @deffn primitive open-file filename mode |
1568 | Open the file whose name is @var{filename}, and return a port | |
780ee65e | 1569 | representing that file. The attributes of the port are |
ae9f3a15 MG |
1570 | determined by the @var{mode} string. The way in which this is |
1571 | interpreted is similar to C stdio. The first character must be | |
1572 | one of the following: | |
780ee65e NJ |
1573 | @table @samp |
1574 | @item r | |
1575 | Open an existing file for input. | |
1576 | @item w | |
1577 | Open a file for output, creating it if it doesn't already exist | |
1578 | or removing its contents if it does. | |
1579 | @item a | |
ae9f3a15 MG |
1580 | Open a file for output, creating it if it doesn't already |
1581 | exist. All writes to the port will go to the end of the file. | |
780ee65e NJ |
1582 | The "append mode" can be turned off while the port is in use |
1583 | @pxref{Ports and File Descriptors, fcntl} | |
1584 | @end table | |
780ee65e | 1585 | The following additional characters can be appended: |
780ee65e NJ |
1586 | @table @samp |
1587 | @item + | |
1588 | Open the port for both input and output. E.g., @code{r+}: open | |
1589 | an existing file for both input and output. | |
1590 | @item 0 | |
ae9f3a15 MG |
1591 | Create an "unbuffered" port. In this case input and output |
1592 | operations are passed directly to the underlying port | |
1593 | implementation without additional buffering. This is likely to | |
1594 | slow down I/O operations. The buffering mode can be changed | |
1595 | while a port is in use @pxref{Ports and File Descriptors, | |
1596 | setvbuf} | |
780ee65e NJ |
1597 | @item l |
1598 | Add line-buffering to the port. The port output buffer will be | |
1599 | automatically flushed whenever a newline character is written. | |
1600 | @end table | |
ae9f3a15 MG |
1601 | In theory we could create read/write ports which were buffered |
1602 | in one direction only. However this isn't included in the | |
1603 | current interfaces. If a file cannot be opened with the access | |
1604 | requested, @code{open-file} throws an exception. | |
780ee65e NJ |
1605 | @end deffn |
1606 | ||
1607 | \fgc-stats | |
89d04205 | 1608 | @c snarfed from gc.c:749 |
780ee65e | 1609 | @deffn primitive gc-stats |
ae9f3a15 MG |
1610 | Return an association list of statistics about Guile's current |
1611 | use of storage. | |
780ee65e NJ |
1612 | @end deffn |
1613 | ||
1614 | \fobject-address | |
89d04205 | 1615 | @c snarfed from gc.c:846 |
780ee65e NJ |
1616 | @deffn primitive object-address obj |
1617 | Return an integer that for the lifetime of @var{obj} is uniquely | |
1618 | returned by this function for @var{obj} | |
1619 | @end deffn | |
1620 | ||
1621 | \fgc | |
89d04205 | 1622 | @c snarfed from gc.c:857 |
780ee65e NJ |
1623 | @deffn primitive gc |
1624 | Scans all of SCM objects and reclaims for further use those that are | |
1625 | no longer accessible. | |
1626 | @end deffn | |
1627 | ||
1628 | \funhash-name | |
72ad43dc | 1629 | @c snarfed from gc.c:2306 |
780ee65e NJ |
1630 | @deffn primitive unhash-name name |
1631 | Flushes the glocs for @var{name}, or all glocs if @var{name} | |
1632 | is @code{#t}. | |
1633 | @end deffn | |
1634 | ||
1635 | \f%compute-slots | |
1636 | @c snarfed from goops.c:290 | |
1637 | @deffn primitive %compute-slots class | |
1638 | Return a list consisting of the names of all slots belonging to | |
1639 | class @var{class}, i. e. the slots of @var{class} and of all of | |
1640 | its superclasses. | |
1641 | @end deffn | |
1642 | ||
1643 | \fget-keyword | |
1644 | @c snarfed from goops.c:375 | |
1645 | @deffn primitive get-keyword key l default_value | |
1646 | Determine an associated value for the keyword @var{key} from | |
1647 | the list @var{l}. The list @var{l} has to consist of an even | |
1648 | number of elements, where, starting with the first, every | |
1649 | second element is a keyword, followed by its associated value. | |
1650 | If @var{l} does not hold a value for @var{key}, the value | |
1651 | @var{default_value} is returned. | |
1652 | @end deffn | |
1653 | ||
1654 | \f%initialize-object | |
1655 | @c snarfed from goops.c:398 | |
1656 | @deffn primitive %initialize-object obj initargs | |
1657 | Initialize the object @var{obj} with the given arguments | |
1658 | @var{initargs}. | |
1659 | @end deffn | |
1660 | ||
1661 | \f%prep-layout! | |
1662 | @c snarfed from goops.c:479 | |
1663 | @deffn primitive %prep-layout! class | |
1664 | @end deffn | |
1665 | ||
1666 | \f%inherit-magic! | |
1667 | @c snarfed from goops.c:542 | |
1668 | @deffn primitive %inherit-magic! class dsupers | |
1669 | @end deffn | |
1670 | ||
1671 | \finstance? | |
1672 | @c snarfed from goops.c:783 | |
1673 | @deffn primitive instance? obj | |
1674 | Return @code{#t} if @var{obj} is an instance. | |
1675 | @end deffn | |
1676 | ||
1677 | \fclass-name | |
1678 | @c snarfed from goops.c:798 | |
1679 | @deffn primitive class-name obj | |
1680 | Return the class name of @var{obj}. | |
1681 | @end deffn | |
1682 | ||
1683 | \fclass-direct-supers | |
1684 | @c snarfed from goops.c:808 | |
1685 | @deffn primitive class-direct-supers obj | |
1686 | Return the direct superclasses of the class @var{obj}. | |
1687 | @end deffn | |
1688 | ||
1689 | \fclass-direct-slots | |
1690 | @c snarfed from goops.c:818 | |
1691 | @deffn primitive class-direct-slots obj | |
1692 | Return the direct slots of the class @var{obj}. | |
1693 | @end deffn | |
1694 | ||
1695 | \fclass-direct-subclasses | |
1696 | @c snarfed from goops.c:828 | |
1697 | @deffn primitive class-direct-subclasses obj | |
1698 | Return the direct subclasses of the class @var{obj}. | |
1699 | @end deffn | |
1700 | ||
1701 | \fclass-direct-methods | |
1702 | @c snarfed from goops.c:838 | |
1703 | @deffn primitive class-direct-methods obj | |
1704 | Return the direct methods of the class @var{obj} | |
1705 | @end deffn | |
1706 | ||
1707 | \fclass-precedence-list | |
1708 | @c snarfed from goops.c:848 | |
1709 | @deffn primitive class-precedence-list obj | |
1710 | Return the class precedence list of the class @var{obj}. | |
1711 | @end deffn | |
1712 | ||
1713 | \fclass-slots | |
1714 | @c snarfed from goops.c:858 | |
1715 | @deffn primitive class-slots obj | |
1716 | Return the slot list of the class @var{obj}. | |
1717 | @end deffn | |
1718 | ||
1719 | \fclass-environment | |
1720 | @c snarfed from goops.c:868 | |
1721 | @deffn primitive class-environment obj | |
1722 | Return the environment of the class @var{obj}. | |
1723 | @end deffn | |
1724 | ||
1725 | \fgeneric-function-name | |
1726 | @c snarfed from goops.c:879 | |
1727 | @deffn primitive generic-function-name obj | |
1728 | Return the name of the generic function @var{obj}. | |
1729 | @end deffn | |
1730 | ||
1731 | \fgeneric-function-methods | |
1732 | @c snarfed from goops.c:889 | |
1733 | @deffn primitive generic-function-methods obj | |
1734 | Return the methods of the generic function @var{obj}. | |
1735 | @end deffn | |
1736 | ||
1737 | \fmethod-generic-function | |
1738 | @c snarfed from goops.c:900 | |
1739 | @deffn primitive method-generic-function obj | |
1740 | Return the generic function fot the method @var{obj}. | |
1741 | @end deffn | |
1742 | ||
1743 | \fmethod-specializers | |
1744 | @c snarfed from goops.c:910 | |
1745 | @deffn primitive method-specializers obj | |
1746 | Return specializers of the method @var{obj}. | |
1747 | @end deffn | |
1748 | ||
1749 | \fmethod-procedure | |
1750 | @c snarfed from goops.c:920 | |
1751 | @deffn primitive method-procedure obj | |
1752 | Return the procedure of the method @var{obj}. | |
1753 | @end deffn | |
1754 | ||
1755 | \faccessor-method-slot-definition | |
1756 | @c snarfed from goops.c:930 | |
1757 | @deffn primitive accessor-method-slot-definition obj | |
1758 | Return the slot definition of the accessor @var{obj}. | |
1759 | @end deffn | |
1760 | ||
1761 | \f%tag-body | |
1762 | @c snarfed from goops.c:940 | |
1763 | @deffn primitive %tag-body body | |
1764 | Internal GOOPS magic---don't use this function! | |
1765 | @end deffn | |
1766 | ||
1767 | \fmake-unbound | |
1768 | @c snarfed from goops.c:955 | |
1769 | @deffn primitive make-unbound | |
1770 | Return the unbound value. | |
1771 | @end deffn | |
1772 | ||
1773 | \funbound? | |
1774 | @c snarfed from goops.c:964 | |
1775 | @deffn primitive unbound? obj | |
1776 | Return @code{#t} if @var{obj} is unbound. | |
1777 | @end deffn | |
1778 | ||
1779 | \fassert-bound | |
1780 | @c snarfed from goops.c:974 | |
1781 | @deffn primitive assert-bound value obj | |
1782 | Return @var{value} if it is bound, and invoke the | |
1783 | @var{slot-unbound} method of @var{obj} if it is not. | |
1784 | @end deffn | |
1785 | ||
1786 | \f@@assert-bound-ref | |
1787 | @c snarfed from goops.c:986 | |
1788 | @deffn primitive @@assert-bound-ref obj index | |
1789 | Like @code{assert-bound}, but use @var{index} for accessing | |
1790 | the value from @var{obj}. | |
1791 | @end deffn | |
1792 | ||
1793 | \f%fast-slot-ref | |
1794 | @c snarfed from goops.c:998 | |
1795 | @deffn primitive %fast-slot-ref obj index | |
1796 | Return the slot value with index @var{index} from @var{obj}. | |
1797 | @end deffn | |
1798 | ||
1799 | \f%fast-slot-set! | |
1800 | @c snarfed from goops.c:1015 | |
1801 | @deffn primitive %fast-slot-set! obj index value | |
1802 | Set the slot with index @var{index} in @var{obj} to | |
1803 | @var{value}. | |
1804 | @end deffn | |
1805 | ||
1806 | \fslot-ref-using-class | |
1807 | @c snarfed from goops.c:1143 | |
1808 | @deffn primitive slot-ref-using-class class obj slot_name | |
1809 | @end deffn | |
1810 | ||
1811 | \fslot-set-using-class! | |
1812 | @c snarfed from goops.c:1162 | |
1813 | @deffn primitive slot-set-using-class! class obj slot_name value | |
1814 | @end deffn | |
1815 | ||
1816 | \fslot-bound-using-class? | |
1817 | @c snarfed from goops.c:1176 | |
1818 | @deffn primitive slot-bound-using-class? class obj slot_name | |
1819 | @end deffn | |
1820 | ||
1821 | \fslot-exists-using-class? | |
1822 | @c snarfed from goops.c:1191 | |
1823 | @deffn primitive slot-exists-using-class? class obj slot_name | |
1824 | @end deffn | |
1825 | ||
1826 | \fslot-ref | |
1827 | @c snarfed from goops.c:1207 | |
1828 | @deffn primitive slot-ref obj slot_name | |
1829 | Return the value from @var{obj}'s slot with the name | |
1830 | @var{slot_name}. | |
1831 | @end deffn | |
1832 | ||
1833 | \fslot-set! | |
1834 | @c snarfed from goops.c:1224 | |
1835 | @deffn primitive slot-set! obj slot_name value | |
1836 | Set the slot named @var{slot_name} of @var{obj} to @var{value}. | |
1837 | @end deffn | |
1838 | ||
1839 | \fslot-bound? | |
1840 | @c snarfed from goops.c:1241 | |
1841 | @deffn primitive slot-bound? obj slot_name | |
1842 | Return @code{#t} if the slot named @var{slot_name} of @var{obj} | |
1843 | is bound. | |
1844 | @end deffn | |
1845 | ||
1846 | \fslot-exists? | |
1847 | @c snarfed from goops.c:1259 | |
1848 | @deffn primitive slot-exists? obj slot_name | |
1849 | Return @code{#t} if @var{obj} has a slot named @var{slot_name}. | |
1850 | @end deffn | |
1851 | ||
1852 | \f%allocate-instance | |
1853 | @c snarfed from goops.c:1302 | |
1854 | @deffn primitive %allocate-instance class initargs | |
1855 | Create a new instance of class @var{class} and initialize it | |
1856 | from the arguments @var{initargs}. | |
1857 | @end deffn | |
1858 | ||
1859 | \f%set-object-setter! | |
1860 | @c snarfed from goops.c:1375 | |
1861 | @deffn primitive %set-object-setter! obj setter | |
1862 | @end deffn | |
1863 | ||
1864 | \f%modify-instance | |
1865 | @c snarfed from goops.c:1400 | |
1866 | @deffn primitive %modify-instance old new | |
1867 | @end deffn | |
1868 | ||
1869 | \f%modify-class | |
1870 | @c snarfed from goops.c:1426 | |
1871 | @deffn primitive %modify-class old new | |
1872 | @end deffn | |
1873 | ||
1874 | \f%invalidate-class | |
1875 | @c snarfed from goops.c:1450 | |
1876 | @deffn primitive %invalidate-class class | |
1877 | @end deffn | |
1878 | ||
1879 | \f%invalidate-method-cache! | |
1880 | @c snarfed from goops.c:1571 | |
1881 | @deffn primitive %invalidate-method-cache! gf | |
1882 | @end deffn | |
1883 | ||
1884 | \fgeneric-capability? | |
1885 | @c snarfed from goops.c:1597 | |
1886 | @deffn primitive generic-capability? proc | |
1887 | @end deffn | |
1888 | ||
1889 | \fenable-primitive-generic! | |
1890 | @c snarfed from goops.c:1610 | |
1891 | @deffn primitive enable-primitive-generic! . subrs | |
1892 | @end deffn | |
1893 | ||
1894 | \fprimitive-generic-generic | |
1895 | @c snarfed from goops.c:1630 | |
1896 | @deffn primitive primitive-generic-generic subr | |
1897 | @end deffn | |
1898 | ||
1899 | \fmake | |
1900 | @c snarfed from goops.c:1989 | |
1901 | @deffn primitive make . args | |
1902 | Make a new object. @var{args} must contain the class and | |
1903 | all necessary initialization information. | |
1904 | @end deffn | |
1905 | ||
1906 | \ffind-method | |
1907 | @c snarfed from goops.c:2082 | |
1908 | @deffn primitive find-method . l | |
1909 | @end deffn | |
1910 | ||
1911 | \f%method-more-specific? | |
1912 | @c snarfed from goops.c:2102 | |
1913 | @deffn primitive %method-more-specific? m1 m2 targs | |
1914 | @end deffn | |
1915 | ||
1916 | \f%goops-loaded | |
1917 | @c snarfed from goops.c:2634 | |
1918 | @deffn primitive %goops-loaded | |
1919 | Announce that GOOPS is loaded and perform initialization | |
1920 | on the C level which depends on the loaded GOOPS modules. | |
1921 | @end deffn | |
1922 | ||
1923 | \fmake-guardian | |
1924 | @c snarfed from guardians.c:336 | |
1925 | @deffn primitive make-guardian [greedy_p] | |
1926 | Create a new guardian. | |
1927 | A guardian protects a set of objects from garbage collection, | |
1928 | allowing a program to apply cleanup or other actions. | |
1929 | ||
1930 | @code{make-guardian} returns a procedure representing the guardian. | |
1931 | Calling the guardian procedure with an argument adds the | |
1932 | argument to the guardian's set of protected objects. | |
1933 | Calling the guardian procedure without an argument returns | |
1934 | one of the protected objects which are ready for garbage | |
1935 | collection, or @code{#f} if no such object is available. | |
1936 | Objects which are returned in this way are removed from | |
1937 | the guardian. | |
1938 | ||
1939 | @code{make-guardian} takes one optional argument that says whether the | |
1940 | new guardian should be greedy or sharing. If there is any chance | |
1941 | that any object protected by the guardian may be resurrected, | |
1942 | then you should make the guardian greedy (this is the default). | |
1943 | ||
1944 | See R. Kent Dybvig, Carl Bruggeman, and David Eby (1993) | |
1945 | "Guardians in a Generation-Based Garbage Collector". | |
1946 | ACM SIGPLAN Conference on Programming Language Design | |
1947 | and Implementation, June 1993. | |
1948 | ||
1949 | (the semantics are slightly different at this point, but the | |
1950 | paper still (mostly) accurately describes the interface). | |
1951 | @end deffn | |
1952 | ||
1953 | \fguardian-destroyed? | |
1954 | @c snarfed from guardians.c:364 | |
1955 | @deffn primitive guardian-destroyed? guardian | |
1956 | Return @code{#t} if @var{guardian} has been destroyed, otherwise @code{#f}. | |
1957 | @end deffn | |
1958 | ||
1959 | \fguardian-greedy? | |
1960 | @c snarfed from guardians.c:382 | |
1961 | @deffn primitive guardian-greedy? guardian | |
1962 | Return @code{#t} if @var{guardian} is a greedy guardian, otherwise @code{#f}. | |
1963 | @end deffn | |
1964 | ||
1965 | \fdestroy-guardian! | |
1966 | @c snarfed from guardians.c:393 | |
1967 | @deffn primitive destroy-guardian! guardian | |
1968 | Destroys @var{guardian}, by making it impossible to put any more | |
1969 | objects in it or get any objects from it. It also unguards any | |
1970 | objects guarded by @var{guardian}. | |
1971 | @end deffn | |
1972 | ||
1973 | \fhashq | |
1974 | @c snarfed from hash.c:202 | |
1975 | @deffn primitive hashq key size | |
1976 | Determine a hash value for @var{key} that is suitable for | |
1977 | lookups in a hashtable of size @var{size}, where @code{eq?} is | |
1978 | used as the equality predicate. The function returns an | |
1979 | integer in the range 0 to @var{size} - 1. Note that | |
1980 | @code{hashq} may use internal addresses. Thus two calls to | |
1981 | hashq where the keys are @code{eq?} are not guaranteed to | |
1982 | deliver the same value if the key object gets garbage collected | |
1983 | in between. This can happen, for example with symbols: | |
1984 | @code{(hashq 'foo n) (gc) (hashq 'foo n)} may produce two | |
1985 | different values, since @code{foo} will be garbage collected. | |
1986 | @end deffn | |
1987 | ||
1988 | \fhashv | |
1989 | @c snarfed from hash.c:238 | |
1990 | @deffn primitive hashv key size | |
1991 | Determine a hash value for @var{key} that is suitable for | |
1992 | lookups in a hashtable of size @var{size}, where @code{eqv?} is | |
1993 | used as the equality predicate. The function returns an | |
1994 | integer in the range 0 to @var{size} - 1. Note that | |
1995 | @code{(hashv key)} may use internal addresses. Thus two calls | |
1996 | to hashv where the keys are @code{eqv?} are not guaranteed to | |
1997 | deliver the same value if the key object gets garbage collected | |
1998 | in between. This can happen, for example with symbols: | |
1999 | @code{(hashv 'foo n) (gc) (hashv 'foo n)} may produce two | |
2000 | different values, since @code{foo} will be garbage collected. | |
2001 | @end deffn | |
2002 | ||
2003 | \fhash | |
2004 | @c snarfed from hash.c:261 | |
2005 | @deffn primitive hash key size | |
2006 | Determine a hash value for @var{key} that is suitable for | |
2007 | lookups in a hashtable of size @var{size}, where @code{equal?} | |
2008 | is used as the equality predicate. The function returns an | |
2009 | integer in the range 0 to @var{size} - 1. | |
2010 | @end deffn | |
2011 | ||
2012 | \fhashq-get-handle | |
89d04205 | 2013 | @c snarfed from hashtab.c:173 |
ae9f3a15 MG |
2014 | @deffn primitive hashq-get-handle table key |
2015 | This procedure returns the @code{(key . value)} pair from the | |
2016 | hash table @var{table}. If @var{table} does not hold an | |
2017 | associated value for @var{key}, @code{#f} is returned. | |
2018 | Uses @code{eq?} for equality testing. | |
780ee65e NJ |
2019 | @end deffn |
2020 | ||
2021 | \fhashq-create-handle! | |
89d04205 | 2022 | @c snarfed from hashtab.c:185 |
780ee65e NJ |
2023 | @deffn primitive hashq-create-handle! table key init |
2024 | This function looks up @var{key} in @var{table} and returns its handle. | |
2025 | If @var{key} is not already present, a new handle is created which | |
2026 | associates @var{key} with @var{init}. | |
2027 | @end deffn | |
2028 | ||
2029 | \fhashq-ref | |
89d04205 | 2030 | @c snarfed from hashtab.c:198 |
ae9f3a15 | 2031 | @deffn primitive hashq-ref table key [dflt] |
780ee65e NJ |
2032 | Look up @var{key} in the hash table @var{table}, and return the |
2033 | value (if any) associated with it. If @var{key} is not found, | |
2034 | return @var{default} (or @code{#f} if no @var{default} argument | |
2035 | is supplied). Uses @code{eq?} for equality testing. | |
2036 | @end deffn | |
2037 | ||
2038 | \fhashq-set! | |
89d04205 | 2039 | @c snarfed from hashtab.c:212 |
ae9f3a15 | 2040 | @deffn primitive hashq-set! table key val |
780ee65e NJ |
2041 | Find the entry in @var{table} associated with @var{key}, and |
2042 | store @var{value} there. Uses @code{eq?} for equality testing. | |
2043 | @end deffn | |
2044 | ||
2045 | \fhashq-remove! | |
89d04205 | 2046 | @c snarfed from hashtab.c:224 |
ae9f3a15 | 2047 | @deffn primitive hashq-remove! table key |
780ee65e NJ |
2048 | Remove @var{key} (and any value associated with it) from |
2049 | @var{table}. Uses @code{eq?} for equality tests. | |
2050 | @end deffn | |
2051 | ||
2052 | \fhashv-get-handle | |
89d04205 | 2053 | @c snarfed from hashtab.c:240 |
ae9f3a15 MG |
2054 | @deffn primitive hashv-get-handle table key |
2055 | This procedure returns the @code{(key . value)} pair from the | |
2056 | hash table @var{table}. If @var{table} does not hold an | |
2057 | associated value for @var{key}, @code{#f} is returned. | |
2058 | Uses @code{eqv?} for equality testing. | |
780ee65e NJ |
2059 | @end deffn |
2060 | ||
2061 | \fhashv-create-handle! | |
89d04205 | 2062 | @c snarfed from hashtab.c:252 |
780ee65e NJ |
2063 | @deffn primitive hashv-create-handle! table key init |
2064 | This function looks up @var{key} in @var{table} and returns its handle. | |
2065 | If @var{key} is not already present, a new handle is created which | |
2066 | associates @var{key} with @var{init}. | |
2067 | @end deffn | |
2068 | ||
2069 | \fhashv-ref | |
89d04205 | 2070 | @c snarfed from hashtab.c:266 |
ae9f3a15 | 2071 | @deffn primitive hashv-ref table key [dflt] |
780ee65e NJ |
2072 | Look up @var{key} in the hash table @var{table}, and return the |
2073 | value (if any) associated with it. If @var{key} is not found, | |
2074 | return @var{default} (or @code{#f} if no @var{default} argument | |
2075 | is supplied). Uses @code{eqv?} for equality testing. | |
2076 | @end deffn | |
2077 | ||
2078 | \fhashv-set! | |
89d04205 | 2079 | @c snarfed from hashtab.c:280 |
ae9f3a15 | 2080 | @deffn primitive hashv-set! table key val |
780ee65e NJ |
2081 | Find the entry in @var{table} associated with @var{key}, and |
2082 | store @var{value} there. Uses @code{eqv?} for equality testing. | |
2083 | @end deffn | |
2084 | ||
2085 | \fhashv-remove! | |
89d04205 | 2086 | @c snarfed from hashtab.c:291 |
ae9f3a15 | 2087 | @deffn primitive hashv-remove! table key |
780ee65e NJ |
2088 | Remove @var{key} (and any value associated with it) from |
2089 | @var{table}. Uses @code{eqv?} for equality tests. | |
2090 | @end deffn | |
2091 | ||
2092 | \fhash-get-handle | |
89d04205 | 2093 | @c snarfed from hashtab.c:306 |
ae9f3a15 MG |
2094 | @deffn primitive hash-get-handle table key |
2095 | This procedure returns the @code{(key . value)} pair from the | |
2096 | hash table @var{table}. If @var{table} does not hold an | |
2097 | associated value for @var{key}, @code{#f} is returned. | |
2098 | Uses @code{equal?} for equality testing. | |
780ee65e NJ |
2099 | @end deffn |
2100 | ||
2101 | \fhash-create-handle! | |
89d04205 | 2102 | @c snarfed from hashtab.c:318 |
780ee65e NJ |
2103 | @deffn primitive hash-create-handle! table key init |
2104 | This function looks up @var{key} in @var{table} and returns its handle. | |
2105 | If @var{key} is not already present, a new handle is created which | |
2106 | associates @var{key} with @var{init}. | |
2107 | @end deffn | |
2108 | ||
2109 | \fhash-ref | |
89d04205 | 2110 | @c snarfed from hashtab.c:331 |
ae9f3a15 | 2111 | @deffn primitive hash-ref table key [dflt] |
780ee65e NJ |
2112 | Look up @var{key} in the hash table @var{table}, and return the |
2113 | value (if any) associated with it. If @var{key} is not found, | |
2114 | return @var{default} (or @code{#f} if no @var{default} argument | |
2115 | is supplied). Uses @code{equal?} for equality testing. | |
2116 | @end deffn | |
2117 | ||
2118 | \fhash-set! | |
89d04205 | 2119 | @c snarfed from hashtab.c:346 |
ae9f3a15 | 2120 | @deffn primitive hash-set! table key val |
780ee65e NJ |
2121 | Find the entry in @var{table} associated with @var{key}, and |
2122 | store @var{value} there. Uses @code{equal?} for equality | |
2123 | testing. | |
2124 | @end deffn | |
2125 | ||
2126 | \fhash-remove! | |
89d04205 | 2127 | @c snarfed from hashtab.c:358 |
ae9f3a15 | 2128 | @deffn primitive hash-remove! table key |
780ee65e NJ |
2129 | Remove @var{key} (and any value associated with it) from |
2130 | @var{table}. Uses @code{equal?} for equality tests. | |
2131 | @end deffn | |
2132 | ||
2133 | \fhashx-get-handle | |
89d04205 | 2134 | @c snarfed from hashtab.c:428 |
ae9f3a15 MG |
2135 | @deffn primitive hashx-get-handle hash assoc table key |
2136 | This behaves the same way as the corresponding | |
2137 | @code{-get-handle} function, but uses @var{hash} as a hash | |
2138 | function and @var{assoc} to compare keys. @code{hash} must be | |
2139 | a function that takes two arguments, a key to be hashed and a | |
780ee65e NJ |
2140 | table size. @code{assoc} must be an associator function, like |
2141 | @code{assoc}, @code{assq} or @code{assv}. | |
2142 | @end deffn | |
2143 | ||
2144 | \fhashx-create-handle! | |
2145 | @c snarfed from hashtab.c:447 | |
ae9f3a15 MG |
2146 | @deffn primitive hashx-create-handle! hash assoc table key init |
2147 | This behaves the same way as the corresponding | |
2148 | @code{-create-handle} function, but uses @var{hash} as a hash | |
2149 | function and @var{assoc} to compare keys. @code{hash} must be | |
2150 | a function that takes two arguments, a key to be hashed and a | |
780ee65e NJ |
2151 | table size. @code{assoc} must be an associator function, like |
2152 | @code{assoc}, @code{assq} or @code{assv}. | |
2153 | @end deffn | |
2154 | ||
2155 | \fhashx-ref | |
89d04205 | 2156 | @c snarfed from hashtab.c:470 |
ae9f3a15 | 2157 | @deffn primitive hashx-ref hash assoc table key [dflt] |
780ee65e | 2158 | This behaves the same way as the corresponding @code{ref} |
ae9f3a15 MG |
2159 | function, but uses @var{hash} as a hash function and |
2160 | @var{assoc} to compare keys. @code{hash} must be a function | |
2161 | that takes two arguments, a key to be hashed and a table size. | |
2162 | @code{assoc} must be an associator function, like @code{assoc}, | |
2163 | @code{assq} or @code{assv}. | |
7a095584 | 2164 | |
ae9f3a15 MG |
2165 | By way of illustration, @code{hashq-ref table key} is |
2166 | equivalent to @code{hashx-ref hashq assq table key}. | |
780ee65e NJ |
2167 | @end deffn |
2168 | ||
2169 | \fhashx-set! | |
89d04205 | 2170 | @c snarfed from hashtab.c:496 |
ae9f3a15 | 2171 | @deffn primitive hashx-set! hash assoc table key val |
780ee65e | 2172 | This behaves the same way as the corresponding @code{set!} |
ae9f3a15 MG |
2173 | function, but uses @var{hash} as a hash function and |
2174 | @var{assoc} to compare keys. @code{hash} must be a function | |
2175 | that takes two arguments, a key to be hashed and a table size. | |
2176 | @code{assoc} must be an associator function, like @code{assoc}, | |
2177 | @code{assq} or @code{assv}. | |
7a095584 | 2178 | |
ae9f3a15 MG |
2179 | By way of illustration, @code{hashq-set! table key} is |
2180 | equivalent to @code{hashx-set! hashq assq table key}. | |
780ee65e NJ |
2181 | @end deffn |
2182 | ||
2183 | \fhash-fold | |
89d04205 | 2184 | @c snarfed from hashtab.c:534 |
780ee65e NJ |
2185 | @deffn primitive hash-fold proc init table |
2186 | An iterator over hash-table elements. | |
2187 | Accumulates and returns a result by applying PROC successively. | |
2188 | The arguments to PROC are "(key value prior-result)" where key | |
2189 | and value are successive pairs from the hash table TABLE, and | |
2190 | prior-result is either INIT (for the first application of PROC) | |
2191 | or the return value of the previous application of PROC. | |
2192 | For example, @code{(hash-fold acons () tab)} will convert a hash | |
2193 | table into an a-list of key-value pairs. | |
2194 | @end deffn | |
2195 | ||
2196 | \fmake-hook-with-name | |
89d04205 | 2197 | @c snarfed from hooks.c:217 |
780ee65e NJ |
2198 | @deffn primitive make-hook-with-name name [n_args] |
2199 | Create a named hook with the name @var{name} for storing | |
5c4b24e1 MG |
2200 | procedures of arity @var{n_args}. @var{n_args} defaults to |
2201 | zero. | |
780ee65e NJ |
2202 | @end deffn |
2203 | ||
2204 | \fmake-hook | |
89d04205 | 2205 | @c snarfed from hooks.c:232 |
780ee65e | 2206 | @deffn primitive make-hook [n_args] |
5c4b24e1 MG |
2207 | Create a hook for storing procedure of arity |
2208 | @var{n_args}. @var{n_args} defaults to zero. | |
780ee65e NJ |
2209 | @end deffn |
2210 | ||
2211 | \fhook? | |
89d04205 | 2212 | @c snarfed from hooks.c:242 |
780ee65e | 2213 | @deffn primitive hook? x |
5c4b24e1 | 2214 | Return @code{#t} if @var{x} is a hook, @code{#f} otherwise. |
780ee65e NJ |
2215 | @end deffn |
2216 | ||
2217 | \fhook-empty? | |
89d04205 | 2218 | @c snarfed from hooks.c:253 |
780ee65e | 2219 | @deffn primitive hook-empty? hook |
5c4b24e1 MG |
2220 | Return @code{#t} if @var{hook} is an empty hook, @code{#f} |
2221 | otherwise. | |
780ee65e NJ |
2222 | @end deffn |
2223 | ||
2224 | \fadd-hook! | |
89d04205 | 2225 | @c snarfed from hooks.c:266 |
780ee65e NJ |
2226 | @deffn primitive add-hook! hook proc [append_p] |
2227 | Add the procedure @var{proc} to the hook @var{hook}. The | |
2228 | procedure is added to the end if @var{append_p} is true, | |
2229 | otherwise it is added to the front. | |
2230 | @end deffn | |
2231 | ||
2232 | \fremove-hook! | |
89d04205 | 2233 | @c snarfed from hooks.c:292 |
780ee65e NJ |
2234 | @deffn primitive remove-hook! hook proc |
2235 | Remove the procedure @var{proc} from the hook @var{hook}. | |
2236 | @end deffn | |
2237 | ||
2238 | \freset-hook! | |
89d04205 | 2239 | @c snarfed from hooks.c:305 |
780ee65e NJ |
2240 | @deffn primitive reset-hook! hook |
2241 | Remove all procedures from the hook @var{hook}. | |
2242 | @end deffn | |
2243 | ||
2244 | \frun-hook | |
89d04205 | 2245 | @c snarfed from hooks.c:319 |
780ee65e NJ |
2246 | @deffn primitive run-hook hook . args |
2247 | Apply all procedures from the hook @var{hook} to the arguments | |
5c4b24e1 MG |
2248 | @var{args}. The order of the procedure application is first to |
2249 | last. | |
780ee65e NJ |
2250 | @end deffn |
2251 | ||
2252 | \fhook->list | |
89d04205 | 2253 | @c snarfed from hooks.c:346 |
780ee65e NJ |
2254 | @deffn primitive hook->list hook |
2255 | Convert the procedure list of @var{hook} to a list. | |
2256 | @end deffn | |
2257 | ||
780ee65e | 2258 | \fftell |
7a095584 | 2259 | @c snarfed from ioext.c:71 |
ae9f3a15 MG |
2260 | @deffn primitive ftell fd_port |
2261 | Return an integer representing the current position of | |
2262 | @var{fd/port}, measured from the beginning. Equivalent to: | |
7a095584 | 2263 | |
ae9f3a15 | 2264 | @lisp |
780ee65e | 2265 | (seek port 0 SEEK_CUR) |
ae9f3a15 | 2266 | @end lisp |
780ee65e NJ |
2267 | @end deffn |
2268 | ||
780ee65e | 2269 | \fredirect-port |
7a095584 | 2270 | @c snarfed from ioext.c:89 |
780ee65e NJ |
2271 | @deffn primitive redirect-port old new |
2272 | This procedure takes two ports and duplicates the underlying file | |
2273 | descriptor from @var{old-port} into @var{new-port}. The | |
2274 | current file descriptor in @var{new-port} will be closed. | |
2275 | After the redirection the two ports will share a file position | |
2276 | and file status flags. | |
2277 | ||
2278 | The return value is unspecified. | |
2279 | ||
2280 | Unexpected behaviour can result if both ports are subsequently used | |
2281 | and the original and/or duplicate ports are buffered. | |
2282 | ||
2283 | This procedure does not have any side effects on other ports or | |
2284 | revealed counts. | |
2285 | @end deffn | |
2286 | ||
2287 | \fdup->fdes | |
7a095584 | 2288 | @c snarfed from ioext.c:128 |
780ee65e | 2289 | @deffn primitive dup->fdes fd_or_port [fd] |
ae9f3a15 MG |
2290 | Return a new integer file descriptor referring to the open file |
2291 | designated by @var{fd_or_port}, which must be either an open | |
2292 | file port or a file descriptor. | |
780ee65e NJ |
2293 | @end deffn |
2294 | ||
2295 | \fdup2 | |
7a095584 | 2296 | @c snarfed from ioext.c:175 |
780ee65e NJ |
2297 | @deffn primitive dup2 oldfd newfd |
2298 | A simple wrapper for the @code{dup2} system call. | |
2299 | Copies the file descriptor @var{oldfd} to descriptor | |
2300 | number @var{newfd}, replacing the previous meaning | |
2301 | of @var{newfd}. Both @var{oldfd} and @var{newfd} must | |
2302 | be integers. | |
2303 | Unlike for dup->fdes or primitive-move->fdes, no attempt | |
2304 | is made to move away ports which are using @var{newfd}. | |
2305 | The return value is unspecified. | |
2306 | @end deffn | |
2307 | ||
2308 | \ffileno | |
7a095584 | 2309 | @c snarfed from ioext.c:194 |
780ee65e | 2310 | @deffn primitive fileno port |
ae9f3a15 MG |
2311 | Return the integer file descriptor underlying @var{port}. Does |
2312 | not change its revealed count. | |
780ee65e NJ |
2313 | @end deffn |
2314 | ||
2315 | \fisatty? | |
7a095584 | 2316 | @c snarfed from ioext.c:210 |
780ee65e | 2317 | @deffn primitive isatty? port |
ae9f3a15 MG |
2318 | Return @code{#t} if @var{port} is using a serial non--file |
2319 | device, otherwise @code{#f}. | |
780ee65e NJ |
2320 | @end deffn |
2321 | ||
2322 | \ffdopen | |
7a095584 | 2323 | @c snarfed from ioext.c:232 |
780ee65e | 2324 | @deffn primitive fdopen fdes modes |
ae9f3a15 MG |
2325 | Return a new port based on the file descriptor @var{fdes}. |
2326 | Modes are given by the string @var{modes}. The revealed count | |
2327 | of the port is initialized to zero. The modes string is the | |
2328 | same as that accepted by @ref{File Ports, open-file}. | |
780ee65e NJ |
2329 | @end deffn |
2330 | ||
2331 | \fprimitive-move->fdes | |
7a095584 | 2332 | @c snarfed from ioext.c:257 |
780ee65e NJ |
2333 | @deffn primitive primitive-move->fdes port fd |
2334 | Moves the underlying file descriptor for @var{port} to the integer | |
2335 | value @var{fdes} without changing the revealed count of @var{port}. | |
2336 | Any other ports already using this descriptor will be automatically | |
2337 | shifted to new descriptors and their revealed counts reset to zero. | |
2338 | The return value is @code{#f} if the file descriptor already had the | |
2339 | required value or @code{#t} if it was moved. | |
2340 | @end deffn | |
2341 | ||
2342 | \ffdes->ports | |
7a095584 | 2343 | @c snarfed from ioext.c:291 |
780ee65e | 2344 | @deffn primitive fdes->ports fd |
ae9f3a15 MG |
2345 | Return a list of existing ports which have @var{fdes} as an |
2346 | underlying file descriptor, without changing their revealed | |
2347 | counts. | |
780ee65e NJ |
2348 | @end deffn |
2349 | ||
2350 | \fmake-keyword-from-dash-symbol | |
2351 | @c snarfed from keywords.c:71 | |
2352 | @deffn primitive make-keyword-from-dash-symbol symbol | |
2353 | Make a keyword object from a @var{symbol} that starts with a dash. | |
2354 | @end deffn | |
2355 | ||
2356 | \fkeyword? | |
89d04205 | 2357 | @c snarfed from keywords.c:113 |
780ee65e | 2358 | @deffn primitive keyword? obj |
ae9f3a15 MG |
2359 | Return @code{#t} if the argument @var{obj} is a keyword, else |
2360 | @code{#f}. | |
780ee65e NJ |
2361 | @end deffn |
2362 | ||
2363 | \fkeyword-dash-symbol | |
89d04205 | 2364 | @c snarfed from keywords.c:124 |
780ee65e NJ |
2365 | @deffn primitive keyword-dash-symbol keyword |
2366 | Return the dash symbol for @var{keyword}. | |
2367 | This is the inverse of @code{make-keyword-from-dash-symbol}. | |
2368 | @end deffn | |
2369 | ||
2370 | \fnil-cons | |
2371 | @c snarfed from lang.c:71 | |
2372 | @deffn primitive nil-cons x y | |
2373 | Create a new cons cell with @var{x} as the car and @var{y} as | |
2374 | the cdr, but convert @var{y} to Scheme's end-of-list if it is | |
2375 | a LISP nil. | |
2376 | @end deffn | |
2377 | ||
2378 | \fnil-car | |
2379 | @c snarfed from lang.c:86 | |
2380 | @deffn primitive nil-car x | |
2381 | Return the car of @var{x}, but convert it to LISP nil if it | |
2382 | is Scheme's end-of-list. | |
2383 | @end deffn | |
2384 | ||
2385 | \fnil-cdr | |
2386 | @c snarfed from lang.c:99 | |
2387 | @deffn primitive nil-cdr x | |
2388 | Return the cdr of @var{x}, but convert it to LISP nil if it | |
2389 | is Scheme's end-of-list. | |
2390 | @end deffn | |
2391 | ||
2392 | \fnull | |
2393 | @c snarfed from lang.c:114 | |
2394 | @deffn primitive null x | |
2395 | Return LISP's @code{t} if @var{x} is nil in the LISP sense, | |
2396 | return LISP's nil otherwise. | |
2397 | @end deffn | |
2398 | ||
2399 | \fnil-eq | |
2400 | @c snarfed from lang.c:143 | |
2401 | @deffn primitive nil-eq x y | |
2402 | Compare @var{x} and @var{y} and return LISP's t if they are | |
2403 | @code{eq?}, return LISP's nil otherwise. | |
2404 | @end deffn | |
2405 | ||
2406 | \flist | |
2407 | @c snarfed from list.c:84 | |
2408 | @deffn primitive list . objs | |
2409 | Return a list containing @var{objs}, the arguments to | |
2410 | @code{list}. | |
2411 | @end deffn | |
2412 | ||
2413 | \flist* | |
2414 | @c snarfed from list.c:94 | |
2415 | @deffn primitive list* | |
2416 | scm_cons_star | |
2417 | @end deffn | |
2418 | ||
2419 | \fcons* | |
2420 | @c snarfed from list.c:105 | |
2421 | @deffn primitive cons* arg . rest | |
2422 | Like @code{list}, but the last arg provides the tail of the | |
2423 | constructed list, returning @code{(cons @var{arg1} (cons | |
a6be01a4 | 2424 | @var{arg2} (cons @dots{} @var{argn})))}. Requires at least one |
780ee65e NJ |
2425 | argument. If given one argument, that argument is returned as |
2426 | result. This function is called @code{list*} in some other | |
2427 | Schemes and in Common LISP. | |
2428 | @end deffn | |
2429 | ||
2430 | \fnull? | |
2431 | @c snarfed from list.c:129 | |
2432 | @deffn primitive null? x | |
2433 | Return @code{#t} iff @var{x} is the empty list, else @code{#f}. | |
2434 | @end deffn | |
2435 | ||
2436 | \flist? | |
2437 | @c snarfed from list.c:139 | |
2438 | @deffn primitive list? x | |
2439 | Return @code{#t} iff @var{x} is a proper list, else @code{#f}. | |
2440 | @end deffn | |
2441 | ||
2442 | \flength | |
2443 | @c snarfed from list.c:180 | |
2444 | @deffn primitive length lst | |
2445 | Return the number of elements in list @var{lst}. | |
2446 | @end deffn | |
2447 | ||
2448 | \fappend | |
2449 | @c snarfed from list.c:209 | |
2450 | @deffn primitive append . args | |
2451 | Return a list consisting of the elements the lists passed as | |
2452 | arguments. | |
ae9f3a15 | 2453 | @lisp |
780ee65e NJ |
2454 | (append '(x) '(y)) @result{} (x y) |
2455 | (append '(a) '(b c d)) @result{} (a b c d) | |
2456 | (append '(a (b)) '((c))) @result{} (a (b) (c)) | |
ae9f3a15 | 2457 | @end lisp |
780ee65e NJ |
2458 | The resulting list is always newly allocated, except that it |
2459 | shares structure with the last list argument. The last | |
2460 | argument may actually be any object; an improper list results | |
2461 | if the last argument is not a proper list. | |
ae9f3a15 | 2462 | @lisp |
780ee65e NJ |
2463 | (append '(a b) '(c . d)) @result{} (a b c . d) |
2464 | (append '() 'a) @result{} a | |
ae9f3a15 | 2465 | @end lisp |
780ee65e NJ |
2466 | @end deffn |
2467 | ||
2468 | \fappend! | |
89d04205 | 2469 | @c snarfed from list.c:243 |
ae9f3a15 MG |
2470 | @deffn primitive append! . lists |
2471 | A destructive version of @code{append} (@pxref{Pairs and | |
2472 | Lists,,,r4rs, The Revised^4 Report on Scheme}). The cdr field | |
2473 | of each list's final pair is changed to point to the head of | |
2474 | the next list, so no consing is performed. Return a pointer to | |
2475 | the mutated list. | |
780ee65e NJ |
2476 | @end deffn |
2477 | ||
2478 | \flast-pair | |
89d04205 | 2479 | @c snarfed from list.c:269 |
780ee65e NJ |
2480 | @deffn primitive last-pair lst |
2481 | Return a pointer to the last pair in @var{lst}, signalling an error if | |
2482 | @var{lst} is circular. | |
2483 | @end deffn | |
2484 | ||
2485 | \freverse | |
89d04205 | 2486 | @c snarfed from list.c:299 |
780ee65e NJ |
2487 | @deffn primitive reverse lst |
2488 | Return a new list that contains the elements of @var{lst} but | |
2489 | in reverse order. | |
2490 | @end deffn | |
2491 | ||
2492 | \freverse! | |
89d04205 | 2493 | @c snarfed from list.c:333 |
780ee65e NJ |
2494 | @deffn primitive reverse! lst [new_tail] |
2495 | A destructive version of @code{reverse} (@pxref{Pairs and Lists,,,r4rs, | |
2496 | The Revised^4 Report on Scheme}). The cdr of each cell in @var{lst} is | |
2497 | modified to point to the previous list element. Return a pointer to the | |
2498 | head of the reversed list. | |
2499 | ||
2500 | Caveat: because the list is modified in place, the tail of the original | |
2501 | list now becomes its head, and the head of the original list now becomes | |
2502 | the tail. Therefore, the @var{lst} symbol to which the head of the | |
2503 | original list was bound now points to the tail. To ensure that the head | |
2504 | of the modified list is not lost, it is wise to save the return value of | |
2505 | @code{reverse!} | |
2506 | @end deffn | |
2507 | ||
2508 | \flist-ref | |
89d04205 | 2509 | @c snarfed from list.c:359 |
780ee65e NJ |
2510 | @deffn primitive list-ref list k |
2511 | Return the @var{k}th element from @var{list}. | |
2512 | @end deffn | |
2513 | ||
2514 | \flist-set! | |
89d04205 | 2515 | @c snarfed from list.c:383 |
780ee65e NJ |
2516 | @deffn primitive list-set! list k val |
2517 | Set the @var{k}th element of @var{list} to @var{val}. | |
2518 | @end deffn | |
2519 | ||
2520 | \flist-cdr-ref | |
89d04205 | 2521 | @c snarfed from list.c:406 |
780ee65e NJ |
2522 | @deffn primitive list-cdr-ref |
2523 | scm_list_tail | |
2524 | @end deffn | |
2525 | ||
2526 | \flist-tail | |
89d04205 | 2527 | @c snarfed from list.c:415 |
780ee65e NJ |
2528 | @deffn primitive list-tail lst k |
2529 | @deffnx primitive list-cdr-ref lst k | |
2530 | Return the "tail" of @var{lst} beginning with its @var{k}th element. | |
2531 | The first element of the list is considered to be element 0. | |
2532 | ||
2533 | @code{list-tail} and @code{list-cdr-ref} are identical. It may help to | |
2534 | think of @code{list-cdr-ref} as accessing the @var{k}th cdr of the list, | |
2535 | or returning the results of cdring @var{k} times down @var{lst}. | |
2536 | @end deffn | |
2537 | ||
2538 | \flist-cdr-set! | |
89d04205 | 2539 | @c snarfed from list.c:431 |
780ee65e NJ |
2540 | @deffn primitive list-cdr-set! list k val |
2541 | Set the @var{k}th cdr of @var{list} to @var{val}. | |
2542 | @end deffn | |
2543 | ||
2544 | \flist-head | |
89d04205 | 2545 | @c snarfed from list.c:460 |
780ee65e NJ |
2546 | @deffn primitive list-head lst k |
2547 | Copy the first @var{k} elements from @var{lst} into a new list, and | |
2548 | return it. | |
2549 | @end deffn | |
2550 | ||
2551 | \flist-copy | |
89d04205 | 2552 | @c snarfed from list.c:484 |
780ee65e NJ |
2553 | @deffn primitive list-copy lst |
2554 | Return a (newly-created) copy of @var{lst}. | |
2555 | @end deffn | |
2556 | ||
2557 | \fsloppy-memq | |
89d04205 | 2558 | @c snarfed from list.c:518 |
780ee65e NJ |
2559 | @deffn primitive sloppy-memq x lst |
2560 | This procedure behaves like @code{memq}, but does no type or error checking. | |
2561 | Its use is recommended only in writing Guile internals, | |
2562 | not for high-level Scheme programs. | |
2563 | @end deffn | |
2564 | ||
2565 | \fsloppy-memv | |
89d04205 | 2566 | @c snarfed from list.c:535 |
780ee65e NJ |
2567 | @deffn primitive sloppy-memv x lst |
2568 | This procedure behaves like @code{memv}, but does no type or error checking. | |
2569 | Its use is recommended only in writing Guile internals, | |
2570 | not for high-level Scheme programs. | |
2571 | @end deffn | |
2572 | ||
2573 | \fsloppy-member | |
89d04205 | 2574 | @c snarfed from list.c:552 |
780ee65e NJ |
2575 | @deffn primitive sloppy-member x lst |
2576 | This procedure behaves like @code{member}, but does no type or error checking. | |
2577 | Its use is recommended only in writing Guile internals, | |
2578 | not for high-level Scheme programs. | |
2579 | @end deffn | |
2580 | ||
2581 | \fmemq | |
89d04205 | 2582 | @c snarfed from list.c:592 |
780ee65e NJ |
2583 | @deffn primitive memq x lst |
2584 | Return the first sublist of @var{lst} whose car is @code{eq?} | |
2585 | to @var{x} where the sublists of @var{lst} are the non-empty | |
2586 | lists returned by @code{(list-tail @var{lst} @var{k})} for | |
2587 | @var{k} less than the length of @var{lst}. If @var{x} does not | |
2588 | occur in @var{lst}, then @code{#f} (not the empty list) is | |
2589 | returned. | |
2590 | @end deffn | |
2591 | ||
2592 | \fmemv | |
89d04205 | 2593 | @c snarfed from list.c:609 |
780ee65e NJ |
2594 | @deffn primitive memv x lst |
2595 | Return the first sublist of @var{lst} whose car is @code{eqv?} | |
2596 | to @var{x} where the sublists of @var{lst} are the non-empty | |
2597 | lists returned by @code{(list-tail @var{lst} @var{k})} for | |
2598 | @var{k} less than the length of @var{lst}. If @var{x} does not | |
2599 | occur in @var{lst}, then @code{#f} (not the empty list) is | |
2600 | returned. | |
2601 | @end deffn | |
2602 | ||
2603 | \fmember | |
89d04205 | 2604 | @c snarfed from list.c:630 |
780ee65e NJ |
2605 | @deffn primitive member x lst |
2606 | Return the first sublist of @var{lst} whose car is | |
2607 | @code{equal?} to @var{x} where the sublists of @var{lst} are | |
2608 | the non-empty lists returned by @code{(list-tail @var{lst} | |
2609 | @var{k})} for @var{k} less than the length of @var{lst}. If | |
2610 | @var{x} does not occur in @var{lst}, then @code{#f} (not the | |
2611 | empty list) is returned. | |
2612 | @end deffn | |
2613 | ||
2614 | \fdelq! | |
89d04205 | 2615 | @c snarfed from list.c:656 |
780ee65e NJ |
2616 | @deffn primitive delq! item lst |
2617 | @deffnx primitive delv! item lst | |
2618 | @deffnx primitive delete! item lst | |
2619 | These procedures are destructive versions of @code{delq}, @code{delv} | |
2620 | and @code{delete}: they modify the pointers in the existing @var{lst} | |
2621 | rather than creating a new list. Caveat evaluator: Like other | |
2622 | destructive list functions, these functions cannot modify the binding of | |
2623 | @var{lst}, and so cannot be used to delete the first element of | |
2624 | @var{lst} destructively. | |
2625 | @end deffn | |
2626 | ||
2627 | \fdelv! | |
89d04205 | 2628 | @c snarfed from list.c:680 |
780ee65e NJ |
2629 | @deffn primitive delv! item lst |
2630 | Destructively remove all elements from @var{lst} that are | |
2631 | @code{eqv?} to @var{item}. | |
2632 | @end deffn | |
2633 | ||
2634 | \fdelete! | |
89d04205 | 2635 | @c snarfed from list.c:705 |
780ee65e NJ |
2636 | @deffn primitive delete! item lst |
2637 | Destructively remove all elements from @var{lst} that are | |
2638 | @code{equal?} to @var{item}. | |
2639 | @end deffn | |
2640 | ||
2641 | \fdelq | |
89d04205 | 2642 | @c snarfed from list.c:734 |
780ee65e NJ |
2643 | @deffn primitive delq item lst |
2644 | Return a newly-created copy of @var{lst} with elements | |
2645 | @code{eq?} to @var{item} removed. This procedure mirrors | |
2646 | @code{memq}: @code{delq} compares elements of @var{lst} against | |
2647 | @var{item} with @code{eq?}. | |
2648 | @end deffn | |
2649 | ||
2650 | \fdelv | |
89d04205 | 2651 | @c snarfed from list.c:747 |
780ee65e NJ |
2652 | @deffn primitive delv item lst |
2653 | Return a newly-created copy of @var{lst} with elements | |
2654 | @code{eqv?} to @var{item} removed. This procedure mirrors | |
2655 | @code{memv}: @code{delv} compares elements of @var{lst} against | |
2656 | @var{item} with @code{eqv?}. | |
2657 | @end deffn | |
2658 | ||
2659 | \fdelete | |
89d04205 | 2660 | @c snarfed from list.c:760 |
780ee65e NJ |
2661 | @deffn primitive delete item lst |
2662 | Return a newly-created copy of @var{lst} with elements | |
2663 | @code{equal?} to @var{item} removed. This procedure mirrors | |
2664 | @code{member}: @code{delete} compares elements of @var{lst} | |
2665 | against @var{item} with @code{equal?}. | |
2666 | @end deffn | |
2667 | ||
2668 | \fdelq1! | |
89d04205 | 2669 | @c snarfed from list.c:773 |
780ee65e NJ |
2670 | @deffn primitive delq1! item lst |
2671 | Like @code{delq!}, but only deletes the first occurrence of | |
2672 | @var{item} from @var{lst}. Tests for equality using | |
2673 | @code{eq?}. See also @code{delv1!} and @code{delete1!}. | |
2674 | @end deffn | |
2675 | ||
2676 | \fdelv1! | |
89d04205 | 2677 | @c snarfed from list.c:801 |
780ee65e NJ |
2678 | @deffn primitive delv1! item lst |
2679 | Like @code{delv!}, but only deletes the first occurrence of | |
2680 | @var{item} from @var{lst}. Tests for equality using | |
2681 | @code{eqv?}. See also @code{delq1!} and @code{delete1!}. | |
2682 | @end deffn | |
2683 | ||
2684 | \fdelete1! | |
89d04205 | 2685 | @c snarfed from list.c:829 |
780ee65e NJ |
2686 | @deffn primitive delete1! item lst |
2687 | Like @code{delete!}, but only deletes the first occurrence of | |
2688 | @var{item} from @var{lst}. Tests for equality using | |
2689 | @code{equal?}. See also @code{delq1!} and @code{delv1!}. | |
2690 | @end deffn | |
2691 | ||
2692 | \fprimitive-load | |
2693 | @c snarfed from load.c:112 | |
2694 | @deffn primitive primitive-load filename | |
2695 | Load the file named @var{filename} and evaluate its contents in | |
2696 | the top-level environment. The load paths are not searched; | |
2697 | @var{filename} must either be a full pathname or be a pathname | |
2698 | relative to the current directory. If the variable | |
2699 | @code{%load-hook} is defined, it should be bound to a procedure | |
2700 | that will be called before any code is loaded. See the | |
2701 | documentation for @code{%load-hook} later in this section. | |
2702 | @end deffn | |
2703 | ||
2704 | \f%package-data-dir | |
2705 | @c snarfed from load.c:147 | |
2706 | @deffn primitive %package-data-dir | |
2707 | Return the name of the directory where Scheme packages, modules and | |
2708 | libraries are kept. On most Unix systems, this will be | |
2709 | @samp{/usr/local/share/guile}. | |
2710 | @end deffn | |
2711 | ||
2712 | \f%library-dir | |
2713 | @c snarfed from load.c:159 | |
2714 | @deffn primitive %library-dir | |
2715 | Return the directory where the Guile Scheme library files are installed. | |
2716 | E.g., may return "/usr/share/guile/1.3.5". | |
2717 | @end deffn | |
2718 | ||
2719 | \f%site-dir | |
2720 | @c snarfed from load.c:171 | |
2721 | @deffn primitive %site-dir | |
2722 | Return the directory where the Guile site files are installed. | |
2723 | E.g., may return "/usr/share/guile/site". | |
2724 | @end deffn | |
2725 | ||
2726 | \fparse-path | |
2727 | @c snarfed from load.c:223 | |
2728 | @deffn primitive parse-path path [tail] | |
2729 | Parse @var{path}, which is expected to be a colon-separated | |
2730 | string, into a list and return the resulting list with | |
2731 | @var{tail} appended. If @var{path} is @code{#f}, @var{tail} | |
2732 | is returned. | |
2733 | @end deffn | |
2734 | ||
2735 | \fsearch-path | |
2736 | @c snarfed from load.c:273 | |
2737 | @deffn primitive search-path path filename [extensions] | |
2738 | Search @var{path} for a directory containing a file named | |
2739 | @var{filename}. The file must be readable, and not a directory. | |
2740 | If we find one, return its full filename; otherwise, return | |
2741 | @code{#f}. If @var{filename} is absolute, return it unchanged. | |
2742 | If given, @var{extensions} is a list of strings; for each | |
2743 | directory in @var{path}, we search for @var{filename} | |
2744 | concatenated with each @var{extension}. | |
2745 | @end deffn | |
2746 | ||
2747 | \f%search-load-path | |
2748 | @c snarfed from load.c:420 | |
2749 | @deffn primitive %search-load-path filename | |
2750 | Search @var{%load-path} for the file named @var{filename}, | |
2751 | which must be readable by the current user. If @var{filename} | |
2752 | is found in the list of paths to search or is an absolute | |
2753 | pathname, return its full pathname. Otherwise, return | |
2754 | @code{#f}. Filenames may have any of the optional extensions | |
2755 | in the @code{%load-extensions} list; @code{%search-load-path} | |
2756 | will try each extension automatically. | |
2757 | @end deffn | |
2758 | ||
2759 | \fprimitive-load-path | |
2760 | @c snarfed from load.c:441 | |
2761 | @deffn primitive primitive-load-path filename | |
2762 | Search @var{%load-path} for the file named @var{filename} and | |
2763 | load it into the top-level environment. If @var{filename} is a | |
2764 | relative pathname and is not found in the list of search paths, | |
2765 | an error is signalled. | |
2766 | @end deffn | |
2767 | ||
2768 | \fread-and-eval! | |
2769 | @c snarfed from load.c:476 | |
2770 | @deffn primitive read-and-eval! [port] | |
2771 | Read a form from @var{port} (standard input by default), and evaluate it | |
2772 | (memoizing it in the process) in the top-level environment. If no data | |
2773 | is left to be read from @var{port}, an @code{end-of-file} error is | |
2774 | signalled. | |
2775 | @end deffn | |
2776 | ||
2777 | \fprocedure->syntax | |
72ad43dc | 2778 | @c snarfed from macros.c:106 |
780ee65e | 2779 | @deffn primitive procedure->syntax code |
ae9f3a15 MG |
2780 | Return a @dfn{macro} which, when a symbol defined to this value |
2781 | appears as the first symbol in an expression, returns the | |
2782 | result of applying @var{code} to the expression and the | |
2783 | environment. | |
780ee65e NJ |
2784 | @end deffn |
2785 | ||
2786 | \fprocedure->macro | |
72ad43dc | 2787 | @c snarfed from macros.c:129 |
780ee65e | 2788 | @deffn primitive procedure->macro code |
ae9f3a15 MG |
2789 | Return a @dfn{macro} which, when a symbol defined to this value |
2790 | appears as the first symbol in an expression, evaluates the | |
2791 | result of applying @var{code} to the expression and the | |
2792 | environment. The value returned from @var{code} which has been | |
2793 | passed to @code{procedure->memoizing-macro} replaces the form | |
2794 | passed to @var{code}. For example: | |
7a095584 | 2795 | |
ae9f3a15 | 2796 | @lisp |
780ee65e NJ |
2797 | (define trace |
2798 | (procedure->macro | |
2799 | (lambda (x env) `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x)))))) | |
2800 | ||
2801 | (trace @i{foo}) @equiv{} (set! @i{foo} (tracef @i{foo} '@i{foo})). | |
ae9f3a15 | 2802 | @end lisp |
780ee65e NJ |
2803 | @end deffn |
2804 | ||
2805 | \fprocedure->memoizing-macro | |
72ad43dc | 2806 | @c snarfed from macros.c:152 |
780ee65e | 2807 | @deffn primitive procedure->memoizing-macro code |
ae9f3a15 MG |
2808 | Return a @dfn{macro} which, when a symbol defined to this value |
2809 | appears as the first symbol in an expression, evaluates the | |
2810 | result of applying @var{proc} to the expression and the | |
2811 | environment. The value returned from @var{proc} which has been | |
2812 | passed to @code{procedure->memoizing-macro} replaces the form | |
2813 | passed to @var{proc}. For example: | |
7a095584 | 2814 | |
ae9f3a15 | 2815 | @lisp |
780ee65e NJ |
2816 | (define trace |
2817 | (procedure->macro | |
2818 | (lambda (x env) `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x)))))) | |
2819 | ||
2820 | (trace @i{foo}) @equiv{} (set! @i{foo} (tracef @i{foo} '@i{foo})). | |
ae9f3a15 | 2821 | @end lisp |
780ee65e NJ |
2822 | @end deffn |
2823 | ||
2824 | \fmacro? | |
72ad43dc | 2825 | @c snarfed from macros.c:164 |
780ee65e NJ |
2826 | @deffn primitive macro? obj |
2827 | Return @code{#t} if @var{obj} is a regular macro, a memoizing macro or a | |
2828 | syntax transformer. | |
2829 | @end deffn | |
2830 | ||
2831 | \fmacro-type | |
72ad43dc | 2832 | @c snarfed from macros.c:182 |
780ee65e | 2833 | @deffn primitive macro-type m |
ae9f3a15 MG |
2834 | Return one of the symbols @code{syntax}, @code{macro} or |
2835 | @code{macro!}, depending on whether @var{m} is a syntax | |
2836 | tranformer, a regular macro, or a memoizing macro, | |
2837 | respectively. If @var{m} is not a macro, @code{#f} is | |
2838 | returned. | |
780ee65e NJ |
2839 | @end deffn |
2840 | ||
2841 | \fmacro-name | |
72ad43dc | 2842 | @c snarfed from macros.c:200 |
780ee65e NJ |
2843 | @deffn primitive macro-name m |
2844 | Return the name of the macro @var{m}. | |
2845 | @end deffn | |
2846 | ||
2847 | \fmacro-transformer | |
72ad43dc | 2848 | @c snarfed from macros.c:211 |
780ee65e NJ |
2849 | @deffn primitive macro-transformer m |
2850 | Return the transformer of the macro @var{m}. | |
2851 | @end deffn | |
2852 | ||
7a095584 NJ |
2853 | \fcurrent-module |
2854 | @c snarfed from modules.c:78 | |
2855 | @deffn primitive current-module | |
2856 | Return the current module. | |
2857 | @end deffn | |
2858 | ||
2859 | \fset-current-module | |
2860 | @c snarfed from modules.c:95 | |
2861 | @deffn primitive set-current-module module | |
2862 | Set the current module to @var{module} and return | |
2863 | the previous current module. | |
2864 | @end deffn | |
2865 | ||
780ee65e | 2866 | \finteraction-environment |
7a095584 | 2867 | @c snarfed from modules.c:128 |
780ee65e | 2868 | @deffn primitive interaction-environment |
ae9f3a15 MG |
2869 | Return a specifier for the environment that contains |
2870 | implementation--defined bindings, typically a superset of those | |
2871 | listed in the report. The intent is that this procedure will | |
2872 | return the environment in which the implementation would | |
2873 | evaluate expressions dynamically typed by the user. | |
780ee65e NJ |
2874 | @end deffn |
2875 | ||
2876 | \fstandard-eval-closure | |
7a095584 | 2877 | @c snarfed from modules.c:312 |
780ee65e NJ |
2878 | @deffn primitive standard-eval-closure module |
2879 | Return an eval closure for the module @var{module}. | |
2880 | @end deffn | |
2881 | ||
780ee65e | 2882 | \fgethost |
7a095584 | 2883 | @c snarfed from net_db.c:146 |
780ee65e NJ |
2884 | @deffn primitive gethost [host] |
2885 | @deffnx procedure gethostbyname hostname | |
2886 | @deffnx procedure gethostbyaddr address | |
2887 | Look up a host by name or address, returning a host object. The | |
2888 | @code{gethost} procedure will accept either a string name or an integer | |
2889 | address; if given no arguments, it behaves like @code{gethostent} (see | |
2890 | below). If a name or address is supplied but the address can not be | |
2891 | found, an error will be thrown to one of the keys: | |
2892 | @code{host-not-found}, @code{try-again}, @code{no-recovery} or | |
2893 | @code{no-data}, corresponding to the equivalent @code{h_error} values. | |
2894 | Unusual conditions may result in errors thrown to the | |
2895 | @code{system-error} or @code{misc_error} keys. | |
2896 | @end deffn | |
2897 | ||
2898 | \fgetnet | |
7a095584 | 2899 | @c snarfed from net_db.c:227 |
780ee65e NJ |
2900 | @deffn primitive getnet [net] |
2901 | @deffnx procedure getnetbyname net-name | |
2902 | @deffnx procedure getnetbyaddr net-number | |
2903 | Look up a network by name or net number in the network database. The | |
2904 | @var{net-name} argument must be a string, and the @var{net-number} | |
2905 | argument must be an integer. @code{getnet} will accept either type of | |
2906 | argument, behaving like @code{getnetent} (see below) if no arguments are | |
2907 | given. | |
2908 | @end deffn | |
2909 | ||
2910 | \fgetproto | |
7a095584 | 2911 | @c snarfed from net_db.c:277 |
780ee65e NJ |
2912 | @deffn primitive getproto [protocol] |
2913 | @deffnx procedure getprotobyname name | |
2914 | @deffnx procedure getprotobynumber number | |
2915 | Look up a network protocol by name or by number. @code{getprotobyname} | |
2916 | takes a string argument, and @code{getprotobynumber} takes an integer | |
2917 | argument. @code{getproto} will accept either type, behaving like | |
2918 | @code{getprotoent} (see below) if no arguments are supplied. | |
2919 | @end deffn | |
2920 | ||
2921 | \fgetserv | |
7a095584 | 2922 | @c snarfed from net_db.c:344 |
780ee65e NJ |
2923 | @deffn primitive getserv [name [protocol]] |
2924 | @deffnx procedure getservbyname name protocol | |
2925 | @deffnx procedure getservbyport port protocol | |
2926 | Look up a network service by name or by service number, and return a | |
2927 | network service object. The @var{protocol} argument specifies the name | |
2928 | of the desired protocol; if the protocol found in the network service | |
2929 | database does not match this name, a system error is signalled. | |
2930 | ||
2931 | The @code{getserv} procedure will take either a service name or number | |
2932 | as its first argument; if given no arguments, it behaves like | |
2933 | @code{getservent} (see below). | |
2934 | @end deffn | |
2935 | ||
2936 | \fsethost | |
7a095584 | 2937 | @c snarfed from net_db.c:383 |
780ee65e NJ |
2938 | @deffn primitive sethost [stayopen] |
2939 | If @var{stayopen} is omitted, this is equivalent to @code{endhostent}. | |
2940 | Otherwise it is equivalent to @code{sethostent stayopen}. | |
2941 | @end deffn | |
2942 | ||
2943 | \fsetnet | |
7a095584 | 2944 | @c snarfed from net_db.c:399 |
780ee65e NJ |
2945 | @deffn primitive setnet [stayopen] |
2946 | If @var{stayopen} is omitted, this is equivalent to @code{endnetent}. | |
2947 | Otherwise it is equivalent to @code{setnetent stayopen}. | |
2948 | @end deffn | |
2949 | ||
2950 | \fsetproto | |
7a095584 | 2951 | @c snarfed from net_db.c:415 |
780ee65e NJ |
2952 | @deffn primitive setproto [stayopen] |
2953 | If @var{stayopen} is omitted, this is equivalent to @code{endprotoent}. | |
2954 | Otherwise it is equivalent to @code{setprotoent stayopen}. | |
2955 | @end deffn | |
2956 | ||
2957 | \fsetserv | |
7a095584 | 2958 | @c snarfed from net_db.c:431 |
780ee65e NJ |
2959 | @deffn primitive setserv [stayopen] |
2960 | If @var{stayopen} is omitted, this is equivalent to @code{endservent}. | |
2961 | Otherwise it is equivalent to @code{setservent stayopen}. | |
2962 | @end deffn | |
2963 | ||
2964 | \fexact? | |
7a095584 | 2965 | @c snarfed from numbers.c:107 |
780ee65e NJ |
2966 | @deffn primitive exact? x |
2967 | Return @code{#t} if @var{x} is an exact number, @code{#f} | |
2968 | otherwise. | |
2969 | @end deffn | |
2970 | ||
2971 | \fodd? | |
7a095584 | 2972 | @c snarfed from numbers.c:124 |
780ee65e NJ |
2973 | @deffn primitive odd? n |
2974 | Return @code{#t} if @var{n} is an odd number, @code{#f} | |
2975 | otherwise. | |
2976 | @end deffn | |
2977 | ||
2978 | \feven? | |
7a095584 | 2979 | @c snarfed from numbers.c:141 |
780ee65e NJ |
2980 | @deffn primitive even? n |
2981 | Return @code{#t} if @var{n} is an even number, @code{#f} | |
2982 | otherwise. | |
2983 | @end deffn | |
2984 | ||
2985 | \flogand | |
7a095584 | 2986 | @c snarfed from numbers.c:756 |
780ee65e | 2987 | @deffn primitive logand n1 n2 |
ae9f3a15 | 2988 | Return the integer which is the bit-wise AND of the two integer |
780ee65e | 2989 | arguments. |
7a095584 | 2990 | |
780ee65e NJ |
2991 | @lisp |
2992 | (number->string (logand #b1100 #b1010) 2) | |
2993 | @result{} "1000" | |
2994 | @end lisp | |
2995 | @end deffn | |
2996 | ||
2997 | \flogior | |
7a095584 | 2998 | @c snarfed from numbers.c:843 |
780ee65e | 2999 | @deffn primitive logior n1 n2 |
ae9f3a15 | 3000 | Return the integer which is the bit-wise OR of the two integer |
780ee65e | 3001 | arguments. |
7a095584 | 3002 | |
780ee65e NJ |
3003 | @lisp |
3004 | (number->string (logior #b1100 #b1010) 2) | |
3005 | @result{} "1110" | |
3006 | @end lisp | |
3007 | @end deffn | |
3008 | ||
3009 | \flogxor | |
7a095584 | 3010 | @c snarfed from numbers.c:929 |
780ee65e | 3011 | @deffn primitive logxor n1 n2 |
ae9f3a15 | 3012 | Return the integer which is the bit-wise XOR of the two integer |
780ee65e | 3013 | arguments. |
7a095584 | 3014 | |
780ee65e NJ |
3015 | @lisp |
3016 | (number->string (logxor #b1100 #b1010) 2) | |
3017 | @result{} "110" | |
3018 | @end lisp | |
3019 | @end deffn | |
3020 | ||
3021 | \flogtest | |
7a095584 | 3022 | @c snarfed from numbers.c:998 |
ae9f3a15 MG |
3023 | @deffn primitive logtest j k |
3024 | @lisp | |
780ee65e NJ |
3025 | (logtest j k) @equiv{} (not (zero? (logand j k))) |
3026 | ||
3027 | (logtest #b0100 #b1011) @result{} #f | |
3028 | (logtest #b0100 #b0111) @result{} #t | |
ae9f3a15 | 3029 | @end lisp |
780ee65e NJ |
3030 | @end deffn |
3031 | ||
3032 | \flogbit? | |
7a095584 | 3033 | @c snarfed from numbers.c:1055 |
780ee65e | 3034 | @deffn primitive logbit? index j |
ae9f3a15 | 3035 | @lisp |
780ee65e NJ |
3036 | (logbit? index j) @equiv{} (logtest (integer-expt 2 index) j) |
3037 | ||
3038 | (logbit? 0 #b1101) @result{} #t | |
3039 | (logbit? 1 #b1101) @result{} #f | |
3040 | (logbit? 2 #b1101) @result{} #t | |
3041 | (logbit? 3 #b1101) @result{} #t | |
3042 | (logbit? 4 #b1101) @result{} #f | |
ae9f3a15 | 3043 | @end lisp |
780ee65e NJ |
3044 | @end deffn |
3045 | ||
3046 | \flognot | |
7a095584 | 3047 | @c snarfed from numbers.c:1104 |
780ee65e | 3048 | @deffn primitive lognot n |
ae9f3a15 MG |
3049 | Return the integer which is the 2s-complement of the integer |
3050 | argument. | |
7a095584 | 3051 | |
780ee65e NJ |
3052 | @lisp |
3053 | (number->string (lognot #b10000000) 2) | |
3054 | @result{} "-10000001" | |
3055 | (number->string (lognot #b0) 2) | |
3056 | @result{} "-1" | |
3057 | @end lisp | |
3058 | @end deffn | |
3059 | ||
3060 | \finteger-expt | |
7a095584 | 3061 | @c snarfed from numbers.c:1121 |
780ee65e | 3062 | @deffn primitive integer-expt n k |
ae9f3a15 MG |
3063 | Return @var{n} raised to the non-negative integer exponent |
3064 | @var{k}. | |
7a095584 | 3065 | |
780ee65e NJ |
3066 | @lisp |
3067 | (integer-expt 2 5) | |
3068 | @result{} 32 | |
3069 | (integer-expt -3 3) | |
3070 | @result{} -27 | |
3071 | @end lisp | |
3072 | @end deffn | |
3073 | ||
3074 | \fash | |
7a095584 | 3075 | @c snarfed from numbers.c:1168 |
780ee65e | 3076 | @deffn primitive ash n cnt |
ae9f3a15 MG |
3077 | The function ash performs an arithmetic shift left by @var{cnt} |
3078 | bits (or shift right, if @var{cnt} is negative). 'Arithmetic' | |
3079 | means, that the function does not guarantee to keep the bit | |
3080 | structure of @var{n}, but rather guarantees that the result | |
3081 | will always be rounded towards minus infinity. Therefore, the | |
3082 | results of ash and a corresponding bitwise shift will differ if | |
3083 | @var{n} is negative. | |
7a095584 | 3084 | |
780ee65e NJ |
3085 | Formally, the function returns an integer equivalent to |
3086 | @code{(inexact->exact (floor (* @var{n} (expt 2 @var{cnt}))))}. | |
7a095584 | 3087 | |
780ee65e | 3088 | @lisp |
ae9f3a15 MG |
3089 | (number->string (ash #b1 3) 2) @result{} "1000" |
3090 | (number->string (ash #b1010 -1) 2) @result{} "101" | |
780ee65e NJ |
3091 | @end lisp |
3092 | @end deffn | |
3093 | ||
3094 | \fbit-extract | |
7a095584 | 3095 | @c snarfed from numbers.c:1221 |
780ee65e | 3096 | @deffn primitive bit-extract n start end |
ae9f3a15 MG |
3097 | Return the integer composed of the @var{start} (inclusive) |
3098 | through @var{end} (exclusive) bits of @var{n}. The | |
3099 | @var{start}th bit becomes the 0-th bit in the result. | |
7a095584 | 3100 | |
780ee65e NJ |
3101 | @lisp |
3102 | (number->string (bit-extract #b1101101010 0 4) 2) | |
3103 | @result{} "1010" | |
3104 | (number->string (bit-extract #b1101101010 4 9) 2) | |
3105 | @result{} "10110" | |
3106 | @end lisp | |
3107 | @end deffn | |
3108 | ||
3109 | \flogcount | |
7a095584 | 3110 | @c snarfed from numbers.c:1293 |
780ee65e | 3111 | @deffn primitive logcount n |
ae9f3a15 MG |
3112 | Return the number of bits in integer @var{n}. If integer is |
3113 | positive, the 1-bits in its binary representation are counted. | |
3114 | If negative, the 0-bits in its two's-complement binary | |
3115 | representation are counted. If 0, 0 is returned. | |
7a095584 | 3116 | |
780ee65e NJ |
3117 | @lisp |
3118 | (logcount #b10101010) | |
3119 | @result{} 4 | |
3120 | (logcount 0) | |
3121 | @result{} 0 | |
3122 | (logcount -2) | |
3123 | @result{} 1 | |
3124 | @end lisp | |
3125 | @end deffn | |
3126 | ||
3127 | \finteger-length | |
7a095584 | 3128 | @c snarfed from numbers.c:1344 |
780ee65e | 3129 | @deffn primitive integer-length n |
ae9f3a15 | 3130 | Return the number of bits neccessary to represent @var{n}. |
7a095584 | 3131 | |
780ee65e NJ |
3132 | @lisp |
3133 | (integer-length #b10101010) | |
3134 | @result{} 8 | |
3135 | (integer-length 0) | |
3136 | @result{} 0 | |
3137 | (integer-length #b1111) | |
3138 | @result{} 4 | |
3139 | @end lisp | |
3140 | @end deffn | |
3141 | ||
3142 | \fnumber->string | |
7a095584 | 3143 | @c snarfed from numbers.c:2290 |
780ee65e NJ |
3144 | @deffn primitive number->string n [radix] |
3145 | Return a string holding the external representation of the | |
3146 | number @var{n} in the given @var{radix}. If @var{n} is | |
3147 | inexact, a radix of 10 will be used. | |
3148 | @end deffn | |
3149 | ||
3150 | \fstring->number | |
7a095584 | 3151 | @c snarfed from numbers.c:2875 |
780ee65e | 3152 | @deffn primitive string->number string [radix] |
ae9f3a15 | 3153 | Return a number of the maximally precise representation |
780ee65e NJ |
3154 | expressed by the given @var{string}. @var{radix} must be an |
3155 | exact integer, either 2, 8, 10, or 16. If supplied, @var{radix} | |
3156 | is a default radix that may be overridden by an explicit radix | |
3157 | prefix in @var{string} (e.g. "#o177"). If @var{radix} is not | |
3158 | supplied, then the default radix is 10. If string is not a | |
3159 | syntactically valid notation for a number, then | |
3160 | @code{string->number} returns @code{#f}. | |
3161 | @end deffn | |
3162 | ||
3163 | \fnumber? | |
7a095584 | 3164 | @c snarfed from numbers.c:2942 |
780ee65e NJ |
3165 | @deffn primitive number? |
3166 | scm_number_p | |
3167 | @end deffn | |
3168 | ||
3169 | \fcomplex? | |
7a095584 | 3170 | @c snarfed from numbers.c:2954 |
780ee65e NJ |
3171 | @deffn primitive complex? x |
3172 | Return @code{#t} if @var{x} is a complex number, @code{#f} | |
3173 | else. Note that the sets of real, rational and integer | |
3174 | values form subsets of the set of complex numbers, i. e. the | |
3175 | predicate will also be fulfilled if @var{x} is a real, | |
3176 | rational or integer number. | |
3177 | @end deffn | |
3178 | ||
3179 | \freal? | |
7a095584 | 3180 | @c snarfed from numbers.c:2962 |
780ee65e NJ |
3181 | @deffn primitive real? |
3182 | scm_real_p | |
3183 | @end deffn | |
3184 | ||
3185 | \frational? | |
7a095584 | 3186 | @c snarfed from numbers.c:2975 |
780ee65e NJ |
3187 | @deffn primitive rational? x |
3188 | Return @code{#t} if @var{x} is a rational number, @code{#f} | |
3189 | else. Note that the set of integer values forms a subset of | |
3190 | the set of rational numbers, i. e. the predicate will also be | |
3191 | fulfilled if @var{x} is an integer number. Real numbers | |
3192 | will also satisfy this predicate, because of their limited | |
3193 | precision. | |
3194 | @end deffn | |
3195 | ||
3196 | \finteger? | |
7a095584 | 3197 | @c snarfed from numbers.c:2996 |
780ee65e NJ |
3198 | @deffn primitive integer? x |
3199 | Return @code{#t} if @var{x} is an integer number, @code{#f} | |
3200 | else. | |
3201 | @end deffn | |
3202 | ||
3203 | \finexact? | |
7a095584 | 3204 | @c snarfed from numbers.c:3021 |
780ee65e NJ |
3205 | @deffn primitive inexact? x |
3206 | Return @code{#t} if @var{x} is an inexact number, @code{#f} | |
3207 | else. | |
3208 | @end deffn | |
3209 | ||
3210 | \f$expt | |
7a095584 | 3211 | @c snarfed from numbers.c:4073 |
780ee65e NJ |
3212 | @deffn primitive $expt x y |
3213 | Return @var{x} raised to the power of @var{y}. This | |
3214 | procedure does not accept complex arguments. | |
3215 | @end deffn | |
3216 | ||
3217 | \f$atan2 | |
7a095584 | 3218 | @c snarfed from numbers.c:4089 |
780ee65e NJ |
3219 | @deffn primitive $atan2 x y |
3220 | Return the arc tangent of the two arguments @var{x} and | |
3221 | @var{y}. This is similar to calculating the arc tangent of | |
3222 | @var{x} / @var{y}, except that the signs of both arguments | |
3223 | are used to determine the quadrant of the result. This | |
3224 | procedure does not accept complex arguments. | |
3225 | @end deffn | |
3226 | ||
3227 | \fmake-rectangular | |
7a095584 | 3228 | @c snarfed from numbers.c:4102 |
780ee65e NJ |
3229 | @deffn primitive make-rectangular real imaginary |
3230 | Return a complex number constructed of the given @var{real} and | |
3231 | @var{imaginary} parts. | |
3232 | @end deffn | |
3233 | ||
3234 | \fmake-polar | |
7a095584 | 3235 | @c snarfed from numbers.c:4115 |
780ee65e NJ |
3236 | @deffn primitive make-polar x y |
3237 | Return the complex number @var{x} * e^(i * @var{y}). | |
3238 | @end deffn | |
3239 | ||
3240 | \finexact->exact | |
7a095584 | 3241 | @c snarfed from numbers.c:4233 |
780ee65e | 3242 | @deffn primitive inexact->exact z |
ae9f3a15 | 3243 | Return an exact number that is numerically closest to @var{z}. |
780ee65e NJ |
3244 | @end deffn |
3245 | ||
3246 | \fclass-of | |
3247 | @c snarfed from objects.c:88 | |
3248 | @deffn primitive class-of x | |
3249 | Return the class of @var{x}. | |
3250 | @end deffn | |
3251 | ||
3252 | \fentity? | |
3253 | @c snarfed from objects.c:359 | |
3254 | @deffn primitive entity? obj | |
3255 | Return @code{#t} if @var{obj} is an entity. | |
3256 | @end deffn | |
3257 | ||
3258 | \foperator? | |
3259 | @c snarfed from objects.c:368 | |
3260 | @deffn primitive operator? obj | |
3261 | Return @code{#t} if @var{obj} is an operator. | |
3262 | @end deffn | |
3263 | ||
3264 | \fset-object-procedure! | |
3265 | @c snarfed from objects.c:380 | |
3266 | @deffn primitive set-object-procedure! obj proc | |
3267 | Return the object procedure of @var{obj} to @var{proc}. | |
3268 | @var{obj} must be either an entity or an operator. | |
3269 | @end deffn | |
3270 | ||
3271 | \fmake-class-object | |
3272 | @c snarfed from objects.c:440 | |
3273 | @deffn primitive make-class-object metaclass layout | |
3274 | Create a new class object of class @var{metaclass}, with the | |
3275 | slot layout specified by @var{layout}. | |
3276 | @end deffn | |
3277 | ||
3278 | \fmake-subclass-object | |
3279 | @c snarfed from objects.c:455 | |
3280 | @deffn primitive make-subclass-object class layout | |
3281 | Create a subclass object of @var{class}, with the slot layout | |
3282 | specified by @var{layout}. | |
3283 | @end deffn | |
3284 | ||
3285 | \fobject-properties | |
3286 | @c snarfed from objprop.c:62 | |
3287 | @deffn primitive object-properties obj | |
3288 | @deffnx primitive procedure-properties obj | |
3289 | Return @var{obj}'s property list. | |
3290 | @end deffn | |
3291 | ||
3292 | \fset-object-properties! | |
3293 | @c snarfed from objprop.c:73 | |
ae9f3a15 | 3294 | @deffn primitive set-object-properties! obj alist |
780ee65e NJ |
3295 | @deffnx primitive set-procedure-properties! obj alist |
3296 | Set @var{obj}'s property list to @var{alist}. | |
3297 | @end deffn | |
3298 | ||
3299 | \fobject-property | |
3300 | @c snarfed from objprop.c:85 | |
3301 | @deffn primitive object-property obj key | |
3302 | @deffnx primitive procedure-property obj key | |
3303 | Return the property of @var{obj} with name @var{key}. | |
3304 | @end deffn | |
3305 | ||
3306 | \fset-object-property! | |
3307 | @c snarfed from objprop.c:98 | |
ae9f3a15 | 3308 | @deffn primitive set-object-property! obj key value |
780ee65e | 3309 | @deffnx primitive set-procedure-property! obj key value |
ae9f3a15 MG |
3310 | In @var{obj}'s property list, set the property named @var{key} |
3311 | to @var{value}. | |
780ee65e NJ |
3312 | @end deffn |
3313 | ||
3314 | \fcons | |
3315 | @c snarfed from pairs.c:61 | |
3316 | @deffn primitive cons x y | |
ae9f3a15 MG |
3317 | Return a newly allocated pair whose car is @var{x} and whose |
3318 | cdr is @var{y}. The pair is guaranteed to be different (in the | |
3319 | sense of @code{eq?}) from every previously existing object. | |
780ee65e NJ |
3320 | @end deffn |
3321 | ||
3322 | \fpair? | |
89d04205 | 3323 | @c snarfed from pairs.c:94 |
780ee65e | 3324 | @deffn primitive pair? x |
ae9f3a15 MG |
3325 | Return @code{#t} if @var{x} is a pair; otherwise return |
3326 | @code{#f}. | |
780ee65e NJ |
3327 | @end deffn |
3328 | ||
3329 | \fset-car! | |
89d04205 | 3330 | @c snarfed from pairs.c:105 |
780ee65e NJ |
3331 | @deffn primitive set-car! pair value |
3332 | Stores @var{value} in the car field of @var{pair}. The value returned | |
3333 | by @code{set-car!} is unspecified. | |
3334 | @end deffn | |
3335 | ||
3336 | \fset-cdr! | |
89d04205 | 3337 | @c snarfed from pairs.c:118 |
780ee65e NJ |
3338 | @deffn primitive set-cdr! pair value |
3339 | Stores @var{value} in the cdr field of @var{pair}. The value returned | |
3340 | by @code{set-cdr!} is unspecified. | |
3341 | @end deffn | |
3342 | ||
3343 | \fchar-ready? | |
3344 | @c snarfed from ports.c:246 | |
3345 | @deffn primitive char-ready? [port] | |
ae9f3a15 MG |
3346 | Return @code{#t} if a character is ready on input @var{port} |
3347 | and return @code{#f} otherwise. If @code{char-ready?} returns | |
3348 | @code{#t} then the next @code{read-char} operation on | |
3349 | @var{port} is guaranteed not to hang. If @var{port} is a file | |
3350 | port at end of file then @code{char-ready?} returns @code{#t}. | |
780ee65e | 3351 | @footnote{@code{char-ready?} exists to make it possible for a |
ae9f3a15 MG |
3352 | program to accept characters from interactive ports without |
3353 | getting stuck waiting for input. Any input editors associated | |
3354 | with such ports must make sure that characters whose existence | |
3355 | has been asserted by @code{char-ready?} cannot be rubbed out. | |
3356 | If @code{char-ready?} were to return @code{#f} at end of file, | |
3357 | a port at end of file would be indistinguishable from an | |
3358 | interactive port that has no ready characters.} | |
780ee65e NJ |
3359 | @end deffn |
3360 | ||
3361 | \fdrain-input | |
3362 | @c snarfed from ports.c:312 | |
3363 | @deffn primitive drain-input port | |
3364 | Drain @var{port}'s read buffers (including any pushed-back | |
ae9f3a15 | 3365 | characters) and return the content as a single string. |
780ee65e NJ |
3366 | @end deffn |
3367 | ||
3368 | \fcurrent-input-port | |
3369 | @c snarfed from ports.c:339 | |
3370 | @deffn primitive current-input-port | |
3371 | Return the current input port. This is the default port used | |
3372 | by many input procedures. Initially, @code{current-input-port} | |
3373 | returns the @dfn{standard input} in Unix and C terminology. | |
3374 | @end deffn | |
3375 | ||
3376 | \fcurrent-output-port | |
3377 | @c snarfed from ports.c:351 | |
3378 | @deffn primitive current-output-port | |
3379 | Return the current output port. This is the default port used | |
3380 | by many output procedures. Initially, | |
3381 | @code{current-output-port} returns the @dfn{standard output} in | |
3382 | Unix and C terminology. | |
3383 | @end deffn | |
3384 | ||
3385 | \fcurrent-error-port | |
3386 | @c snarfed from ports.c:361 | |
3387 | @deffn primitive current-error-port | |
3388 | Return the port to which errors and warnings should be sent (the | |
3389 | @dfn{standard error} in Unix and C terminology). | |
3390 | @end deffn | |
3391 | ||
3392 | \fcurrent-load-port | |
3393 | @c snarfed from ports.c:371 | |
3394 | @deffn primitive current-load-port | |
3395 | Return the current-load-port. | |
3396 | The load port is used internally by @code{primitive-load}. | |
3397 | @end deffn | |
3398 | ||
3399 | \fset-current-input-port | |
3400 | @c snarfed from ports.c:384 | |
3401 | @deffn primitive set-current-input-port port | |
3402 | @deffnx primitive set-current-output-port port | |
3403 | @deffnx primitive set-current-error-port port | |
3404 | Change the ports returned by @code{current-input-port}, | |
3405 | @code{current-output-port} and @code{current-error-port}, respectively, | |
3406 | so that they use the supplied @var{port} for input or output. | |
3407 | @end deffn | |
3408 | ||
3409 | \fset-current-output-port | |
3410 | @c snarfed from ports.c:397 | |
3411 | @deffn primitive set-current-output-port port | |
3412 | Set the current default output port to @var{port}. | |
3413 | @end deffn | |
3414 | ||
3415 | \fset-current-error-port | |
3416 | @c snarfed from ports.c:411 | |
3417 | @deffn primitive set-current-error-port port | |
3418 | Set the current default error port to @var{port}. | |
3419 | @end deffn | |
3420 | ||
3421 | \fport-revealed | |
3422 | @c snarfed from ports.c:556 | |
3423 | @deffn primitive port-revealed port | |
ae9f3a15 | 3424 | Return the revealed count for @var{port}. |
780ee65e NJ |
3425 | @end deffn |
3426 | ||
3427 | \fset-port-revealed! | |
3428 | @c snarfed from ports.c:569 | |
3429 | @deffn primitive set-port-revealed! port rcount | |
3430 | Sets the revealed count for a port to a given value. | |
3431 | The return value is unspecified. | |
3432 | @end deffn | |
3433 | ||
3434 | \fport-mode | |
3435 | @c snarfed from ports.c:612 | |
3436 | @deffn primitive port-mode port | |
ae9f3a15 MG |
3437 | Return the port modes associated with the open port @var{port}. |
3438 | These will not necessarily be identical to the modes used when | |
3439 | the port was opened, since modes such as "append" which are | |
3440 | used only during port creation are not retained. | |
780ee65e NJ |
3441 | @end deffn |
3442 | ||
3443 | \fclose-port | |
3444 | @c snarfed from ports.c:649 | |
3445 | @deffn primitive close-port port | |
ae9f3a15 MG |
3446 | Close the specified port object. Return @code{#t} if it |
3447 | successfully closes a port or @code{#f} if it was already | |
3448 | closed. An exception may be raised if an error occurs, for | |
3449 | example when flushing buffered output. See also @ref{Ports and | |
3450 | File Descriptors, close}, for a procedure which can close file | |
3451 | descriptors. | |
780ee65e NJ |
3452 | @end deffn |
3453 | ||
3454 | \fclose-input-port | |
3455 | @c snarfed from ports.c:677 | |
3456 | @deffn primitive close-input-port port | |
3457 | Close the specified input port object. The routine has no effect if | |
3458 | the file has already been closed. An exception may be raised if an | |
3459 | error occurs. The value returned is unspecified. | |
3460 | ||
3461 | See also @ref{Ports and File Descriptors, close}, for a procedure | |
3462 | which can close file descriptors. | |
3463 | @end deffn | |
3464 | ||
3465 | \fclose-output-port | |
3466 | @c snarfed from ports.c:692 | |
3467 | @deffn primitive close-output-port port | |
3468 | Close the specified output port object. The routine has no effect if | |
3469 | the file has already been closed. An exception may be raised if an | |
3470 | error occurs. The value returned is unspecified. | |
3471 | ||
3472 | See also @ref{Ports and File Descriptors, close}, for a procedure | |
3473 | which can close file descriptors. | |
3474 | @end deffn | |
3475 | ||
3476 | \fport-for-each | |
3477 | @c snarfed from ports.c:709 | |
3478 | @deffn primitive port-for-each proc | |
3479 | Apply @var{proc} to each port in the Guile port table | |
3480 | in turn. The return value is unspecified. More specifically, | |
3481 | @var{proc} is applied exactly once to every port that exists | |
3482 | in the system at the time @var{port-for-each} is invoked. | |
3483 | Changes to the port table while @var{port-for-each} is running | |
3484 | have no effect as far as @var{port-for-each} is concerned. | |
3485 | @end deffn | |
3486 | ||
3487 | \fclose-all-ports-except | |
3488 | @c snarfed from ports.c:752 | |
3489 | @deffn primitive close-all-ports-except . ports | |
3490 | [DEPRECATED] Close all open file ports used by the interpreter | |
3491 | except for those supplied as arguments. This procedure | |
3492 | was intended to be used before an exec call to close file descriptors | |
3493 | which are not needed in the new process. However it has the | |
3494 | undesirable side-effect of flushing buffes, so it's deprecated. | |
3495 | Use port-for-each instead. | |
3496 | @end deffn | |
3497 | ||
3498 | \finput-port? | |
3499 | @c snarfed from ports.c:791 | |
3500 | @deffn primitive input-port? x | |
ae9f3a15 | 3501 | Return @code{#t} if @var{x} is an input port, otherwise return |
780ee65e NJ |
3502 | @code{#f}. Any object satisfying this predicate also satisfies |
3503 | @code{port?}. | |
3504 | @end deffn | |
3505 | ||
3506 | \foutput-port? | |
3507 | @c snarfed from ports.c:804 | |
3508 | @deffn primitive output-port? x | |
ae9f3a15 | 3509 | Return @code{#t} if @var{x} is an output port, otherwise return |
780ee65e NJ |
3510 | @code{#f}. Any object satisfying this predicate also satisfies |
3511 | @code{port?}. | |
3512 | @end deffn | |
3513 | ||
3514 | \fport? | |
3515 | @c snarfed from ports.c:819 | |
3516 | @deffn primitive port? x | |
ae9f3a15 | 3517 | Return a boolean indicating whether @var{x} is a port. |
780ee65e NJ |
3518 | Equivalent to @code{(or (input-port? @var{x}) (output-port? |
3519 | @var{x}))}. | |
3520 | @end deffn | |
3521 | ||
3522 | \fport-closed? | |
89d04205 | 3523 | @c snarfed from ports.c:829 |
780ee65e | 3524 | @deffn primitive port-closed? port |
ae9f3a15 MG |
3525 | Return @code{#t} if @var{port} is closed or @code{#f} if it is |
3526 | open. | |
780ee65e NJ |
3527 | @end deffn |
3528 | ||
3529 | \feof-object? | |
89d04205 | 3530 | @c snarfed from ports.c:840 |
780ee65e | 3531 | @deffn primitive eof-object? x |
ae9f3a15 MG |
3532 | Return @code{#t} if @var{x} is an end-of-file object; otherwise |
3533 | return @code{#f}. | |
780ee65e NJ |
3534 | @end deffn |
3535 | ||
3536 | \fforce-output | |
89d04205 | 3537 | @c snarfed from ports.c:854 |
780ee65e NJ |
3538 | @deffn primitive force-output [port] |
3539 | Flush the specified output port, or the current output port if @var{port} | |
3540 | is omitted. The current output buffer contents are passed to the | |
3541 | underlying port implementation (e.g., in the case of fports, the | |
3542 | data will be written to the file and the output buffer will be cleared.) | |
3543 | It has no effect on an unbuffered port. | |
3544 | ||
3545 | The return value is unspecified. | |
3546 | @end deffn | |
3547 | ||
3548 | \fflush-all-ports | |
89d04205 | 3549 | @c snarfed from ports.c:872 |
780ee65e NJ |
3550 | @deffn primitive flush-all-ports |
3551 | Equivalent to calling @code{force-output} on | |
3552 | all open output ports. The return value is unspecified. | |
3553 | @end deffn | |
3554 | ||
3555 | \fread-char | |
89d04205 | 3556 | @c snarfed from ports.c:890 |
780ee65e | 3557 | @deffn primitive read-char [port] |
ae9f3a15 | 3558 | Return the next character available from @var{port}, updating |
780ee65e | 3559 | @var{port} to point to the following character. If no more |
ae9f3a15 | 3560 | characters are available, the end-of-file object is returned. |
780ee65e NJ |
3561 | @end deffn |
3562 | ||
3563 | \fpeek-char | |
89d04205 | 3564 | @c snarfed from ports.c:1207 |
780ee65e | 3565 | @deffn primitive peek-char [port] |
ae9f3a15 | 3566 | Return the next character available from @var{port}, |
780ee65e | 3567 | @emph{without} updating @var{port} to point to the following |
ae9f3a15 MG |
3568 | character. If no more characters are available, the |
3569 | end-of-file object is returned.@footnote{The value returned by | |
3570 | a call to @code{peek-char} is the same as the value that would | |
3571 | have been returned by a call to @code{read-char} on the same | |
3572 | port. The only difference is that the very next call to | |
3573 | @code{read-char} or @code{peek-char} on that @var{port} will | |
3574 | return the value returned by the preceding call to | |
3575 | @code{peek-char}. In particular, a call to @code{peek-char} on | |
3576 | an interactive port will hang waiting for input whenever a call | |
3577 | to @code{read-char} would have hung.} | |
780ee65e NJ |
3578 | @end deffn |
3579 | ||
3580 | \funread-char | |
89d04205 | 3581 | @c snarfed from ports.c:1228 |
780ee65e NJ |
3582 | @deffn primitive unread-char cobj [port] |
3583 | Place @var{char} in @var{port} so that it will be read by the | |
3584 | next read operation. If called multiple times, the unread characters | |
3585 | will be read again in last-in first-out order. If @var{port} is | |
3586 | not supplied, the current input port is used. | |
3587 | @end deffn | |
3588 | ||
3589 | \funread-string | |
89d04205 | 3590 | @c snarfed from ports.c:1251 |
780ee65e NJ |
3591 | @deffn primitive unread-string str port |
3592 | Place the string @var{str} in @var{port} so that its characters will be | |
3593 | read in subsequent read operations. If called multiple times, the | |
3594 | unread characters will be read again in last-in first-out order. If | |
3595 | @var{port} is not supplied, the current-input-port is used. | |
3596 | @end deffn | |
3597 | ||
3598 | \fseek | |
89d04205 | 3599 | @c snarfed from ports.c:1290 |
ae9f3a15 MG |
3600 | @deffn primitive seek fd_port offset whence |
3601 | Sets the current position of @var{fd/port} to the integer | |
3602 | @var{offset}, which is interpreted according to the value of | |
3603 | @var{whence}. | |
7a095584 | 3604 | |
ae9f3a15 MG |
3605 | One of the following variables should be supplied for |
3606 | @var{whence}: | |
780ee65e NJ |
3607 | @defvar SEEK_SET |
3608 | Seek from the beginning of the file. | |
3609 | @end defvar | |
3610 | @defvar SEEK_CUR | |
3611 | Seek from the current position. | |
3612 | @end defvar | |
3613 | @defvar SEEK_END | |
3614 | Seek from the end of the file. | |
3615 | @end defvar | |
ae9f3a15 MG |
3616 | If @var{fd/port} is a file descriptor, the underlying system |
3617 | call is @code{lseek}. @var{port} may be a string port. | |
7a095584 | 3618 | |
ae9f3a15 MG |
3619 | The value returned is the new position in the file. This means |
3620 | that the current position of a port can be obtained using: | |
3621 | @lisp | |
780ee65e | 3622 | (seek port 0 SEEK_CUR) |
ae9f3a15 | 3623 | @end lisp |
780ee65e NJ |
3624 | @end deffn |
3625 | ||
3626 | \ftruncate-file | |
89d04205 | 3627 | @c snarfed from ports.c:1331 |
780ee65e | 3628 | @deffn primitive truncate-file object [length] |
ae9f3a15 MG |
3629 | Truncates the object referred to by @var{object} to at most |
3630 | @var{length} bytes. @var{object} can be a string containing a | |
3631 | file name or an integer file descriptor or a port. | |
3632 | @var{length} may be omitted if @var{object} is not a file name, | |
3633 | in which case the truncation occurs at the current port. | |
3634 | position. The return value is unspecified. | |
780ee65e NJ |
3635 | @end deffn |
3636 | ||
3637 | \fport-line | |
89d04205 | 3638 | @c snarfed from ports.c:1385 |
780ee65e NJ |
3639 | @deffn primitive port-line port |
3640 | Return the current line number for @var{port}. | |
3641 | @end deffn | |
3642 | ||
3643 | \fset-port-line! | |
89d04205 | 3644 | @c snarfed from ports.c:1396 |
780ee65e NJ |
3645 | @deffn primitive set-port-line! port line |
3646 | Set the current line number for @var{port} to @var{line}. | |
3647 | @end deffn | |
3648 | ||
3649 | \fport-column | |
89d04205 | 3650 | @c snarfed from ports.c:1417 |
780ee65e NJ |
3651 | @deffn primitive port-column port |
3652 | @deffnx primitive port-line port | |
3653 | Return the current column number or line number of @var{port}, | |
3654 | using the current input port if none is specified. If the number is | |
3655 | unknown, the result is #f. Otherwise, the result is a 0-origin integer | |
3656 | - i.e. the first character of the first line is line 0, column 0. | |
3657 | (However, when you display a file position, for example in an error | |
3658 | message, we recommend you add 1 to get 1-origin integers. This is | |
3659 | because lines and column numbers traditionally start with 1, and that is | |
3660 | what non-programmers will find most natural.) | |
3661 | @end deffn | |
3662 | ||
3663 | \fset-port-column! | |
89d04205 | 3664 | @c snarfed from ports.c:1430 |
780ee65e NJ |
3665 | @deffn primitive set-port-column! port column |
3666 | @deffnx primitive set-port-line! port line | |
3667 | Set the current column or line number of @var{port}, using the | |
3668 | current input port if none is specified. | |
3669 | @end deffn | |
3670 | ||
3671 | \fport-filename | |
89d04205 | 3672 | @c snarfed from ports.c:1445 |
780ee65e NJ |
3673 | @deffn primitive port-filename port |
3674 | Return the filename associated with @var{port}. This function returns | |
3675 | the strings "standard input", "standard output" and "standard error" | |
3676 | when called on the current input, output and error ports respectively. | |
3677 | @end deffn | |
3678 | ||
3679 | \fset-port-filename! | |
89d04205 | 3680 | @c snarfed from ports.c:1459 |
780ee65e NJ |
3681 | @deffn primitive set-port-filename! port filename |
3682 | Change the filename associated with @var{port}, using the current input | |
3683 | port if none is specified. Note that this does not change the port's | |
3684 | source of data, but only the value that is returned by | |
3685 | @code{port-filename} and reported in diagnostic output. | |
3686 | @end deffn | |
3687 | ||
3688 | \f%make-void-port | |
89d04205 | 3689 | @c snarfed from ports.c:1551 |
780ee65e NJ |
3690 | @deffn primitive %make-void-port mode |
3691 | Create and return a new void port. A void port acts like | |
3692 | /dev/null. The @var{mode} argument | |
3693 | specifies the input/output modes for this port: see the | |
3694 | documentation for @code{open-file} in @ref{File Ports}. | |
3695 | @end deffn | |
3696 | ||
3697 | \fpipe | |
3698 | @c snarfed from posix.c:201 | |
3699 | @deffn primitive pipe | |
ae9f3a15 MG |
3700 | Return a newly created pipe: a pair of ports which are linked |
3701 | together on the local machine. The @emph{car} is the input | |
3702 | port and the @emph{cdr} is the output port. Data written (and | |
3703 | flushed) to the output port can be read from the input port. | |
3704 | Pipes are commonly used for communication with a newly forked | |
3705 | child process. The need to flush the output port can be | |
3706 | avoided by making it unbuffered using @code{setvbuf}. | |
7a095584 | 3707 | |
ae9f3a15 MG |
3708 | Writes occur atomically provided the size of the data in bytes |
3709 | is not greater than the value of @code{PIPE_BUF}. Note that | |
3710 | the output port is likely to block if too much data (typically | |
3711 | equal to @code{PIPE_BUF}) has been written but not yet read | |
3712 | from the input port. | |
780ee65e NJ |
3713 | @end deffn |
3714 | ||
3715 | \fgetgroups | |
89d04205 | 3716 | @c snarfed from posix.c:222 |
780ee65e | 3717 | @deffn primitive getgroups |
ae9f3a15 MG |
3718 | Return a vector of integers representing the current |
3719 | supplimentary group IDs. | |
780ee65e NJ |
3720 | @end deffn |
3721 | ||
3722 | \fgetpw | |
89d04205 | 3723 | @c snarfed from posix.c:255 |
780ee65e NJ |
3724 | @deffn primitive getpw [user] |
3725 | Look up an entry in the user database. @var{obj} can be an integer, | |
3726 | a string, or omitted, giving the behaviour of getpwuid, getpwnam | |
3727 | or getpwent respectively. | |
3728 | @end deffn | |
3729 | ||
3730 | \fsetpw | |
89d04205 | 3731 | @c snarfed from posix.c:308 |
780ee65e NJ |
3732 | @deffn primitive setpw [arg] |
3733 | If called with a true argument, initialize or reset the password data | |
3734 | stream. Otherwise, close the stream. The @code{setpwent} and | |
3735 | @code{endpwent} procedures are implemented on top of this. | |
3736 | @end deffn | |
3737 | ||
3738 | \fgetgr | |
89d04205 | 3739 | @c snarfed from posix.c:327 |
780ee65e NJ |
3740 | @deffn primitive getgr [name] |
3741 | Look up an entry in the group database. @var{obj} can be an integer, | |
3742 | a string, or omitted, giving the behaviour of getgrgid, getgrnam | |
3743 | or getgrent respectively. | |
3744 | @end deffn | |
3745 | ||
3746 | \fsetgr | |
89d04205 | 3747 | @c snarfed from posix.c:368 |
780ee65e NJ |
3748 | @deffn primitive setgr [arg] |
3749 | If called with a true argument, initialize or reset the group data | |
3750 | stream. Otherwise, close the stream. The @code{setgrent} and | |
3751 | @code{endgrent} procedures are implemented on top of this. | |
3752 | @end deffn | |
3753 | ||
3754 | \fkill | |
89d04205 | 3755 | @c snarfed from posix.c:404 |
780ee65e NJ |
3756 | @deffn primitive kill pid sig |
3757 | Sends a signal to the specified process or group of processes. | |
3758 | ||
3759 | @var{pid} specifies the processes to which the signal is sent: | |
3760 | ||
3761 | @table @r | |
3762 | @item @var{pid} greater than 0 | |
3763 | The process whose identifier is @var{pid}. | |
3764 | @item @var{pid} equal to 0 | |
3765 | All processes in the current process group. | |
3766 | @item @var{pid} less than -1 | |
3767 | The process group whose identifier is -@var{pid} | |
3768 | @item @var{pid} equal to -1 | |
3769 | If the process is privileged, all processes except for some special | |
3770 | system processes. Otherwise, all processes with the current effective | |
3771 | user ID. | |
3772 | @end table | |
3773 | ||
3774 | @var{sig} should be specified using a variable corresponding to | |
3775 | the Unix symbolic name, e.g., | |
3776 | ||
3777 | @defvar SIGHUP | |
3778 | Hang-up signal. | |
3779 | @end defvar | |
3780 | ||
3781 | @defvar SIGINT | |
3782 | Interrupt signal. | |
3783 | @end defvar | |
3784 | @end deffn | |
3785 | ||
3786 | \fwaitpid | |
89d04205 | 3787 | @c snarfed from posix.c:452 |
780ee65e NJ |
3788 | @deffn primitive waitpid pid [options] |
3789 | This procedure collects status information from a child process which | |
3790 | has terminated or (optionally) stopped. Normally it will | |
3791 | suspend the calling process until this can be done. If more than one | |
3792 | child process is eligible then one will be chosen by the operating system. | |
3793 | ||
3794 | The value of @var{pid} determines the behaviour: | |
3795 | ||
3796 | @table @r | |
3797 | @item @var{pid} greater than 0 | |
3798 | Request status information from the specified child process. | |
3799 | @item @var{pid} equal to -1 or WAIT_ANY | |
3800 | Request status information for any child process. | |
3801 | @item @var{pid} equal to 0 or WAIT_MYPGRP | |
3802 | Request status information for any child process in the current process | |
3803 | group. | |
3804 | @item @var{pid} less than -1 | |
3805 | Request status information for any child process whose process group ID | |
3806 | is -@var{PID}. | |
3807 | @end table | |
3808 | ||
3809 | The @var{options} argument, if supplied, should be the bitwise OR of the | |
3810 | values of zero or more of the following variables: | |
3811 | ||
3812 | @defvar WNOHANG | |
3813 | Return immediately even if there are no child processes to be collected. | |
3814 | @end defvar | |
3815 | ||
3816 | @defvar WUNTRACED | |
3817 | Report status information for stopped processes as well as terminated | |
3818 | processes. | |
3819 | @end defvar | |
3820 | ||
3821 | The return value is a pair containing: | |
3822 | ||
3823 | @enumerate | |
3824 | @item | |
3825 | The process ID of the child process, or 0 if @code{WNOHANG} was | |
3826 | specified and no process was collected. | |
3827 | @item | |
3828 | The integer status value. | |
3829 | @end enumerate | |
3830 | @end deffn | |
3831 | ||
3832 | \fstatus:exit-val | |
89d04205 | 3833 | @c snarfed from posix.c:479 |
780ee65e | 3834 | @deffn primitive status:exit-val status |
ae9f3a15 MG |
3835 | Return the exit status value, as would be set if a process |
3836 | ended normally through a call to @code{exit} or @code{_exit}, | |
3837 | if any, otherwise @code{#f}. | |
780ee65e NJ |
3838 | @end deffn |
3839 | ||
3840 | \fstatus:term-sig | |
89d04205 | 3841 | @c snarfed from posix.c:499 |
780ee65e | 3842 | @deffn primitive status:term-sig status |
ae9f3a15 MG |
3843 | Return the signal number which terminated the process, if any, |
3844 | otherwise @code{#f}. | |
780ee65e NJ |
3845 | @end deffn |
3846 | ||
3847 | \fstatus:stop-sig | |
89d04205 | 3848 | @c snarfed from posix.c:517 |
780ee65e | 3849 | @deffn primitive status:stop-sig status |
ae9f3a15 MG |
3850 | Return the signal number which stopped the process, if any, |
3851 | otherwise @code{#f}. | |
780ee65e NJ |
3852 | @end deffn |
3853 | ||
3854 | \fgetppid | |
89d04205 | 3855 | @c snarfed from posix.c:535 |
780ee65e | 3856 | @deffn primitive getppid |
ae9f3a15 MG |
3857 | Return an integer representing the process ID of the parent |
3858 | process. | |
780ee65e NJ |
3859 | @end deffn |
3860 | ||
3861 | \fgetuid | |
89d04205 | 3862 | @c snarfed from posix.c:546 |
780ee65e | 3863 | @deffn primitive getuid |
ae9f3a15 | 3864 | Return an integer representing the current real user ID. |
780ee65e NJ |
3865 | @end deffn |
3866 | ||
3867 | \fgetgid | |
89d04205 | 3868 | @c snarfed from posix.c:557 |
780ee65e | 3869 | @deffn primitive getgid |
ae9f3a15 | 3870 | Return an integer representing the current real group ID. |
780ee65e NJ |
3871 | @end deffn |
3872 | ||
3873 | \fgeteuid | |
89d04205 | 3874 | @c snarfed from posix.c:571 |
780ee65e | 3875 | @deffn primitive geteuid |
ae9f3a15 | 3876 | Return an integer representing the current effective user ID. |
780ee65e | 3877 | If the system does not support effective IDs, then the real ID |
ae9f3a15 MG |
3878 | is returned. @code{(feature? 'EIDs)} reports whether the |
3879 | system supports effective IDs. | |
780ee65e NJ |
3880 | @end deffn |
3881 | ||
3882 | \fgetegid | |
89d04205 | 3883 | @c snarfed from posix.c:589 |
780ee65e | 3884 | @deffn primitive getegid |
ae9f3a15 | 3885 | Return an integer representing the current effective group ID. |
780ee65e | 3886 | If the system does not support effective IDs, then the real ID |
ae9f3a15 MG |
3887 | is returned. @code{(feature? 'EIDs)} reports whether the |
3888 | system supports effective IDs. | |
780ee65e NJ |
3889 | @end deffn |
3890 | ||
3891 | \fsetuid | |
89d04205 | 3892 | @c snarfed from posix.c:605 |
780ee65e NJ |
3893 | @deffn primitive setuid id |
3894 | Sets both the real and effective user IDs to the integer @var{id}, provided | |
3895 | the process has appropriate privileges. | |
3896 | The return value is unspecified. | |
3897 | @end deffn | |
3898 | ||
3899 | \fsetgid | |
89d04205 | 3900 | @c snarfed from posix.c:619 |
780ee65e NJ |
3901 | @deffn primitive setgid id |
3902 | Sets both the real and effective group IDs to the integer @var{id}, provided | |
3903 | the process has appropriate privileges. | |
3904 | The return value is unspecified. | |
3905 | @end deffn | |
3906 | ||
3907 | \fseteuid | |
89d04205 | 3908 | @c snarfed from posix.c:635 |
780ee65e NJ |
3909 | @deffn primitive seteuid id |
3910 | Sets the effective user ID to the integer @var{id}, provided the process | |
3911 | has appropriate privileges. If effective IDs are not supported, the | |
3912 | real ID is set instead -- @code{(feature? 'EIDs)} reports whether the | |
3913 | system supports effective IDs. | |
3914 | The return value is unspecified. | |
3915 | @end deffn | |
3916 | ||
3917 | \fsetegid | |
89d04205 | 3918 | @c snarfed from posix.c:659 |
780ee65e NJ |
3919 | @deffn primitive setegid id |
3920 | Sets the effective group ID to the integer @var{id}, provided the process | |
3921 | has appropriate privileges. If effective IDs are not supported, the | |
3922 | real ID is set instead -- @code{(feature? 'EIDs)} reports whether the | |
3923 | system supports effective IDs. | |
3924 | The return value is unspecified. | |
3925 | @end deffn | |
3926 | ||
3927 | \fgetpgrp | |
89d04205 | 3928 | @c snarfed from posix.c:681 |
780ee65e | 3929 | @deffn primitive getpgrp |
ae9f3a15 | 3930 | Return an integer representing the current process group ID. |
780ee65e NJ |
3931 | This is the POSIX definition, not BSD. |
3932 | @end deffn | |
3933 | ||
3934 | \fsetpgid | |
89d04205 | 3935 | @c snarfed from posix.c:697 |
780ee65e NJ |
3936 | @deffn primitive setpgid pid pgid |
3937 | Move the process @var{pid} into the process group @var{pgid}. @var{pid} or | |
3938 | @var{pgid} must be integers: they can be zero to indicate the ID of the | |
3939 | current process. | |
3940 | Fails on systems that do not support job control. | |
3941 | The return value is unspecified. | |
3942 | @end deffn | |
3943 | ||
3944 | \fsetsid | |
89d04205 | 3945 | @c snarfed from posix.c:716 |
780ee65e NJ |
3946 | @deffn primitive setsid |
3947 | Creates a new session. The current process becomes the session leader | |
3948 | and is put in a new process group. The process will be detached | |
3949 | from its controlling terminal if it has one. | |
3950 | The return value is an integer representing the new process group ID. | |
3951 | @end deffn | |
3952 | ||
3953 | \fttyname | |
89d04205 | 3954 | @c snarfed from posix.c:730 |
780ee65e | 3955 | @deffn primitive ttyname port |
ae9f3a15 MG |
3956 | Return a string with the name of the serial terminal device |
3957 | underlying @var{port}. | |
780ee65e NJ |
3958 | @end deffn |
3959 | ||
3960 | \fctermid | |
89d04205 | 3961 | @c snarfed from posix.c:753 |
780ee65e | 3962 | @deffn primitive ctermid |
ae9f3a15 MG |
3963 | Return a string containing the file name of the controlling |
3964 | terminal for the current process. | |
780ee65e NJ |
3965 | @end deffn |
3966 | ||
3967 | \ftcgetpgrp | |
89d04205 | 3968 | @c snarfed from posix.c:776 |
780ee65e | 3969 | @deffn primitive tcgetpgrp port |
ae9f3a15 MG |
3970 | Return the process group ID of the foreground process group |
3971 | associated with the terminal open on the file descriptor | |
780ee65e | 3972 | underlying @var{port}. |
7a095584 | 3973 | |
780ee65e NJ |
3974 | If there is no foreground process group, the return value is a |
3975 | number greater than 1 that does not match the process group ID | |
3976 | of any existing process group. This can happen if all of the | |
3977 | processes in the job that was formerly the foreground job have | |
3978 | terminated, and no other job has yet been moved into the | |
3979 | foreground. | |
3980 | @end deffn | |
3981 | ||
3982 | \ftcsetpgrp | |
89d04205 | 3983 | @c snarfed from posix.c:800 |
780ee65e NJ |
3984 | @deffn primitive tcsetpgrp port pgid |
3985 | Set the foreground process group ID for the terminal used by the file | |
3986 | descriptor underlying @var{port} to the integer @var{pgid}. | |
3987 | The calling process | |
3988 | must be a member of the same session as @var{pgid} and must have the same | |
3989 | controlling terminal. The return value is unspecified. | |
3990 | @end deffn | |
3991 | ||
3992 | \fexecl | |
89d04205 | 3993 | @c snarfed from posix.c:860 |
780ee65e NJ |
3994 | @deffn primitive execl filename . args |
3995 | Executes the file named by @var{path} as a new process image. | |
3996 | The remaining arguments are supplied to the process; from a C program | |
3997 | they are accessable as the @code{argv} argument to @code{main}. | |
3998 | Conventionally the first @var{arg} is the same as @var{path}. | |
3999 | All arguments must be strings. | |
4000 | ||
4001 | If @var{arg} is missing, @var{path} is executed with a null | |
4002 | argument list, which may have system-dependent side-effects. | |
4003 | ||
4004 | This procedure is currently implemented using the @code{execv} system | |
4005 | call, but we call it @code{execl} because of its Scheme calling interface. | |
4006 | @end deffn | |
4007 | ||
4008 | \fexeclp | |
89d04205 | 4009 | @c snarfed from posix.c:881 |
780ee65e NJ |
4010 | @deffn primitive execlp filename . args |
4011 | Similar to @code{execl}, however if | |
4012 | @var{filename} does not contain a slash | |
4013 | then the file to execute will be located by searching the | |
4014 | directories listed in the @code{PATH} environment variable. | |
4015 | ||
4016 | This procedure is currently implemented using the @code{execvp} system | |
4017 | call, but we call it @code{execlp} because of its Scheme calling interface. | |
4018 | @end deffn | |
4019 | ||
4020 | \fexecle | |
89d04205 | 4021 | @c snarfed from posix.c:932 |
780ee65e NJ |
4022 | @deffn primitive execle filename env . args |
4023 | Similar to @code{execl}, but the environment of the new process is | |
4024 | specified by @var{env}, which must be a list of strings as returned by the | |
4025 | @code{environ} procedure. | |
4026 | ||
4027 | This procedure is currently implemented using the @code{execve} system | |
4028 | call, but we call it @code{execle} because of its Scheme calling interface. | |
4029 | @end deffn | |
4030 | ||
4031 | \fprimitive-fork | |
89d04205 | 4032 | @c snarfed from posix.c:956 |
780ee65e NJ |
4033 | @deffn primitive primitive-fork |
4034 | Creates a new "child" process by duplicating the current "parent" process. | |
4035 | In the child the return value is 0. In the parent the return value is | |
4036 | the integer process ID of the child. | |
4037 | ||
4038 | This procedure has been renamed from @code{fork} to avoid a naming conflict | |
4039 | with the scsh fork. | |
4040 | @end deffn | |
4041 | ||
4042 | \funame | |
89d04205 | 4043 | @c snarfed from posix.c:971 |
780ee65e | 4044 | @deffn primitive uname |
ae9f3a15 MG |
4045 | Return an object with some information about the computer |
4046 | system the program is running on. | |
780ee65e NJ |
4047 | @end deffn |
4048 | ||
4049 | \fenviron | |
89d04205 | 4050 | @c snarfed from posix.c:1001 |
780ee65e | 4051 | @deffn primitive environ [env] |
ae9f3a15 MG |
4052 | If @var{env} is omitted, return the current environment (in the |
4053 | Unix sense) as a list of strings. Otherwise set the current | |
4054 | environment, which is also the default environment for child | |
4055 | processes, to the supplied list of strings. Each member of | |
4056 | @var{env} should be of the form @code{NAME=VALUE} and values of | |
4057 | @code{NAME} should not be duplicated. If @var{env} is supplied | |
4058 | then the return value is unspecified. | |
780ee65e NJ |
4059 | @end deffn |
4060 | ||
4061 | \ftmpnam | |
89d04205 | 4062 | @c snarfed from posix.c:1039 |
780ee65e | 4063 | @deffn primitive tmpnam |
ae9f3a15 MG |
4064 | Return a name in the file system that does not match any |
4065 | existing file. However there is no guarantee that another | |
4066 | process will not create the file after @code{tmpnam} is called. | |
4067 | Care should be taken if opening the file, e.g., use the | |
4068 | @code{O_EXCL} open flag or use @code{mkstemp!} instead. | |
780ee65e NJ |
4069 | @end deffn |
4070 | ||
4071 | \fmkstemp! | |
89d04205 | 4072 | @c snarfed from posix.c:1061 |
780ee65e | 4073 | @deffn primitive mkstemp! tmpl |
ae9f3a15 MG |
4074 | Create a new unique file in the file system and returns a new |
4075 | buffered port open for reading and writing to the file. | |
4076 | @var{tmpl} is a string specifying where the file should be | |
4077 | created: it must end with @code{XXXXXX} and will be changed in | |
4078 | place to return the name of the temporary file. | |
780ee65e NJ |
4079 | @end deffn |
4080 | ||
4081 | \futime | |
89d04205 | 4082 | @c snarfed from posix.c:1087 |
780ee65e | 4083 | @deffn primitive utime pathname [actime [modtime]] |
ae9f3a15 MG |
4084 | @code{utime} sets the access and modification times for the |
4085 | file named by @var{path}. If @var{actime} or @var{modtime} is | |
4086 | not supplied, then the current time is used. @var{actime} and | |
4087 | @var{modtime} must be integer time values as returned by the | |
4088 | @code{current-time} procedure. | |
4089 | @lisp | |
780ee65e | 4090 | (utime "foo" (- (current-time) 3600)) |
ae9f3a15 MG |
4091 | @end lisp |
4092 | will set the access time to one hour in the past and the | |
4093 | modification time to the current time. | |
780ee65e NJ |
4094 | @end deffn |
4095 | ||
4096 | \faccess? | |
89d04205 | 4097 | @c snarfed from posix.c:1136 |
780ee65e | 4098 | @deffn primitive access? path how |
ae9f3a15 MG |
4099 | Return @code{#t} if @var{path} corresponds to an existing file |
4100 | and the current process has the type of access specified by | |
4101 | @var{how}, otherwise @code{#f}. @var{how} should be specified | |
4102 | using the values of the variables listed below. Multiple | |
4103 | values can be combined using a bitwise or, in which case | |
4104 | @code{#t} will only be returned if all accesses are granted. | |
7a095584 | 4105 | |
ae9f3a15 MG |
4106 | Permissions are checked using the real id of the current |
4107 | process, not the effective id, although it's the effective id | |
4108 | which determines whether the access would actually be granted. | |
7a095584 | 4109 | |
780ee65e NJ |
4110 | @defvar R_OK |
4111 | test for read permission. | |
4112 | @end defvar | |
4113 | @defvar W_OK | |
4114 | test for write permission. | |
4115 | @end defvar | |
4116 | @defvar X_OK | |
4117 | test for execute permission. | |
4118 | @end defvar | |
4119 | @defvar F_OK | |
4120 | test for existence of the file. | |
4121 | @end defvar | |
4122 | @end deffn | |
4123 | ||
4124 | \fgetpid | |
89d04205 | 4125 | @c snarfed from posix.c:1151 |
780ee65e | 4126 | @deffn primitive getpid |
ae9f3a15 | 4127 | Return an integer representing the current process ID. |
780ee65e NJ |
4128 | @end deffn |
4129 | ||
4130 | \fputenv | |
89d04205 | 4131 | @c snarfed from posix.c:1168 |
780ee65e NJ |
4132 | @deffn primitive putenv str |
4133 | Modifies the environment of the current process, which is | |
4134 | also the default environment inherited by child processes. | |
4135 | ||
4136 | If @var{string} is of the form @code{NAME=VALUE} then it will be written | |
4137 | directly into the environment, replacing any existing environment string | |
4138 | with | |
4139 | name matching @code{NAME}. If @var{string} does not contain an equal | |
4140 | sign, then any existing string with name matching @var{string} will | |
4141 | be removed. | |
4142 | ||
4143 | The return value is unspecified. | |
4144 | @end deffn | |
4145 | ||
4146 | \fsetlocale | |
89d04205 | 4147 | @c snarfed from posix.c:1199 |
780ee65e | 4148 | @deffn primitive setlocale category [locale] |
ae9f3a15 MG |
4149 | If @var{locale} is omitted, return the current value of the |
4150 | specified locale category as a system-dependent string. | |
4151 | @var{category} should be specified using the values | |
4152 | @code{LC_COLLATE}, @code{LC_ALL} etc. | |
7a095584 | 4153 | |
ae9f3a15 MG |
4154 | Otherwise the specified locale category is set to the string |
4155 | @var{locale} and the new value is returned as a | |
4156 | system-dependent string. If @var{locale} is an empty string, | |
4157 | the locale will be set using envirionment variables. | |
780ee65e NJ |
4158 | @end deffn |
4159 | ||
4160 | \fmknod | |
89d04205 | 4161 | @c snarfed from posix.c:1240 |
780ee65e NJ |
4162 | @deffn primitive mknod path type perms dev |
4163 | Creates a new special file, such as a file corresponding to a device. | |
4164 | @var{path} specifies the name of the file. @var{type} should | |
4165 | be one of the following symbols: | |
4166 | regular, directory, symlink, block-special, char-special, | |
4167 | fifo, or socket. @var{perms} (an integer) specifies the file permissions. | |
4168 | @var{dev} (an integer) specifies which device the special file refers | |
4169 | to. Its exact interpretation depends on the kind of special file | |
4170 | being created. | |
4171 | ||
4172 | E.g., | |
ae9f3a15 | 4173 | @lisp |
780ee65e | 4174 | (mknod "/dev/fd0" 'block-special #o660 (+ (* 2 256) 2)) |
ae9f3a15 | 4175 | @end lisp |
780ee65e NJ |
4176 | |
4177 | The return value is unspecified. | |
4178 | @end deffn | |
4179 | ||
4180 | \fnice | |
89d04205 | 4181 | @c snarfed from posix.c:1287 |
780ee65e NJ |
4182 | @deffn primitive nice incr |
4183 | Increment the priority of the current process by @var{incr}. A higher | |
4184 | priority value means that the process runs less often. | |
4185 | The return value is unspecified. | |
4186 | @end deffn | |
4187 | ||
4188 | \fsync | |
89d04205 | 4189 | @c snarfed from posix.c:1302 |
780ee65e NJ |
4190 | @deffn primitive sync |
4191 | Flush the operating system disk buffers. | |
4192 | The return value is unspecified. | |
4193 | @end deffn | |
4194 | ||
4195 | \fcrypt | |
89d04205 | 4196 | @c snarfed from posix.c:1315 |
780ee65e NJ |
4197 | @deffn primitive crypt key salt |
4198 | Encrypt @var{key} using @var{salt} as the salt value to the | |
4199 | crypt(3) library call | |
4200 | @end deffn | |
4201 | ||
4202 | \fchroot | |
89d04205 | 4203 | @c snarfed from posix.c:1338 |
780ee65e NJ |
4204 | @deffn primitive chroot path |
4205 | Change the root directory to that specified in @var{path}. | |
4206 | This directory will be used for path names beginning with | |
4207 | @file{/}. The root directory is inherited by all children | |
4208 | of the current process. Only the superuser may change the | |
4209 | root directory. | |
4210 | @end deffn | |
4211 | ||
4212 | \fgetlogin | |
89d04205 | 4213 | @c snarfed from posix.c:1356 |
780ee65e NJ |
4214 | @deffn primitive getlogin |
4215 | Return a string containing the name of the user logged in on | |
4216 | the controlling terminal of the process, or @code{#f} if this | |
4217 | information cannot be obtained. | |
4218 | @end deffn | |
4219 | ||
4220 | \fcuserid | |
89d04205 | 4221 | @c snarfed from posix.c:1374 |
780ee65e NJ |
4222 | @deffn primitive cuserid |
4223 | Return a string containing a user name associated with the | |
4224 | effective user id of the process. Return @code{#f} if this | |
4225 | information cannot be obtained. | |
4226 | @end deffn | |
4227 | ||
4228 | \fgetpriority | |
89d04205 | 4229 | @c snarfed from posix.c:1399 |
780ee65e NJ |
4230 | @deffn primitive getpriority which who |
4231 | Return the scheduling priority of the process, process group | |
4232 | or user, as indicated by @var{which} and @var{who}. @var{which} | |
4233 | is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP} | |
4234 | or @code{PRIO_USER}, and @var{who} is interpreted relative to | |
4235 | @var{which} (a process identifier for @code{PRIO_PROCESS}, | |
4236 | process group identifier for @code{PRIO_PGRP}, and a user | |
4237 | identifier for @code{PRIO_USER}. A zero value of @var{who} | |
4238 | denotes the current process, process group, or user. Return | |
4239 | the highest priority (lowest numerical value) of any of the | |
4240 | specified processes. | |
4241 | @end deffn | |
4242 | ||
4243 | \fsetpriority | |
89d04205 | 4244 | @c snarfed from posix.c:1433 |
780ee65e NJ |
4245 | @deffn primitive setpriority which who prio |
4246 | Set the scheduling priority of the process, process group | |
4247 | or user, as indicated by @var{which} and @var{who}. @var{which} | |
4248 | is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP} | |
4249 | or @code{PRIO_USER}, and @var{who} is interpreted relative to | |
4250 | @var{which} (a process identifier for @code{PRIO_PROCESS}, | |
4251 | process group identifier for @code{PRIO_PGRP}, and a user | |
4252 | identifier for @code{PRIO_USER}. A zero value of @var{who} | |
4253 | denotes the current process, process group, or user. | |
4254 | @var{prio} is a value in the range -20 and 20, the default | |
4255 | priority is 0; lower priorities cause more favorable | |
4256 | scheduling. Sets the priority of all of the specified | |
4257 | processes. Only the super-user may lower priorities. | |
4258 | The return value is not specified. | |
4259 | @end deffn | |
4260 | ||
4261 | \fgetpass | |
89d04205 | 4262 | @c snarfed from posix.c:1458 |
780ee65e NJ |
4263 | @deffn primitive getpass prompt |
4264 | Display @var{prompt} to the standard error output and read | |
4265 | a password from @file{/dev/tty}. If this file is not | |
4266 | accessible, it reads from standard input. The password may be | |
4267 | up to 127 characters in length. Additional characters and the | |
4268 | terminating newline character are discarded. While reading | |
4269 | the password, echoing and the generation of signals by special | |
4270 | characters is disabled. | |
4271 | @end deffn | |
4272 | ||
4273 | \fflock | |
89d04205 | 4274 | @c snarfed from posix.c:1497 |
780ee65e NJ |
4275 | @deffn primitive flock file operation |
4276 | Apply or remove an advisory lock on an open file. | |
4277 | @var{operation} specifies the action to be done: | |
4278 | @table @code | |
4279 | @item LOCK_SH | |
4280 | Shared lock. More than one process may hold a shared lock | |
4281 | for a given file at a given time. | |
4282 | @item LOCK_EX | |
4283 | Exclusive lock. Only one process may hold an exclusive lock | |
4284 | for a given file at a given time. | |
4285 | @item LOCK_UN | |
4286 | Unlock the file. | |
4287 | @item LOCK_NB | |
4288 | Don't block when locking. May be specified by bitwise OR'ing | |
4289 | it to one of the other operations. | |
4290 | @end table | |
4291 | The return value is not specified. @var{file} may be an open | |
4292 | file descriptor or an open file descriptior port. | |
4293 | @end deffn | |
4294 | ||
4295 | \fsethostname | |
89d04205 | 4296 | @c snarfed from posix.c:1523 |
780ee65e NJ |
4297 | @deffn primitive sethostname name |
4298 | Set the host name of the current processor to @var{name}. May | |
4299 | only be used by the superuser. The return value is not | |
4300 | specified. | |
4301 | @end deffn | |
4302 | ||
4303 | \fgethostname | |
89d04205 | 4304 | @c snarfed from posix.c:1539 |
780ee65e NJ |
4305 | @deffn primitive gethostname |
4306 | Return the host name of the current processor. | |
4307 | @end deffn | |
4308 | ||
4309 | \fprint-options-interface | |
4310 | @c snarfed from print.c:142 | |
4311 | @deffn primitive print-options-interface [setting] | |
4312 | Option interface for the print options. Instead of using | |
4313 | this procedure directly, use the procedures | |
4314 | @code{print-enable}, @code{print-disable}, @code{print-set!} | |
4315 | and @code{print-options}. | |
4316 | @end deffn | |
4317 | ||
4318 | \fsimple-format | |
72ad43dc | 4319 | @c snarfed from print.c:909 |
780ee65e NJ |
4320 | @deffn primitive simple-format destination message . args |
4321 | Write @var{message} to @var{destination}, defaulting to | |
4322 | the current output port. | |
4323 | @var{message} can contain @code{~A} (was @code{%s}) and | |
4324 | @code{~S} (was @code{%S}) escapes. When printed, | |
4325 | the escapes are replaced with corresponding members of | |
4326 | @var{ARGS}: | |
4327 | @code{~A} formats using @code{display} and @code{~S} formats | |
4328 | using @code{write}. | |
4329 | If @var{destination} is @code{#t}, then use the current output | |
4330 | port, if @var{destination} is @code{#f}, then return a string | |
4331 | containing the formatted text. Does not add a trailing newline. | |
4332 | @end deffn | |
4333 | ||
4334 | \fnewline | |
72ad43dc | 4335 | @c snarfed from print.c:974 |
780ee65e NJ |
4336 | @deffn primitive newline [port] |
4337 | Send a newline to @var{port}. | |
4338 | @end deffn | |
4339 | ||
4340 | \fwrite-char | |
72ad43dc | 4341 | @c snarfed from print.c:989 |
780ee65e NJ |
4342 | @deffn primitive write-char chr [port] |
4343 | Send character @var{chr} to @var{port}. | |
4344 | @end deffn | |
4345 | ||
4346 | \fport-with-print-state | |
72ad43dc | 4347 | @c snarfed from print.c:1043 |
780ee65e NJ |
4348 | @deffn primitive port-with-print-state port pstate |
4349 | Create a new port which behaves like @var{port}, but with an | |
4350 | included print state @var{pstate}. | |
4351 | @end deffn | |
4352 | ||
4353 | \fget-print-state | |
72ad43dc | 4354 | @c snarfed from print.c:1058 |
780ee65e NJ |
4355 | @deffn primitive get-print-state port |
4356 | Return the print state of the port @var{port}. If @var{port} | |
4357 | has no associated print state, @code{#f} is returned. | |
4358 | @end deffn | |
4359 | ||
4360 | \fprocedure-properties | |
4361 | @c snarfed from procprop.c:180 | |
4362 | @deffn primitive procedure-properties proc | |
4363 | Return @var{obj}'s property list. | |
4364 | @end deffn | |
4365 | ||
4366 | \fset-procedure-properties! | |
4367 | @c snarfed from procprop.c:193 | |
4368 | @deffn primitive set-procedure-properties! proc new_val | |
4369 | Set @var{obj}'s property list to @var{alist}. | |
4370 | @end deffn | |
4371 | ||
4372 | \fprocedure-property | |
4373 | @c snarfed from procprop.c:206 | |
4374 | @deffn primitive procedure-property p k | |
4375 | Return the property of @var{obj} with name @var{key}. | |
4376 | @end deffn | |
4377 | ||
4378 | \fset-procedure-property! | |
4379 | @c snarfed from procprop.c:229 | |
4380 | @deffn primitive set-procedure-property! p k v | |
4381 | In @var{obj}'s property list, set the property named @var{key} to | |
4382 | @var{value}. | |
4383 | @end deffn | |
4384 | ||
4385 | \fprocedure? | |
4386 | @c snarfed from procs.c:196 | |
4387 | @deffn primitive procedure? obj | |
4388 | Return @code{#t} if @var{obj} is a procedure. | |
4389 | @end deffn | |
4390 | ||
4391 | \fclosure? | |
4392 | @c snarfed from procs.c:223 | |
4393 | @deffn primitive closure? obj | |
4394 | Return @code{#t} if @var{obj} is a closure. | |
4395 | @end deffn | |
4396 | ||
4397 | \fthunk? | |
4398 | @c snarfed from procs.c:232 | |
4399 | @deffn primitive thunk? obj | |
4400 | Return @code{#t} if @var{obj} is a thunk. | |
4401 | @end deffn | |
4402 | ||
4403 | \fprocedure-documentation | |
72ad43dc | 4404 | @c snarfed from procs.c:282 |
780ee65e NJ |
4405 | @deffn primitive procedure-documentation proc |
4406 | Return the documentation string associated with @code{proc}. By | |
4407 | convention, if a procedure contains more than one expression and the | |
4408 | first expression is a string constant, that string is assumed to contain | |
4409 | documentation for that procedure. | |
4410 | @end deffn | |
4411 | ||
4412 | \fprocedure-with-setter? | |
72ad43dc | 4413 | @c snarfed from procs.c:318 |
780ee65e NJ |
4414 | @deffn primitive procedure-with-setter? obj |
4415 | Return @code{#t} if @var{obj} is a procedure with an | |
4416 | associated setter procedure. | |
4417 | @end deffn | |
4418 | ||
4419 | \fmake-procedure-with-setter | |
72ad43dc | 4420 | @c snarfed from procs.c:328 |
780ee65e NJ |
4421 | @deffn primitive make-procedure-with-setter procedure setter |
4422 | Create a new procedure which behaves like @var{procedure}, but | |
4423 | with the associated setter @var{setter}. | |
4424 | @end deffn | |
4425 | ||
4426 | \fprocedure | |
72ad43dc | 4427 | @c snarfed from procs.c:347 |
780ee65e NJ |
4428 | @deffn primitive procedure proc |
4429 | Return the procedure of @var{proc}, which must be either a | |
4430 | procedure with setter, or an operator struct. | |
4431 | @end deffn | |
4432 | ||
4433 | \fprimitive-make-property | |
4434 | @c snarfed from properties.c:66 | |
4435 | @deffn primitive primitive-make-property not_found_proc | |
4436 | Create a @dfn{property token} that can be used with | |
4437 | @code{primitive-property-ref} and @code{primitive-property-set!}. | |
4438 | See @code{primitive-property-ref} for the significance of | |
4439 | @var{not_found_proc}. | |
4440 | @end deffn | |
4441 | ||
4442 | \fprimitive-property-ref | |
89d04205 | 4443 | @c snarfed from properties.c:84 |
780ee65e NJ |
4444 | @deffn primitive primitive-property-ref prop obj |
4445 | Return the property @var{prop} of @var{obj}. When no value | |
4446 | has yet been associated with @var{prop} and @var{obj}, call | |
4447 | @var{not-found-proc} instead (see @code{primitive-make-property}) | |
4448 | and use its return value. That value is also associated with | |
4449 | @var{obj} via @code{primitive-property-set!}. When | |
4450 | @var{not-found-proc} is @code{#f}, use @code{#f} as the | |
4451 | default value of @var{prop}. | |
4452 | @end deffn | |
4453 | ||
4454 | \fprimitive-property-set! | |
89d04205 | 4455 | @c snarfed from properties.c:115 |
780ee65e NJ |
4456 | @deffn primitive primitive-property-set! prop obj val |
4457 | Associate @var{code} with @var{prop} and @var{obj}. | |
4458 | @end deffn | |
4459 | ||
4460 | \fprimitive-property-del! | |
89d04205 | 4461 | @c snarfed from properties.c:136 |
780ee65e NJ |
4462 | @deffn primitive primitive-property-del! prop obj |
4463 | Remove any value associated with @var{prop} and @var{obj}. | |
4464 | @end deffn | |
4465 | ||
4466 | \farray-fill! | |
4467 | @c snarfed from ramap.c:467 | |
4468 | @deffn primitive array-fill! ra fill | |
4469 | Stores @var{fill} in every element of @var{array}. The value returned | |
4470 | is unspecified. | |
4471 | @end deffn | |
4472 | ||
4473 | \farray-copy-in-order! | |
4474 | @c snarfed from ramap.c:832 | |
4475 | @deffn primitive array-copy-in-order! | |
4476 | scm_array_copy_x | |
4477 | @end deffn | |
4478 | ||
4479 | \farray-copy! | |
4480 | @c snarfed from ramap.c:841 | |
4481 | @deffn primitive array-copy! src dst | |
4482 | @deffnx primitive array-copy-in-order! src dst | |
4483 | Copies every element from vector or array @var{source} to the | |
4484 | corresponding element of @var{destination}. @var{destination} must have | |
4485 | the same rank as @var{source}, and be at least as large in each | |
4486 | dimension. The order is unspecified. | |
4487 | @end deffn | |
4488 | ||
4489 | \farray-map-in-order! | |
4490 | @c snarfed from ramap.c:1515 | |
4491 | @deffn primitive array-map-in-order! | |
4492 | scm_array_map_x | |
4493 | @end deffn | |
4494 | ||
4495 | \farray-map! | |
4496 | @c snarfed from ramap.c:1526 | |
4497 | @deffn primitive array-map! ra0 proc . lra | |
4498 | @deffnx primitive array-map-in-order! ra0 proc . lra | |
4499 | @var{array1}, @dots{} must have the same number of dimensions as | |
4500 | @var{array0} and have a range for each index which includes the range | |
4501 | for the corresponding index in @var{array0}. @var{proc} is applied to | |
4502 | each tuple of elements of @var{array1} @dots{} and the result is stored | |
4503 | as the corresponding element in @var{array0}. The value returned is | |
4504 | unspecified. The order of application is unspecified. | |
4505 | @end deffn | |
4506 | ||
4507 | \farray-for-each | |
4508 | @c snarfed from ramap.c:1673 | |
4509 | @deffn primitive array-for-each proc ra0 . lra | |
4510 | @var{proc} is applied to each tuple of elements of @var{array0} @dots{} | |
4511 | in row-major order. The value returned is unspecified. | |
4512 | @end deffn | |
4513 | ||
4514 | \farray-index-map! | |
4515 | @c snarfed from ramap.c:1701 | |
4516 | @deffn primitive array-index-map! ra proc | |
4517 | applies @var{proc} to the indices of each element of @var{array} in | |
4518 | turn, storing the result in the corresponding element. The value | |
4519 | returned and the order of application are unspecified. | |
4520 | ||
4521 | One can implement @var{array-indexes} as | |
ae9f3a15 | 4522 | @lisp |
780ee65e NJ |
4523 | (define (array-indexes array) |
4524 | (let ((ra (apply make-array #f (array-shape array)))) | |
4525 | (array-index-map! ra (lambda x x)) | |
4526 | ra)) | |
ae9f3a15 | 4527 | @end lisp |
780ee65e | 4528 | Another example: |
ae9f3a15 | 4529 | @lisp |
780ee65e NJ |
4530 | (define (apl:index-generator n) |
4531 | (let ((v (make-uniform-vector n 1))) | |
4532 | (array-index-map! v (lambda (i) i)) | |
4533 | v)) | |
ae9f3a15 | 4534 | @end lisp |
780ee65e NJ |
4535 | @end deffn |
4536 | ||
4537 | \frandom | |
4538 | @c snarfed from random.c:370 | |
4539 | @deffn primitive random n [state] | |
4540 | Return a number in [0,N). | |
7a095584 | 4541 | |
780ee65e NJ |
4542 | Accepts a positive integer or real n and returns a |
4543 | number of the same type between zero (inclusive) and | |
4544 | N (exclusive). The values returned have a uniform | |
4545 | distribution. | |
7a095584 | 4546 | |
780ee65e NJ |
4547 | The optional argument @var{state} must be of the type produced |
4548 | by @code{seed->random-state}. It defaults to the value of the | |
4549 | variable @var{*random-state*}. This object is used to maintain | |
4550 | the state of the pseudo-random-number generator and is altered | |
4551 | as a side effect of the random operation. | |
4552 | @end deffn | |
4553 | ||
4554 | \fcopy-random-state | |
4555 | @c snarfed from random.c:393 | |
4556 | @deffn primitive copy-random-state [state] | |
4557 | Return a copy of the random state @var{state}. | |
4558 | @end deffn | |
4559 | ||
4560 | \fseed->random-state | |
4561 | @c snarfed from random.c:405 | |
4562 | @deffn primitive seed->random-state seed | |
4563 | Return a new random state using @var{seed}. | |
4564 | @end deffn | |
4565 | ||
4566 | \frandom:uniform | |
89d04205 | 4567 | @c snarfed from random.c:419 |
780ee65e | 4568 | @deffn primitive random:uniform [state] |
ae9f3a15 MG |
4569 | Return a uniformly distributed inexact real random number in |
4570 | [0,1). | |
780ee65e NJ |
4571 | @end deffn |
4572 | ||
4573 | \frandom:normal | |
89d04205 | 4574 | @c snarfed from random.c:434 |
780ee65e | 4575 | @deffn primitive random:normal [state] |
ae9f3a15 MG |
4576 | Return an inexact real in a normal distribution. The |
4577 | distribution used has mean 0 and standard deviation 1. For a | |
4578 | normal distribution with mean m and standard deviation d use | |
4579 | @code{(+ m (* d (random:normal)))}. | |
780ee65e NJ |
4580 | @end deffn |
4581 | ||
4582 | \frandom:solid-sphere! | |
89d04205 | 4583 | @c snarfed from random.c:490 |
780ee65e NJ |
4584 | @deffn primitive random:solid-sphere! v [state] |
4585 | Fills vect with inexact real random numbers | |
4586 | the sum of whose squares is less than 1.0. | |
4587 | Thinking of vect as coordinates in space of | |
4588 | dimension n = (vector-length vect), the coordinates | |
4589 | are uniformly distributed within the unit n-shere. | |
4590 | The sum of the squares of the numbers is returned. | |
4591 | @end deffn | |
4592 | ||
4593 | \frandom:hollow-sphere! | |
89d04205 | 4594 | @c snarfed from random.c:513 |
780ee65e NJ |
4595 | @deffn primitive random:hollow-sphere! v [state] |
4596 | Fills vect with inexact real random numbers | |
4597 | the sum of whose squares is equal to 1.0. | |
4598 | Thinking of vect as coordinates in space of | |
4599 | dimension n = (vector-length vect), the coordinates | |
4600 | are uniformly distributed over the surface of the | |
4601 | unit n-shere. | |
4602 | @end deffn | |
4603 | ||
4604 | \frandom:normal-vector! | |
89d04205 | 4605 | @c snarfed from random.c:531 |
780ee65e NJ |
4606 | @deffn primitive random:normal-vector! v [state] |
4607 | Fills vect with inexact real random numbers that are | |
4608 | independent and standard normally distributed | |
4609 | (i.e., with mean 0 and variance 1). | |
4610 | @end deffn | |
4611 | ||
4612 | \frandom:exp | |
89d04205 | 4613 | @c snarfed from random.c:556 |
780ee65e | 4614 | @deffn primitive random:exp [state] |
ae9f3a15 MG |
4615 | Return an inexact real in an exponential distribution with mean |
4616 | 1. For an exponential distribution with mean u use (* u | |
4617 | (random:exp)). | |
780ee65e NJ |
4618 | @end deffn |
4619 | ||
4620 | \f%read-delimited! | |
4621 | @c snarfed from rdelim.c:78 | |
4622 | @deffn primitive %read-delimited! delims str gobble [port [start [end]]] | |
4623 | Read characters from @var{port} into @var{str} until one of the | |
4624 | characters in the @var{delims} string is encountered. If | |
4625 | @var{gobble} is true, discard the delimiter character; | |
4626 | otherwise, leave it in the input stream for the next read. If | |
4627 | @var{port} is not specified, use the value of | |
4628 | @code{(current-input-port)}. If @var{start} or @var{end} are | |
4629 | specified, store data only into the substring of @var{str} | |
4630 | bounded by @var{start} and @var{end} (which default to the | |
4631 | beginning and end of the string, respectively). | |
7a095584 | 4632 | |
780ee65e NJ |
4633 | Return a pair consisting of the delimiter that terminated the |
4634 | string and the number of characters read. If reading stopped | |
4635 | at the end of file, the delimiter returned is the | |
4636 | @var{eof-object}; if the string was filled without encountering | |
4637 | a delimiter, this value is @code{#f}. | |
4638 | @end deffn | |
4639 | ||
4640 | \f%read-line | |
4641 | @c snarfed from rdelim.c:223 | |
4642 | @deffn primitive %read-line [port] | |
4643 | Read a newline-terminated line from @var{port}, allocating storage as | |
4644 | necessary. The newline terminator (if any) is removed from the string, | |
4645 | and a pair consisting of the line and its delimiter is returned. The | |
4646 | delimiter may be either a newline or the @var{eof-object}; if | |
4647 | @code{%read-line} is called at the end of file, it returns the pair | |
4648 | @code{(#<eof> . #<eof>)}. | |
4649 | @end deffn | |
4650 | ||
4651 | \fwrite-line | |
4652 | @c snarfed from rdelim.c:277 | |
4653 | @deffn primitive write-line obj [port] | |
ae9f3a15 MG |
4654 | Display @var{obj} and a newline character to @var{port}. If |
4655 | @var{port} is not specified, @code{(current-output-port)} is | |
4656 | used. This function is equivalent to: | |
4657 | @lisp | |
780ee65e NJ |
4658 | (display obj [port]) |
4659 | (newline [port]) | |
ae9f3a15 | 4660 | @end lisp |
780ee65e NJ |
4661 | @end deffn |
4662 | ||
4663 | \fread-options-interface | |
4664 | @c snarfed from read.c:84 | |
4665 | @deffn primitive read-options-interface [setting] | |
4666 | Option interface for the read options. Instead of using | |
4667 | this procedure directly, use the procedures @code{read-enable}, | |
4668 | @code{read-disable}, @code{read-set!} and @var{read-options}. | |
4669 | @end deffn | |
4670 | ||
4671 | \fread | |
4672 | @c snarfed from read.c:104 | |
4673 | @deffn primitive read [port] | |
4674 | Read an s-expression from the input port @var{port}, or from | |
4675 | the current input port if @var{port} is not specified. | |
4676 | Any whitespace before the next token is discarded. | |
4677 | @end deffn | |
4678 | ||
4679 | \fread-hash-extend | |
4680 | @c snarfed from read.c:746 | |
4681 | @deffn primitive read-hash-extend chr proc | |
4682 | Install the procedure @var{proc} for reading expressions | |
4683 | starting with the character sequence @code{#} and @var{chr}. | |
4684 | @var{proc} will be called with two arguments: the character | |
4685 | @var{chr} and the port to read further data from. The object | |
4686 | returned will be the return value of @code{read}. | |
4687 | @end deffn | |
4688 | ||
4689 | \fregexp? | |
4690 | @c snarfed from regex-posix.c:139 | |
ae9f3a15 MG |
4691 | @deffn primitive regexp? obj |
4692 | Return @code{#t} if @var{obj} is a compiled regular expression, | |
4693 | or @code{#f} otherwise. | |
780ee65e NJ |
4694 | @end deffn |
4695 | ||
4696 | \fmake-regexp | |
89d04205 | 4697 | @c snarfed from regex-posix.c:184 |
780ee65e | 4698 | @deffn primitive make-regexp pat . flags |
ae9f3a15 MG |
4699 | Compile the regular expression described by @var{pat}, and |
4700 | return the compiled regexp structure. If @var{pat} does not | |
4701 | describe a legal regular expression, @code{make-regexp} throws | |
4702 | a @code{regular-expression-syntax} error. | |
7a095584 | 4703 | |
ae9f3a15 MG |
4704 | The @var{flags} arguments change the behavior of the compiled |
4705 | regular expression. The following flags may be supplied: | |
7a095584 | 4706 | |
780ee65e NJ |
4707 | @table @code |
4708 | @item regexp/icase | |
ae9f3a15 MG |
4709 | Consider uppercase and lowercase letters to be the same when |
4710 | matching. | |
780ee65e | 4711 | @item regexp/newline |
ae9f3a15 MG |
4712 | If a newline appears in the target string, then permit the |
4713 | @samp{^} and @samp{$} operators to match immediately after or | |
4714 | immediately before the newline, respectively. Also, the | |
4715 | @samp{.} and @samp{[^...]} operators will never match a newline | |
4716 | character. The intent of this flag is to treat the target | |
4717 | string as a buffer containing many lines of text, and the | |
4718 | regular expression as a pattern that may match a single one of | |
4719 | those lines. | |
780ee65e NJ |
4720 | @item regexp/basic |
4721 | Compile a basic (``obsolete'') regexp instead of the extended | |
ae9f3a15 MG |
4722 | (``modern'') regexps that are the default. Basic regexps do |
4723 | not consider @samp{|}, @samp{+} or @samp{?} to be special | |
4724 | characters, and require the @samp{@{...@}} and @samp{(...)} | |
4725 | metacharacters to be backslash-escaped (@pxref{Backslash | |
4726 | Escapes}). There are several other differences between basic | |
4727 | and extended regular expressions, but these are the most | |
4728 | significant. | |
780ee65e | 4729 | @item regexp/extended |
ae9f3a15 MG |
4730 | Compile an extended regular expression rather than a basic |
4731 | regexp. This is the default behavior; this flag will not | |
4732 | usually be needed. If a call to @code{make-regexp} includes | |
4733 | both @code{regexp/basic} and @code{regexp/extended} flags, the | |
4734 | one which comes last will override the earlier one. | |
780ee65e NJ |
4735 | @end table |
4736 | @end deffn | |
4737 | ||
4738 | \fregexp-exec | |
89d04205 | 4739 | @c snarfed from regex-posix.c:232 |
780ee65e | 4740 | @deffn primitive regexp-exec rx str [start [flags]] |
ae9f3a15 MG |
4741 | Match the compiled regular expression @var{rx} against |
4742 | @code{str}. If the optional integer @var{start} argument is | |
4743 | provided, begin matching from that position in the string. | |
4744 | Return a match structure describing the results of the match, | |
4745 | or @code{#f} if no match could be found. | |
780ee65e NJ |
4746 | @end deffn |
4747 | ||
4748 | \fcall-with-dynamic-root | |
4749 | @c snarfed from root.c:358 | |
4750 | @deffn primitive call-with-dynamic-root thunk handler | |
4751 | Evaluate @code{(thunk)} in a new dynamic context, returning its value. | |
4752 | ||
4753 | If an error occurs during evaluation, apply @var{handler} to the | |
4754 | arguments to the throw, just as @code{throw} would. If this happens, | |
4755 | @var{handler} is called outside the scope of the new root -- it is | |
4756 | called in the same dynamic context in which | |
4757 | @code{call-with-dynamic-root} was evaluated. | |
4758 | ||
4759 | If @var{thunk} captures a continuation, the continuation is rooted at | |
4760 | the call to @var{thunk}. In particular, the call to | |
4761 | @code{call-with-dynamic-root} is not captured. Therefore, | |
4762 | @code{call-with-dynamic-root} always returns at most one time. | |
4763 | ||
4764 | Before calling @var{thunk}, the dynamic-wind chain is un-wound back to | |
4765 | the root and a new chain started for @var{thunk}. Therefore, this call | |
4766 | may not do what you expect: | |
4767 | ||
ae9f3a15 | 4768 | @lisp |
780ee65e NJ |
4769 | ;; Almost certainly a bug: |
4770 | (with-output-to-port | |
4771 | some-port | |
4772 | ||
4773 | (lambda () | |
4774 | (call-with-dynamic-root | |
4775 | (lambda () | |
4776 | (display 'fnord) | |
4777 | (newline)) | |
4778 | (lambda (errcode) errcode)))) | |
ae9f3a15 | 4779 | @end lisp |
780ee65e NJ |
4780 | |
4781 | The problem is, on what port will @samp{fnord} be displayed? You | |
4782 | might expect that because of the @code{with-output-to-port} that | |
4783 | it will be displayed on the port bound to @code{some-port}. But it | |
4784 | probably won't -- before evaluating the thunk, dynamic winds are | |
4785 | unwound, including those created by @code{with-output-to-port}. | |
4786 | So, the standard output port will have been re-set to its default value | |
4787 | before @code{display} is evaluated. | |
4788 | ||
4789 | (This function was added to Guile mostly to help calls to functions in C | |
4790 | libraries that can not tolerate non-local exits or calls that return | |
4791 | multiple times. If such functions call back to the interpreter, it should | |
4792 | be under a new dynamic root.) | |
4793 | @end deffn | |
4794 | ||
4795 | \fdynamic-root | |
4796 | @c snarfed from root.c:371 | |
4797 | @deffn primitive dynamic-root | |
4798 | Return an object representing the current dynamic root. | |
4799 | ||
4800 | These objects are only useful for comparison using @code{eq?}. | |
4801 | They are currently represented as numbers, but your code should | |
4802 | in no way depend on this. | |
4803 | @end deffn | |
4804 | ||
7a095584 NJ |
4805 | \fread-string!/partial |
4806 | @c snarfed from rw.c:110 | |
4807 | @deffn primitive read-string!/partial str [port_or_fdes [start [end]]] | |
4808 | Read characters from an fport or file descriptor into a | |
4809 | string @var{str}. This procedure is scsh-compatible | |
4810 | and can efficiently read large strings. It will: | |
4811 | ||
4812 | @itemize | |
4813 | @item | |
4814 | attempt to fill the entire string, unless the @var{start} | |
4815 | and/or @var{end} arguments are supplied. i.e., @var{start} | |
4816 | defaults to 0 and @var{end} defaults to | |
4817 | @code{(string-length str)} | |
4818 | @item | |
4819 | use the current input port if @var{port_or_fdes} is not | |
4820 | supplied. | |
4821 | @item | |
4822 | read any characters that are currently available, | |
4823 | without waiting for the rest (short reads are possible). | |
4824 | ||
4825 | @item | |
4826 | wait for as long as it needs to for the first character to | |
4827 | become available, unless the port is in non-blocking mode | |
4828 | @item | |
4829 | return @code{#f} if end-of-file is encountered before reading | |
4830 | any characters, otherwise return the number of characters | |
4831 | read. | |
4832 | @item | |
4833 | return 0 if the port is in non-blocking mode and no characters | |
4834 | are immediately available. | |
4835 | @item | |
4836 | return 0 if the request is for 0 bytes, with no | |
4837 | end-of-file check | |
4838 | @end itemize | |
4839 | @end deffn | |
4840 | ||
780ee65e NJ |
4841 | \fsigaction |
4842 | @c snarfed from scmsigs.c:201 | |
4843 | @deffn primitive sigaction signum [handler [flags]] | |
4844 | Install or report the signal handler for a specified signal. | |
4845 | ||
4846 | @var{signum} is the signal number, which can be specified using the value | |
4847 | of variables such as @code{SIGINT}. | |
4848 | ||
4849 | If @var{action} is omitted, @code{sigaction} returns a pair: the | |
4850 | CAR is the current | |
4851 | signal hander, which will be either an integer with the value @code{SIG_DFL} | |
4852 | (default action) or @code{SIG_IGN} (ignore), or the Scheme procedure which | |
4853 | handles the signal, or @code{#f} if a non-Scheme procedure handles the | |
4854 | signal. The CDR contains the current @code{sigaction} flags for the handler. | |
4855 | ||
4856 | If @var{action} is provided, it is installed as the new handler for | |
4857 | @var{signum}. @var{action} can be a Scheme procedure taking one | |
4858 | argument, or the value of @code{SIG_DFL} (default action) or | |
4859 | @code{SIG_IGN} (ignore), or @code{#f} to restore whatever signal handler | |
4860 | was installed before @code{sigaction} was first used. Flags can | |
4861 | optionally be specified for the new handler (@code{SA_RESTART} will | |
4862 | always be added if it's available and the system is using restartable | |
4863 | system calls.) The return value is a pair with information about the | |
4864 | old handler as described above. | |
4865 | ||
4866 | This interface does not provide access to the "signal blocking" | |
4867 | facility. Maybe this is not needed, since the thread support may | |
4868 | provide solutions to the problem of consistent access to data | |
4869 | structures. | |
4870 | @end deffn | |
4871 | ||
4872 | \frestore-signals | |
4873 | @c snarfed from scmsigs.c:360 | |
4874 | @deffn primitive restore-signals | |
4875 | Return all signal handlers to the values they had before any call to | |
4876 | @code{sigaction} was made. The return value is unspecified. | |
4877 | @end deffn | |
4878 | ||
4879 | \falarm | |
4880 | @c snarfed from scmsigs.c:399 | |
4881 | @deffn primitive alarm i | |
4882 | Set a timer to raise a @code{SIGALRM} signal after the specified | |
4883 | number of seconds (an integer). It's advisable to install a signal | |
4884 | handler for | |
4885 | @code{SIGALRM} beforehand, since the default action is to terminate | |
4886 | the process. | |
4887 | ||
4888 | The return value indicates the time remaining for the previous alarm, | |
4889 | if any. The new value replaces the previous alarm. If there was | |
4890 | no previous alarm, the return value is zero. | |
4891 | @end deffn | |
4892 | ||
4893 | \fpause | |
4894 | @c snarfed from scmsigs.c:414 | |
4895 | @deffn primitive pause | |
4896 | Pause the current process (thread?) until a signal arrives whose | |
4897 | action is to either terminate the current process or invoke a | |
4898 | handler procedure. The return value is unspecified. | |
4899 | @end deffn | |
4900 | ||
4901 | \fsleep | |
4902 | @c snarfed from scmsigs.c:427 | |
4903 | @deffn primitive sleep i | |
4904 | Wait for the given number of seconds (an integer) or until a signal | |
4905 | arrives. The return value is zero if the time elapses or the number | |
4906 | of seconds remaining otherwise. | |
4907 | @end deffn | |
4908 | ||
4909 | \fusleep | |
4910 | @c snarfed from scmsigs.c:445 | |
4911 | @deffn primitive usleep i | |
4912 | Sleep for I microseconds. @code{usleep} is not available on | |
4913 | all platforms. | |
4914 | @end deffn | |
4915 | ||
4916 | \fraise | |
7a095584 | 4917 | @c snarfed from scmsigs.c:474 |
780ee65e NJ |
4918 | @deffn primitive raise sig |
4919 | Sends a specified signal @var{sig} to the current process, where | |
4920 | @var{sig} is as described for the kill procedure. | |
4921 | @end deffn | |
4922 | ||
4923 | \fsystem | |
89d04205 | 4924 | @c snarfed from simpos.c:78 |
780ee65e | 4925 | @deffn primitive system [cmd] |
ae9f3a15 MG |
4926 | Execute @var{cmd} using the operating system's "command |
4927 | processor". Under Unix this is usually the default shell | |
4928 | @code{sh}. The value returned is @var{cmd}'s exit status as | |
4929 | returned by @code{waitpid}, which can be interpreted using the | |
4930 | functions above. | |
7a095584 | 4931 | |
ae9f3a15 | 4932 | If @code{system} is called without arguments, return a boolean |
780ee65e NJ |
4933 | indicating whether the command processor is available. |
4934 | @end deffn | |
4935 | ||
4936 | \fgetenv | |
89d04205 | 4937 | @c snarfed from simpos.c:106 |
780ee65e NJ |
4938 | @deffn primitive getenv nam |
4939 | Looks up the string @var{name} in the current environment. The return | |
4940 | value is @code{#f} unless a string of the form @code{NAME=VALUE} is | |
4941 | found, in which case the string @code{VALUE} is returned. | |
4942 | @end deffn | |
4943 | ||
4944 | \fprimitive-exit | |
89d04205 | 4945 | @c snarfed from simpos.c:122 |
780ee65e NJ |
4946 | @deffn primitive primitive-exit [status] |
4947 | Terminate the current process without unwinding the Scheme stack. | |
4948 | This is would typically be useful after a fork. The exit status | |
4949 | is @var{status} if supplied, otherwise zero. | |
4950 | @end deffn | |
4951 | ||
4952 | \fhtons | |
4953 | @c snarfed from socket.c:89 | |
7a095584 NJ |
4954 | @deffn primitive htons value |
4955 | Convert a 16 bit quantity from host to network byte ordering. | |
4956 | @var{value} is packed into 2 bytes, which are then converted | |
4957 | and returned as a new integer. | |
780ee65e NJ |
4958 | @end deffn |
4959 | ||
4960 | \fntohs | |
4961 | @c snarfed from socket.c:106 | |
7a095584 NJ |
4962 | @deffn primitive ntohs value |
4963 | Convert a 16 bit quantity from network to host byte ordering. | |
4964 | @var{value} is packed into 2 bytes, which are then converted | |
4965 | and returned as a new integer. | |
780ee65e NJ |
4966 | @end deffn |
4967 | ||
4968 | \fhtonl | |
4969 | @c snarfed from socket.c:123 | |
7a095584 NJ |
4970 | @deffn primitive htonl value |
4971 | Convert a 32 bit quantity from host to network byte ordering. | |
4972 | @var{value} is packed into 4 bytes, which are then converted | |
4973 | and returned as a new integer. | |
780ee65e NJ |
4974 | @end deffn |
4975 | ||
4976 | \fntohl | |
7a095584 NJ |
4977 | @c snarfed from socket.c:136 |
4978 | @deffn primitive ntohl value | |
4979 | Convert a 32 bit quantity from network to host byte ordering. | |
4980 | @var{value} is packed into 4 bytes, which are then converted | |
4981 | and returned as a new integer. | |
4982 | @end deffn | |
4983 | ||
4984 | \finet-aton | |
4985 | @c snarfed from socket.c:156 | |
4986 | @deffn primitive inet-aton address | |
4987 | Convert an IPv4 Internet address from printable string | |
4988 | (dotted decimal notation) to an integer. E.g., | |
4989 | ||
4990 | @lisp | |
4991 | (inet-aton "127.0.0.1") @result{} 2130706433 | |
4992 | @end lisp | |
4993 | @end deffn | |
4994 | ||
4995 | \finet-ntoa | |
4996 | @c snarfed from socket.c:176 | |
4997 | @deffn primitive inet-ntoa inetid | |
4998 | Convert an IPv4 Internet address to a printable | |
4999 | (dotted decimal notation) string. E.g., | |
5000 | ||
5001 | @lisp | |
5002 | (inet-ntoa 2130706433) @result{} "127.0.0.1" | |
5003 | @end lisp | |
5004 | @end deffn | |
5005 | ||
5006 | \finet-netof | |
5007 | @c snarfed from socket.c:196 | |
5008 | @deffn primitive inet-netof address | |
5009 | Return the network number part of the given IPv4 | |
5010 | Internet address. E.g., | |
5011 | ||
5012 | @lisp | |
5013 | (inet-netof 2130706433) @result{} 127 | |
5014 | @end lisp | |
5015 | @end deffn | |
5016 | ||
5017 | \finet-lnaof | |
5018 | @c snarfed from socket.c:214 | |
5019 | @deffn primitive inet-lnaof address | |
5020 | Return the local-address-with-network part of the given | |
5021 | IPv4 Internet address, using the obsolete class A/B/C system. | |
5022 | E.g., | |
5023 | ||
5024 | @lisp | |
5025 | (inet-lnaof 2130706433) @result{} 1 | |
5026 | @end lisp | |
5027 | @end deffn | |
5028 | ||
5029 | \finet-makeaddr | |
5030 | @c snarfed from socket.c:232 | |
5031 | @deffn primitive inet-makeaddr net lna | |
5032 | Make an IPv4 Internet address by combining the network number | |
5033 | @var{net} with the local-address-within-network number | |
5034 | @var{lna}. E.g., | |
5035 | ||
5036 | @lisp | |
5037 | (inet-makeaddr 127 1) @result{} 2130706433 | |
5038 | @end lisp | |
5039 | @end deffn | |
5040 | ||
5041 | \finet-pton | |
5042 | @c snarfed from socket.c:350 | |
5043 | @deffn primitive inet-pton family address | |
5044 | Convert a string containing a printable network address to | |
5045 | an integer address. Note that unlike the C version of this | |
5046 | function, | |
5047 | the result is an integer with normal host byte ordering. | |
5048 | @var{family} can be @code{AF_INET} or @code{AF_INET6}. E.g., | |
5049 | ||
5050 | @lisp | |
5051 | (inet-pton AF_INET "127.0.0.1") @result{} 2130706433 | |
5052 | (inet-pton AF_INET6 "::1") @result{} 1 | |
5053 | @end lisp | |
5054 | @end deffn | |
5055 | ||
5056 | \finet-ntop | |
5057 | @c snarfed from socket.c:385 | |
5058 | @deffn primitive inet-ntop family address | |
5059 | Convert a network address into a printable string. | |
5060 | Note that unlike the C version of this function, | |
5061 | the input is an integer with normal host byte ordering. | |
5062 | @var{family} can be @code{AF_INET} or @code{AF_INET6}. E.g., | |
5063 | ||
5064 | @lisp | |
5065 | (inet-ntop AF_INET 2130706433) @result{} "127.0.0.1" | |
5066 | (inet-ntop AF_INET6 (- (expt 2 128) 1)) @result{} | |
5067 | ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff | |
5068 | @end lisp | |
780ee65e NJ |
5069 | @end deffn |
5070 | ||
5071 | \fsocket | |
7a095584 | 5072 | @c snarfed from socket.c:430 |
780ee65e | 5073 | @deffn primitive socket family style proto |
ae9f3a15 | 5074 | Return a new socket port of the type specified by @var{family}, |
7a095584 | 5075 | @var{style} and @var{proto}. All three parameters are |
72ad43dc NJ |
5076 | integers. Supported values for @var{family} are |
5077 | @code{AF_UNIX}, @code{AF_INET} and @code{AF_INET6}. | |
5078 | Typical values for @var{style} are @code{SOCK_STREAM}, | |
ae9f3a15 | 5079 | @code{SOCK_DGRAM} and @code{SOCK_RAW}. |
7a095584 NJ |
5080 | |
5081 | @var{proto} can be obtained from a protocol name using | |
ae9f3a15 MG |
5082 | @code{getprotobyname}. A value of zero specifies the default |
5083 | protocol, which is usually right. | |
7a095584 | 5084 | |
ae9f3a15 MG |
5085 | A single socket port cannot by used for communication until it |
5086 | has been connected to another socket. | |
780ee65e NJ |
5087 | @end deffn |
5088 | ||
5089 | \fsocketpair | |
7a095584 | 5090 | @c snarfed from socket.c:452 |
780ee65e | 5091 | @deffn primitive socketpair family style proto |
ae9f3a15 | 5092 | Return a pair of connected (but unnamed) socket ports of the |
7a095584 | 5093 | type specified by @var{family}, @var{style} and @var{proto}. |
ae9f3a15 MG |
5094 | Many systems support only socket pairs of the @code{AF_UNIX} |
5095 | family. Zero is likely to be the only meaningful value for | |
7a095584 | 5096 | @var{proto}. |
780ee65e NJ |
5097 | @end deffn |
5098 | ||
5099 | \fgetsockopt | |
7a095584 | 5100 | @c snarfed from socket.c:481 |
780ee65e | 5101 | @deffn primitive getsockopt sock level optname |
ae9f3a15 | 5102 | Return the value of a particular socket option for the socket |
7a095584 | 5103 | port @var{sock}. @var{level} is an integer code for type of |
ae9f3a15 MG |
5104 | option being requested, e.g., @code{SOL_SOCKET} for |
5105 | socket-level options. @var{optname} is an integer code for the | |
5106 | option required and should be specified using one of the | |
5107 | symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc. | |
7a095584 | 5108 | |
ae9f3a15 MG |
5109 | The returned value is typically an integer but @code{SO_LINGER} |
5110 | returns a pair of integers. | |
780ee65e NJ |
5111 | @end deffn |
5112 | ||
5113 | \fsetsockopt | |
7a095584 | 5114 | @c snarfed from socket.c:549 |
780ee65e | 5115 | @deffn primitive setsockopt sock level optname value |
7a095584 NJ |
5116 | Set the value of a particular socket option for the socket |
5117 | port @var{sock}. @var{level} is an integer code for type of option | |
780ee65e NJ |
5118 | being set, e.g., @code{SOL_SOCKET} for socket-level options. |
5119 | @var{optname} is an | |
5120 | integer code for the option to set and should be specified using one of | |
5121 | the symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc. | |
5122 | @var{value} is the value to which the option should be set. For | |
5123 | most options this must be an integer, but for @code{SO_LINGER} it must | |
5124 | be a pair. | |
5125 | ||
5126 | The return value is unspecified. | |
5127 | @end deffn | |
5128 | ||
5129 | \fshutdown | |
7a095584 | 5130 | @c snarfed from socket.c:653 |
780ee65e NJ |
5131 | @deffn primitive shutdown sock how |
5132 | Sockets can be closed simply by using @code{close-port}. The | |
5133 | @code{shutdown} procedure allows reception or tranmission on a | |
5134 | connection to be shut down individually, according to the parameter | |
5135 | @var{how}: | |
5136 | ||
5137 | @table @asis | |
5138 | @item 0 | |
5139 | Stop receiving data for this socket. If further data arrives, reject it. | |
5140 | @item 1 | |
5141 | Stop trying to transmit data from this socket. Discard any | |
5142 | data waiting to be sent. Stop looking for acknowledgement of | |
5143 | data already sent; don't retransmit it if it is lost. | |
5144 | @item 2 | |
5145 | Stop both reception and transmission. | |
5146 | @end table | |
5147 | ||
5148 | The return value is unspecified. | |
5149 | @end deffn | |
5150 | ||
5151 | \fconnect | |
7a095584 | 5152 | @c snarfed from socket.c:797 |
780ee65e | 5153 | @deffn primitive connect sock fam address . args |
7a095584 | 5154 | Initiate a connection from a socket using a specified address |
72ad43dc NJ |
5155 | family to the address |
5156 | specified by @var{address} and possibly @var{args}. | |
5157 | The format required for @var{address} | |
5158 | and @var{args} depends on the family of the socket. | |
780ee65e NJ |
5159 | |
5160 | For a socket of family @code{AF_UNIX}, | |
72ad43dc | 5161 | only @var{address} is specified and must be a string with the |
780ee65e NJ |
5162 | filename where the socket is to be created. |
5163 | ||
5164 | For a socket of family @code{AF_INET}, | |
72ad43dc NJ |
5165 | @var{address} must be an integer IPv4 host address and |
5166 | @var{args} must be a single integer port number. | |
5167 | ||
5168 | For a socket of family @code{AF_INET6}, | |
5169 | @var{address} must be an integer IPv6 host address and | |
5170 | @var{args} may be up to three integers: | |
5171 | port [flowinfo] [scope_id], | |
5172 | where flowinfo and scope_id default to zero. | |
780ee65e NJ |
5173 | |
5174 | The return value is unspecified. | |
5175 | @end deffn | |
5176 | ||
5177 | \fbind | |
7a095584 | 5178 | @c snarfed from socket.c:857 |
780ee65e | 5179 | @deffn primitive bind sock fam address . args |
7a095584 | 5180 | Assign an address to the socket port @var{sock}. |
780ee65e NJ |
5181 | Generally this only needs to be done for server sockets, |
5182 | so they know where to look for incoming connections. A socket | |
5183 | without an address will be assigned one automatically when it | |
5184 | starts communicating. | |
5185 | ||
7a095584 NJ |
5186 | The format of @var{address} and @var{args} depends |
5187 | on the family of the socket. | |
780ee65e NJ |
5188 | |
5189 | For a socket of family @code{AF_UNIX}, only @var{address} | |
7a095584 NJ |
5190 | is specified and must be a string with the filename where |
5191 | the socket is to be created. | |
780ee65e | 5192 | |
7a095584 NJ |
5193 | For a socket of family @code{AF_INET}, @var{address} |
5194 | must be an integer IPv4 address and @var{args} | |
5195 | must be a single integer port number. | |
780ee65e | 5196 | |
7a095584 NJ |
5197 | The values of the following variables can also be used for |
5198 | @var{address}: | |
780ee65e NJ |
5199 | |
5200 | @defvar INADDR_ANY | |
5201 | Allow connections from any address. | |
5202 | @end defvar | |
5203 | ||
5204 | @defvar INADDR_LOOPBACK | |
5205 | The address of the local host using the loopback device. | |
5206 | @end defvar | |
5207 | ||
5208 | @defvar INADDR_BROADCAST | |
5209 | The broadcast address on the local network. | |
5210 | @end defvar | |
5211 | ||
5212 | @defvar INADDR_NONE | |
5213 | No address. | |
5214 | @end defvar | |
5215 | ||
7a095584 NJ |
5216 | For a socket of family @code{AF_INET6}, @var{address} |
5217 | must be an integer IPv6 address and @var{args} | |
5218 | may be up to three integers: | |
5219 | port [flowinfo] [scope_id], | |
5220 | where flowinfo and scope_id default to zero. | |
5221 | ||
780ee65e NJ |
5222 | The return value is unspecified. |
5223 | @end deffn | |
5224 | ||
5225 | \flisten | |
7a095584 | 5226 | @c snarfed from socket.c:891 |
780ee65e | 5227 | @deffn primitive listen sock backlog |
7a095584 | 5228 | Enable @var{sock} to accept connection |
780ee65e NJ |
5229 | requests. @var{backlog} is an integer specifying |
5230 | the maximum length of the queue for pending connections. | |
7a095584 NJ |
5231 | If the queue fills, new clients will fail to connect until |
5232 | the server calls @code{accept} to accept a connection from | |
5233 | the queue. | |
780ee65e NJ |
5234 | |
5235 | The return value is unspecified. | |
5236 | @end deffn | |
5237 | ||
5238 | \faccept | |
7a095584 | 5239 | @c snarfed from socket.c:997 |
780ee65e | 5240 | @deffn primitive accept sock |
7a095584 NJ |
5241 | Accept a connection on a bound, listening socket. |
5242 | If there | |
5243 | are no pending connections in the queue, wait until | |
5244 | one is available unless the non-blocking option has been | |
5245 | set on the socket. | |
780ee65e NJ |
5246 | |
5247 | The return value is a | |
7a095584 NJ |
5248 | pair in which the @emph{car} is a new socket port for the |
5249 | connection and | |
5250 | the @emph{cdr} is an object with address information about the | |
5251 | client which initiated the connection. | |
780ee65e | 5252 | |
7a095584 | 5253 | @var{sock} does not become part of the |
780ee65e NJ |
5254 | connection and will continue to accept new requests. |
5255 | @end deffn | |
5256 | ||
5257 | \fgetsockname | |
7a095584 | 5258 | @c snarfed from socket.c:1024 |
780ee65e | 5259 | @deffn primitive getsockname sock |
7a095584 | 5260 | Return the address of @var{sock}, in the same form as the |
ae9f3a15 MG |
5261 | object returned by @code{accept}. On many systems the address |
5262 | of a socket in the @code{AF_FILE} namespace cannot be read. | |
780ee65e NJ |
5263 | @end deffn |
5264 | ||
5265 | \fgetpeername | |
7a095584 | 5266 | @c snarfed from socket.c:1046 |
780ee65e | 5267 | @deffn primitive getpeername sock |
7a095584 | 5268 | Return the address that @var{sock} |
ae9f3a15 MG |
5269 | is connected to, in the same form as the object returned by |
5270 | @code{accept}. On many systems the address of a socket in the | |
5271 | @code{AF_FILE} namespace cannot be read. | |
780ee65e NJ |
5272 | @end deffn |
5273 | ||
5274 | \frecv! | |
7a095584 | 5275 | @c snarfed from socket.c:1081 |
780ee65e | 5276 | @deffn primitive recv! sock buf [flags] |
7a095584 NJ |
5277 | Receive data from a socket port. |
5278 | @var{sock} must already | |
780ee65e NJ |
5279 | be bound to the address from which data is to be received. |
5280 | @var{buf} is a string into which | |
7a095584 NJ |
5281 | the data will be written. The size of @var{buf} limits |
5282 | the amount of | |
780ee65e | 5283 | data which can be received: in the case of packet |
7a095584 NJ |
5284 | protocols, if a packet larger than this limit is encountered |
5285 | then some data | |
780ee65e NJ |
5286 | will be irrevocably lost. |
5287 | ||
5288 | The optional @var{flags} argument is a value or | |
5289 | bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc. | |
5290 | ||
7a095584 NJ |
5291 | The value returned is the number of bytes read from the |
5292 | socket. | |
780ee65e | 5293 | |
7a095584 NJ |
5294 | Note that the data is read directly from the socket file |
5295 | descriptor: | |
780ee65e NJ |
5296 | any unread buffered port data is ignored. |
5297 | @end deffn | |
5298 | ||
5299 | \fsend | |
7a095584 | 5300 | @c snarfed from socket.c:1114 |
780ee65e | 5301 | @deffn primitive send sock message [flags] |
7a095584 NJ |
5302 | Transmit the string @var{message} on a socket port @var{sock}. |
5303 | @var{sock} must already be bound to a destination address. The | |
5304 | value returned is the number of bytes transmitted -- | |
5305 | it's possible for | |
5306 | this to be less than the length of @var{message} | |
5307 | if the socket is | |
5308 | set to be non-blocking. The optional @var{flags} argument | |
5309 | is a value or | |
780ee65e NJ |
5310 | bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc. |
5311 | ||
7a095584 NJ |
5312 | Note that the data is written directly to the socket |
5313 | file descriptor: | |
780ee65e NJ |
5314 | any unflushed buffered port data is ignored. |
5315 | @end deffn | |
5316 | ||
5317 | \frecvfrom! | |
7a095584 | 5318 | @c snarfed from socket.c:1154 |
780ee65e | 5319 | @deffn primitive recvfrom! sock str [flags [start [end]]] |
7a095584 | 5320 | Return data from the socket port @var{sock} and also |
ae9f3a15 | 5321 | information about where the data was received from. |
7a095584 | 5322 | @var{sock} must already be bound to the address from which |
ae9f3a15 MG |
5323 | data is to be received. @code{str}, is a string into which the |
5324 | data will be written. The size of @var{str} limits the amount | |
5325 | of data which can be received: in the case of packet protocols, | |
5326 | if a packet larger than this limit is encountered then some | |
5327 | data will be irrevocably lost. | |
7a095584 | 5328 | |
ae9f3a15 MG |
5329 | The optional @var{flags} argument is a value or bitwise OR of |
5330 | @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc. | |
7a095584 | 5331 | |
ae9f3a15 MG |
5332 | The value returned is a pair: the @emph{car} is the number of |
5333 | bytes read from the socket and the @emph{cdr} an address object | |
7a095584 NJ |
5334 | in the same form as returned by @code{accept}. The address |
5335 | will given as @code{#f} if not available, as is usually the | |
5336 | case for stream sockets. | |
5337 | ||
ae9f3a15 MG |
5338 | The @var{start} and @var{end} arguments specify a substring of |
5339 | @var{str} to which the data should be written. | |
7a095584 | 5340 | |
ae9f3a15 MG |
5341 | Note that the data is read directly from the socket file |
5342 | descriptor: any unread buffered port data is ignored. | |
780ee65e NJ |
5343 | @end deffn |
5344 | ||
5345 | \fsendto | |
7a095584 | 5346 | @c snarfed from socket.c:1212 |
780ee65e | 5347 | @deffn primitive sendto sock message fam address . args_and_flags |
7a095584 NJ |
5348 | Transmit the string @var{message} on the socket port |
5349 | @var{sock}. The | |
5350 | destination address is specified using the @var{fam}, | |
5351 | @var{address} and | |
5352 | @var{args_and_flags} arguments, in a similar way to the | |
5353 | @code{connect} procedure. @var{args_and_flags} contains | |
5354 | the usual connection arguments optionally followed by | |
5355 | a flags argument, which is a value or | |
780ee65e NJ |
5356 | bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc. |
5357 | ||
7a095584 NJ |
5358 | The value returned is the number of bytes transmitted -- |
5359 | it's possible for | |
5360 | this to be less than the length of @var{message} if the | |
5361 | socket is | |
5362 | set to be non-blocking. | |
5363 | Note that the data is written directly to the socket | |
5364 | file descriptor: | |
780ee65e NJ |
5365 | any unflushed buffered port data is ignored. |
5366 | @end deffn | |
5367 | ||
5368 | \frestricted-vector-sort! | |
5369 | @c snarfed from sort.c:425 | |
5370 | @deffn primitive restricted-vector-sort! vec less startpos endpos | |
5371 | Sort the vector @var{vec}, using @var{less} for comparing | |
5372 | the vector elements. @var{startpos} and @var{endpos} delimit | |
5373 | the range of the vector which gets sorted. The return value | |
5374 | is not specified. | |
5375 | @end deffn | |
5376 | ||
5377 | \fsorted? | |
5378 | @c snarfed from sort.c:456 | |
5379 | @deffn primitive sorted? items less | |
5380 | Return @code{#t} iff @var{items} is a list or a vector such that | |
5381 | for all 1 <= i <= m, the predicate @var{less} returns true when | |
5382 | applied to all elements i - 1 and i | |
5383 | @end deffn | |
5384 | ||
5385 | \fmerge | |
5386 | @c snarfed from sort.c:528 | |
5387 | @deffn primitive merge alist blist less | |
5388 | Takes two lists @var{alist} and @var{blist} such that | |
5389 | @code{(sorted? alist less?)} and @code{(sorted? blist less?)} and | |
5390 | returns a new list in which the elements of @var{alist} and | |
5391 | @var{blist} have been stably interleaved so that | |
5392 | @code{(sorted? (merge alist blist less?) less?)}. | |
5393 | Note: this does _not_ accept vectors. | |
5394 | @end deffn | |
5395 | ||
5396 | \fmerge! | |
5397 | @c snarfed from sort.c:641 | |
5398 | @deffn primitive merge! alist blist less | |
5399 | Takes two lists @var{alist} and @var{blist} such that | |
5400 | @code{(sorted? alist less?)} and @code{(sorted? blist less?)} and | |
5401 | returns a new list in which the elements of @var{alist} and | |
5402 | @var{blist} have been stably interleaved so that | |
5403 | @code{(sorted? (merge alist blist less?) less?)}. | |
5404 | This is the destructive variant of @code{merge} | |
5405 | Note: this does _not_ accept vectors. | |
5406 | @end deffn | |
5407 | ||
5408 | \fsort! | |
5409 | @c snarfed from sort.c:717 | |
5410 | @deffn primitive sort! items less | |
5411 | Sort the sequence @var{items}, which may be a list or a | |
5412 | vector. @var{less} is used for comparing the sequence | |
5413 | elements. The sorting is destructive, that means that the | |
5414 | input sequence is modified to produce the sorted result. | |
5415 | This is not a stable sort. | |
5416 | @end deffn | |
5417 | ||
5418 | \fsort | |
5419 | @c snarfed from sort.c:751 | |
5420 | @deffn primitive sort items less | |
5421 | Sort the sequence @var{items}, which may be a list or a | |
5422 | vector. @var{less} is used for comparing the sequence | |
5423 | elements. This is not a stable sort. | |
5424 | @end deffn | |
5425 | ||
5426 | \fstable-sort! | |
5427 | @c snarfed from sort.c:847 | |
5428 | @deffn primitive stable-sort! items less | |
5429 | Sort the sequence @var{items}, which may be a list or a | |
5430 | vector. @var{less} is used for comparing the sequence elements. | |
5431 | The sorting is destructive, that means that the input sequence | |
5432 | is modified to produce the sorted result. | |
5433 | This is a stable sort. | |
5434 | @end deffn | |
5435 | ||
5436 | \fstable-sort | |
5437 | @c snarfed from sort.c:887 | |
5438 | @deffn primitive stable-sort items less | |
5439 | Sort the sequence @var{items}, which may be a list or a | |
5440 | vector. @var{less} is used for comparing the sequence elements. | |
5441 | This is a stable sort. | |
5442 | @end deffn | |
5443 | ||
5444 | \fsort-list! | |
5445 | @c snarfed from sort.c:933 | |
5446 | @deffn primitive sort-list! items less | |
5447 | Sort the list @var{items}, using @var{less} for comparing the | |
5448 | list elements. The sorting is destructive, that means that the | |
5449 | input list is modified to produce the sorted result. | |
5450 | This is a stable sort. | |
5451 | @end deffn | |
5452 | ||
5453 | \fsort-list | |
5454 | @c snarfed from sort.c:947 | |
5455 | @deffn primitive sort-list items less | |
5456 | Sort the list @var{items}, using @var{less} for comparing the | |
5457 | list elements. This is a stable sort. | |
5458 | @end deffn | |
5459 | ||
5460 | \fsource-properties | |
72ad43dc | 5461 | @c snarfed from srcprop.c:172 |
780ee65e NJ |
5462 | @deffn primitive source-properties obj |
5463 | Return the source property association list of @var{obj}. | |
5464 | @end deffn | |
5465 | ||
5466 | \fset-source-properties! | |
72ad43dc | 5467 | @c snarfed from srcprop.c:195 |
780ee65e NJ |
5468 | @deffn primitive set-source-properties! obj plist |
5469 | Install the association list @var{plist} as the source property | |
5470 | list for @var{obj}. | |
5471 | @end deffn | |
5472 | ||
5473 | \fsource-property | |
72ad43dc | 5474 | @c snarfed from srcprop.c:215 |
780ee65e NJ |
5475 | @deffn primitive source-property obj key |
5476 | Return the source property specified by @var{key} from | |
5477 | @var{obj}'s source property list. | |
5478 | @end deffn | |
5479 | ||
5480 | \fset-source-property! | |
72ad43dc | 5481 | @c snarfed from srcprop.c:248 |
780ee65e NJ |
5482 | @deffn primitive set-source-property! obj key datum |
5483 | Set the source property of object @var{obj}, which is specified by | |
5484 | @var{key} to @var{datum}. Normally, the key will be a symbol. | |
5485 | @end deffn | |
5486 | ||
5487 | \fstack? | |
5488 | @c snarfed from stacks.c:407 | |
5489 | @deffn primitive stack? obj | |
5490 | Return @code{#t} if @var{obj} is a calling stack. | |
5491 | @end deffn | |
5492 | ||
5493 | \fmake-stack | |
5494 | @c snarfed from stacks.c:421 | |
5495 | @deffn primitive make-stack obj . args | |
5496 | Create a new stack. If @var{obj} is @code{#t}, the current | |
5497 | evaluation stack is used for creating the stack frames, | |
5498 | otherwise the frames are taken from @var{obj} (which must be | |
5499 | either a debug object or a continuation). | |
7a095584 | 5500 | @var{args} must be a list of integers and specifies how the |
780ee65e NJ |
5501 | resulting stack will be narrowed. |
5502 | @end deffn | |
5503 | ||
5504 | \fstack-id | |
5505 | @c snarfed from stacks.c:512 | |
5506 | @deffn primitive stack-id stack | |
5507 | Return the identifier given to @var{stack} by @code{start-stack}. | |
5508 | @end deffn | |
5509 | ||
5510 | \fstack-ref | |
5511 | @c snarfed from stacks.c:548 | |
5512 | @deffn primitive stack-ref stack i | |
5513 | Return the @var{i}'th frame from @var{stack}. | |
5514 | @end deffn | |
5515 | ||
5516 | \fstack-length | |
5517 | @c snarfed from stacks.c:562 | |
5518 | @deffn primitive stack-length stack | |
5519 | Return the length of @var{stack}. | |
5520 | @end deffn | |
5521 | ||
5522 | \fframe? | |
5523 | @c snarfed from stacks.c:575 | |
5524 | @deffn primitive frame? obj | |
5525 | Return @code{#t} if @var{obj} is a stack frame. | |
5526 | @end deffn | |
5527 | ||
5528 | \flast-stack-frame | |
5529 | @c snarfed from stacks.c:586 | |
5530 | @deffn primitive last-stack-frame obj | |
5531 | Return a stack which consists of a single frame, which is the | |
5532 | last stack frame for @var{obj}. @var{obj} must be either a | |
5533 | debug object or a continuation. | |
5534 | @end deffn | |
5535 | ||
5536 | \fframe-number | |
5537 | @c snarfed from stacks.c:627 | |
5538 | @deffn primitive frame-number frame | |
5539 | Return the frame number of @var{frame}. | |
5540 | @end deffn | |
5541 | ||
5542 | \fframe-source | |
5543 | @c snarfed from stacks.c:637 | |
5544 | @deffn primitive frame-source frame | |
5545 | Return the source of @var{frame}. | |
5546 | @end deffn | |
5547 | ||
5548 | \fframe-procedure | |
5549 | @c snarfed from stacks.c:648 | |
5550 | @deffn primitive frame-procedure frame | |
5551 | Return the procedure for @var{frame}, or @code{#f} if no | |
5552 | procedure is associated with @var{frame}. | |
5553 | @end deffn | |
5554 | ||
5555 | \fframe-arguments | |
5556 | @c snarfed from stacks.c:660 | |
5557 | @deffn primitive frame-arguments frame | |
5558 | Return the arguments of @var{frame}. | |
5559 | @end deffn | |
5560 | ||
5561 | \fframe-previous | |
5562 | @c snarfed from stacks.c:671 | |
5563 | @deffn primitive frame-previous frame | |
5564 | Return the previous frame of @var{frame}, or @code{#f} if | |
5565 | @var{frame} is the first frame in its stack. | |
5566 | @end deffn | |
5567 | ||
5568 | \fframe-next | |
5569 | @c snarfed from stacks.c:687 | |
5570 | @deffn primitive frame-next frame | |
5571 | Return the next frame of @var{frame}, or @code{#f} if | |
5572 | @var{frame} is the last frame in its stack. | |
5573 | @end deffn | |
5574 | ||
5575 | \fframe-real? | |
5576 | @c snarfed from stacks.c:702 | |
5577 | @deffn primitive frame-real? frame | |
5578 | Return @code{#t} if @var{frame} is a real frame. | |
5579 | @end deffn | |
5580 | ||
5581 | \fframe-procedure? | |
5582 | @c snarfed from stacks.c:712 | |
5583 | @deffn primitive frame-procedure? frame | |
5584 | Return @code{#t} if a procedure is associated with @var{frame}. | |
5585 | @end deffn | |
5586 | ||
5587 | \fframe-evaluating-args? | |
5588 | @c snarfed from stacks.c:722 | |
5589 | @deffn primitive frame-evaluating-args? frame | |
5590 | Return @code{#t} if @var{frame} contains evaluated arguments. | |
5591 | @end deffn | |
5592 | ||
5593 | \fframe-overflow? | |
5594 | @c snarfed from stacks.c:732 | |
5595 | @deffn primitive frame-overflow? frame | |
5596 | Return @code{#t} if @var{frame} is an overflow frame. | |
5597 | @end deffn | |
5598 | ||
5599 | \fget-internal-real-time | |
89d04205 | 5600 | @c snarfed from stime.c:142 |
780ee65e | 5601 | @deffn primitive get-internal-real-time |
ae9f3a15 MG |
5602 | Return the number of time units since the interpreter was |
5603 | started. | |
780ee65e NJ |
5604 | @end deffn |
5605 | ||
5606 | \ftimes | |
89d04205 | 5607 | @c snarfed from stime.c:187 |
780ee65e | 5608 | @deffn primitive times |
ae9f3a15 MG |
5609 | Return an object with information about real and processor |
5610 | time. The following procedures accept such an object as an | |
5611 | argument and return a selected component: | |
7a095584 | 5612 | |
780ee65e NJ |
5613 | @table @code |
5614 | @item tms:clock | |
5615 | The current real time, expressed as time units relative to an | |
5616 | arbitrary base. | |
5617 | @item tms:utime | |
5618 | The CPU time units used by the calling process. | |
5619 | @item tms:stime | |
ae9f3a15 MG |
5620 | The CPU time units used by the system on behalf of the calling |
5621 | process. | |
780ee65e | 5622 | @item tms:cutime |
ae9f3a15 MG |
5623 | The CPU time units used by terminated child processes of the |
5624 | calling process, whose status has been collected (e.g., using | |
5625 | @code{waitpid}). | |
780ee65e NJ |
5626 | @item tms:cstime |
5627 | Similarly, the CPU times units used by the system on behalf of | |
5628 | terminated child processes. | |
5629 | @end table | |
5630 | @end deffn | |
5631 | ||
5632 | \fget-internal-run-time | |
89d04205 | 5633 | @c snarfed from stime.c:219 |
780ee65e | 5634 | @deffn primitive get-internal-run-time |
ae9f3a15 MG |
5635 | Return the number of time units of processor time used by the |
5636 | interpreter. Both @emph{system} and @emph{user} time are | |
5637 | included but subprocesses are not. | |
780ee65e NJ |
5638 | @end deffn |
5639 | ||
5640 | \fcurrent-time | |
89d04205 | 5641 | @c snarfed from stime.c:229 |
780ee65e | 5642 | @deffn primitive current-time |
ae9f3a15 MG |
5643 | Return the number of seconds since 1970-01-01 00:00:00 UTC, |
5644 | excluding leap seconds. | |
780ee65e NJ |
5645 | @end deffn |
5646 | ||
5647 | \fgettimeofday | |
89d04205 | 5648 | @c snarfed from stime.c:247 |
780ee65e | 5649 | @deffn primitive gettimeofday |
ae9f3a15 MG |
5650 | Return a pair containing the number of seconds and microseconds |
5651 | since 1970-01-01 00:00:00 UTC, excluding leap seconds. Note: | |
5652 | whether true microsecond resolution is available depends on the | |
5653 | operating system. | |
780ee65e NJ |
5654 | @end deffn |
5655 | ||
5656 | \flocaltime | |
89d04205 | 5657 | @c snarfed from stime.c:347 |
780ee65e | 5658 | @deffn primitive localtime time [zone] |
ae9f3a15 MG |
5659 | Return an object representing the broken down components of |
5660 | @var{time}, an integer like the one returned by | |
5661 | @code{current-time}. The time zone for the calculation is | |
5662 | optionally specified by @var{zone} (a string), otherwise the | |
5663 | @code{TZ} environment variable or the system default is used. | |
780ee65e NJ |
5664 | @end deffn |
5665 | ||
5666 | \fgmtime | |
89d04205 | 5667 | @c snarfed from stime.c:419 |
780ee65e | 5668 | @deffn primitive gmtime time |
ae9f3a15 MG |
5669 | Return an object representing the broken down components of |
5670 | @var{time}, an integer like the one returned by | |
5671 | @code{current-time}. The values are calculated for UTC. | |
780ee65e NJ |
5672 | @end deffn |
5673 | ||
5674 | \fmktime | |
89d04205 | 5675 | @c snarfed from stime.c:481 |
780ee65e NJ |
5676 | @deffn primitive mktime sbd_time [zone] |
5677 | @var{bd-time} is an object representing broken down time and @code{zone} | |
5678 | is an optional time zone specifier (otherwise the TZ environment variable | |
5679 | or the system default is used). | |
5680 | ||
5681 | Returns a pair: the car is a corresponding | |
5682 | integer time value like that returned | |
5683 | by @code{current-time}; the cdr is a broken down time object, similar to | |
5684 | as @var{bd-time} but with normalized values. | |
5685 | @end deffn | |
5686 | ||
5687 | \ftzset | |
89d04205 | 5688 | @c snarfed from stime.c:554 |
780ee65e NJ |
5689 | @deffn primitive tzset |
5690 | Initialize the timezone from the TZ environment variable | |
5691 | or the system default. It's not usually necessary to call this procedure | |
5692 | since it's done automatically by other procedures that depend on the | |
5693 | timezone. | |
5694 | @end deffn | |
5695 | ||
5696 | \fstrftime | |
89d04205 | 5697 | @c snarfed from stime.c:571 |
780ee65e NJ |
5698 | @deffn primitive strftime format stime |
5699 | Formats a time specification @var{time} using @var{template}. @var{time} | |
5700 | is an object with time components in the form returned by @code{localtime} | |
5701 | or @code{gmtime}. @var{template} is a string which can include formatting | |
5702 | specifications introduced by a @code{%} character. The formatting of | |
5703 | month and day names is dependent on the current locale. The value returned | |
5704 | is the formatted string. | |
5705 | @xref{Formatting Date and Time, , , libc, The GNU C Library Reference Manual}.) | |
5706 | @end deffn | |
5707 | ||
5708 | \fstrptime | |
89d04205 | 5709 | @c snarfed from stime.c:669 |
780ee65e NJ |
5710 | @deffn primitive strptime format string |
5711 | Performs the reverse action to @code{strftime}, parsing | |
5712 | @var{string} according to the specification supplied in | |
5713 | @var{template}. The interpretation of month and day names is | |
5714 | dependent on the current locale. The value returned is a pair. | |
5715 | The car has an object with time components | |
5716 | in the form returned by @code{localtime} or @code{gmtime}, | |
5717 | but the time zone components | |
5718 | are not usefully set. | |
5719 | The cdr reports the number of characters from @var{string} | |
5720 | which were used for the conversion. | |
5721 | @end deffn | |
5722 | ||
5723 | \fstring? | |
5724 | @c snarfed from strings.c:62 | |
5725 | @deffn primitive string? obj | |
ae9f3a15 | 5726 | Return @code{#t} iff @var{obj} is a string, else returns |
780ee65e NJ |
5727 | @code{#f}. |
5728 | @end deffn | |
5729 | ||
5730 | \fread-only-string? | |
89d04205 | 5731 | @c snarfed from strings.c:78 |
780ee65e | 5732 | @deffn primitive read-only-string? obj |
89d04205 NJ |
5733 | Return @code{#t} if @var{obj} is either a string or a symbol, |
5734 | otherwise return @code{#f}. | |
780ee65e NJ |
5735 | @end deffn |
5736 | ||
5737 | \flist->string | |
89d04205 | 5738 | @c snarfed from strings.c:87 |
780ee65e NJ |
5739 | @deffn primitive list->string |
5740 | scm_string | |
5741 | @end deffn | |
5742 | ||
5743 | \fstring | |
89d04205 | 5744 | @c snarfed from strings.c:93 |
780ee65e NJ |
5745 | @deffn primitive string . chrs |
5746 | @deffnx primitive list->string chrs | |
ae9f3a15 | 5747 | Return a newly allocated string composed of the arguments, |
780ee65e NJ |
5748 | @var{chrs}. |
5749 | @end deffn | |
5750 | ||
5751 | \fmake-string | |
89d04205 | 5752 | @c snarfed from strings.c:246 |
780ee65e NJ |
5753 | @deffn primitive make-string k [chr] |
5754 | Return a newly allocated string of | |
5755 | length @var{k}. If @var{chr} is given, then all elements of | |
5756 | the string are initialized to @var{chr}, otherwise the contents | |
5757 | of the @var{string} are unspecified. | |
5758 | @end deffn | |
5759 | ||
5760 | \fstring-length | |
89d04205 | 5761 | @c snarfed from strings.c:279 |
780ee65e NJ |
5762 | @deffn primitive string-length string |
5763 | Return the number of characters in @var{string}. | |
5764 | @end deffn | |
5765 | ||
5766 | \fstring-ref | |
89d04205 | 5767 | @c snarfed from strings.c:290 |
780ee65e NJ |
5768 | @deffn primitive string-ref str k |
5769 | Return character @var{k} of @var{str} using zero-origin | |
5770 | indexing. @var{k} must be a valid index of @var{str}. | |
5771 | @end deffn | |
5772 | ||
5773 | \fstring-set! | |
89d04205 | 5774 | @c snarfed from strings.c:307 |
780ee65e NJ |
5775 | @deffn primitive string-set! str k chr |
5776 | Store @var{chr} in element @var{k} of @var{str} and return | |
5777 | an unspecified value. @var{k} must be a valid index of | |
5778 | @var{str}. | |
5779 | @end deffn | |
5780 | ||
5781 | \fsubstring | |
89d04205 | 5782 | @c snarfed from strings.c:330 |
780ee65e NJ |
5783 | @deffn primitive substring str start [end] |
5784 | Return a newly allocated string formed from the characters | |
5785 | of @var{str} beginning with index @var{start} (inclusive) and | |
5786 | ending with index @var{end} (exclusive). | |
5787 | @var{str} must be a string, @var{start} and @var{end} must be | |
5788 | exact integers satisfying: | |
5789 | ||
5790 | 0 <= @var{start} <= @var{end} <= (string-length @var{str}). | |
5791 | @end deffn | |
5792 | ||
5793 | \fstring-append | |
89d04205 | 5794 | @c snarfed from strings.c:353 |
780ee65e NJ |
5795 | @deffn primitive string-append . args |
5796 | Return a newly allocated string whose characters form the | |
5797 | concatenation of the given strings, @var{args}. | |
5798 | @end deffn | |
5799 | ||
5800 | \fmake-shared-substring | |
89d04205 | 5801 | @c snarfed from strings.c:393 |
ae9f3a15 | 5802 | @deffn primitive make-shared-substring str [start [end]] |
72ad43dc | 5803 | Return a shared substring of @var{str}. The arguments are the |
ae9f3a15 MG |
5804 | same as for the @code{substring} function: the shared substring |
5805 | returned includes all of the text from @var{str} between | |
5806 | indexes @var{start} (inclusive) and @var{end} (exclusive). If | |
5807 | @var{end} is omitted, it defaults to the end of @var{str}. The | |
5808 | shared substring returned by @code{make-shared-substring} | |
5809 | occupies the same storage space as @var{str}. | |
780ee65e NJ |
5810 | @end deffn |
5811 | ||
5812 | \fstring-index | |
89d04205 | 5813 | @c snarfed from strop.c:116 |
780ee65e NJ |
5814 | @deffn primitive string-index str chr [frm [to]] |
5815 | Return the index of the first occurrence of @var{chr} in | |
5816 | @var{str}. The optional integer arguments @var{frm} and | |
5817 | @var{to} limit the search to a portion of the string. This | |
5818 | procedure essentially implements the @code{index} or | |
a6be01a4 | 5819 | @code{strchr} functions from the C library. |
7a095584 | 5820 | |
ae9f3a15 | 5821 | @lisp |
a6be01a4 | 5822 | (string-index "weiner" #\e) |
780ee65e NJ |
5823 | @result{} 1 |
5824 | ||
a6be01a4 | 5825 | (string-index "weiner" #\e 2) |
780ee65e NJ |
5826 | @result{} 4 |
5827 | ||
a6be01a4 | 5828 | (string-index "weiner" #\e 2 4) |
780ee65e | 5829 | @result{} #f |
ae9f3a15 | 5830 | @end lisp |
780ee65e NJ |
5831 | @end deffn |
5832 | ||
5833 | \fstring-rindex | |
89d04205 | 5834 | @c snarfed from strop.c:146 |
780ee65e | 5835 | @deffn primitive string-rindex str chr [frm [to]] |
ae9f3a15 MG |
5836 | Like @code{string-index}, but search from the right of the |
5837 | string rather than from the left. This procedure essentially | |
5838 | implements the @code{rindex} or @code{strrchr} functions from | |
5839 | the C library. | |
7a095584 | 5840 | |
ae9f3a15 | 5841 | @lisp |
a6be01a4 | 5842 | (string-rindex "weiner" #\e) |
780ee65e NJ |
5843 | @result{} 4 |
5844 | ||
a6be01a4 | 5845 | (string-rindex "weiner" #\e 2 4) |
780ee65e NJ |
5846 | @result{} #f |
5847 | ||
a6be01a4 | 5848 | (string-rindex "weiner" #\e 2 5) |
780ee65e | 5849 | @result{} 4 |
ae9f3a15 | 5850 | @end lisp |
780ee65e NJ |
5851 | @end deffn |
5852 | ||
5853 | \fsubstring-move-left! | |
89d04205 | 5854 | @c snarfed from strop.c:163 |
780ee65e NJ |
5855 | @deffn primitive substring-move-left! |
5856 | scm_substring_move_x | |
5857 | @end deffn | |
5858 | ||
5859 | \fsubstring-move-right! | |
89d04205 | 5860 | @c snarfed from strop.c:164 |
780ee65e NJ |
5861 | @deffn primitive substring-move-right! |
5862 | scm_substring_move_x | |
5863 | @end deffn | |
5864 | ||
5865 | \fsubstring-move! | |
89d04205 | 5866 | @c snarfed from strop.c:238 |
780ee65e NJ |
5867 | @deffn primitive substring-move! str1 start1 end1 str2 start2 |
5868 | @deffnx primitive substring-move-left! str1 start1 end1 str2 start2 | |
5869 | @deffnx primitive substring-move-right! str1 start1 end1 str2 start2 | |
5870 | Copy the substring of @var{str1} bounded by @var{start1} and @var{end1} | |
5871 | into @var{str2} beginning at position @var{end2}. | |
5872 | @code{substring-move-right!} begins copying from the rightmost character | |
5873 | and moves left, and @code{substring-move-left!} copies from the leftmost | |
5874 | character moving right. | |
5875 | ||
5876 | It is useful to have two functions that copy in different directions so | |
5877 | that substrings can be copied back and forth within a single string. If | |
5878 | you wish to copy text from the left-hand side of a string to the | |
5879 | right-hand side of the same string, and the source and destination | |
5880 | overlap, you must be careful to copy the rightmost characters of the | |
5881 | text first, to avoid clobbering your data. Hence, when @var{str1} and | |
5882 | @var{str2} are the same string, you should use | |
5883 | @code{substring-move-right!} when moving text from left to right, and | |
5884 | @code{substring-move-left!} otherwise. If @code{str1} and @samp{str2} | |
5885 | are different strings, it does not matter which function you use. | |
5886 | @end deffn | |
5887 | ||
5888 | \fsubstring-fill! | |
89d04205 | 5889 | @c snarfed from strop.c:274 |
780ee65e | 5890 | @deffn primitive substring-fill! str start end fill |
ae9f3a15 MG |
5891 | Change every character in @var{str} between @var{start} and |
5892 | @var{end} to @var{fill}. | |
7a095584 | 5893 | |
ae9f3a15 | 5894 | @lisp |
780ee65e | 5895 | (define y "abcdefg") |
a6be01a4 | 5896 | (substring-fill! y 1 3 #\r) |
780ee65e NJ |
5897 | y |
5898 | @result{} "arrdefg" | |
ae9f3a15 | 5899 | @end lisp |
780ee65e NJ |
5900 | @end deffn |
5901 | ||
5902 | \fstring-null? | |
89d04205 | 5903 | @c snarfed from strop.c:299 |
780ee65e | 5904 | @deffn primitive string-null? str |
ae9f3a15 MG |
5905 | Return @code{#t} if @var{str}'s length is nonzero, and |
5906 | @code{#f} otherwise. | |
5907 | @lisp | |
5908 | (string-null? "") @result{} #t | |
5909 | y @result{} "foo" | |
5910 | (string-null? y) @result{} #f | |
5911 | @end lisp | |
780ee65e NJ |
5912 | @end deffn |
5913 | ||
5914 | \fstring->list | |
89d04205 | 5915 | @c snarfed from strop.c:313 |
780ee65e | 5916 | @deffn primitive string->list str |
ae9f3a15 MG |
5917 | Return a newly allocated list of the characters that make up |
5918 | the given string @var{str}. @code{string->list} and | |
5919 | @code{list->string} are inverses as far as @samp{equal?} is | |
5920 | concerned. | |
780ee65e NJ |
5921 | @end deffn |
5922 | ||
5923 | \fstring-copy | |
89d04205 | 5924 | @c snarfed from strop.c:338 |
780ee65e | 5925 | @deffn primitive string-copy str |
ae9f3a15 | 5926 | Return a newly allocated copy of the given @var{string}. |
780ee65e NJ |
5927 | @end deffn |
5928 | ||
5929 | \fstring-fill! | |
89d04205 | 5930 | @c snarfed from strop.c:351 |
780ee65e | 5931 | @deffn primitive string-fill! str chr |
ae9f3a15 MG |
5932 | Store @var{char} in every element of the given @var{string} and |
5933 | return an unspecified value. | |
780ee65e NJ |
5934 | @end deffn |
5935 | ||
5936 | \fstring-upcase! | |
89d04205 | 5937 | @c snarfed from strop.c:386 |
780ee65e | 5938 | @deffn primitive string-upcase! str |
ae9f3a15 MG |
5939 | Destructively upcase every character in @var{str} and return |
5940 | @var{str}. | |
5941 | @lisp | |
5942 | y @result{} "arrdefg" | |
5943 | (string-upcase! y) @result{} "ARRDEFG" | |
5944 | y @result{} "ARRDEFG" | |
5945 | @end lisp | |
780ee65e NJ |
5946 | @end deffn |
5947 | ||
5948 | \fstring-upcase | |
89d04205 | 5949 | @c snarfed from strop.c:399 |
780ee65e | 5950 | @deffn primitive string-upcase str |
ae9f3a15 MG |
5951 | Return a freshly allocated string containing the characters of |
5952 | @var{str} in upper case. | |
780ee65e NJ |
5953 | @end deffn |
5954 | ||
5955 | \fstring-downcase! | |
89d04205 | 5956 | @c snarfed from strop.c:431 |
780ee65e | 5957 | @deffn primitive string-downcase! str |
ae9f3a15 MG |
5958 | Destructively downcase every character in @var{str} and return |
5959 | @var{str}. | |
5960 | @lisp | |
5961 | y @result{} "ARRDEFG" | |
5962 | (string-downcase! y) @result{} "arrdefg" | |
5963 | y @result{} "arrdefg" | |
5964 | @end lisp | |
780ee65e NJ |
5965 | @end deffn |
5966 | ||
5967 | \fstring-downcase | |
89d04205 | 5968 | @c snarfed from strop.c:444 |
780ee65e | 5969 | @deffn primitive string-downcase str |
ae9f3a15 MG |
5970 | Return a freshly allocation string containing the characters in |
5971 | @var{str} in lower case. | |
780ee65e NJ |
5972 | @end deffn |
5973 | ||
5974 | \fstring-capitalize! | |
89d04205 | 5975 | @c snarfed from strop.c:488 |
780ee65e | 5976 | @deffn primitive string-capitalize! str |
ae9f3a15 MG |
5977 | Upcase the first character of every word in @var{str} |
5978 | destructively and return @var{str}. | |
7a095584 | 5979 | |
ae9f3a15 MG |
5980 | @lisp |
5981 | y @result{} "hello world" | |
5982 | (string-capitalize! y) @result{} "Hello World" | |
5983 | y @result{} "Hello World" | |
5984 | @end lisp | |
780ee65e NJ |
5985 | @end deffn |
5986 | ||
5987 | \fstring-capitalize | |
89d04205 | 5988 | @c snarfed from strop.c:502 |
780ee65e | 5989 | @deffn primitive string-capitalize str |
ae9f3a15 MG |
5990 | Return a freshly allocated string with the characters in |
5991 | @var{str}, where the first character of every word is | |
5992 | capitalized. | |
780ee65e NJ |
5993 | @end deffn |
5994 | ||
5995 | \fstring-ci->symbol | |
89d04205 | 5996 | @c snarfed from strop.c:516 |
780ee65e | 5997 | @deffn primitive string-ci->symbol str |
ae9f3a15 MG |
5998 | Return the symbol whose name is @var{str}. @var{str} is |
5999 | converted to lowercase before the conversion is done, if Guile | |
6000 | is currently reading symbols case--insensitively. | |
780ee65e NJ |
6001 | @end deffn |
6002 | ||
6003 | \fstring=? | |
6004 | @c snarfed from strorder.c:64 | |
6005 | @deffn primitive string=? s1 s2 | |
ae9f3a15 MG |
6006 | Lexicographic equality predicate; return @code{#t} if the two |
6007 | strings are the same length and contain the same characters in | |
6008 | the same positions, otherwise return @code{#f}. | |
7a095584 | 6009 | |
780ee65e NJ |
6010 | The procedure @code{string-ci=?} treats upper and lower case |
6011 | letters as though they were the same character, but | |
6012 | @code{string=?} treats upper and lower case as distinct | |
6013 | characters. | |
6014 | @end deffn | |
6015 | ||
6016 | \fstring-ci=? | |
6017 | @c snarfed from strorder.c:99 | |
6018 | @deffn primitive string-ci=? s1 s2 | |
ae9f3a15 MG |
6019 | Case-insensitive string equality predicate; return @code{#t} if |
6020 | the two strings are the same length and their component | |
780ee65e | 6021 | characters match (ignoring case) at each position; otherwise |
ae9f3a15 | 6022 | return @code{#f}. |
780ee65e NJ |
6023 | @end deffn |
6024 | ||
6025 | \fstring<? | |
6026 | @c snarfed from strorder.c:156 | |
6027 | @deffn primitive string<? s1 s2 | |
ae9f3a15 MG |
6028 | Lexicographic ordering predicate; return @code{#t} if @var{s1} |
6029 | is lexicographically less than @var{s2}. | |
780ee65e NJ |
6030 | @end deffn |
6031 | ||
6032 | \fstring<=? | |
89d04205 | 6033 | @c snarfed from strorder.c:170 |
780ee65e | 6034 | @deffn primitive string<=? s1 s2 |
ae9f3a15 MG |
6035 | Lexicographic ordering predicate; return @code{#t} if @var{s1} |
6036 | is lexicographically less than or equal to @var{s2}. | |
780ee65e NJ |
6037 | @end deffn |
6038 | ||
6039 | \fstring>? | |
89d04205 | 6040 | @c snarfed from strorder.c:184 |
780ee65e | 6041 | @deffn primitive string>? s1 s2 |
ae9f3a15 MG |
6042 | Lexicographic ordering predicate; return @code{#t} if @var{s1} |
6043 | is lexicographically greater than @var{s2}. | |
780ee65e NJ |
6044 | @end deffn |
6045 | ||
6046 | \fstring>=? | |
89d04205 | 6047 | @c snarfed from strorder.c:198 |
780ee65e | 6048 | @deffn primitive string>=? s1 s2 |
ae9f3a15 MG |
6049 | Lexicographic ordering predicate; return @code{#t} if @var{s1} |
6050 | is lexicographically greater than or equal to @var{s2}. | |
780ee65e NJ |
6051 | @end deffn |
6052 | ||
6053 | \fstring-ci<? | |
89d04205 | 6054 | @c snarfed from strorder.c:237 |
780ee65e | 6055 | @deffn primitive string-ci<? s1 s2 |
ae9f3a15 MG |
6056 | Case insensitive lexicographic ordering predicate; return |
6057 | @code{#t} if @var{s1} is lexicographically less than @var{s2} | |
6058 | regardless of case. | |
780ee65e NJ |
6059 | @end deffn |
6060 | ||
6061 | \fstring-ci<=? | |
89d04205 | 6062 | @c snarfed from strorder.c:252 |
780ee65e | 6063 | @deffn primitive string-ci<=? s1 s2 |
ae9f3a15 MG |
6064 | Case insensitive lexicographic ordering predicate; return |
6065 | @code{#t} if @var{s1} is lexicographically less than or equal | |
6066 | to @var{s2} regardless of case. | |
780ee65e NJ |
6067 | @end deffn |
6068 | ||
6069 | \fstring-ci>? | |
89d04205 | 6070 | @c snarfed from strorder.c:267 |
780ee65e | 6071 | @deffn primitive string-ci>? s1 s2 |
ae9f3a15 MG |
6072 | Case insensitive lexicographic ordering predicate; return |
6073 | @code{#t} if @var{s1} is lexicographically greater than | |
6074 | @var{s2} regardless of case. | |
780ee65e NJ |
6075 | @end deffn |
6076 | ||
6077 | \fstring-ci>=? | |
89d04205 | 6078 | @c snarfed from strorder.c:282 |
780ee65e | 6079 | @deffn primitive string-ci>=? s1 s2 |
ae9f3a15 MG |
6080 | Case insensitive lexicographic ordering predicate; return |
6081 | @code{#t} if @var{s1} is lexicographically greater than or | |
6082 | equal to @var{s2} regardless of case. | |
780ee65e NJ |
6083 | @end deffn |
6084 | ||
6085 | \fobject->string | |
6086 | @c snarfed from strports.c:318 | |
6087 | @deffn primitive object->string obj [printer] | |
6088 | Return a Scheme string obtained by printing @var{obj}. | |
6089 | Printing function can be specified by the optional second | |
6090 | argument @var{printer} (default: @code{write}). | |
6091 | @end deffn | |
6092 | ||
6093 | \fcall-with-output-string | |
6094 | @c snarfed from strports.c:352 | |
6095 | @deffn primitive call-with-output-string proc | |
6096 | Calls the one-argument procedure @var{proc} with a newly created output | |
6097 | port. When the function returns, the string composed of the characters | |
6098 | written into the port is returned. | |
6099 | @end deffn | |
6100 | ||
6101 | \fcall-with-input-string | |
6102 | @c snarfed from strports.c:371 | |
ae9f3a15 MG |
6103 | @deffn primitive call-with-input-string string proc |
6104 | Calls the one-argument procedure @var{proc} with a newly | |
6105 | created input port from which @var{string}'s contents may be | |
6106 | read. The value yielded by the @var{proc} is returned. | |
780ee65e NJ |
6107 | @end deffn |
6108 | ||
6109 | \fopen-input-string | |
6110 | @c snarfed from strports.c:384 | |
6111 | @deffn primitive open-input-string str | |
ae9f3a15 MG |
6112 | Take a string and return an input port that delivers characters |
6113 | from the string. The port can be closed by | |
780ee65e NJ |
6114 | @code{close-input-port}, though its storage will be reclaimed |
6115 | by the garbage collector if it becomes inaccessible. | |
6116 | @end deffn | |
6117 | ||
6118 | \fopen-output-string | |
6119 | @c snarfed from strports.c:398 | |
6120 | @deffn primitive open-output-string | |
ae9f3a15 | 6121 | Return an output port that will accumulate characters for |
780ee65e NJ |
6122 | retrieval by @code{get-output-string}. The port can be closed |
6123 | by the procedure @code{close-output-port}, though its storage | |
6124 | will be reclaimed by the garbage collector if it becomes | |
6125 | inaccessible. | |
6126 | @end deffn | |
6127 | ||
6128 | \fget-output-string | |
6129 | @c snarfed from strports.c:415 | |
6130 | @deffn primitive get-output-string port | |
6131 | Given an output port created by @code{open-output-string}, | |
ae9f3a15 | 6132 | return a string consisting of the characters that have been |
780ee65e NJ |
6133 | output to the port so far. |
6134 | @end deffn | |
6135 | ||
6136 | \feval-string | |
6137 | @c snarfed from strports.c:456 | |
6138 | @deffn primitive eval-string string | |
6139 | Evaluate @var{string} as the text representation of a Scheme | |
6140 | form or forms, and return whatever value they produce. | |
6141 | Evaluation takes place in the environment returned by the | |
6142 | procedure @code{interaction-environment}. | |
6143 | @end deffn | |
6144 | ||
6145 | \fmake-struct-layout | |
6146 | @c snarfed from struct.c:79 | |
6147 | @deffn primitive make-struct-layout fields | |
6148 | Return a new structure layout object. | |
6149 | ||
6150 | @var{fields} must be a string made up of pairs of characters | |
6151 | strung together. The first character of each pair describes a field | |
6152 | type, the second a field protection. Allowed types are 'p' for | |
6153 | GC-protected Scheme data, 'u' for unprotected binary data, and 's' for | |
6154 | a field that points to the structure itself. Allowed protections | |
6155 | are 'w' for mutable fields, 'r' for read-only fields, and 'o' for opaque | |
6156 | fields. The last field protection specification may be capitalized to | |
6157 | indicate that the field is a tail-array. | |
6158 | @end deffn | |
6159 | ||
6160 | \fstruct? | |
6161 | @c snarfed from struct.c:246 | |
6162 | @deffn primitive struct? x | |
6163 | Return @code{#t} iff @var{obj} is a structure object, else | |
6164 | @code{#f}. | |
6165 | @end deffn | |
6166 | ||
6167 | \fstruct-vtable? | |
6168 | @c snarfed from struct.c:255 | |
6169 | @deffn primitive struct-vtable? x | |
6170 | Return @code{#t} iff obj is a vtable structure. | |
6171 | @end deffn | |
6172 | ||
6173 | \fmake-struct | |
6174 | @c snarfed from struct.c:437 | |
6175 | @deffn primitive make-struct vtable tail_array_size . init | |
6176 | Create a new structure. | |
6177 | ||
6178 | @var{type} must be a vtable structure (@pxref{Vtables}). | |
6179 | ||
6180 | @var{tail-elts} must be a non-negative integer. If the layout | |
6181 | specification indicated by @var{type} includes a tail-array, | |
6182 | this is the number of elements allocated to that array. | |
6183 | ||
6184 | The @var{init1}, @dots{} are optional arguments describing how | |
6185 | successive fields of the structure should be initialized. Only fields | |
6186 | with protection 'r' or 'w' can be initialized, except for fields of | |
6187 | type 's', which are automatically initialized to point to the new | |
6188 | structure itself; fields with protection 'o' can not be initialized by | |
6189 | Scheme programs. | |
6190 | ||
6191 | If fewer optional arguments than initializable fields are supplied, | |
6192 | fields of type 'p' get default value #f while fields of type 'u' are | |
6193 | initialized to 0. | |
6194 | ||
6195 | Structs are currently the basic representation for record-like data | |
6196 | structures in Guile. The plan is to eventually replace them with a | |
6197 | new representation which will at the same time be easier to use and | |
6198 | more powerful. | |
6199 | ||
6200 | For more information, see the documentation for @code{make-vtable-vtable}. | |
6201 | @end deffn | |
6202 | ||
6203 | \fmake-vtable-vtable | |
6204 | @c snarfed from struct.c:523 | |
6205 | @deffn primitive make-vtable-vtable user_fields tail_array_size . init | |
6206 | Return a new, self-describing vtable structure. | |
6207 | ||
6208 | @var{user-fields} is a string describing user defined fields of the | |
6209 | vtable beginning at index @code{vtable-offset-user} | |
6210 | (see @code{make-struct-layout}). | |
6211 | ||
6212 | @var{tail-size} specifies the size of the tail-array (if any) of | |
6213 | this vtable. | |
6214 | ||
6215 | @var{init1}, @dots{} are the optional initializers for the fields of | |
6216 | the vtable. | |
6217 | ||
6218 | Vtables have one initializable system field---the struct printer. | |
6219 | This field comes before the user fields in the initializers passed | |
6220 | to @code{make-vtable-vtable} and @code{make-struct}, and thus works as | |
6221 | a third optional argument to @code{make-vtable-vtable} and a fourth to | |
6222 | @code{make-struct} when creating vtables: | |
6223 | ||
6224 | If the value is a procedure, it will be called instead of the standard | |
6225 | printer whenever a struct described by this vtable is printed. | |
6226 | The procedure will be called with arguments STRUCT and PORT. | |
6227 | ||
6228 | The structure of a struct is described by a vtable, so the vtable is | |
6229 | in essence the type of the struct. The vtable is itself a struct with | |
6230 | a vtable. This could go on forever if it weren't for the | |
6231 | vtable-vtables which are self-describing vtables, and thus terminate | |
6232 | the chain. | |
6233 | ||
6234 | There are several potential ways of using structs, but the standard | |
6235 | one is to use three kinds of structs, together building up a type | |
6236 | sub-system: one vtable-vtable working as the root and one or several | |
6237 | "types", each with a set of "instances". (The vtable-vtable should be | |
6238 | compared to the class <class> which is the class of itself.) | |
6239 | ||
ae9f3a15 | 6240 | @lisp |
780ee65e NJ |
6241 | (define ball-root (make-vtable-vtable "pr" 0)) |
6242 | ||
6243 | (define (make-ball-type ball-color) | |
6244 | (make-struct ball-root 0 | |
6245 | (make-struct-layout "pw") | |
6246 | (lambda (ball port) | |
6247 | (format port "#<a ~A ball owned by ~A>" | |
6248 | (color ball) | |
6249 | (owner ball))) | |
6250 | ball-color)) | |
6251 | (define (color ball) (struct-ref (struct-vtable ball) vtable-offset-user)) | |
6252 | (define (owner ball) (struct-ref ball 0)) | |
6253 | ||
6254 | (define red (make-ball-type 'red)) | |
6255 | (define green (make-ball-type 'green)) | |
6256 | ||
6257 | (define (make-ball type owner) (make-struct type 0 owner)) | |
6258 | ||
6259 | (define ball (make-ball green 'Nisse)) | |
6260 | ball @result{} #<a green ball owned by Nisse> | |
ae9f3a15 | 6261 | @end lisp |
780ee65e NJ |
6262 | @end deffn |
6263 | ||
6264 | \fstruct-ref | |
6265 | @c snarfed from struct.c:565 | |
6266 | @deffn primitive struct-ref handle pos | |
6267 | @deffnx primitive struct-set! struct n value | |
6268 | Access (or modify) the @var{n}th field of @var{struct}. | |
6269 | ||
6270 | If the field is of type 'p', then it can be set to an arbitrary value. | |
6271 | ||
6272 | If the field is of type 'u', then it can only be set to a non-negative | |
6273 | integer value small enough to fit in one machine word. | |
6274 | @end deffn | |
6275 | ||
6276 | \fstruct-set! | |
6277 | @c snarfed from struct.c:643 | |
6278 | @deffn primitive struct-set! handle pos val | |
6279 | Set the slot of the structure @var{handle} with index @var{pos} | |
6280 | to @var{val}. Signal an error if the slot can not be written | |
6281 | to. | |
6282 | @end deffn | |
6283 | ||
6284 | \fstruct-vtable | |
6285 | @c snarfed from struct.c:713 | |
6286 | @deffn primitive struct-vtable handle | |
6287 | Return the vtable structure that describes the type of @var{struct}. | |
6288 | @end deffn | |
6289 | ||
6290 | \fstruct-vtable-tag | |
6291 | @c snarfed from struct.c:724 | |
6292 | @deffn primitive struct-vtable-tag handle | |
6293 | Return the vtable tag of the structure @var{handle}. | |
6294 | @end deffn | |
6295 | ||
6296 | \fstruct-vtable-name | |
6297 | @c snarfed from struct.c:763 | |
6298 | @deffn primitive struct-vtable-name vtable | |
6299 | Return the name of the vtable @var{vtable}. | |
6300 | @end deffn | |
6301 | ||
6302 | \fset-struct-vtable-name! | |
6303 | @c snarfed from struct.c:773 | |
6304 | @deffn primitive set-struct-vtable-name! vtable name | |
6305 | Set the name of the vtable @var{vtable} to @var{name}. | |
6306 | @end deffn | |
6307 | ||
6308 | \fsymbol? | |
6309 | @c snarfed from symbols.c:422 | |
6310 | @deffn primitive symbol? obj | |
ae9f3a15 MG |
6311 | Return @code{#t} if @var{obj} is a symbol, otherwise return |
6312 | @code{#f}. | |
780ee65e NJ |
6313 | @end deffn |
6314 | ||
6315 | \fsymbol->string | |
89d04205 | 6316 | @c snarfed from symbols.c:453 |
780ee65e | 6317 | @deffn primitive symbol->string s |
ae9f3a15 MG |
6318 | Return the name of @var{symbol} as a string. If the symbol was |
6319 | part of an object returned as the value of a literal expression | |
6320 | (section @pxref{Literal expressions,,,r4rs, The Revised^4 | |
6321 | Report on Scheme}) or by a call to the @code{read} procedure, | |
6322 | and its name contains alphabetic characters, then the string | |
6323 | returned will contain characters in the implementation's | |
6324 | preferred standard case---some implementations will prefer | |
6325 | upper case, others lower case. If the symbol was returned by | |
6326 | @code{string->symbol}, the case of characters in the string | |
6327 | returned will be the same as the case in the string that was | |
6328 | passed to @code{string->symbol}. It is an error to apply | |
6329 | mutation procedures like @code{string-set!} to strings returned | |
6330 | by this procedure. | |
7a095584 | 6331 | |
780ee65e NJ |
6332 | The following examples assume that the implementation's |
6333 | standard case is lower case: | |
7a095584 | 6334 | |
780ee65e | 6335 | @lisp |
ae9f3a15 MG |
6336 | (symbol->string 'flying-fish) @result{} "flying-fish" |
6337 | (symbol->string 'Martin) @result{} "martin" | |
780ee65e NJ |
6338 | (symbol->string |
6339 | (string->symbol "Malvina")) @result{} "Malvina" | |
6340 | @end lisp | |
6341 | @end deffn | |
6342 | ||
6343 | \fstring->symbol | |
89d04205 | 6344 | @c snarfed from symbols.c:483 |
ae9f3a15 MG |
6345 | @deffn primitive string->symbol string |
6346 | Return the symbol whose name is @var{string}. This procedure | |
780ee65e NJ |
6347 | can create symbols with names containing special characters or |
6348 | letters in the non-standard case, but it is usually a bad idea | |
ae9f3a15 MG |
6349 | to create such symbols because in some implementations of |
6350 | Scheme they cannot be read as themselves. See | |
6351 | @code{symbol->string}. | |
7a095584 | 6352 | |
780ee65e NJ |
6353 | The following examples assume that the implementation's |
6354 | standard case is lower case: | |
7a095584 | 6355 | |
780ee65e NJ |
6356 | @lisp |
6357 | (eq? 'mISSISSIppi 'mississippi) @result{} #t | |
6358 | (string->symbol "mISSISSIppi") @result{} @r{the symbol with name "mISSISSIppi"} | |
6359 | (eq? 'bitBlt (string->symbol "bitBlt")) @result{} #f | |
6360 | (eq? 'JollyWog | |
6361 | (string->symbol (symbol->string 'JollyWog))) @result{} #t | |
6362 | (string=? "K. Harper, M.D." | |
6363 | (symbol->string | |
6364 | (string->symbol "K. Harper, M.D."))) @result{}#t | |
6365 | @end lisp | |
6366 | @end deffn | |
6367 | ||
6368 | \fstring->obarray-symbol | |
89d04205 | 6369 | @c snarfed from symbols.c:505 |
780ee65e NJ |
6370 | @deffn primitive string->obarray-symbol o s [softp] |
6371 | Intern a new symbol in @var{obarray}, a symbol table, with name | |
6372 | @var{string}. | |
6373 | ||
6374 | If @var{obarray} is @code{#f}, use the default system symbol table. If | |
6375 | @var{obarray} is @code{#t}, the symbol should not be interned in any | |
6376 | symbol table; merely return the pair (@var{symbol} | |
6377 | . @var{#<undefined>}). | |
6378 | ||
6379 | The @var{soft?} argument determines whether new symbol table entries | |
6380 | should be created when the specified symbol is not already present in | |
6381 | @var{obarray}. If @var{soft?} is specified and is a true value, then | |
6382 | new entries should not be added for symbols not already present in the | |
6383 | table; instead, simply return @code{#f}. | |
6384 | @end deffn | |
6385 | ||
6386 | \fintern-symbol | |
89d04205 | 6387 | @c snarfed from symbols.c:537 |
780ee65e NJ |
6388 | @deffn primitive intern-symbol o s |
6389 | Add a new symbol to @var{obarray} with name @var{string}, bound to an | |
6390 | unspecified initial value. The symbol table is not modified if a symbol | |
6391 | with this name is already present. | |
6392 | @end deffn | |
6393 | ||
6394 | \funintern-symbol | |
89d04205 | 6395 | @c snarfed from symbols.c:574 |
780ee65e NJ |
6396 | @deffn primitive unintern-symbol o s |
6397 | Remove the symbol with name @var{string} from @var{obarray}. This | |
6398 | function returns @code{#t} if the symbol was present and @code{#f} | |
6399 | otherwise. | |
6400 | @end deffn | |
6401 | ||
6402 | \fsymbol-binding | |
89d04205 | 6403 | @c snarfed from symbols.c:615 |
780ee65e NJ |
6404 | @deffn primitive symbol-binding o s |
6405 | Look up in @var{obarray} the symbol whose name is @var{string}, and | |
6406 | return the value to which it is bound. If @var{obarray} is @code{#f}, | |
6407 | use the global symbol table. If @var{string} is not interned in | |
6408 | @var{obarray}, an error is signalled. | |
6409 | @end deffn | |
6410 | ||
6411 | \fsymbol-interned? | |
89d04205 | 6412 | @c snarfed from symbols.c:632 |
780ee65e NJ |
6413 | @deffn primitive symbol-interned? o s |
6414 | Return @code{#t} if @var{obarray} contains a symbol with name | |
6415 | @var{string}, and @code{#f} otherwise. | |
6416 | @end deffn | |
6417 | ||
6418 | \fsymbol-bound? | |
89d04205 | 6419 | @c snarfed from symbols.c:655 |
780ee65e NJ |
6420 | @deffn primitive symbol-bound? o s |
6421 | Return @code{#t} if @var{obarray} contains a symbol with name | |
6422 | @var{string} bound to a defined value. This differs from | |
6423 | @var{symbol-interned?} in that the mere mention of a symbol | |
6424 | usually causes it to be interned; @code{symbol-bound?} | |
6425 | determines whether a symbol has been given any meaningful | |
6426 | value. | |
6427 | @end deffn | |
6428 | ||
6429 | \fsymbol-set! | |
89d04205 | 6430 | @c snarfed from symbols.c:673 |
780ee65e NJ |
6431 | @deffn primitive symbol-set! o s v |
6432 | Find the symbol in @var{obarray} whose name is @var{string}, and rebind | |
6433 | it to @var{value}. An error is signalled if @var{string} is not present | |
6434 | in @var{obarray}. | |
6435 | @end deffn | |
6436 | ||
6437 | \fsymbol-fref | |
89d04205 | 6438 | @c snarfed from symbols.c:690 |
780ee65e NJ |
6439 | @deffn primitive symbol-fref s |
6440 | Return the contents of @var{symbol}'s @dfn{function slot}. | |
6441 | @end deffn | |
6442 | ||
6443 | \fsymbol-pref | |
89d04205 | 6444 | @c snarfed from symbols.c:701 |
780ee65e NJ |
6445 | @deffn primitive symbol-pref s |
6446 | Return the @dfn{property list} currently associated with @var{symbol}. | |
6447 | @end deffn | |
6448 | ||
6449 | \fsymbol-fset! | |
89d04205 | 6450 | @c snarfed from symbols.c:712 |
780ee65e NJ |
6451 | @deffn primitive symbol-fset! s val |
6452 | Change the binding of @var{symbol}'s function slot. | |
6453 | @end deffn | |
6454 | ||
6455 | \fsymbol-pset! | |
89d04205 | 6456 | @c snarfed from symbols.c:724 |
780ee65e NJ |
6457 | @deffn primitive symbol-pset! s val |
6458 | Change the binding of @var{symbol}'s property slot. | |
6459 | @end deffn | |
6460 | ||
6461 | \fsymbol-hash | |
89d04205 | 6462 | @c snarfed from symbols.c:738 |
780ee65e NJ |
6463 | @deffn primitive symbol-hash symbol |
6464 | Return a hash value for @var{symbol}. | |
6465 | @end deffn | |
6466 | ||
6467 | \fbuiltin-bindings | |
89d04205 | 6468 | @c snarfed from symbols.c:775 |
780ee65e NJ |
6469 | @deffn primitive builtin-bindings |
6470 | Create and return a copy of the global symbol table, removing all | |
6471 | unbound symbols. | |
6472 | @end deffn | |
6473 | ||
6474 | \fgensym | |
89d04205 | 6475 | @c snarfed from symbols.c:796 |
780ee65e NJ |
6476 | @deffn primitive gensym [prefix] |
6477 | Create a new symbol with a name constructed from a prefix and | |
6478 | a counter value. The string @var{prefix} can be specified as | |
6479 | an optional argument. Default prefix is @code{g}. The counter | |
6480 | is increased by 1 at each call. There is no provision for | |
6481 | resetting the counter. | |
6482 | @end deffn | |
6483 | ||
6484 | \fgentemp | |
89d04205 | 6485 | @c snarfed from symbols.c:835 |
780ee65e NJ |
6486 | @deffn primitive gentemp [prefix [obarray]] |
6487 | Create a new symbol with a name unique in an obarray. | |
6488 | The name is constructed from an optional string @var{prefix} | |
6489 | and a counter value. The default prefix is @code{t}. The | |
6490 | @var{obarray} is specified as a second optional argument. | |
6491 | Default is the system obarray where all normal symbols are | |
6492 | interned. The counter is increased by 1 at each | |
6493 | call. There is no provision for resetting the counter. | |
6494 | @end deffn | |
6495 | ||
780ee65e | 6496 | \fcatch |
89d04205 | 6497 | @c snarfed from throw.c:535 |
ae9f3a15 | 6498 | @deffn primitive catch key thunk handler |
780ee65e | 6499 | Invoke @var{thunk} in the dynamic context of @var{handler} for |
ae9f3a15 MG |
6500 | exceptions matching @var{key}. If thunk throws to the symbol |
6501 | @var{key}, then @var{handler} is invoked this way: | |
6502 | @lisp | |
780ee65e | 6503 | (handler key args ...) |
ae9f3a15 | 6504 | @end lisp |
7a095584 | 6505 | |
ae9f3a15 | 6506 | @var{key} is a symbol or @code{#t}. |
7a095584 | 6507 | |
ae9f3a15 MG |
6508 | @var{thunk} takes no arguments. If @var{thunk} returns |
6509 | normally, that is the return value of @code{catch}. | |
7a095584 | 6510 | |
ae9f3a15 MG |
6511 | Handler is invoked outside the scope of its own @code{catch}. |
6512 | If @var{handler} again throws to the same key, a new handler | |
6513 | from further up the call chain is invoked. | |
7a095584 | 6514 | |
ae9f3a15 MG |
6515 | If the key is @code{#t}, then a throw to @emph{any} symbol will |
6516 | match this call to @code{catch}. | |
780ee65e NJ |
6517 | @end deffn |
6518 | ||
6519 | \flazy-catch | |
89d04205 | 6520 | @c snarfed from throw.c:562 |
ae9f3a15 | 6521 | @deffn primitive lazy-catch key thunk handler |
780ee65e NJ |
6522 | This behaves exactly like @code{catch}, except that it does |
6523 | not unwind the stack (this is the major difference), and if | |
6524 | handler returns, its value is returned from the throw. | |
6525 | @end deffn | |
6526 | ||
6527 | \fthrow | |
89d04205 | 6528 | @c snarfed from throw.c:595 |
780ee65e NJ |
6529 | @deffn primitive throw key . args |
6530 | Invoke the catch form matching @var{key}, passing @var{args} to the | |
6531 | @var{handler}. | |
6532 | ||
6533 | @var{key} is a symbol. It will match catches of the same symbol or of | |
7a095584 | 6534 | @code{#t}. |
780ee65e | 6535 | |
7a095584 | 6536 | If there is no handler at all, Guile prints an error and then exits. |
780ee65e NJ |
6537 | @end deffn |
6538 | ||
6539 | \funiform-vector-length | |
6540 | @c snarfed from unif.c:255 | |
6541 | @deffn primitive uniform-vector-length v | |
ae9f3a15 | 6542 | Return the number of elements in @var{uve}. |
780ee65e NJ |
6543 | @end deffn |
6544 | ||
6545 | \farray? | |
6546 | @c snarfed from unif.c:289 | |
6547 | @deffn primitive array? v [prot] | |
ae9f3a15 MG |
6548 | Return @code{#t} if the @var{obj} is an array, and @code{#f} if |
6549 | not. The @var{prototype} argument is used with uniform arrays | |
6550 | and is described elsewhere. | |
780ee65e NJ |
6551 | @end deffn |
6552 | ||
6553 | \farray-rank | |
6554 | @c snarfed from unif.c:360 | |
6555 | @deffn primitive array-rank ra | |
ae9f3a15 MG |
6556 | Return the number of dimensions of @var{obj}. If @var{obj} is |
6557 | not an array, @code{0} is returned. | |
780ee65e NJ |
6558 | @end deffn |
6559 | ||
6560 | \farray-dimensions | |
6561 | @c snarfed from unif.c:398 | |
6562 | @deffn primitive array-dimensions ra | |
6563 | @code{Array-dimensions} is similar to @code{array-shape} but replaces | |
6564 | elements with a @code{0} minimum with one greater than the maximum. So: | |
ae9f3a15 | 6565 | @lisp |
780ee65e | 6566 | (array-dimensions (make-array 'foo '(-1 3) 5)) @result{} ((-1 3) 5) |
ae9f3a15 | 6567 | @end lisp |
780ee65e NJ |
6568 | @end deffn |
6569 | ||
6570 | \fshared-array-root | |
6571 | @c snarfed from unif.c:445 | |
6572 | @deffn primitive shared-array-root ra | |
6573 | Return the root vector of a shared array. | |
6574 | @end deffn | |
6575 | ||
6576 | \fshared-array-offset | |
6577 | @c snarfed from unif.c:456 | |
6578 | @deffn primitive shared-array-offset ra | |
6579 | Return the root vector index of the first element in the array. | |
6580 | @end deffn | |
6581 | ||
6582 | \fshared-array-increments | |
6583 | @c snarfed from unif.c:467 | |
6584 | @deffn primitive shared-array-increments ra | |
6585 | For each dimension, return the distance between elements in the root vector. | |
6586 | @end deffn | |
6587 | ||
6588 | \fdimensions->uniform-array | |
6589 | @c snarfed from unif.c:586 | |
6590 | @deffn primitive dimensions->uniform-array dims prot [fill] | |
6591 | @deffnx primitive make-uniform-vector length prototype [fill] | |
ae9f3a15 MG |
6592 | Create and return a uniform array or vector of type |
6593 | corresponding to @var{prototype} with dimensions @var{dims} or | |
6594 | length @var{length}. If @var{fill} is supplied, it's used to | |
6595 | fill the array, otherwise @var{prototype} is used. | |
780ee65e NJ |
6596 | @end deffn |
6597 | ||
6598 | \fmake-shared-array | |
6599 | @c snarfed from unif.c:672 | |
6600 | @deffn primitive make-shared-array oldra mapfunc . dims | |
6601 | @code{make-shared-array} can be used to create shared subarrays of other | |
6602 | arrays. The @var{mapper} is a function that translates coordinates in | |
6603 | the new array into coordinates in the old array. A @var{mapper} must be | |
6604 | linear, and its range must stay within the bounds of the old array, but | |
6605 | it can be otherwise arbitrary. A simple example: | |
ae9f3a15 | 6606 | @lisp |
780ee65e NJ |
6607 | (define fred (make-array #f 8 8)) |
6608 | (define freds-diagonal | |
6609 | (make-shared-array fred (lambda (i) (list i i)) 8)) | |
6610 | (array-set! freds-diagonal 'foo 3) | |
6611 | (array-ref fred 3 3) @result{} foo | |
6612 | (define freds-center | |
6613 | (make-shared-array fred (lambda (i j) (list (+ 3 i) (+ 3 j))) 2 2)) | |
6614 | (array-ref freds-center 0 0) @result{} foo | |
ae9f3a15 | 6615 | @end lisp |
780ee65e NJ |
6616 | @end deffn |
6617 | ||
6618 | \ftranspose-array | |
89d04205 | 6619 | @c snarfed from unif.c:804 |
780ee65e | 6620 | @deffn primitive transpose-array ra . args |
ae9f3a15 MG |
6621 | Return an array sharing contents with @var{array}, but with |
6622 | dimensions arranged in a different order. There must be one | |
6623 | @var{dim} argument for each dimension of @var{array}. | |
6624 | @var{dim0}, @var{dim1}, @dots{} should be integers between 0 | |
6625 | and the rank of the array to be returned. Each integer in that | |
6626 | range must appear at least once in the argument list. | |
7a095584 | 6627 | |
ae9f3a15 MG |
6628 | The values of @var{dim0}, @var{dim1}, @dots{} correspond to |
6629 | dimensions in the array to be returned, their positions in the | |
6630 | argument list to dimensions of @var{array}. Several @var{dim}s | |
6631 | may have the same value, in which case the returned array will | |
6632 | have smaller rank than @var{array}. | |
7a095584 | 6633 | |
ae9f3a15 | 6634 | @lisp |
780ee65e NJ |
6635 | (transpose-array '#2((a b) (c d)) 1 0) @result{} #2((a c) (b d)) |
6636 | (transpose-array '#2((a b) (c d)) 0 0) @result{} #1(a d) | |
6637 | (transpose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 1 0) @result{} | |
6638 | #2((a 4) (b 5) (c 6)) | |
ae9f3a15 | 6639 | @end lisp |
780ee65e NJ |
6640 | @end deffn |
6641 | ||
6642 | \fenclose-array | |
89d04205 | 6643 | @c snarfed from unif.c:913 |
780ee65e NJ |
6644 | @deffn primitive enclose-array ra . axes |
6645 | @var{dim0}, @var{dim1} @dots{} should be nonnegative integers less than | |
6646 | the rank of @var{array}. @var{enclose-array} returns an array | |
6647 | resembling an array of shared arrays. The dimensions of each shared | |
6648 | array are the same as the @var{dim}th dimensions of the original array, | |
6649 | the dimensions of the outer array are the same as those of the original | |
6650 | array that did not match a @var{dim}. | |
6651 | ||
6652 | An enclosed array is not a general Scheme array. Its elements may not | |
6653 | be set using @code{array-set!}. Two references to the same element of | |
6654 | an enclosed array will be @code{equal?} but will not in general be | |
6655 | @code{eq?}. The value returned by @var{array-prototype} when given an | |
6656 | enclosed array is unspecified. | |
6657 | ||
6658 | examples: | |
ae9f3a15 | 6659 | @lisp |
780ee65e NJ |
6660 | (enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1) @result{} |
6661 | #<enclosed-array (#1(a d) #1(b e) #1(c f)) (#1(1 4) #1(2 5) #1(3 6))> | |
6662 | ||
6663 | (enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 0) @result{} | |
6664 | #<enclosed-array #2((a 1) (d 4)) #2((b 2) (e 5)) #2((c 3) (f 6))> | |
ae9f3a15 | 6665 | @end lisp |
780ee65e NJ |
6666 | @end deffn |
6667 | ||
6668 | \farray-in-bounds? | |
89d04205 | 6669 | @c snarfed from unif.c:997 |
780ee65e | 6670 | @deffn primitive array-in-bounds? v . args |
ae9f3a15 MG |
6671 | Return @code{#t} if its arguments would be acceptable to |
6672 | @code{array-ref}. | |
780ee65e NJ |
6673 | @end deffn |
6674 | ||
6675 | \farray-ref | |
89d04205 | 6676 | @c snarfed from unif.c:1076 |
780ee65e NJ |
6677 | @deffn primitive array-ref |
6678 | scm_uniform_vector_ref | |
6679 | @end deffn | |
6680 | ||
6681 | \funiform-vector-ref | |
89d04205 | 6682 | @c snarfed from unif.c:1083 |
780ee65e NJ |
6683 | @deffn primitive uniform-vector-ref v args |
6684 | @deffnx primitive array-ref v . args | |
ae9f3a15 MG |
6685 | Return the element at the @code{(index1, index2)} element in |
6686 | @var{array}. | |
780ee65e NJ |
6687 | @end deffn |
6688 | ||
6689 | \funiform-array-set1! | |
89d04205 | 6690 | @c snarfed from unif.c:1252 |
780ee65e NJ |
6691 | @deffn primitive uniform-array-set1! |
6692 | scm_array_set_x | |
6693 | @end deffn | |
6694 | ||
6695 | \farray-set! | |
89d04205 | 6696 | @c snarfed from unif.c:1261 |
780ee65e NJ |
6697 | @deffn primitive array-set! v obj . args |
6698 | @deffnx primitive uniform-array-set1! v obj args | |
6699 | Sets the element at the @code{(index1, index2)} element in @var{array} to | |
6700 | @var{new-value}. The value returned by array-set! is unspecified. | |
6701 | @end deffn | |
6702 | ||
6703 | \farray-contents | |
89d04205 | 6704 | @c snarfed from unif.c:1376 |
780ee65e NJ |
6705 | @deffn primitive array-contents ra [strict] |
6706 | @deffnx primitive array-contents array strict | |
6707 | If @var{array} may be @dfn{unrolled} into a one dimensional shared array | |
6708 | without changing their order (last subscript changing fastest), then | |
6709 | @code{array-contents} returns that shared array, otherwise it returns | |
6710 | @code{#f}. All arrays made by @var{make-array} and | |
6711 | @var{make-uniform-array} may be unrolled, some arrays made by | |
6712 | @var{make-shared-array} may not be. | |
6713 | ||
6714 | If the optional argument @var{strict} is provided, a shared array will | |
6715 | be returned only if its elements are stored internally contiguous in | |
6716 | memory. | |
6717 | @end deffn | |
6718 | ||
6719 | \funiform-array-read! | |
89d04205 | 6720 | @c snarfed from unif.c:1490 |
780ee65e NJ |
6721 | @deffn primitive uniform-array-read! ra [port_or_fd [start [end]]] |
6722 | @deffnx primitive uniform-vector-read! uve [port-or-fdes] [start] [end] | |
6723 | Attempts to read all elements of @var{ura}, in lexicographic order, as | |
6724 | binary objects from @var{port-or-fdes}. | |
6725 | If an end of file is encountered during | |
6726 | uniform-array-read! the objects up to that point only are put into @var{ura} | |
6727 | (starting at the beginning) and the remainder of the array is | |
6728 | unchanged. | |
6729 | ||
6730 | The optional arguments @var{start} and @var{end} allow | |
6731 | a specified region of a vector (or linearized array) to be read, | |
6732 | leaving the remainder of the vector unchanged. | |
6733 | ||
6734 | @code{uniform-array-read!} returns the number of objects read. | |
6735 | @var{port-or-fdes} may be omitted, in which case it defaults to the value | |
6736 | returned by @code{(current-input-port)}. | |
6737 | @end deffn | |
6738 | ||
6739 | \funiform-array-write | |
89d04205 | 6740 | @c snarfed from unif.c:1653 |
780ee65e NJ |
6741 | @deffn primitive uniform-array-write v [port_or_fd [start [end]]] |
6742 | @deffnx primitive uniform-vector-write uve [port-or-fdes] [start] [end] | |
6743 | Writes all elements of @var{ura} as binary objects to | |
6744 | @var{port-or-fdes}. | |
6745 | ||
6746 | The optional arguments @var{start} | |
6747 | and @var{end} allow | |
6748 | a specified region of a vector (or linearized array) to be written. | |
6749 | ||
6750 | The number of objects actually written is returned. | |
6751 | @var{port-or-fdes} may be | |
6752 | omitted, in which case it defaults to the value returned by | |
6753 | @code{(current-output-port)}. | |
6754 | @end deffn | |
6755 | ||
6756 | \fbit-count | |
89d04205 | 6757 | @c snarfed from unif.c:1778 |
780ee65e | 6758 | @deffn primitive bit-count b bitvector |
ae9f3a15 | 6759 | Return the number of occurrences of the boolean @var{b} in |
780ee65e NJ |
6760 | @var{bitvector}. |
6761 | @end deffn | |
6762 | ||
6763 | \fbit-position | |
89d04205 | 6764 | @c snarfed from unif.c:1817 |
780ee65e | 6765 | @deffn primitive bit-position item v k |
ae9f3a15 MG |
6766 | Return the minimum index of an occurrence of @var{bool} in |
6767 | @var{bv} which is at least @var{k}. If no @var{bool} occurs | |
6768 | within the specified range @code{#f} is returned. | |
780ee65e NJ |
6769 | @end deffn |
6770 | ||
6771 | \fbit-set*! | |
89d04205 | 6772 | @c snarfed from unif.c:1885 |
780ee65e NJ |
6773 | @deffn primitive bit-set*! v kv obj |
6774 | If uve is a bit-vector @var{bv} and uve must be of the same | |
6775 | length. If @var{bool} is @code{#t}, uve is OR'ed into | |
6776 | @var{bv}; If @var{bool} is @code{#f}, the inversion of uve is | |
6777 | AND'ed into @var{bv}. | |
6778 | ||
6779 | If uve is a unsigned integer vector all the elements of uve | |
6780 | must be between 0 and the @code{length} of @var{bv}. The bits | |
6781 | of @var{bv} corresponding to the indexes in uve are set to | |
6782 | @var{bool}. The return value is unspecified. | |
6783 | @end deffn | |
6784 | ||
6785 | \fbit-count* | |
89d04205 | 6786 | @c snarfed from unif.c:1939 |
780ee65e | 6787 | @deffn primitive bit-count* v kv obj |
ae9f3a15 MG |
6788 | Return |
6789 | @lisp | |
780ee65e | 6790 | (bit-count (bit-set*! (if bool bv (bit-invert! bv)) uve #t) #t). |
ae9f3a15 | 6791 | @end lisp |
780ee65e NJ |
6792 | @var{bv} is not modified. |
6793 | @end deffn | |
6794 | ||
6795 | \fbit-invert! | |
89d04205 | 6796 | @c snarfed from unif.c:2003 |
780ee65e NJ |
6797 | @deffn primitive bit-invert! v |
6798 | Modifies @var{bv} by replacing each element with its negation. | |
6799 | @end deffn | |
6800 | ||
6801 | \farray->list | |
89d04205 | 6802 | @c snarfed from unif.c:2082 |
780ee65e | 6803 | @deffn primitive array->list v |
ae9f3a15 MG |
6804 | Return a list consisting of all the elements, in order, of |
6805 | @var{array}. | |
780ee65e NJ |
6806 | @end deffn |
6807 | ||
6808 | \flist->uniform-array | |
72ad43dc | 6809 | @c snarfed from unif.c:2183 |
780ee65e NJ |
6810 | @deffn primitive list->uniform-array ndim prot lst |
6811 | @deffnx procedure list->uniform-vector prot lst | |
ae9f3a15 MG |
6812 | Return a uniform array of the type indicated by prototype |
6813 | @var{prot} with elements the same as those of @var{lst}. | |
6814 | Elements must be of the appropriate type, no coercions are | |
6815 | done. | |
780ee65e NJ |
6816 | @end deffn |
6817 | ||
6818 | \farray-prototype | |
72ad43dc | 6819 | @c snarfed from unif.c:2534 |
780ee65e | 6820 | @deffn primitive array-prototype ra |
ae9f3a15 MG |
6821 | Return an object that would produce an array of the same type |
6822 | as @var{array}, if used as the @var{prototype} for | |
780ee65e NJ |
6823 | @code{make-uniform-array}. |
6824 | @end deffn | |
6825 | ||
6826 | \fvalues | |
89d04205 | 6827 | @c snarfed from values.c:80 |
780ee65e NJ |
6828 | @deffn primitive values . args |
6829 | Delivers all of its arguments to its continuation. Except for | |
6830 | continuations created by the @code{call-with-values} procedure, | |
6831 | all continuations take exactly one value. The effect of | |
6832 | passing no value or more than one value to continuations that | |
6833 | were not created by @code{call-with-values} is unspecified. | |
6834 | @end deffn | |
6835 | ||
780ee65e | 6836 | \fmake-variable |
89d04205 | 6837 | @c snarfed from variable.c:99 |
780ee65e NJ |
6838 | @deffn primitive make-variable init [name_hint] |
6839 | Return a variable object initialized to value @var{init}. | |
6840 | If given, uses @var{name-hint} as its internal (debugging) | |
6841 | name, otherwise just treat it as an anonymous variable. | |
6842 | Remember, of course, that multiple bindings to the same | |
6843 | variable may exist, so @var{name-hint} is just that---a hint. | |
6844 | @end deffn | |
6845 | ||
6846 | \fmake-undefined-variable | |
89d04205 | 6847 | @c snarfed from variable.c:119 |
780ee65e NJ |
6848 | @deffn primitive make-undefined-variable [name_hint] |
6849 | Return a variable object initialized to an undefined value. | |
6850 | If given, uses @var{name-hint} as its internal (debugging) | |
6851 | name, otherwise just treat it as an anonymous variable. | |
6852 | Remember, of course, that multiple bindings to the same | |
6853 | variable may exist, so @var{name-hint} is just that---a hint. | |
6854 | @end deffn | |
6855 | ||
6856 | \fvariable? | |
89d04205 | 6857 | @c snarfed from variable.c:136 |
780ee65e NJ |
6858 | @deffn primitive variable? obj |
6859 | Return @code{#t} iff @var{obj} is a variable object, else | |
6860 | return @code{#f} | |
6861 | @end deffn | |
6862 | ||
6863 | \fvariable-ref | |
89d04205 | 6864 | @c snarfed from variable.c:148 |
780ee65e NJ |
6865 | @deffn primitive variable-ref var |
6866 | Dereference @var{var} and return its value. | |
6867 | @var{var} must be a variable object; see @code{make-variable} | |
6868 | and @code{make-undefined-variable}. | |
6869 | @end deffn | |
6870 | ||
6871 | \fvariable-set! | |
89d04205 | 6872 | @c snarfed from variable.c:162 |
780ee65e NJ |
6873 | @deffn primitive variable-set! var val |
6874 | Set the value of the variable @var{var} to @var{val}. | |
6875 | @var{var} must be a variable object, @var{val} can be any | |
6876 | value. Return an unspecified value. | |
6877 | @end deffn | |
6878 | ||
6879 | \fbuiltin-variable | |
89d04205 | 6880 | @c snarfed from variable.c:176 |
780ee65e NJ |
6881 | @deffn primitive builtin-variable name |
6882 | Return the built-in variable with the name @var{name}. | |
6883 | @var{name} must be a symbol (not a string). | |
6884 | Then use @code{variable-ref} to access its value. | |
6885 | @end deffn | |
6886 | ||
6887 | \fvariable-bound? | |
89d04205 | 6888 | @c snarfed from variable.c:204 |
780ee65e NJ |
6889 | @deffn primitive variable-bound? var |
6890 | Return @code{#t} iff @var{var} is bound to a value. | |
6891 | Throws an error if @var{var} is not a variable object. | |
6892 | @end deffn | |
6893 | ||
6894 | \fvector? | |
6895 | @c snarfed from vectors.c:142 | |
6896 | @deffn primitive vector? obj | |
ae9f3a15 MG |
6897 | Return @code{#t} if @var{obj} is a vector, otherwise return |
6898 | @code{#f}. | |
780ee65e NJ |
6899 | @end deffn |
6900 | ||
6901 | \flist->vector | |
6902 | @c snarfed from vectors.c:161 | |
6903 | @deffn primitive list->vector | |
6904 | scm_vector | |
6905 | @end deffn | |
6906 | ||
6907 | \fvector | |
89d04205 | 6908 | @c snarfed from vectors.c:178 |
780ee65e NJ |
6909 | @deffn primitive vector . l |
6910 | @deffnx primitive list->vector l | |
ae9f3a15 MG |
6911 | Return a newly allocated vector whose elements contain the |
6912 | given arguments. Analogous to @code{list}. | |
7a095584 | 6913 | |
780ee65e | 6914 | @lisp |
ae9f3a15 | 6915 | (vector 'a 'b 'c) @result{} #(a b c) |
780ee65e NJ |
6916 | @end lisp |
6917 | @end deffn | |
6918 | ||
6919 | \fmake-vector | |
89d04205 | 6920 | @c snarfed from vectors.c:264 |
780ee65e | 6921 | @deffn primitive make-vector k [fill] |
ae9f3a15 MG |
6922 | Return a newly allocated vector of @var{k} elements. If a |
6923 | second argument is given, then each element is initialized to | |
6924 | @var{fill}. Otherwise the initial contents of each element is | |
6925 | unspecified. | |
780ee65e NJ |
6926 | @end deffn |
6927 | ||
6928 | \fvector->list | |
89d04205 | 6929 | @c snarfed from vectors.c:321 |
780ee65e | 6930 | @deffn primitive vector->list v |
ae9f3a15 MG |
6931 | Return a newly allocated list of the objects contained in the |
6932 | elements of @var{vector}. | |
7a095584 | 6933 | |
780ee65e NJ |
6934 | @lisp |
6935 | (vector->list '#(dah dah didah)) @result{} (dah dah didah) | |
6936 | (list->vector '(dididit dah)) @result{} #(dididit dah) | |
6937 | @end lisp | |
6938 | @end deffn | |
6939 | ||
6940 | \fvector-fill! | |
89d04205 | 6941 | @c snarfed from vectors.c:338 |
ae9f3a15 MG |
6942 | @deffn primitive vector-fill! v fill |
6943 | Store @var{fill} in every element of @var{vector}. The value | |
6944 | returned by @code{vector-fill!} is unspecified. | |
780ee65e NJ |
6945 | @end deffn |
6946 | ||
6947 | \fvector-move-left! | |
89d04205 | 6948 | @c snarfed from vectors.c:365 |
780ee65e NJ |
6949 | @deffn primitive vector-move-left! vec1 start1 end1 vec2 start2 |
6950 | Vector version of @code{substring-move-left!}. | |
6951 | @end deffn | |
6952 | ||
6953 | \fvector-move-right! | |
89d04205 | 6954 | @c snarfed from vectors.c:388 |
780ee65e NJ |
6955 | @deffn primitive vector-move-right! vec1 start1 end1 vec2 start2 |
6956 | Vector version of @code{substring-move-right!}. | |
6957 | @end deffn | |
6958 | ||
6959 | \fmajor-version | |
6960 | @c snarfed from version.c:59 | |
6961 | @deffn primitive major-version | |
6962 | Return a string containing Guile's major version number. | |
6963 | E.g., "1". | |
6964 | @end deffn | |
6965 | ||
6966 | \fminor-version | |
6967 | @c snarfed from version.c:71 | |
6968 | @deffn primitive minor-version | |
6969 | Return a string containing Guile's minor version number. | |
6970 | E.g., "3.5". | |
6971 | @end deffn | |
6972 | ||
6973 | \fversion | |
6974 | @c snarfed from version.c:90 | |
6975 | @deffn primitive version | |
6976 | @deffnx primitive major-version | |
6977 | @deffnx primitive minor-version | |
6978 | Return a string describing Guile's version number, or its major or minor | |
6979 | version numbers, respectively. | |
6980 | ||
ae9f3a15 | 6981 | @lisp |
780ee65e NJ |
6982 | (version) @result{} "1.3a" |
6983 | (major-version) @result{} "1" | |
6984 | (minor-version) @result{} "3a" | |
ae9f3a15 | 6985 | @end lisp |
780ee65e NJ |
6986 | @end deffn |
6987 | ||
6988 | \fmake-soft-port | |
89d04205 | 6989 | @c snarfed from vports.c:190 |
780ee65e | 6990 | @deffn primitive make-soft-port pv modes |
ae9f3a15 | 6991 | Return a port capable of receiving or delivering characters as |
780ee65e | 6992 | specified by the @var{modes} string (@pxref{File Ports, |
ae9f3a15 MG |
6993 | open-file}). @var{pv} must be a vector of length 5. Its |
6994 | components are as follows: | |
7a095584 | 6995 | |
780ee65e NJ |
6996 | @enumerate 0 |
6997 | @item | |
6998 | procedure accepting one character for output | |
6999 | @item | |
7000 | procedure accepting a string for output | |
7001 | @item | |
7002 | thunk for flushing output | |
7003 | @item | |
7004 | thunk for getting one character | |
7005 | @item | |
7006 | thunk for closing port (not by garbage collection) | |
7007 | @end enumerate | |
7a095584 | 7008 | |
780ee65e | 7009 | For an output-only port only elements 0, 1, 2, and 4 need be |
ae9f3a15 MG |
7010 | procedures. For an input-only port only elements 3 and 4 need |
7011 | be procedures. Thunks 2 and 4 can instead be @code{#f} if | |
7012 | there is no useful operation for them to perform. | |
7a095584 | 7013 | |
ae9f3a15 MG |
7014 | If thunk 3 returns @code{#f} or an @code{eof-object} |
7015 | (@pxref{Input, eof-object?, ,r4rs, The Revised^4 Report on | |
7016 | Scheme}) it indicates that the port has reached end-of-file. | |
7017 | For example: | |
7a095584 | 7018 | |
ae9f3a15 | 7019 | @lisp |
780ee65e NJ |
7020 | (define stdout (current-output-port)) |
7021 | (define p (make-soft-port | |
7022 | (vector | |
7023 | (lambda (c) (write c stdout)) | |
7024 | (lambda (s) (display s stdout)) | |
7025 | (lambda () (display "." stdout)) | |
7026 | (lambda () (char-upcase (read-char))) | |
7027 | (lambda () (display "@@" stdout))) | |
7028 | "rw")) | |
7a095584 | 7029 | |
780ee65e | 7030 | (write p p) @result{} #<input-output: soft 8081e20> |
ae9f3a15 | 7031 | @end lisp |
780ee65e NJ |
7032 | @end deffn |
7033 | ||
7034 | \fmake-weak-vector | |
89d04205 | 7035 | @c snarfed from weaks.c:63 |
ae9f3a15 | 7036 | @deffn primitive make-weak-vector size [fill] |
780ee65e | 7037 | Return a weak vector with @var{size} elements. If the optional |
ae9f3a15 MG |
7038 | argument @var{fill} is given, all entries in the vector will be |
7039 | set to @var{fill}. The default value for @var{fill} is the | |
7040 | empty list. | |
780ee65e NJ |
7041 | @end deffn |
7042 | ||
7043 | \flist->weak-vector | |
89d04205 | 7044 | @c snarfed from weaks.c:80 |
780ee65e NJ |
7045 | @deffn primitive list->weak-vector |
7046 | scm_weak_vector | |
7047 | @end deffn | |
7048 | ||
7049 | \fweak-vector | |
89d04205 | 7050 | @c snarfed from weaks.c:88 |
780ee65e NJ |
7051 | @deffn primitive weak-vector . l |
7052 | @deffnx primitive list->weak-vector l | |
ae9f3a15 MG |
7053 | Construct a weak vector from a list: @code{weak-vector} uses |
7054 | the list of its arguments while @code{list->weak-vector} uses | |
7055 | its only argument @var{l} (a list) to construct a weak vector | |
7056 | the same way @code{list->vector} would. | |
780ee65e NJ |
7057 | @end deffn |
7058 | ||
7059 | \fweak-vector? | |
89d04205 | 7060 | @c snarfed from weaks.c:116 |
ae9f3a15 | 7061 | @deffn primitive weak-vector? obj |
780ee65e NJ |
7062 | Return @code{#t} if @var{obj} is a weak vector. Note that all |
7063 | weak hashes are also weak vectors. | |
7064 | @end deffn | |
7065 | ||
7066 | \fmake-weak-key-hash-table | |
89d04205 | 7067 | @c snarfed from weaks.c:138 |
ae9f3a15 | 7068 | @deffn primitive make-weak-key-hash-table size |
780ee65e NJ |
7069 | @deffnx primitive make-weak-value-hash-table size |
7070 | @deffnx primitive make-doubly-weak-hash-table size | |
ae9f3a15 MG |
7071 | Return a weak hash table with @var{size} buckets. As with any |
7072 | hash table, choosing a good size for the table requires some | |
7073 | caution. | |
7a095584 | 7074 | |
ae9f3a15 MG |
7075 | You can modify weak hash tables in exactly the same way you |
7076 | would modify regular hash tables. (@pxref{Hash Tables}) | |
780ee65e NJ |
7077 | @end deffn |
7078 | ||
7079 | \fmake-weak-value-hash-table | |
89d04205 NJ |
7080 | @c snarfed from weaks.c:155 |
7081 | @deffn primitive make-weak-value-hash-table size | |
780ee65e NJ |
7082 | Return a hash table with weak values with @var{size} buckets. |
7083 | (@pxref{Hash Tables}) | |
7084 | @end deffn | |
7085 | ||
7086 | \fmake-doubly-weak-hash-table | |
89d04205 NJ |
7087 | @c snarfed from weaks.c:173 |
7088 | @deffn primitive make-doubly-weak-hash-table size | |
780ee65e NJ |
7089 | Return a hash table with weak keys and values with @var{size} |
7090 | buckets. (@pxref{Hash Tables}) | |
7091 | @end deffn | |
7092 | ||
7093 | \fweak-key-hash-table? | |
89d04205 | 7094 | @c snarfed from weaks.c:192 |
ae9f3a15 | 7095 | @deffn primitive weak-key-hash-table? obj |
780ee65e NJ |
7096 | @deffnx primitive weak-value-hash-table? obj |
7097 | @deffnx primitive doubly-weak-hash-table? obj | |
7098 | Return @code{#t} if @var{obj} is the specified weak hash | |
7099 | table. Note that a doubly weak hash table is neither a weak key | |
7100 | nor a weak value hash table. | |
7101 | @end deffn | |
7102 | ||
7103 | \fweak-value-hash-table? | |
89d04205 NJ |
7104 | @c snarfed from weaks.c:202 |
7105 | @deffn primitive weak-value-hash-table? obj | |
7106 | Return @code{#t} if @var{obj} is a weak value hash table. | |
780ee65e NJ |
7107 | @end deffn |
7108 | ||
7109 | \fdoubly-weak-hash-table? | |
89d04205 NJ |
7110 | @c snarfed from weaks.c:212 |
7111 | @deffn primitive doubly-weak-hash-table? obj | |
7112 | Return @code{#t} if @var{obj} is a doubly weak hash table. | |
780ee65e | 7113 | @end deffn |