diff options
-rw-r--r-- | doc/sources/.cvsignore | 19 | ||||
-rw-r--r-- | doc/sources/Makefile.am | 7 | ||||
-rw-r--r-- | doc/sources/contributors.texi | 80 | ||||
-rw-r--r-- | doc/sources/debug-c.texi | 2 | ||||
-rw-r--r-- | doc/sources/debug-scheme.texi | 2 | ||||
-rw-r--r-- | doc/sources/guile-slib.texi | 2 | ||||
-rw-r--r-- | doc/sources/jimb-org.texi | 131 | ||||
-rw-r--r-- | doc/sources/libguile-overview.texi | 30 | ||||
-rw-r--r-- | doc/sources/libguile-tools.texi | 191 | ||||
-rw-r--r-- | doc/sources/new-types.texi | 2 | ||||
-rw-r--r-- | doc/sources/old-intro.texi | 290 | ||||
-rw-r--r-- | doc/sources/sample-APIs.texi | 6 | ||||
-rw-r--r-- | doc/sources/scheme-concepts.texi | 249 | ||||
-rw-r--r-- | doc/sources/scm-ref.texi | 4 | ||||
-rw-r--r-- | doc/sources/snarf.texi | 0 | ||||
-rw-r--r-- | doc/sources/strings.texi | 45 | ||||
-rw-r--r-- | doc/sources/tk.texi | 5 | ||||
-rw-r--r-- | doc/sources/unix-other.texi | 132 | ||||
-rw-r--r-- | doc/sources/unix.texi | 622 |
19 files changed, 1819 insertions, 0 deletions
diff --git a/doc/sources/.cvsignore b/doc/sources/.cvsignore new file mode 100644 index 000000000..dc9df74a2 --- /dev/null +++ b/doc/sources/.cvsignore @@ -0,0 +1,19 @@ +Makefile +stamp-vti +*.log +*.dvi +*.aux +*.toc +*.cp +*.fn +*.vr +*.tp +*.ky +*.pg +*.cps +*.fns +*.tps +*.vrs +*.ps +*.info* +version.texi diff --git a/doc/sources/Makefile.am b/doc/sources/Makefile.am new file mode 100644 index 000000000..d201637e4 --- /dev/null +++ b/doc/sources/Makefile.am @@ -0,0 +1,7 @@ +# -*- Makefile -*- + +EXTRA_DIST = libguile-overview.texi snarf.texi contributors.texi \ + libguile-tools.texi strings.texi data-rep.texi new-types.texi tk.texi \ + debug-c.texi old-intro.texi unix-other.texi debug-scheme.texi \ + sample-APIs.texi unix.texi guile-slib.texi scheme-concepts.texi \ + jimb-org.texi scm-ref.texi diff --git a/doc/sources/contributors.texi b/doc/sources/contributors.texi new file mode 100644 index 000000000..578c358f7 --- /dev/null +++ b/doc/sources/contributors.texi @@ -0,0 +1,80 @@ +@node Contributors to Guile +@appendix Contributors to Guile + +This Guile Manual was written by Mark Galassi, Jim Blandy and Gary +Houston. + +Guile was developed over many years by the following people: + +@table @strong +@item George Carrette +Wrote files present in Siod version 2.3, released in December of 1989. + +@item Aubrey Jaffer +Wrote substantial portions of guile.texi, and surely others. +Changes to: eval.c, ioext.c, posix.c, gscm.c, scm.h, socket.c, +gsubr.c, sys.c, test.scm, stime.c, and unif.c. + +@item Gary Houston +changes to many files in libguile. + +wrote: libguile/socket.c, ice-9/expect.scm + +@item Tom Lord +Many changes throughout. +In the subdirectory ctax, wrote: + Makefile.in configure.in hashtabs.scm macros.scm scm-ops.scm + c-ops.scm grammar.scm lexer.scm reader.scm +In the subdirectory gtcltk-lib, wrote: + Makefile.in guile-tcl.c guile-tk.c + configure.in guile-tcl.h guile-tk.h +In the subdirectory guile, wrote: + Makefile.in getopt.c getopt1.c + configure.in getopt.h guile.c +In the subdirectory ice-9, wrote: + Makefile.in configure.in lineio.scm poe.scm + boot-9.scm hcons.scm mapping.scm +In the subdirectory lang, wrote: + Makefile.in grammar.scm lr0.scm pp.scm + configure.in lex.scm lr1.scm +In the subdirectory rx, wrote: + Makefile.in runtests.c rxbitset.h rxnfa.c rxspencer.c + TESTS rx.c rxcontext.h rxnfa.h rxspencer.h + TESTS2C.sed rx.h rxcset.c rxnode.c rxstr.c + _rx.h rxall.h rxcset.h rxnode.h rxstr.h + configure.in rxanal.c rxdbug.c rxposix.c rxsuper.c + hashrexp.c rxanal.h rxgnucomp.c rxposix.h rxsuper.h + inst-rxposix.h rxbasic.c rxgnucomp.h rxproto.h rxunfa.c + rgx.c rxbasic.h rxhash.c rxsimp.c rxunfa.h + rgx.h rxbitset.c rxhash.h rxsimp.h testcases.h +In the subdirectory doc, wrote: + ctax.texi gtcltk.texi in.texi lang.texi +and portions of guile.texi. + +@item Anthony Green +wrote the original code in the 'threads' directory, and +ice-9/threads.scm. + +@item Mikael Djurfeldt +@example +In the subdirectory libguile, wrote: + backtrace.c debug.c options.c root.c srcprop.c stacks.c + backtrace.h debug.h options.h root.h srcprop.h stacks.h +In the subdirectory threads, rewrote: + coop-threads.c coop.c mit-pthreads.c threads.c + coop-threads.h fsu-pthreads.h mit-pthreads.h threads.h +Many other changes throughout. +@end example + +@item Mark Galassi +@example +Designed and implemented the high-level libguile API (the @code{gh_} +interface), based largely on the defunct @code{gscm_} interface. In the +subdirectory gh, wrote: +gh.c gh_eval.c gh_io.c gh_test_c.c +gh.h gh_funcs.c gh_list.c gh_test_repl.c +gh_data.c gh_init.c gh_predicates.c +@end example + + +@end table diff --git a/doc/sources/debug-c.texi b/doc/sources/debug-c.texi new file mode 100644 index 000000000..77d02f440 --- /dev/null +++ b/doc/sources/debug-c.texi @@ -0,0 +1,2 @@ +@node Debugging libguile +@chapter Debugging libguile diff --git a/doc/sources/debug-scheme.texi b/doc/sources/debug-scheme.texi new file mode 100644 index 000000000..35340f943 --- /dev/null +++ b/doc/sources/debug-scheme.texi @@ -0,0 +1,2 @@ +@node Debugging Scheme programs +@chapter Debugging Scheme programs diff --git a/doc/sources/guile-slib.texi b/doc/sources/guile-slib.texi new file mode 100644 index 000000000..c8f07d1b2 --- /dev/null +++ b/doc/sources/guile-slib.texi @@ -0,0 +1,2 @@ +@node Guile and SLIB +@chapter Guile and SLIB diff --git a/doc/sources/jimb-org.texi b/doc/sources/jimb-org.texi new file mode 100644 index 000000000..5ec4216db --- /dev/null +++ b/doc/sources/jimb-org.texi @@ -0,0 +1,131 @@ +@menu +Preliminary + +* Introduction:: +* Using Guile:: + + + +@bye + +>You can actually put any English text to break up the menu, so you +>could put the "Part n" headings in it. + + + +Introduction + --- Explains Guile's goals, and gives brief examples of how to use + Guile interactively (show off repl), as a script interpreter, + and as an embedded interpreter. + +Part I: Guile Scheme + R4RS Scheme as a Starting Point + --- Here we refer to R4RS, and explain that we're only + describing differences. + Block comments and interpreter triggers + Symbol case + Keywords + Exceptions + Modules + --- the preceeding three come first, because we need them + in order to explain the behavior of some things later + Exception Handling + --- mention that repls usually establish default exception handlers + Dynamic Wind + Records + Structures + Arrays + Binary Numeric Operations + Shared and Read-Only Strings + Object Properties + Association Lists and Hash Tables + (Dictionaries In General) + association lists + hash tables (Hash Values) + Input/Output ports + file ports + soft ports + string ports + extended I/O (fseek; line read/write) + Garbage Collection + Threads and Dynamic Roots + Reflection + eval + Tag Values + Weak references + Regular Expressions + SLIB + POSIX system calls and networking + --- I think people will generally know whether they're looking + for a system call or not, so this should be an okay category. + conventions (includes error handling) + ports vs. file descriptors + file system (mknod goes here, no?) + user database + time (includes gettimeofday or whatever, strftime, strptime) + processes + terminals and pseudo-terminals + pipes + networking (includes databases, address conversion, and sockets) + system identification (uname) + locales (setlocale) + --- Note that there is no more 'misc'. It's better to have + small sections than unhelpful names. + SCSH + --- includes info on how to get SCSH features (open this + module), but mostly just a pointer to the SCSH manual. + This should not be under POSIX. SCSH includes plenty of + high-level stuff for starting processes and string + processing. SCSH is not a subset of POSIX, nor the + reverse. + Tcl/Tk interface + Module internals + first-class variables + first-class modules + internal debugging interface + --- The name of this chapter needs to clearly distinguish it + from the appendix describing the debugger UI. The intro + should have a pointer to the UI appendix. + +Part II: Using Scheme with C --- a Portable Interface + --- We cover gh in a completely separate section. Why? I admit + I'm on shaky ground, but here's my reasoning: People who want + to write portable C code need to restrict themselves to only + using GH, and GH's semantics are (necessarily) well-defined + without reference to Guile's particulars. This makes life + more difficult for folks who just prefer to use the GH + interface when they can, but I really think the SCM interface + is not so bad, once you're used to it. A *lot* of GH + functions are just wrappers for SCM functions. + --- We cover repls here too, since GH has repl functions. + +Part III: Using Scheme with C --- Guile's Interface + Scheme data representation + Relationship between Scheme and C functions + --- this is where we explain that all the functions marked as + "Primitive Functions" are also accessible from C, and how + to derive the C interface given the Scheme interface, when + we don't spell it out. + ... I think there's other stuff needed here ... + I/O internals + linking Guile with your code + --- Mark's "Tools to automate adding libraries" is not a + well-defined concept. I think this is closer to what we + want to cover for now. + snarfing + +Appendices: + Obtaining and Installing Guile + Invoking Guile + --- mentions read-eval-print loops + --- both the SCSH and GAWK manuals relegate invocation details + to an appendix. We can give examples in the introduction. + debugger user interface + --- The title and introduction of this appendix need to + distinguish this clearly from the chapter on the internal + debugging interface. + +Indices: + --- At the top of the function/variable index, remind people + to look for functions under their Scheme names as well as + their C names. diff --git a/doc/sources/libguile-overview.texi b/doc/sources/libguile-overview.texi new file mode 100644 index 000000000..96a4a76ce --- /dev/null +++ b/doc/sources/libguile-overview.texi @@ -0,0 +1,30 @@ +@node Libguile overview +@chapter Libguile overview +@cindex libguile - overview + +Extension languages, like Guile, Python and Tcl, can be embedded into a +C program, @footnote{Or a C++ or Fortran or Pascal program if you want.} +and thus allow the user to @emph{extend} the C program. + +The way this is done is by providing a C language library with a well +defined interface. The interface consists of a set of public and +documented C-callable routines that offer the full interpreter +functionality, and allow the conversion of data between C and the +extension language. + +@menu +* An example of libguile functionality:: +* What can be done with libguile:: +* Schizofrenia -- two APIs:: +@end menu + +@node An example of libguile functionality +@section An example of libguile functionality + +[Two examples: using strings and using data conversion.] + +@node What can be done with libguile +@section What can be done with libguile + +@node Schizofrenia -- two APIs +@section Schizofrenia -- two APIs diff --git a/doc/sources/libguile-tools.texi b/doc/sources/libguile-tools.texi new file mode 100644 index 000000000..d434406e9 --- /dev/null +++ b/doc/sources/libguile-tools.texi @@ -0,0 +1,191 @@ +@node Tools to automate adding libraries +@chapter Tools to automate adding libraries + +You want to ... + +The chapters @ref{Libguile -- high level interface} and @ref{Libguile -- +SCM interface} showed how to make C libraries available from Scheme. +Here I will describe some automated tools that the Guile team has made +available. Some have been written especially for Guile (the Guile Magic +Snarfer), and some are also in use with other languages (Python, Perl, +...) + +@menu +* By hand with gh_:: +* By hand with Guile Magic Snarfer:: +* Automatically using libtool:: +* Automatically using SWIG:: +@end menu + +@node By hand with gh_ +@section By hand with gh_ + +@node By hand with Guile Magic Snarfer +@section By hand with Guile Magic Snarfer + +When writing C code for use with Guile, you typically define a set of C +functions, and then make some of them visible to the Scheme world by +calling the @code{scm_make_gsubr} function; a C functions published in +this way is called a @dfn{subr}. If you have many subrs to publish, it +can sometimes be annoying to keep the list of calls to +@code{scm_make_gsubr} in sync with the list of function definitions. +Frequently, a programmer will define a new subr in C, recompile his +application, and then discover that the Scheme interpreter cannot see +the subr, because he forgot to call @code{scm_make_gsubr}. + +Guile provides the @code{guile-snarf} command to manage this problem. +Using this tool, you can keep all the information needed to define the +subr alongside the function definition itself; @code{guile-snarf} will +extract this information from your source code, and automatically +generate a file of calls to @code{scm_make_gsubr} which you can +@code{#include} into an initialization function. (The command name +comes from the verb ``to snarf'', here meaning ``to unceremoniously +extract information from a somewhat unwilling source.'') + +@menu +* How guile-snarf works:: Using the @code{guile-snarf} command. +* Macros guile-snarf recognizes:: How to mark up code for @code{guile-snarf}. +@end menu + +@node How guile-snarf works +@subsection How @code{guile-snarf} works + +For example, here is how you might define a new subr called +@code{clear-image}, implemented by the C function @code{clear_image}: + +@example +@group +#include <libguile.h> + +@dots{} + +SCM_PROC (s_clear_image, "clear-image", 1, 0, 0, clear_image); + +SCM +clear_image (SCM image_smob) +@{ + @dots{} +@} + +@dots{} + +void +init_image_type () +@{ +#include "image-type.x" +@} +@end group +@end example + +The @code{SCM_PROC} declaration says that the C function +@code{clear_image} implements a Scheme subr called @code{clear-image}, +which takes one required argument, no optional arguments, and no tail +argument. @code{SCM_PROC} also declares a static array of characters +named @code{s_clear_image}, initialized to the string +@code{"clear-image"}. The body of @code{clear_image} may use the array +in error messages, instead of writing out the literal string; this may +save string space on some systems. + +Assuming the text above lives in a file named @file{image-type.c}, you will +need to execute the following command to compile this file: +@example +guile-snarf image-type.c > image-type.x +@end example +@noindent This scans @file{image-type.c} for @code{SCM_PROC} +declarations, and sends the following output to the file +@file{image-type.x}: +@example +scm_make_gsubr (s_clear_image, 1, 0, 0, clear_image); +@end example +When compiled normally, @code{SCM_PROC} is a macro which expands to a +declaration of the @code{s_clear_image} string. + +In other words, @code{guile-snarf} scans source code looking for uses of +the @code{SCM_PROC} macro, and generates C code to define the +appropriate subrs. You need to provide all the same information you +would if you were using @code{scm_make_gsubr} yourself, but you can +place the information near the function definition itself, so it is less +likely to become incorrect or out-of-date. + +If you have many files that @code{guile-snarf} must process, you should +consider using a rule like the following in your Makefile: +@example +.SUFFIXES: .x +.c.x: + ./guile-snarf $(DEFS) $(INCLUDES) $(CPPFLAGS) $(CFLAGS) $< > $@ +@end example +This tells make to run @code{guile-snarf} to produce each needed +@file{.x} file from the corresponding @file{.c} file. + +@code{guile-snarf} passes all its command-line arguments directly to the +C preprocessor, which it uses to extract the information it needs from +the source code. this means you can pass normal compilation flags to +@code{guile-snarf} to define preprocessor symbols, add header file +directories, and so on. + + + +@node Macros guile-snarf recognizes +@subsection Macros @code{guile-snarf} recognizes + +Here are the macros you can use in your source code from which +@code{guile-snarf} can construct initialization code: + + +@defmac SCM_PROC (@var{namestr}, @var{name}, @var{req}, @var{opt}, @var{tail}, @var{c_func}) +Declare a new Scheme primitive function, or @dfn{subr}. The new subr +will be named @var{name} in Scheme code, and be implemented by the C +function @var{c_func}. The subr will take @var{req} required arguments +and @var{opt} optional arguments. If @var{tail} is non-zero, the +function will accept any remaining arguments as a list. + +Use this macro outside all function bodies, preferably above the +definition of @var{c_func} itself. When compiled, the @code{SCM_PROC} +declaration will expand to a definition for the @var{namestr} array, +initialized to @var{name}. The @code{guile-snarf} command uses this +declaration to automatically generate initialization code to create the +subr and bind it in the top-level environment. @xref{How guile-snarf +works}, for more info. + +@xref{Subrs}, for details on argument passing and how to write +@var{c_func}. +@end defmac + + +@defmac SCM_GLOBAL (@var{var}, @var{scheme_name}) +Declare a global Scheme variable named @var{scheme_name}, and a static C +variable named @var{var} to point to it. The value of the Scheme +variable lives in the @sc{cdr} of the cell @var{var} points to. +Initialize the variable to @code{#f}. + +Use this macro outside all function bodies. When compiled, the +@code{SCM_GLOBAL} macro will expand to a definition for the variable +@var{var}, initialized to an innocuous value. The @code{guile-snarf} +command will use this declaration to automatically generate code to +create a global variable named @var{scheme_name}, and store a pointer to +its cell in @var{var}. +@end defmac + + +@defmac SCM_CONST_LONG (@var{var}, @var{scheme_name}, @var{value}) +Like @code{SCM_GLOBAL}, but initialize the variable to @var{value}, +which must be an integer. +@end defmac + + +@defmac SCM_SYMBOL (@var{var}, @var{name}) +Declare a C variable of type @code{SCM} named @var{var}, and initialize +it to the Scheme symbol object whose name is @var{name}. + +Use this macro outside all function bodies. When compiled, the +@code{SCM_SYMBOL} macro will expand to a definition for the variable +@var{var}, initialized to an innocuous value. The @code{guile-snarf} +command will use this declaration to automatically generate code to +create a symbol named @var{name}, and store it in @var{var}. +@end defmac + +@node Automatically using libtool +@section Automatically using libtool + +@node Automatically using SWIG +@section Automatically using SWIG diff --git a/doc/sources/new-types.texi b/doc/sources/new-types.texi new file mode 100644 index 000000000..1840b214f --- /dev/null +++ b/doc/sources/new-types.texi @@ -0,0 +1,2 @@ +@node Adding types to Guile +@chapter Adding types to Guile diff --git a/doc/sources/old-intro.texi b/doc/sources/old-intro.texi new file mode 100644 index 000000000..0774f64d4 --- /dev/null +++ b/doc/sources/old-intro.texi @@ -0,0 +1,290 @@ +@node Introduction +@chapter Introduction + +Guile is an interpreter for Scheme, a clean, economical programming +language in the Lisp family. You can invoke Guile from the shell to +evaluate Scheme expressions interactively, or use it as an interpreter +for script files. However, Guile is also packaged as a library, to be +embedded as an extension language into other applications. The +application can supplement the base language with special-purpose +functions and datatypes, allowing the user to customize and extend it by +writing Scheme code. + +In its simplest form, Guile is an ordinary interpreter. The +@code{guile} program can read and evaluate Scheme expressions entered +from the terminal. Here is a sample interaction between Guile and a +user; the user's input appears after the @code{$} and @code{guile>} +prompts: + +@example +$ guile +guile> (+ 1 2 3) ; add some numbers +6 +guile> (define (factorial n) ; define a function + (if (zero? n) 1 (* n (factorial (- n 1))))) +guile> (factorial 20) +2432902008176640000 +guile> (getpwnam "jimb") ; find my entry in /etc/passwd +#("jimb" ".0krIpK2VqNbU" 4008 10 "Jim Blandy" "/u/jimb" + "/usr/local/bin/bash") +guile> @kbd{C-d} +$ +@end example + +Guile can also interpret script files. For example, here is a Guile script +containing a script which displays the + + +application can +supplement the base language with its own functions, datatypes and +syntax, allowing the user to extend and + + + Guile interpret + +. An +application the Guile interpreter to allow + + +, allowing +applications to incorporate the Scheme interpreter for customization + +[[interactive]] +[[script interpreter]] +[[embedded]] + +[[other languages]] +The concept of an extension language library does not originate with +Guile. However, Guile is the first to offer users a choice of languages +to program in. + + +Guile currently supports Scheme and Ctax , and we expect to support Emacs Lisp in the near future. + + +Scheme is powerful enough that other languages can be +conveniently translated into it, + +However, unlike other extension packages, Guile gives users a choice of +languages to program in. Guile can + + +In this sense, Guile resembles the Tcl and Python packages, providing +both an ordinary interpreter and an extension language library. +However, unlike those packages, Guile supports more than one programming +language. + +; users can +write Scheme code to control and customize applications which +incorporate Guile + +, adding their own functions, +datatypes, and syntax, to allow the user to programm + + +link it into your own programs to make them + + + +Guile is a library containing an interpreter for Scheme, a complete but +economical programming language, which the developer can customize to +suit the application at hand by adding new functions, data types, and +control structures. These may be implemented in C, and then +``exported'' for use by the interpreted code. Because Guile already +provides a full-featured interpreter, the developer need not neglect the +language's design in order to concentrate on code relevant to the task. +In this way, Guile provides a framework for the construction of +domain-specific languages. + +Guile provides first-class functions, a rich set of data types, +exception handling, a module system, and a powerful macro facility. +Guile also supports dynamic linking and direct access to Unix system +calls. Releases in the near future will support a source-level +debugger and bindings for the Tk user interface toolkit. + + + +Guile is a framework for writing applications controlled by specialized +languages. In its simplest form, Guile is an interpreter for Scheme, a +clean, economical programming language in the Lisp family. However, +Guile is packaged as a library, allowing applications to link against it +and use Scheme as their extension language. The application can add +primitive functions to the language, implement new data types, and even +adjust the language's syntax. + + + +[the introduction is probably not what Jim has in mind; I just took the +one I had in earlier, since the file had the same name intro.texi] + +Guile is an implementation of the Scheme programming language, but, like +other modern implementations of Scheme, it adds many features that the +community of Scheme programmers considers necessary for an ``industrial +strength'' language. + +Examples of extensions to Scheme are the module system +(@pxref{Modules}), the Unix system programming tools (@pxref{POSIX +system calls and networking} and @pxref{The Scheme shell (scsh)}), an +interface to @emph{libtool} to make it easier to add C libraries as +primitives (@pxref{Linking Guile with your code}), and (FIXME add more). + +On top of these extensions, which many other Scheme implementations +provide, Guile also offers the possibility of writing routines in other +languages and running them simultaneously with Scheme. The desire to +implement other languages (in particular Emacs Lisp) on top of Scheme is +responsible for Guile's only deviation from the R4RS @footnote{R4RS is +the Revised^4 Report on the Algorithmic Language Scheme, the closest +thing to a standard Scheme specification today} Scheme standard +(@cite{r4rs}): Guile is case sensitive, whereas ``standard'' Scheme is +not. + +But even more fundamentally, Guile is meant to be an @emph{embeddable} +Scheme interpreter. This means that a lot of work has gone into +packaging the interpreter as a C library (@pxref{A Portable C to Scheme Interface} and @pxref{Scheme data representation}). + +This reference manual is mainly driven by the need to document all the +features that go beyond standard Scheme. + +@menu +* Getting started:: +* Guile feature list:: +* What you need to use Guile:: +* Roadmap to the Manual:: +* Motivation for Guile:: +* History of Guile:: +@end menu + +@node Getting started +@section Getting started + +We assume that you know how to program in Scheme, although we do not +assume advanced knowledge. If you don't know Scheme, there are many +good books on Scheme at all levels, and the Guile Tutorial might give +you a good enough feel for the language. We also assume that you know +how to program in C, since there will be many examples of how to program +in C using Guile as a library. + +Many diverse topics from the world of Unix hacking will be covered here, +such as shared libraries, socket programming, garbage collection, and so +forth. If at any time you feel you don't have enough background on a +given topic, just go up a level or two in the manual, and you will find +that the chapter begins with a few paragraphs that introduce the topic. +If you are still lost, read through the Guile tutorial and then come +back to this reference manual. + +To run the core Guile interpreter and extension library you need no more +than a basically configured GNU/Unix system and the Guile sources. You +should download and install the Guile sources (@pxref{Obtaining and +Installing Guile}). + + +@node Guile feature list +@section Guile feature list + +In a reductionist view, Guile could be regarded as: +@itemize @bullet +@item +An R4RS-compliant Scheme interpreter. + +@item +Some Scheme features that go beyond the R4RS standard, notably a module +system, exception handling primitives and an interface to Aubrey +Jaffer's SLIB. + +@item +A symbolic debugger for Scheme, and gdb extensions to facilitate +debugging libguile programs. + +@item +An embeddable version of the same interpreter, called @emph{libguile}. + +@item +A portable high level API on top of libguile (the @code{gh_} interface). + +@item +A collection of bundled C libraries with a Guile API. As we write, this +list includes: + +@table @strong +@item Rx +a regular expression library. + +@item Unix +a low-level interface to the POSIX system calls, socket library +and other Unix system services. + +@item Tk +an interface to John Ousterhout's Tk toolkit. + +@end table + +@item +A set of tools for implementing other languages @emph{on top of Scheme}, +and an example implementation of a language called @emph{Ctax}. + + +@end itemize + + +@node What you need to use Guile +@section What you need to use Guile + + +@node Roadmap to the Manual +@section Roadmap to the Manual + +@node Motivation for Guile +@section Motivation for Guile + +@node History of Guile +@section History of Guile + +@page +@node Using Guile +@chapter Using Guile + +[I think that this might go in the appendix in Jim's view of the manual] + +@page +@node Invoking Guile +@appendix Invoking Guile + --- mentions read-eval-print loops + --- both the SCSH and GAWK manuals relegate invocation details + to an appendix. We can give examples in the introduction. + +@table @samp +@item -h +@itemx --help +Display a helpful message. +@item -v +@item --version +Display the current version. +@item --emacs +To be used for emacs editing support. +@item -s @var{file} +Process @var{file} as a script then quit. This is a terminating option: +any further command line arguments can be accessed by the script using +the @code{(program-arguments)} procedure. + +An executable script can start with the following: + +@smallexample +#!/usr/bin/guile -s +!# +@end smallexample + +Note the @code{!#} token on the second line. It is very important +to include this token when writing Guile scripts. Guile and SCSH, +the Scheme shell, share the convention that @code{#!} and +@code{!#} may be used to mark block comments (@pxref{Block +comments and interpreter triggers}). If the closing @code{!#} +token is not included, then Guile will consider the block comment +to be unclosed, and the script will probably not compile +correctly. + +It is also important to include the @samp{-s} option at the +beginning of the Guile script, so that Guile knows not to behave +in an interactive fashion. + +@end table + diff --git a/doc/sources/sample-APIs.texi b/doc/sources/sample-APIs.texi new file mode 100644 index 000000000..c8c4b8e72 --- /dev/null +++ b/doc/sources/sample-APIs.texi @@ -0,0 +1,6 @@ +@node Examples of adding libraries +@chapter Examples of adding libraries + +Should contain examples of brute-force gh_, Guile magic snarfer, +libtool, SWIG on a dummy API, followed by some real examples of how +libraries are added. diff --git a/doc/sources/scheme-concepts.texi b/doc/sources/scheme-concepts.texi new file mode 100644 index 000000000..e8e78f14d --- /dev/null +++ b/doc/sources/scheme-concepts.texi @@ -0,0 +1,249 @@ +@node Guile Scheme concepts +@chapter Guile Scheme concepts + +Most Scheme implementations go beyond what is specified in the R4RS +document @footnote{Remember? R4RS is the Revised^4 report on the +Algorithmic Language Scheme}, mostly because R4RS does not give +specifications (or even recommendations) regarding some issues that are +quite important in practical programming. + +Here is a list of how Guile implements some of these much-needed Scheme +extensions; other Scheme implementations do so quite similarly. + +@menu +* Scheme slang:: +* Read-eval-print loops:: +* Extra data types:: +* Miscellaneous features:: +@end menu + +@node Scheme slang +@section Scheme slang +@cindex slang + +Even if you read some of the nice books on Scheme, or the R4RS report, +you might not find some of the terms frequently used by Scheme hackers, +both in the manual and in the @url{news:comp.lang.scheme} newsgroup. + +Here is a glossary of some of the terms that make Scheme beginners and +intermediate users say ``huh?'' + +@table @strong +@item thunk +@cindex thunk +A Scheme procedure that takes no arguments. In this example, +@code{thunk} and @code{another-thunk} are both thunks: +@lisp +(define (thunk) + (display "Dude, I'm a thunk!") + (newline)) +(define another-thunk + (lambda () + (display "Me too!\n") + (newline))) +@end lisp + +@item closure +@cindex closure +A closure is a procedure. However, the term emphasizes the fact that a +Scheme procedure remembers (or @dfn{closes over}) the variables that +were visible when the @code{lambda} expression was +evaluated. + +In the example below, we might refer to @code{q} as a closure, because +it has closed over the value of @code{x}: +@lisp +(define p + (lambda (x) + (lambda (y) + (+ x y)))) +(define q (p 5.7)) + +(q 10) +@result{} 15.7 +@end lisp + +However, strictly speaking, every Scheme procedure is really a closure, +since it closes over the top-level environment. + +@item alist +@itemx association list + +@item plist +@itemx property list + +@end table + + +@node Read-eval-print loops +@section Read-eval-print loops +@cindex Read-eval-print loop +@cindex REPL + +To explicitly mention the Scheme read-eval-print loop (REPL) seems weird +because we are all accustomed to firing up an interpreter and having it +read and execute commands. + +But the REPL is not specified in R4RS; rather, it is proposed by the +Scheme Bible @cite{Structure and Interpretation of Computer Programs} +(also known as @emph{SICP}), and implemented in some form in all Scheme +interpreters. +@cindex Structure and Interpretation of Computer Programs +@cindex SICP + +[FIXME: Someone needs to tell me what needs to be said about Guile's +REPL.] + +@node Extra data types +@section Extra data types + +The fundamental Scheme data types specified in R4RS are @emph{numbers} +(both exact and inexact), @emph{characters}, @emph{strings}, +@emph{symbols}, @emph{vectors}, @emph{pairs} and @emph{lists} [FIXME: is +this complete?]. + +Many Scheme interpreters offer more types, and Guile is no exception. +Guile is based on Aubrey Jaffer's SCM interpreter, and thus inherits +@emph{uniform arrays}, [FIXME: any others? How about records?]. + +On top of that, Guile allows you to add extra types, but that is covered +in @ref{Adding types to Guile}. Here I will simply document all the +extra Scheme types shipped with Guile. + +@menu +* Conventional arrays:: +* Uniform arrays:: +* Bit vectors:: +* Complex numbers:: +@end menu + +@node Conventional arrays +@subsection Conventional arrays + +@node Uniform arrays +@subsection Uniform arrays +@cindex arrays - uniform + +The motivation for uniform arrays in Scheme is performance. A vector +provides a performance increase over lists when you want a fixed-size +indexable list. But the elements in a vector can be of different types, +and this makes for larger storage requirements and slightly lower +performance. + +A uniform array is similar to a vector, but all elements have to be of +the same type. + +arrays, uniform arrays, bit vectors: + +@deffn procedure array-fill ra fill +@end deffn +@deffn procedure serial-array-copy! src dst +@end deffn +@deffn procedure serial-array-map ra0 proc [lra] +@end deffn +@deffn procedure array-map ra0 proc [lra] +@end deffn +@deffn procedure array-for-each proc ra0 [lra] +@end deffn +@deffn procedure array-index-map! ra proc +@end deffn +@deffn procedure array-copy! src dst +@end deffn +@deffn procedure array-copy! src dst +@end deffn +@deffn procedure array-copy! src dst +@end deffn +@deffn procedure array-copy! src dst +@end deffn +@deffn procedure array-copy! src dst +@end deffn +@deffn procedure array? ra [prot] +@end deffn +@deffn procedure array-rank ra +@end deffn +@deffn procedure array-dimensions ra +@end deffn +@deffn procedure dimensions->uniform-array dims prot fill ... +@end deffn +@deffn procedure make-shared-array ra mapfunc dims ... +@end deffn +@deffn procedure transpose-array arg ... +@end deffn +@deffn procedure enclose-array axes ... +@end deffn +@deffn procedure array-in-bounds? arg ... +@end deffn +@deffn procedure array-ref ra arg .. +@end deffn +@deffn procedure uniform-vector-ref vec pos +@end deffn +@deffn procedure array-set! ra obj arg ... +@end deffn +@deffn procedure uniform-array-set1! ua obj arg +@end deffn +@deffn procedure array-contents ra [strict] +@end deffn +@deffn procedure uniform-array-read! ra [port-or-fd] [start] [end] +@end deffn +@deffn procedure uniform-array-write! ra [port-or-fd] [start] [end] +@end deffn +@deffn procedure bit-count item seq +@end deffn +@deffn procedure bit-position item v k +@end deffn +@deffn procedure bit-set! v kv obj +@end deffn +@deffn procedure bit-count* v kv obj +@end deffn +@deffn procedure bit-invert v +@end deffn +@deffn procedure array->list ra +@end deffn +@deffn procedure list->uniform-array ndim prot list +@end deffn +@deffn procedure array-prototype ra +@end deffn + +Unform arrays can be written and read, but @code{read} won't recognize +them unless the optional @code{read-sharp} parameter is supplied, +e.g, +@smalllisp +(read port #t read-sharp) +@end smalllisp + +where @code{read-sharp} is the default procedure for parsing extended +sharp notations. + +Reading an array is not very efficient at present, since it's implemented +by reading a list and converting the list to an array. + +@c FIXME: must use @deftp, but its generation of TeX code is buggy. +@c Must fix it when TeXinfo gets fixed. +@deftp {Scheme type} {uniform array} + +@end deftp + +@node Bit vectors +@subsection Bit vectors + +@node Complex numbers +@subsection Complex numbers + +@c FIXME: must use @deftp, but its generation of TeX code is buggy. +@c Must fix it when TeXinfo gets fixed. +@deftp {Scheme type} complex +Standard complex numbers. +@end deftp + +@node Miscellaneous features +@section Miscellaneous features + +@defun defined? symbol +Returns @code{#t} if a symbol is bound to a value, @code{#f} otherwise. +This kind of procedure is not specified in R4RS because @c FIXME: finish +this thought +@end defun + +@defun object-properties OBJ +and so forth +@end defun diff --git a/doc/sources/scm-ref.texi b/doc/sources/scm-ref.texi new file mode 100644 index 000000000..eca672580 --- /dev/null +++ b/doc/sources/scm-ref.texi @@ -0,0 +1,4 @@ +@node Libguile -- SCM interface +@chapter Libguile -- SCM interface + + diff --git a/doc/sources/snarf.texi b/doc/sources/snarf.texi new file mode 100644 index 000000000..e69de29bb --- /dev/null +++ b/doc/sources/snarf.texi diff --git a/doc/sources/strings.texi b/doc/sources/strings.texi new file mode 100644 index 000000000..9a1ddc952 --- /dev/null +++ b/doc/sources/strings.texi @@ -0,0 +1,45 @@ +@node Strings +@chapter Facilities for string manipulation + +@deffn procedure string? string +@end deffn +@deffn procedure read-only-string? string +@end deffn +@deffn procedure list->string list +@end deffn +@deffn procedure make-string length [char] +@end deffn +@deffn procedure string-length string +@end deffn +@deffn procedure string-ref string [index] +@end deffn +@deffn procedure string-set! string index char +@end deffn +@deffn procedure substring string start [end] +@end deffn +@deffn procedure string-append arg ... +@end deffn +@deffn procedure make-shared-substring string [from] [to] +@end deffn +@deffn procedure string-set! string index char +@end deffn +@deffn procedure string-index string char [from] [to] +@end deffn +@deffn procedure string-rindex string char [from] [to] +@end deffn +@deffn procedure substring-move-left! string1 start1 [end1] [string2] [start2] +@end deffn +@deffn procedure substring-move-right! string1 start1 [end1] [string2] [start2] +@end deffn +@deffn procedure substring-fill! string start [end] [fill] +@end deffn +@deffn procedure string-null? string +@end deffn +@deffn procedure string->list string +@end deffn +@deffn procedure string-copy string +@end deffn +@deffn procedure string-upcase! string +@end deffn +@deffn procedure string-downcase! string +@end deffn diff --git a/doc/sources/tk.texi b/doc/sources/tk.texi new file mode 100644 index 000000000..176c8c7b8 --- /dev/null +++ b/doc/sources/tk.texi @@ -0,0 +1,5 @@ +@node Tk interface +@chapter Tk interface + +For now Guile has no well-specified Tk interface. It is an important part +of Guile, though, and will be documented here when it is written. diff --git a/doc/sources/unix-other.texi b/doc/sources/unix-other.texi new file mode 100644 index 000000000..7b810d5d6 --- /dev/null +++ b/doc/sources/unix-other.texi @@ -0,0 +1,132 @@ +@node Other Unix +@chapter Other Unix-specific facilities + +@menu +* Expect:: Expect, for pattern matching from a port. +@end menu + +@node Expect +@section Expect: Pattern Matching from a Port + +@code{expect} is a macro for selecting actions based on the output from +a port. The name comes from a tool of similar functionality by Don Libes. +Actions can be taken when a particular string is matched, when a timeout +occurs, or when end-of-file is seen on the port. The @code{expect} macro +is described below; @code{expect-strings} is a front-end to @code{expect} +based on regexec @xref{Regular expressions}. + +Using these macros requires for now: +@smalllisp +(load-from-path "ice-9/expect") +@end smalllisp + +@defun expect-strings clause @dots{} +By default, @code{expect-strings} will read from the current input port. +The first term in each clause consists of an expression evaluating to +a string pattern (regular expression). As characters +are read one-by-one from the port, they are accumulated in a buffer string +which is matched against each of the patterns. When a +pattern matches, the remaining expression(s) in +the clause are evaluated and the value of the last is returned. For example: + +@smalllisp +(with-input-from-file "/etc/passwd" + (lambda () + (expect-strings + ("^nobody" (display "Got a nobody user.\n") + (display "That's no problem.\n")) + ("^daemon" (display "Got a daemon user.\n"))))) +@end smalllisp + +The regular expression is compiled with the @code{REG_NEWLINE} flag, so +that the @code{^} and @code{$} anchors will match at any newline, not +just at the start +and end of the string. + +There are two other ways to write a clause: + +The expression(s) to evaluate on a match +can be omitted, in which case the result of the match +(converted to strings, as obtained from regexec with @var{match-pick} +set to @code{""}) will be returned if the pattern matches. + +The symbol @code{=>} can be used to indicate that there is a single +expression to evaluate on a match, which must be a +procedure which will accept the result of a successful match (converted +to strings, as obtained from regexec with @var{match-pick} set to +@code{""}). E.g., + +@smalllisp +("^daemon" => write) +("^d\\(aemon\\)" => (lambda args (map write args))) +("^da\\(em\\)on" => (lambda (all sub) + (write all) + (write sub))) +@end smalllisp + +The order of the substrings corresponds to the order in which the +opening brackets occur in the regular expression. + +A number of variables can be used to control the behaviour +of @code{expect} (and @code{expect-strings}). +By default they are all bound at the top level to +the value @code{#f}, which produces the default behaviour. +They can be redefined at the +top level or locally bound in a form enclosing the @code{expect} expression. + +@table @code +@item expect-port +A port to read characters from, instead of the current input port. +@item expect-timeout +@code{expect} will terminate after this number of +seconds, returning @code{#f} or the value returned by +@code{expect-timeout-proc}. +@item expect-timeout-proc +A procedure called if timeout occurs. The procedure takes a single argument: +the accumulated string. +@item expect-eof-proc +A procedure called if end-of-file is detected on the input port. The +procedure takes a single argument: the accumulated string. +@item expect-char-proc +A procedure to be called every time a character is read from the +port. The procedure takes a single argument: the character which was read. +@end table + +Here's an example using all of the variables: + +@smalllisp +(let ((expect-port (open-input-file "/etc/passwd")) + (expect-timeout 1) + (expect-timeout-proc + (lambda (s) (display "Times up!\n"))) + (expect-eof-proc + (lambda (s) (display "Reached the end of the file!\n"))) + (expect-char-proc display)) + (expect-strings + ("^nobody" (display "Got a nobody user\n")))) +@end smalllisp +@end defun + +@defun expect clause @dots{} +@code{expect} is used in the same way as @code{expect-strings}, +but tests are specified not as patterns, but as procedures. The +procedures are called in turn after each character is read from the +port, with the value of the accumulated string as the argument. The +test is successful if the procedure returns a non-false value. + +If the @code{=>} syntax is used, then if the test succeeds it must return +a list containing the arguments to be provided to the corresponding +expression. + +In the following example, a string will only be matched at the beginning +of the file: +@smalllisp +(let ((expect-port (open-input-file "/etc/passwd"))) + (expect + ((lambda (s) (string=? s "fnord!")) + (display "Got a nobody user!\n")))) +@end smalllisp + +The control variables described for @code{expect-strings} can also +be used with @code{expect}. +@end defun diff --git a/doc/sources/unix.texi b/doc/sources/unix.texi new file mode 100644 index 000000000..e8a189c5b --- /dev/null +++ b/doc/sources/unix.texi @@ -0,0 +1,622 @@ +@node Low level Unix +@chapter Low level Unix interfaces + +The low level Unix interfaces are currently available by +default in the Guile top level. However in the future they will probably +be placed in a module and @code{use-modules} or something similar will +be required to make them available. + +@menu +* Unix conventions:: Conventions followed by the low level Unix + interfaces. +* Ports and descriptors:: Ports, file descriptors and how they + interact. +* Extended I/O:: Reading and writing to ports. +* File system:: Working in a hierarchical filesystem. +* User database:: Information about users from system databases. +* Processes:: Information and control of Unix processes. +* Terminals:: Terminals and pseudo-terminals. +* Network databases:: Network address conversion and information + from system databases. +* Network sockets:: An interface to the BSD socket library. +* Miscellaneous Unix:: Miscellaneous Unix interfaces. +@end menu + +@node Unix conventions +@section Low level Unix conventions + +The low-level interfaces are designed to give Scheme programs +access to as much functionality as possible from the underlying +Unix system. They can be used to implement higher level +intefaces such as the Scheme shell @ref{scsh}. + +Generally there is a single procedure for each corresponding Unix +facility. However some of the procedures are implemented for +speed and convenience in Scheme and have no Unix equivalent +(e.g., @code{read-delimited}, @code{copy-file}.) + +This interface is intended as far as possible to be portable across +different versions of Unix, so that Scheme programmers don't need to be +concerned with implementation differences. In some cases procedures +which can't be implemented (or reimplemented) on particular systems may +become no-ops, or perform limited actions. In other cases they may +throw errors. It should be possible to use the feature system to +determine what functionality is available. + +General naming conventions are as follows: + +@itemize @bullet +@item +The Scheme name is often identical to the name of the underlying Unix +facility. +@item +Underscores in Unix names are converted to hyphens. +@item +Procedures which destructively modify Scheme data gain postpended +exclaimation marks, e.g., @code{recv!}. +@item +Predicates are postpended with question marks, e.g., @code{access?}. +@item +Some names are changed to avoid conflict with dissimilar interfaces +defined by scsh. +@item +Unix preprocessor names such as @code{EPERM} or @code{R_OK} are converted +to Scheme variables of the same name (underscores are not replaced +with hyphens) +@end itemize + +Most of the Unix interface procedures can be relied on to return a +well-specified value. Unexpected conditions are handled by raising +exceptions. + +There are a few procedures which return a special +value if they don't succeed, e.g., @code{getenv} returns @code{#f} +if it the requested string is not found in the environment. These +cases will be noted in the documentation. + +For ways to deal with exceptions, @ref{Exceptions}. + +Errors which the C-library would report by returning a NULL +pointer or through some other means cause a @code{system-error} exception +to be raised. The value of the Unix @code{errno} variable is available +in the data passed by the exception, so there is no need to access the +global errno value (doing so would be unreliable in the presence of +continuations or multiple threads). + +@deffn procedure errno [n] +@end deffn +@deffn procedure perror string +@end deffn + +@node Ports and descriptors +@section Ports and file descriptors + +@deffn procedure move->fdes port fd +@end deffn +@deffn procedure release-port-handle port +@end deffn +@deffn procedure set-port-revealed! @var{port} count +@end deffn +@deffn procedure fdes->ports fdes +@end deffn +@deffn procedure fileno port +@end deffn +@deffn procedure fdopen fdes modes +@end deffn +@deffn procedure duplicate-port port modes +@end deffn +@deffn procedure redirect-port into-port from-port +@end deffn +@deffn procedure freopen filename modes port +@end deffn + +@node Extended I/O +@section Extended I/O + +Extended I/O procedures are available which read or write lines of text, +read text delimited by a specified set of characters, or report or +set the current position of a port. + +@findex fwrite +@findex fread +Interfaces to @code{read}/@code{fread} and @code{write}/@code{fwrite} are +also available, as @code{uniform-array-read!} and @code{uniform-array-write!}, +@ref{Uniform arrays}. + +@deffn procedure read-line [port] [handle-delim] +Return a line of text from @var{port} if specified, otherwise from the +value returned by @code{(current-input-port)}. Under Unix, a line of text +is terminated by the first end-of-line character or by end-of-file. + +If @var{handle-delim} is specified, it should be one of the following +symbols: +@table @code +@item trim +Discard the terminating delimiter. This is the default, but it will +be impossible to tell whether the read terminated with a delimiter or +end-of-file. +@item concat +Append the terminating delimiter (if any) to the returned string. +@item peek +Push the terminating delimiter (if any) back on to the port. +@item split +Return a pair containing the string read from the port and the +terminating delimiter or end-of-file object. + +NOTE: if the scsh module is loaded then +multiple values are returned instead of a pair. +@end table +@end deffn +@deffn procedure read-line! buf [port] +Read a line of text into the supplied string @var{buf} and return the +number of characters added to @var{buf}. If @var{buf} is filled, then +@code{#f} is returned. +Read from @var{port} if +specified, otherwise from the value returned by @code{(current-input-port)}. +@end deffn +@deffn procedure read-delimited delims [port] [handle-delim] +Read text until one of the characters in the string @var{delims} is found +or end-of-file is reached. Read from @var{port} if supplied, otherwise +from the value returned by @code{(current-input-port)}. +@var{handle-delim} takes the same values as described for @code{read-line}. + +NOTE: if the scsh module is loaded then @var{delims} must be an scsh +char-set, not a string. +@end deffn +@deffn procedure read-delimited! delims buf [port] [handle-delim] [start] [end] +Read text into the supplied string @var{buf} and return the number of +characters added to @var{buf} (subject to @var{handle-delim}, which takes +the same values specified for @code{read-line}. If @var{buf} is filled, +@code{#f} is returned for both the number of characters read and the +delimiter. Also terminates if one of the characters in the string +@var{delims} is found +or end-of-file is reached. Read from @var{port} if supplied, otherwise +from the value returned by @code{(current-input-port)}. + +NOTE: if the scsh module is loaded then @var{delims} must be an scsh +char-set, not a string. +@end deffn +@deffn procedure write-line obj [port] +Display @var{obj} and a new-line character to @var{port} if specified, +otherwise to the +value returned by @code{(current-output-port)}; equivalent to: + +@smalllisp +(display obj [port]) +(newline [port]) +@end smalllisp +@end deffn +@deffn procedure ftell port +Returns an integer representing the current position of @var{port}, +measured from the beginning. +@end deffn +@deffn procedure fseek port offset whence +Sets the current position of @var{port} to the integer @var{offset}, +which is interpreted according to the value of @var{whence}. + +One of the following variables should be supplied +for @var{whence}: +@defvar SEEK_SET +Seek from the beginning of the file. +@end defvar +@defvar SEEK_CUR +Seek from the current position. +@end defvar +@defvar SEEK_END +Seek from the end of the file. +@end defvar +@end deffn + +@node File system +@section File system + +These procedures query and set file system attributes (such as owner, +permissions, sizes and types of files); deleting, copying, renaming and +linking files; creating and removing directories and querying their +contents; and the @code{sync} interface. + +@deffn procedure access? path how +Evaluates to @code{#t} if @var{path} corresponds to an existing +file and the current process +has the type of access specified by @var{how}, otherwise +@code{#f}. +@var{how} should be specified +using the values of the variables listed below. Multiple values can +be combined using a bitwise or, in which case @code{#t} will only +be returned if all accesses are granted. + +Permissions are checked using the real id of the current process, +not the effective id, although it's the effective id which determines +whether the access would actually be granted. + +@defvar R_OK +test for read permission. +@end defvar +@defvar W_OK +test for write permission. +@end defvar +@defvar X_OK +test for execute permission. +@end defvar +@defvar F_OK +test for existence of the file. +@end defvar +@end deffn +@findex fstat +@deffn procedure stat obj +Evaluates to an object containing various information +about the file determined by @var{obj}. +@var{obj} can be a string containing a file name or a port or file +descriptor which is open on a file (in which case @code{fstat} is used +as the underlying system call). + +The object returned by @code{stat} can be passed as a single parameter +to the following procedures, all of which return integers: + +@table @r +@item stat:dev +The device containing the file. +@item stat:ino +The file serial number, which distinguishes this file from all other +files on the same device. +@item stat:mode +The mode of the file. This includes file type information +and the file permission bits. See @code{stat:type} and @code{stat:perms} +below. +@item stat:nlink +The number of hard links to the file. +@item stat:uid +The user ID of the file's owner. +@item stat:gid +The group ID of the file. +@item stat:rdev +Device ID; this entry is defined only for character or block +special files. +@item stat:size +The size of a regular file in bytes. +@item stat:atime +The last access time for the file. +@item stat:mtime +The last modification time for the file. +@item stat:ctime +The last modification time for the attributes of the file. +@item stat:blksize +The optimal block size for reading or writing the file, in bytes. +@item stat:blocks +The amount of disk space that the file occupies measured in units of +512 byte blocks. +@end table + +In addition, the following procedures return the information +from stat:mode in a more convenient form: + +@table @r +@item stat:type +A symbol representing the type of file. Possible values are +currently: regular, directory, symlink, block-special, char-special, +fifo, socket, unknown +@item stat:perms +An integer representing the access permission bits. +@end table +@end deffn +@deffn procedure lstat path +Similar to @code{stat}, but does not follow symbolic links, i.e., +it will return information about a symbolic link itself, not the +file it points to. @var{path} must be a string. +@end deffn +@deffn procedure readlink path +@end deffn +@deffn procedure chown path owner group +@end deffn +@deffn procedure chmod port-or-path mode +@end deffn +@deffn procedure utime path [actime] [modtime] +@end deffn +@deffn procedure delete-file path +@end deffn +@deffn procedure copy-file path-from path-to +@end deffn +@deffn procedure rename-file path-from path-to +@end deffn +@deffn procedure link path-from path-to +@end deffn +@deffn procedure symlink path-from path-to +@end deffn +@deffn procedure mkdir path [mode] +@end deffn +@deffn procedure rmdir path +@end deffn +@deffn procedure opendir path +@end deffn +@deffn procedure readdir port +@end deffn +@deffn procedure rewinddir port +@end deffn +@deffn procedure closedir port +@end deffn +@deffn procedure sync +@end deffn + +@node User database +@section User database + +@deffn procedure getpwuid uid +@end deffn +@deffn procedure getpwnam name +@end deffn +@deffn procedure getpwent +@end deffn +@deffn procedure setpwent port +@end deffn +@deffn procedure endpwent +@end deffn +@deffn procedure getgrgid uid +@end deffn +@deffn procedure getgrnam name +@end deffn +@deffn procedure getgrent +@end deffn +@deffn procedure setgrent port +@end deffn +@deffn procedure endgrent +@end deffn + +@node Processes +@section Processes + +@deffn procedure chdir path +@end deffn +@deffn procedure getcwd +@end deffn +@deffn procedure umask [mode] +@end deffn +@deffn procedure getpid +@end deffn +@deffn procedure getgroups +@end deffn +@deffn procedure kill pid sig + +@var{sig} should be specified using a variable corresponding to +the Unix symbolic name, e.g, +@defvar SIGHUP +Hang-up signal. +@end defvar +@defvar SIGINT +Interrupt signal. +@end defvar +@end deffn +@deffn procedure waitpid pid options +@defvar WAIT_ANY +@end defvar +@defvar WAIT_MYPGRP +@end defvar +@defvar WNOHANG +@end defvar +@defvar WUNTRACED +@end defvar +@end deffn +@deffn procedure getppid +@end deffn +@deffn procedure getuid +@end deffn +@deffn procedure getgid +@end deffn +@deffn procedure geteuid +@end deffn +@deffn procedure getegid +@end deffn +@deffn procedure setuid id +@end deffn +@deffn procedure setgid id +@end deffn +@deffn procedure seteuid id +@end deffn +@deffn procedure setegid id +@end deffn +@deffn procedure getpgrp +@end deffn +@deffn procedure setpgid pid pgid +@end deffn +@deffn procedure setsid +@end deffn +@deffn procedure execl arg ... +@end deffn +@deffn procedure execlp arg ... +@end deffn +@deffn procedure primitive-fork +@end deffn +@deffn procedure environ [env] +@end deffn +@deffn procedure putenv string +@end deffn +@deffn procedure nice incr +@end deffn + +@node Terminals +@section Terminals and pseudo-terminals + +@deffn procedure isatty? port +@end deffn +@deffn procedure ttyname port +@end deffn +@deffn procedure ctermid +@end deffn +@deffn procedure tcgetpgrp port +@end deffn +@deffn procedure tcsetpgrp port pgid +@end deffn + +@node Network databases +@section Network address conversion and system databases + +@deffn procedure inet-aton address +@end deffn +@deffn procedure inet-ntoa number +@end deffn +@deffn procedure inet-netof address +@end deffn +@deffn procedure inet-lnaof address +@end deffn +@deffn procedure inet-makeaddr net lna +@end deffn +@deffn procedure gethostbyname name +@end deffn +@deffn procedure gethostbyaddr address +@end deffn +@deffn procedure gethostent +@end deffn +@deffn procedure sethostent port +@end deffn +@deffn procedure endhostent +@end deffn +@deffn procedure getnetbyname name +@end deffn +@deffn procedure getnetbyaddr address +@end deffn +@deffn procedure getnetent +@end deffn +@deffn procedure setnetent port +@end deffn +@deffn procedure endnetent +@end deffn +@deffn procedure getprotobyname name +@end deffn +@deffn procedure getprotobynumber number +@end deffn +@deffn procedure getprotoent +@end deffn +@deffn procedure setprotoent port +@end deffn +@deffn procedure endprotoent +@end deffn +@deffn procedure getservbyname name protocol +@end deffn +@deffn procedure getservbyport port protocol +@end deffn +@deffn procedure getservent +@end deffn +@deffn procedure setservent port +@end deffn +@deffn procedure endservent +@end deffn + +@node Network sockets +@section BSD socket library interface + +@deffn procedure socket family style protocol +@end deffn +@deffn procedure socketpair family style protocol +@end deffn +@deffn procedure getsockopt socket level optname +@end deffn +@deffn procedure setsockopt socket level optname value +@end deffn +@deffn procedure shutdown socket how +@end deffn +@deffn procedure connect socket family address arg ... +@end deffn +@deffn procedure bind socket family address arg ... +@end deffn +@deffn procedure listen socket backlog +@end deffn +@deffn procedure accept socket +@end deffn +@deffn procedure getsockname socket +@end deffn +@deffn procedure getpeername socket +@end deffn +@deffn procedure recv! socket buf [flags] +@end deffn +@deffn procedure send socket message [flags] +@end deffn +@deffn procedure recvfrom! socket buf [flags] [start] [end] +@end deffn +@deffn procedure sendto socket message family address args ... [flags] +@end deffn + +@node Miscellaneous Unix +@section Miscellaneous Unix interfaces + +Things which haven't been classified elsewhere (yet?). + +@deffn procedure open path flags [mode] +@defvar O_RDONLY +@end defvar +@defvar O_WRONLY +@end defvar +@defvar O_RDWR +@end defvar +@defvar O_CREAT +@end defvar +@defvar O_EXCL +@end defvar +@defvar O_NOCTTY +@end defvar +@defvar O_TRUNC +@end defvar +@defvar O_APPEND +@end defvar +@defvar O_NONBLOCK +@end defvar +@defvar O_NDELAY +@end defvar +@defvar O_SYNC +@end defvar +@end deffn +@deffn procedure select reads writes excepts secs msecs +@end deffn +@deffn procedure uname +@end deffn +@deffn procedure pipe +@end deffn +@deffn procedure open-pipe command modes +@end deffn +@deffn procedure open-input-pipe command +@end deffn +@deffn procedure open-output-pipe command +@end deffn +@deffn procedure setlocale category [locale] +@defvar LC_COLLATE +@end defvar +@defvar LC_CTYPE +@end defvar +@defvar LC_MONETARY +@end defvar +@defvar LC_NUMERIC +@end defvar +@defvar LC_TIME +@end defvar +@defvar LC_MESSAGES +@end defvar +@defvar LC_ALL +@end defvar +@end deffn +@deffn procedure strftime format stime +@end deffn +@deffn procedure strptime format string +@end deffn +@deffn procedure mknod +@end deffn + +@node scsh +@chapter The Scheme shell (scsh) + +Guile includes an incomplete port of the Scheme shell (scsh) 0.4.4. + +For information about scsh on the Web see +@url{http://www-swiss.ai.mit.edu/scsh/scsh.html}. +The original scsh is available by ftp from +@url{ftp://swiss-ftp.ai.mit.edu:/pub/su}. + +This port of scsh does not currently use the Guile module system, but +can be initialized using: +@smalllisp +(load-from-path "scsh/init") +@end smalllisp + +Note that SLIB must be installed before scsh can be initialized, see +@ref{SLIB} for details. + +@node Threads +@chapter Programming Threads. + |