summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/ref/ChangeLog33
-rw-r--r--doc/ref/api-compound.texi547
-rw-r--r--doc/ref/api-io.texi29
-rw-r--r--doc/ref/posix.texi107
-rw-r--r--doc/ref/slib.texi40
5 files changed, 441 insertions, 315 deletions
diff --git a/doc/ref/ChangeLog b/doc/ref/ChangeLog
index 85020e993..e911cfb0d 100644
--- a/doc/ref/ChangeLog
+++ b/doc/ref/ChangeLog
@@ -1,8 +1,36 @@
+2007-03-08 Kevin Ryde <user42@zip.com.au>
+
+ * api-compound.texi (Structures): Revise and expand variously, add
+ make-vtable.
+
+ * api-io.texi: Add various @cindex entries.
+
+ * slib.texi (SLIB): Shorten the bit about core funcs overridden.
+ Don't want to duplicate the SLIB specs, and the set of modified bits
+ is likely to change over time and don't want to have to keep up with
+ that.
+
+2007-02-22 Kevin Ryde <user42@zip.com.au>
+
+ * posix.texi (Signals): Merge sleep and usleep, note usleep not
+ actually microsecond accurate, remove warning usleep not always
+ available (guile has own code for it now, it's not the system call).
+ Cross reference scm_std_sleep / scm_std_usleep.
+
+ * posix.texi (Signals): Merge getitimer and setitimer, describe what
+ each timer does, use @defvar to get them indexed, caution may not
+ actually be microsecond accurate.
+
2007-02-20 Neil Jerram <neil@ossau.uklinux.net>
* Makefile.am (EXTRA_DIST): Add lib-version.texi to the
distribution.
+2007-02-16 Kevin Ryde <user42@zip.com.au>
+
+ * api-compound.texi (Records): In make-record-type, describe optional
+ print function argument.
+
2007-01-31 Ludovic Courtès <ludovic.courtes@laas.fr>
* api-data.texi (Conversion): Made cross refs point to `Number
@@ -18,6 +46,11 @@
* srfi-modules.texi (SRFI-19 String to date): Mention the
internationalization of `string->date'.
+2007-01-25 Kevin Ryde <user42@zip.com.au>
+
+ * posix.texi (Signals): Note signal handlers run via system async and
+ can hence be delayed quite a while. Struck by William Xu.
+
2007-01-19 Han-Wen Nienhuys <hanwen@lilypond.org>
* api-options.texi (Evaluator trap options): document
diff --git a/doc/ref/api-compound.texi b/doc/ref/api-compound.texi
index 44410d158..c551c4d10 100644
--- a/doc/ref/api-compound.texi
+++ b/doc/ref/api-compound.texi
@@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@@ -2611,14 +2611,22 @@ Note that @code{record?} may be true of any Scheme value; there is no
promise that records are disjoint with other Scheme types.
@end deffn
-@deffn {Scheme Procedure} make-record-type type-name field-names
-Return a @dfn{record-type descriptor}, a value representing a new data
-type disjoint from all others. The @var{type-name} argument must be a
-string, but is only used for debugging purposes (such as the printed
-representation of a record of the new type). The @var{field-names}
-argument is a list of symbols naming the @dfn{fields} of a record of the
-new type. It is an error if the list contains any duplicates. It is
-unspecified how record-type descriptors are represented.
+@deffn {Scheme Procedure} make-record-type type-name field-names [print]
+Create and return a new @dfn{record-type descriptor}.
+
+@var{type-name} is a string naming the type. Currently it's only used
+in the printed representation of records, and in diagnostics.
+@var{field-names} is a list of symbols naming the fields of a record
+of the type. Duplicates are not allowed among these symbols.
+
+@example
+(make-record-type "employee" '(name age salary))
+@end example
+
+The optional @var{print} argument is a function used by
+@code{display}, @code{write}, etc, for printing a record of the new
+type. It's called as @code{(@var{print} record port)} and should look
+at @var{record} and write to @var{port}.
@end deffn
@deffn {Scheme Procedure} record-constructor rtd [field-names]
@@ -2692,296 +2700,369 @@ created the type represented by @var{rtd}.
@subsection Structures
@tpindex Structures
-[FIXME: this is pasted in from Tom Lord's original guile.texi and should
-be reviewed]
-
-A @dfn{structure type} is a first class user-defined data type. A
-@dfn{structure} is an instance of a structure type. A structure type is
-itself a structure.
+A @dfn{structure} is a first class data type which holds Scheme values
+or C words in fields numbered 0 upwards. A @dfn{vtable} represents a
+structure type, giving field types and permissions, and an optional
+print function for @code{write} etc.
-Structures are less abstract and more general than traditional records.
-In fact, in Guile Scheme, records are implemented using structures.
+Structures are lower level than records (@pxref{Records}) but have
+some extra features. The vtable system allows sets of types be
+constructed, with class data. The uninterpreted words can
+inter-operate with C code, allowing arbitrary pointers or other values
+to be stored along side usual Scheme @code{SCM} values.
@menu
-* Structure Concepts:: The structure of Structures
-* Structure Layout:: Defining the layout of structure types
-* Structure Basics:: make-, -ref and -set! procedures for structs
-* Vtables:: Accessing type-specific data
+* Vtables::
+* Structure Basics::
+* Vtable Contents::
+* Vtable Vtables::
@end menu
-@node Structure Concepts
-@subsubsection Structure Concepts
+@node Vtables, Structure Basics, Structures, Structures
+@subsubsection Vtables
-A structure object consists of a handle, structure data, and a vtable.
-The handle is a Scheme value which points to both the vtable and the
-structure's data. Structure data is a dynamically allocated region of
-memory, private to the structure, divided up into typed fields. A
-vtable is another structure used to hold type-specific data. Multiple
-structures can share a common vtable.
+A vtable is a structure type, specifying its layout, and other
+information. A vtable is actually itself a structure, but there's no
+need to worray about that initially (@pxref{Vtable Contents}.)
-When applied to structures, the @code{equal?} predicate
-(@pxref{Equality}) returns @code{#t} if the two structures share a
-common vtable @emph{and} all their fields satisfy @code{equal?}.
+@deffn {Scheme Procedure} make-vtable fields [print]
+Create a new vtable.
-Three concepts are key to understanding structures.
+@var{fields} is a string describing the fields in the structures to be
+created. Each field is represented by two characters, a type letter
+and a permissions letter, for example @code{"pw"}. The types are as
+follows.
@itemize @bullet{}
-@item @dfn{layout specifications}
-
-Layout specifications determine how memory allocated to structures is
-divided up into fields. Programmers must write a layout specification
-whenever a new type of structure is defined.
-
-@item @dfn{structural accessors}
-
-Structure access is by field number. There is only one set of
-accessors common to all structure objects.
+@item
+@code{p} -- a Scheme value. ``p'' stands for ``protected'' meaning
+it's protected against garbage collection.
-@item @dfn{vtables}
+@item
+@code{u} -- an arbitrary word of data (an @code{scm_t_bits}). At the
+Scheme level it's read and written as an unsigned integer. ``u''
+stands for ``uninterpreted'' (it's not treated as a Scheme value), or
+``unprotected'' (it's not marked during GC), or ``unsigned long'' (its
+size), or all of these things.
-Vtables, themselves structures, are first class representations of
-disjoint sub-types of structures in general. In most cases, when a
-new structure is created, programmers must specify a vtable for the
-new structure. Each vtable has a field describing the layout of its
-instances. Vtables can have additional, user-defined fields as well.
+@item
+@code{s} -- a self-reference. Such a field holds the @code{SCM} value
+of the structure itself (a circular reference). This can be useful in
+C code where you might have a pointer to the data array, and want to
+get the Scheme @code{SCM} handle for the structure. In Scheme code it
+has no use.
@end itemize
-
-
-@node Structure Layout
-@subsubsection Structure Layout
-
-When a structure is created, a region of memory is allocated to hold its
-state. The @dfn{layout} of the structure's type determines how that
-memory is divided into fields.
-
-Each field has a specified type. There are only three types allowed, each
-corresponding to a one letter code. The allowed types are:
+The second letter for each field is a permission code,
@itemize @bullet{}
-@item 'u' -- unprotected
-
-The field holds binary data that is not GC protected.
-
-@item 'p' -- protected
-
-The field holds a Scheme value and is GC protected.
-
-@item 's' -- self
-
-The field holds a Scheme value and is GC protected. When a structure is
-created with this type of field, the field is initialized to refer to
-the structure's own handle. This kind of field is mainly useful when
-mixing Scheme and C code in which the C code may need to compute a
-structure's handle given only the address of its malloc'd data.
+@item
+@code{w} -- writable, the field can be read and written.
+@item
+@code{r} -- read-only, the field can be read but not written.
+@item
+@code{o} -- opaque, the field can be neither read nor written at the
+Scheme level. This can be used for fields which should only be used
+from C code.
+@item
+@code{W},@code{R},@code{O} -- a tail array, with permissions for the
+array fields as per @code{w},@code{r},@code{o}.
@end itemize
+A tail array is further fields at the end of a structure. The last
+field in the layout string might be for instance @samp{pW} to have a
+tail of writable Scheme-valued fields. The @samp{pW} field itself
+holds the tail size, and the tail fields come after it.
-Each field also has an associated access protection. There are only
-three kinds of protection, each corresponding to a one letter code.
-The allowed protections are:
+Here are some examples.
-@itemize @bullet{}
-@item 'w' -- writable
+@example
+(make-vtable "pw") ;; one writable field
+(make-vtable "prpw") ;; one read-only and one writable
+(make-vtable "pwuwuw") ;; one scheme and two uninterpreted
-The field can be read and written.
+(make-vtable "prpW") ;; one fixed then a tail array
+@end example
-@item 'r' -- readable
+The optional @var{print} argument is a function called by
+@code{display} and @code{write} (etc) to give a printed representation
+of a structure created from this vtable. It's called
+@code{(@var{print} struct port)} and should look at @var{struct} and
+write to @var{port}. The default print merely gives a form like
+@samp{#<struct ADDR:ADDR>} with a pair of machine addresses.
-The field can be read, but not written.
+The following print function for example shows the two fields of its
+structure.
-@item 'o' -- opaque
+@example
+(make-vtable "prpw"
+ (lambda (struct port)
+ (display "#<")
+ (display (struct-ref 0))
+ (display " and ")
+ (display (struct-ref 1))
+ (display ">")))
+@end example
+@end deffn
-The field can be neither read nor written. This kind
-of protection is for fields useful only to built-in routines.
-@end itemize
-A layout specification is described by stringing together pairs
-of letters: one to specify a field type and one to specify a field
-protection. For example, a traditional cons pair type object could
-be described as:
+@node Structure Basics, Vtable Contents, Vtables, Structures
+@subsubsection Structure Basics
-@example
-; cons pairs have two writable fields of Scheme data
-"pwpw"
-@end example
+This section describes the basic procedures for working with
+structures. @code{make-struct} creates a structure, and
+@code{struct-ref} and @code{struct-set!} access write fields.
+
+@deffn {Scheme Procedure} make-struct vtable tail-size [init...]
+@deffnx {C Function} scm_make_struct (vtable, tail_size, init_list)
+Create a new structure, with layout per the given @var{vtable}
+(@pxref{Vtables}).
+
+@var{tail-size} is the size of the tail array if @var{vtable}
+specifies a tail array. @var{tail-size} should be 0 when @var{vtable}
+doesn't specify a tail array.
+
+The optional @var{init}@dots{} arguments are initial values for the
+fields of the structure (and the tail array). This is the only way to
+put values in read-only fields. If there are fewer @var{init}
+arguments than fields then the defaults are @code{#f} for a Scheme
+field (type @code{p}) or 0 for an uninterpreted field (type @code{u}).
+
+Type @code{s} self-reference fields, permission @code{o} opaque
+fields, and the count field of a tail array are all ignored for the
+@var{init} arguments, ie.@: an argument is not consumed by such a
+field. An @code{s} is always set to the structure itself, an @code{o}
+is always set to @code{#f} or 0 (with the intention that C code will
+do something to it later), and the tail count is always the given
+@var{tail-size}.
-A pair object in which the first field is held constant could be:
+For example,
@example
-"prpw"
+(define v (make-vtable "prpwpw"))
+(define s (make-struct v 0 123 "abc" 456))
+(struct-ref s 0) @result{} 123
+(struct-ref s 1) @result{} "abc"
@end example
-Binary fields, (fields of type "u"), hold one @dfn{word} each. The
-size of a word is a machine dependent value defined to be equal to the
-value of the C expression: @code{sizeof (long)}.
-
-The last field of a structure layout may specify a tail array.
-A tail array is indicated by capitalizing the field's protection
-code ('W', 'R' or 'O'). A tail-array field is replaced by
-a read-only binary data field containing an array size. The array
-size is determined at the time the structure is created. It is followed
-by a corresponding number of fields of the type specified for the
-tail array. For example, a conventional Scheme vector can be
-described as:
-
@example
-; A vector is an arbitrary number of writable fields holding Scheme
-; values:
-"pW"
+(define v (make-vtable "prpW"))
+(define s (make-struct v 6 "fixed field" 'x 'y))
+(struct-ref s 0) @result{} "fixed field"
+(struct-ref s 1) @result{} 2 ;; tail size
+(struct-ref s 2) @result{} x ;; tail array ...
+(struct-ref s 3) @result{} y
+(struct-ref s 4) @result{} #f
@end example
+@end deffn
-In the above example, field 0 contains the size of the vector and
-fields beginning at 1 contain the vector elements.
+@deffn {Scheme Procedure} struct? obj
+@deffnx {C Function} scm_struct_p (obj)
+Return @code{#t} if @var{obj} is a structure, or @code{#f} if not.
+@end deffn
-A kind of tagged vector (a constant tag followed by conventional
-vector elements) might be:
+@deffn {Scheme Procedure} struct-ref struct n
+@deffnx {C Function} scm_struct_ref (struct, n)
+Return the contents of field number @var{n} in @var{struct}. The
+first field is number 0.
-@example
-"prpW"
-@end example
+An error is thrown if @var{n} is out of range, or if the field cannot
+be read because it's @code{o} opaque.
+@end deffn
+@deffn {Scheme Procedure} struct-set! struct n value
+@deffnx {C Function} scm_struct_set_x (struct, n, value)
+Set field number @var{n} in @var{struct} to @var{value}. The first
+field is number 0.
-Structure layouts are represented by specially interned symbols whose
-name is a string of type and protection codes. To create a new
-structure layout, use this procedure:
+An error is thrown if @var{n} is out of range, or if the field cannot
+be written because it's @code{r} read-only or @code{o} opaque.
+@end deffn
-@deffn {Scheme Procedure} make-struct-layout fields
-@deffnx {C Function} scm_make_struct_layout (fields)
-Return a new structure layout object.
+@deffn {Scheme Procedure} struct-vtable struct
+@deffnx {C Function} scm_struct_vtable (struct)
+Return the vtable used by @var{struct}.
-@var{fields} must be a string made up of pairs of characters
-strung together. The first character of each pair describes a field
-type, the second a field protection. Allowed types are 'p' for
-GC-protected Scheme data, 'u' for unprotected binary data, and 's' for
-a field that points to the structure itself. Allowed protections
-are 'w' for mutable fields, 'r' for read-only fields, and 'o' for opaque
-fields. The last field protection specification may be capitalized to
-indicate that the field is a tail-array.
+This can be used to examine the layout of an unknown structure, see
+@ref{Vtable Contents}.
@end deffn
+@node Vtable Contents, Vtable Vtables, Structure Basics, Structures
+@subsubsection Vtable Contents
-@node Structure Basics
-@subsubsection Structure Basics
+A vtable is itself a structure, with particular fields that hold
+information about the structures to be created. These include the
+fields of those structures, and the print function for them. The
+variables below allow access to those fields.
-This section describes the basic procedures for creating and accessing
-structures.
+@deffn {Scheme Procedure} struct-vtable? obj
+@deffnx {C Function} scm_struct_vtable_p (obj)
+Return @code{#t} if @var{obj} is a vtable structure.
-@deffn {Scheme Procedure} make-struct vtable tail_array_size . init
-@deffnx {C Function} scm_make_struct (vtable, tail_array_size, init)
-Create a new structure.
+Note that because vtables are simply structures with a particular
+layout, @code{struct-vtable?} can potentially return true on an
+application structure which merely happens to look like a vtable.
+@end deffn
-@var{type} must be a vtable structure (@pxref{Vtables}).
+@defvr {Scheme Variable} vtable-index-layout
+@defvrx {C Macro} scm_vtable_index_layout
+The field number of the layout specification in a vtable. The layout
+specification is a symbol like @code{pwpw} formed from the fields
+string passed to @code{make-vtable}, or created by
+@code{make-struct-layout} (@pxref{Vtable Vtables}).
-@var{tail-elts} must be a non-negative integer. If the layout
-specification indicated by @var{type} includes a tail-array,
-this is the number of elements allocated to that array.
+@example
+(define v (make-vtable "pwpw" 0))
+(struct-ref v vtable-index-layout) @result{} pwpw
+@end example
-The @var{init1}, @dots{} are optional arguments describing how
-successive fields of the structure should be initialized. Only fields
-with protection 'r' or 'w' can be initialized, except for fields of
-type 's', which are automatically initialized to point to the new
-structure itself; fields with protection 'o' can not be initialized by
-Scheme programs.
+This field is read-only, since the layout of structures using a vtable
+cannot be changed.
+@end defvr
-If fewer optional arguments than initializable fields are supplied,
-fields of type 'p' get default value #f while fields of type 'u' are
-initialized to 0.
+@defvr {Scheme Variable} vtable-index-vtable
+@defvrx {C Macro} scm_vtable_index_vtable
+A self-reference to the vtable, ie.@: a type @code{s} field. This is
+used by C code within Guile and has no use at the Scheme level.
+@end defvr
-Structs are currently the basic representation for record-like data
-structures in Guile. The plan is to eventually replace them with a
-new representation which will at the same time be easier to use and
-more powerful.
+@defvr {Scheme Variable} vtable-index-printer
+@defvrx {C Macro} scm_vtable_index_printer
+The field number of the printer function. This field contains @code{#f}
+if the default print function should be used.
-For more information, see the documentation for @code{make-vtable-vtable}.
-@end deffn
+@example
+(define (my-print-func struct port)
+ ...)
+(define v (make-vtable "pwpw" my-print-func))
+(struct-ref v vtable-index-printer) @result{} my-print-func
+@end example
-@deffn {Scheme Procedure} struct? x
-@deffnx {C Function} scm_struct_p (x)
-Return @code{#t} iff @var{x} is a structure object, else
-@code{#f}.
-@end deffn
+This field is writable, allowing the print function to be changed
+dynamically.
+@end defvr
+@deffn {Scheme Procedure} struct-vtable-name vtable
+@deffnx {Scheme Procedure} set-struct-vtable-name! vtable name
+@deffnx {C Function} scm_struct_vtable_name (vtable)
+@deffnx {C Function} scm_set_struct_vtable_name_x (vtable, name)
+Get or set the name of @var{vtable}. @var{name} is a symbol and is
+used in the default print function when printing structures created
+from @var{vtable}.
-@deffn {Scheme Procedure} struct-ref handle pos
-@deffnx {Scheme Procedure} struct-set! struct n value
-@deffnx {C Function} scm_struct_ref (handle, pos)
-@deffnx {C Function} scm_struct_set_x (struct, n, value)
-Access (or modify) the @var{n}th field of @var{struct}.
+@example
+(define v (make-vtable "pw"))
+(set-struct-vtable-name! v 'my-name)
-If the field is of type 'p', then it can be set to an arbitrary value.
+(define s (make-struct v 0))
+(display s) @print{} #<my-name b7ab3ae0:b7ab3730>
+@end example
+@end deffn
-If the field is of type 'u', then it can only be set to a non-negative
-integer value small enough to fit in one machine word.
+@deffn {Scheme Procedure} struct-vtable-tag vtable
+@deffnx {C Function} scm_struct_vtable_tag (vtable)
+Return the tag of the given @var{vtable}.
+@c
+@c FIXME: what can be said about what this means?
+@c
@end deffn
+@node Vtable Vtables, , Vtable Contents, Structures
+@subsubsection Vtable Vtables
-@node Vtables
-@subsubsection Vtables
+As noted above, a vtable is a structure and that structure is itself
+described by a vtable. Such a ``vtable of a vtable'' can be created
+with @code{make-vtable-vtable} below. This can be used to build sets
+of related vtables, possibly with extra application fields.
-Vtables are structures that are used to represent structure types. Each
-vtable contains a layout specification in field
-@code{vtable-index-layout} -- instances of the type are laid out
-according to that specification. Vtables contain additional fields
-which are used only internally to libguile. The variable
-@code{vtable-offset-user} is bound to a field number. Vtable fields
-at that position or greater are user definable.
+This second level of vtable can be a little confusing. The ball
+example below is a typical use, adding a ``class data'' field to the
+vtables, from which instance structures are created. The current
+implementation of Guile's own records (@pxref{Records}) does something
+similar, a record type descriptor is a vtable with room to hold the
+field names of the records to be created from it.
-@deffn {Scheme Procedure} struct-vtable handle
-@deffnx {C Function} scm_struct_vtable (handle)
-Return the vtable structure that describes the type of @var{struct}.
-@end deffn
+@deffn {Scheme Procedure} make-vtable-vtable user-fields tail-size [print]
+@deffnx {C Function} scm_make_vtable_vtable (user_fields, tail_size, print_and_init_list)
+Create a ``vtable-vtable'' which can be used to create vtables. This
+vtable-vtable is also a vtable, and is self-describing, meaning its
+vtable is itself. The following is a simple usage.
-@deffn {Scheme Procedure} struct-vtable? x
-@deffnx {C Function} scm_struct_vtable_p (x)
-Return @code{#t} iff @var{x} is a vtable structure.
-@end deffn
+@example
+(define vt-vt (make-vtable-vtable "" 0))
+(define vt (make-struct vt-vt 0
+ (make-struct-layout "pwpw"))
+(define s (make-struct vt 0 123 456))
-If you have a vtable structure, @code{V}, you can create an instance of
-the type it describes by using @code{(make-struct V ...)}. But where
-does @code{V} itself come from? One possibility is that @code{V} is an
-instance of a user-defined vtable type, @code{V'}, so that @code{V} is
-created by using @code{(make-struct V' ...)}. Another possibility is
-that @code{V} is an instance of the type it itself describes. Vtable
-structures of the second sort are created by this procedure:
+(struct-ref s 0) @result{} 123
+@end example
-@deffn {Scheme Procedure} make-vtable-vtable user_fields tail_array_size . init
-@deffnx {C Function} scm_make_vtable_vtable (user_fields, tail_array_size, init)
-Return a new, self-describing vtable structure.
+@code{make-struct} is used to create a vtable from the vtable-vtable.
+The first initializer is a layout object (field
+@code{vtable-index-layout}), usually obtained from
+@code{make-struct-layout} (below). An optional second initializer is
+a printer function (field @code{vtable-index-printer}), used as
+described under @code{make-vtable} (@pxref{Vtables}).
-@var{user-fields} is a string describing user defined fields of the
-vtable beginning at index @code{vtable-offset-user}
-(see @code{make-struct-layout}).
+@sp 1
+@var{user-fields} is a layout string giving extra fields to have in
+the vtables. A vtable starts with some base fields as per @ref{Vtable
+Contents}, and @var{user-fields} is appended. The @var{user-fields}
+start at field number @code{vtable-offset-user} (below), and exist in
+both the vtable-vtable and in the vtables created from it. Such
+fields provide space for ``class data''. For example,
-@var{tail-size} specifies the size of the tail-array (if any) of
-this vtable.
+@example
+(define vt-of-vt (make-vtable-vtable "pw" 0))
+(define vt (make-struct vt-of-vt 0))
+(struct-set! vt vtable-offset-user "my class data")
+@end example
+
+@var{tail-size} is the size of the tail array in the vtable-vtable
+itself, if @var{user-fields} specifies a tail array. This should be 0
+if nothing extra is required or the format has no tail array. The
+tail array field such as @samp{pW} holds the tail array size, as
+usual, and is followed by the extra space.
-@var{init1}, @dots{} are the optional initializers for the fields of
-the vtable.
+@example
+(define vt-vt (make-vtable-vtable "pW" 20))
+(define my-vt-tail-start (1+ vtable-offset-user))
+(struct-set! vt-vt (+ 3 my-vt-tail-start) "data in tail")
+@end example
-Vtables have one initializable system field---the struct printer.
-This field comes before the user fields in the initializers passed
-to @code{make-vtable-vtable} and @code{make-struct}, and thus works as
-a third optional argument to @code{make-vtable-vtable} and a fourth to
-@code{make-struct} when creating vtables:
+The optional @var{print} argument is used by @code{display} and
+@code{write} (etc) to print the vtable-vtable and any vtables created
+from it. It's called as @code{(@var{print} vtable port)} and should
+look at @var{vtable} and write to @var{port}. The default is the
+usual structure print function, which just gives machine addresses.
+@end deffn
-If the value is a procedure, it will be called instead of the standard
-printer whenever a struct described by this vtable is printed.
-The procedure will be called with arguments STRUCT and PORT.
+@deffn {Scheme Procedure} make-struct-layout fields
+@deffnx {C Function} scm_make_struct_layout (fields)
+Return a structure layout symbol, from a @var{fields} string.
+@var{fields} is as described under @code{make-vtable}
+(@pxref{Vtables}). An invalid @var{fields} string is an error.
-The structure of a struct is described by a vtable, so the vtable is
-in essence the type of the struct. The vtable is itself a struct with
-a vtable. This could go on forever if it weren't for the
-vtable-vtables which are self-describing vtables, and thus terminate
-the chain.
+@example
+(make-struct-layout "prpW") @result{} prpW
+(make-struct-layout "blah") @result{} ERROR
+@end example
+@end deffn
-There are several potential ways of using structs, but the standard
-one is to use three kinds of structs, together building up a type
-sub-system: one vtable-vtable working as the root and one or several
-"types", each with a set of "instances". (The vtable-vtable should be
-compared to the class <class> which is the class of itself.)
+@defvr {Scheme Variable} vtable-offset-user
+@defvrx {C Macro} scm_vtable_offset_user
+The first field in a vtable which is available for application use.
+Such fields only exist when specified by @var{user-fields} in
+@code{make-vtable-vtable} above.
+@end defvr
+
+@sp 1
+Here's an extended vtable-vtable example, creating classes of
+``balls''. Each class has a ``colour'', which is fixed. Instances of
+those classes are created, and such each such ball has an ``owner'',
+which can be changed.
@lisp
(define ball-root (make-vtable-vtable "pr" 0))
@@ -3005,22 +3086,6 @@ compared to the class <class> which is the class of itself.)
(define ball (make-ball green 'Nisse))
ball @result{} #<a green ball owned by Nisse>
@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} struct-vtable-name vtable
-@deffnx {C Function} scm_struct_vtable_name (vtable)
-Return the name of the vtable @var{vtable}.
-@end deffn
-
-@deffn {Scheme Procedure} set-struct-vtable-name! vtable name
-@deffnx {C Function} scm_set_struct_vtable_name_x (vtable, name)
-Set the name of the vtable @var{vtable} to @var{name}.
-@end deffn
-
-@deffn {Scheme Procedure} struct-vtable-tag handle
-@deffnx {C Function} scm_struct_vtable_tag (handle)
-Return the vtable tag of the structure @var{handle}.
-@end deffn
@node Dictionary Types
diff --git a/doc/ref/api-io.texi b/doc/ref/api-io.texi
index 0d30c4d2a..f69d07ede 100644
--- a/doc/ref/api-io.texi
+++ b/doc/ref/api-io.texi
@@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@@ -24,6 +24,7 @@
@node Ports
@subsection Ports
+@cindex Port
Sequential input/output in Scheme is represented by operations on a
@dfn{port}. This chapter explains the operations that Guile provides
@@ -94,10 +95,12 @@ Equivalent to @code{(or (input-port? @var{x}) (output-port?
@node Reading
@subsection Reading
+@cindex Reading
[Generic procedures for reading from ports.]
@rnindex eof-object?
+@cindex End of file object
@deffn {Scheme Procedure} eof-object? x
@deffnx {C Function} scm_eof_object_p (x)
Return @code{#t} if @var{x} is an end-of-file object; otherwise
@@ -217,6 +220,7 @@ Set the current column or line number of @var{port}.
@node Writing
@subsection Writing
+@cindex Writing
[Generic procedures for writing to ports.]
@@ -320,6 +324,8 @@ all open output ports. The return value is unspecified.
@node Closing
@subsection Closing
+@cindex Closing ports
+@cindex Port, close
@deffn {Scheme Procedure} close-port port
@deffnx {C Function} scm_close_port (port)
@@ -354,6 +360,8 @@ open.
@node Random Access
@subsection Random Access
+@cindex Random access, ports
+@cindex Port, random access
@deffn {Scheme Procedure} seek fd_port offset whence
@deffnx {C Function} scm_seek (fd_port, offset, whence)
@@ -410,6 +418,8 @@ the current size, but this is not mandatory in the POSIX standard.
@node Line/Delimited
@subsection Line Oriented and Delimited Text
+@cindex Line input/output
+@cindex Port, line input/output
The delimited-I/O module can be accessed with:
@@ -520,6 +530,8 @@ delimiter may be either a newline or the @var{eof-object}; if
@node Block Reading and Writing
@subsection Block reading and writing
+@cindex Block read/write
+@cindex Port, block read/write
The Block-string-I/O module can be accessed with:
@@ -618,6 +630,8 @@ return 0 immediately if the request size is 0 bytes.
@node Default Ports
@subsection Default Ports for Input, Output and Errors
+@cindex Default ports
+@cindex Port, default
@rnindex current-input-port
@deffn {Scheme Procedure} current-input-port
@@ -693,6 +707,8 @@ initialized with the @var{port} argument.
@node Port Types
@subsection Types of Port
+@cindex Types of ports
+@cindex Port, types
[Types of port; how to make them.]
@@ -706,6 +722,8 @@ initialized with the @var{port} argument.
@node File Ports
@subsubsection File Ports
+@cindex File port
+@cindex Port, file
The following procedures are used to open file ports.
See also @ref{Ports and File Descriptors, open}, for an interface
@@ -866,6 +884,8 @@ Determine whether @var{obj} is a port that is related to a file.
@node String Ports
@subsubsection String Ports
+@cindex String port
+@cindex Port, string
The following allow string ports to be opened by analogy to R4R*
file port facilities:
@@ -931,6 +951,8 @@ but trying to extract the file descriptor number will fail.
@node Soft Ports
@subsubsection Soft Ports
+@cindex Soft port
+@cindex Port, soft
A @dfn{soft-port} is a port based on a vector of procedures capable of
accepting or delivering characters. It allows emulation of I/O ports.
@@ -986,6 +1008,8 @@ For example:
@node Void Ports
@subsubsection Void Ports
+@cindex Void port
+@cindex Port, void
This kind of port causes any data to be discarded when written to, and
always returns the end-of-file object when read from.
@@ -1010,6 +1034,8 @@ documentation for @code{open-file} in @ref{File Ports}.
@node C Port Interface
@subsubsection C Port Interface
+@cindex C port interface
+@cindex Port, C interface
This section describes how to use Scheme ports from C.
@@ -1119,6 +1145,7 @@ is set.
@node Port Implementation
@subsubsection Port Implementation
+@cindex Port implemenation
This section describes how to implement a new port type in C.
diff --git a/doc/ref/posix.texi b/doc/ref/posix.texi
index faf57d6b1..341bcf450 100644
--- a/doc/ref/posix.texi
+++ b/doc/ref/posix.texi
@@ -1388,17 +1388,17 @@ and @code{command-line} above.
@var{argv} is an array of null-terminated strings, as in a C
@code{main} function. @var{argc} is the number of strings in
-@var{argv}, or if it's negative then a @code{NULL} entry in @var{argv}
-marks its end.
+@var{argv}, or if it's negative then a @code{NULL} in @var{argv} marks
+its end.
@var{first} is an extra string put at the start of the arguments, or
@code{NULL} for no such extra. This is a convenient way to pass the
program name after advancing @var{argv} to strip option arguments.
+Eg.@:
@example
@{
char *progname = argv[0];
- int i;
for (argv++; argv[0] != NULL && argv[0][0] == '-'; argv++)
@{
/* munch option ... */
@@ -1409,7 +1409,7 @@ program name after advancing @var{argv} to strip option arguments.
@end example
This sort of thing is often done at startup under
-@code{scm_boot_guile} with any options handled at the C level removed.
+@code{scm_boot_guile} with options handled at the C level removed.
The given strings are all copied, so the C data is not accessed again
once @code{scm_set_program_arguments} returns.
@end deftypefn
@@ -1836,7 +1836,13 @@ specified processes.
@subsection Signals
@cindex signal
-Procedures to raise, handle and wait for signals.
+The following procedures raise, handle and wait for signals.
+
+Scheme code signal handlers are run via a system async (@pxref{System
+asyncs}), so they're called in the handler's thread at the next safe
+opportunity. Generally this is after any currently executing
+primitive procedure finishes (which could be a long time for
+primitives that wait for an external event).
@deffn {Scheme Procedure} kill pid sig
@deffnx {C Function} scm_kill (pid, sig)
@@ -1961,47 +1967,72 @@ action is to either terminate the current process or invoke a
handler procedure. The return value is unspecified.
@end deffn
-@deffn {Scheme Procedure} sleep i
-@deffnx {C Function} scm_sleep (i)
-Wait for the given number of seconds (an integer) or until a signal
-arrives. The return value is zero if the time elapses or the number
-of seconds remaining otherwise.
-@end deffn
-
-@deffn {Scheme Procedure} usleep i
-@deffnx {C Function} scm_usleep (i)
-Sleep for @var{i} microseconds. @code{usleep} is not available on
-all platforms. [FIXME: so what happens when it isn't?]
-@end deffn
-
-@deffn {Scheme Procedure} setitimer which_timer interval_seconds interval_microseconds value_seconds value_microseconds
-@deffnx {C Function} scm_setitimer (which_timer, interval_seconds, interval_microseconds, value_seconds, value_microseconds)
-Set the timer specified by @var{which_timer} according to the given
-@var{interval_seconds}, @var{interval_microseconds},
-@var{value_seconds}, and @var{value_microseconds} values.
-
-Return information about the timer's previous setting.
+@deffn {Scheme Procedure} sleep secs
+@deffnx {Scheme Procedure} usleep usecs
+@deffnx {C Function} scm_sleep (secs)
+@deffnx {C Function} scm_usleep (usecs)
+Wait the given period @var{secs} seconds or @var{usecs} microseconds
+(both integers). If a signal arrives the wait stops and the return
+value is the time remaining, in seconds or microseconds respectively.
+If the period elapses with no signal the return is zero.
-The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL},
-and @code{ITIMER_PROF}.
+On most systems the process scheduler is not microsecond accurate and
+the actual period slept by @code{usleep} might be rounded to a system
+clock tick boundary, which might be 10 milliseconds for instance.
-The return value will be a list of two cons pairs representing the
-current state of the given timer. The first pair is the seconds and
-microseconds of the timer @code{it_interval}, and the second pair is
-the seconds and microseconds of the timer @code{it_value}.
+See @code{scm_std_sleep} and @code{scm_std_usleep} for equivalents at
+the C level (@pxref{Blocking}).
@end deffn
@deffn {Scheme Procedure} getitimer which_timer
+@deffnx {Scheme Procedure} setitimer which_timer interval_seconds interval_microseconds periodic_seconds periodic_microseconds
@deffnx {C Function} scm_getitimer (which_timer)
-Return information about the timer specified by @var{which_timer}.
+@deffnx {C Function} scm_setitimer (which_timer, interval_seconds, interval_microseconds, periodic_seconds, periodic_microseconds)
+Get or set the periods programmed in certain system timers. These
+timers have a current interval value which counts down and on reaching
+zero raises a signal. An optional periodic value can be set to
+restart from there each time, for periodic operation.
+@var{which_timer} is one of the following values
+
+@defvar ITIMER_REAL
+A real-time timer, counting down elapsed real time. At zero it raises
+@code{SIGALRM}. This is like @code{alarm} above, but with a higher
+resolution period.
+@end defvar
+
+@defvar ITIMER_VIRTUAL
+A virtual-time timer, counting down while the current process is
+actually using CPU. At zero it raises @code{SIGVTALRM}.
+@end defvar
+
+@defvar ITIMER_PROF
+A profiling timer, counting down while the process is running (like
+@code{ITIMER_VIRTUAL}) and also while system calls are running on the
+process's behalf. At zero it raises a @code{SIGPROF}.
+
+This timer is intended for profiling where a program is spending its
+time (by looking where it is when the timer goes off).
+@end defvar
+
+@code{getitimer} returns the current timer value and its programmed
+restart value, as a list containing two pairs. Each pair is a time in
+seconds and microseconds: @code{((@var{interval_secs}
+. @var{interval_usecs}) (@var{periodic_secs}
+. @var{periodic_usecs}))}.
+
+@code{setitimer} sets the timer values similarly, in seconds and
+microseconds (which must be integers). The periodic value can be zero
+to have the timer run down just once. The return value is the timer's
+previous setting, in the same form as @code{getitimer} returns.
-The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL},
-and @code{ITIMER_PROF}.
+@example
+(setitimer ITIMER_REAL
+ 5 500000 ;; first SIGALRM in 5.5 seconds time
+ 2 0) ;; then repeat every 2 seconds
+@end example
-The return value will be a list of two cons pairs representing the
-current state of the given timer. The first pair is the seconds and
-microseconds of the timer @code{it_interval}, and the second pair is
-the seconds and microseconds of the timer @code{it_value}.
+Although the timers are programmed in microseconds, the actual
+accuracy might not be that high.
@end deffn
diff --git a/doc/ref/slib.texi b/doc/ref/slib.texi
index a719494b6..7d433cc17 100644
--- a/doc/ref/slib.texi
+++ b/doc/ref/slib.texi
@@ -27,41 +27,11 @@ slib, The SLIB Manual}). For example,
@result{} #t
@end example
-Note that the following Guile core functions are overridden by
-@code{(ice-9 slib)}, to implement SLIB specified semantics.
-
-@table @code
-@item delete-file
-@findex delete-file
-Returns @code{#t} for success or @code{#f} for failure
-(@pxref{Input/Output,,, slib, The SLIB Manual}), as opposed to the
-Guile core version unspecified for success and throwing an error for
-failure (@pxref{File System}).
-
-@c `provide' is also exported by ice-9 slib, but its definition in
-@c slib require.scm is the same as guile boot-9.scm, so believe
-@c nothing needs to be said about that.
-
-@item provided?
-@findex provided?
-Accepts a feature specification containing @code{and} and @code{or}
-forms combining symbols (@pxref{Feature,,, slib, The SLIB Manual}), as
-opposed to the Guile core taking only plain symbols (@pxref{Feature
-Manipulation}).
-
-@item open-file
-@findex open-file
-Takes a symbol @code{r}, @code{rb}, @code{w} or @code{wb} for the open
-mode (@pxref{Input/Output,,, slib, The SLIB Manual}), as opposed to
-the Guile core version taking a string (@pxref{File Ports}).
-
-@item system
-@findex system
-Returns a plain exit code 0 to 255 (@pxref{System Interface,,, slib,
-The SLIB Manual}), as opposed to the Guile core version returning a
-wait status that must be examined with @code{status:exit-val} etc
-(@pxref{Processes}).
-@end table
+A few Guile core functions are overridden by the SLIB setups; for
+example the SLIB version of @code{delete-file} returns a boolean
+indicating success or failure, whereas the Guile core version throws
+an error for failure. In general (and as might be expected) when SLIB
+is loaded it's the SLIB specifications which are followed.
@menu
* SLIB installation::