Add examples from Ian Sheldon, and merge recent updates from stable branch.

doc/ref/ChangeLog

@@ -1,3 +1,11 @@
+2002-08-08  Neil Jerram  <neil@ossau.uklinux.net>
+
+	* data-rep.texi, scheme-memory.texi, scheme-modules.texi: Merge
+	recent updates from stable branch.
+
+	* posix.texi (File System, Time, Pipes, Network Databases,
+	Internet Socket Examples): Add examples provided by Ian Sheldon.
+
 2002-08-08  Marius Vollmer  <marius.vollmer@uni-dortmund.de>
 
 	* scheme-binding.texi: Don't talk about 'bound?' which is gone.

doc/ref/data-rep.texi

@@ -46,7 +46,7 @@
 @c essay @sp 10
 @c essay @comment The title is printed in a large font.
 @c essay @title Data Representation in Guile
-@c essay @subtitle $Id: data-rep.texi,v 1.7 2002-03-29 20:25:23 ossau Exp $
+@c essay @subtitle $Id: data-rep.texi,v 1.8 2002-08-08 21:47:53 ossau Exp $
 @c essay @subtitle For use with Guile @value{VERSION}
 @c essay @author Jim Blandy
 @c essay @author Free Software Foundation
@@ -961,7 +961,7 @@ Return the name of the subr @var{x}.  The result is undefined if
 @var{x} is not a subr.
 @end deftypefn
 
-@deftypefun SCM scm_make_gsubr (char *@var{name}, int @var{req}, int @var{opt}, int @var{rest}, SCM (*@var{function})())
+@deftypefun SCM scm_c_define_gsubr (char *@var{name}, int @var{req}, int @var{opt}, int @var{rest}, SCM (*@var{function})())
 Create a new subr object named @var{name}, based on the C function
 @var{function}, make it visible to Scheme the value of as a global
 variable named @var{name}, and return the subr object.
@@ -986,8 +986,8 @@ combinations of required, optional, and rest arguments.  For example, a
 subr can take one required argument, or one required and one optional
 argument, but a subr can't take one required and two optional arguments.
 It's bizarre, but that's the way the interpreter was written.  If the
-arguments to @code{scm_make_gsubr} do not fit one of the predefined
-patterns, then @code{scm_make_gsubr} will return a compiled closure
+arguments to @code{scm_c_define_gsubr} do not fit one of the predefined
+patterns, then @code{scm_c_define_gsubr} will return a compiled closure
 object instead of a subr object.
 @end deftypefun
 
@@ -1048,22 +1048,23 @@ represented and used at the C level.
 
 In fact, there are two basic C data types to represent objects in Guile:
 
-@itemize @bullet
-@item
+@deftp {Data type} SCM
 @code{SCM} is the user level abstract C type that is used to represent
 all of Guile's Scheme objects, no matter what the Scheme object type is.
 No C operation except assignment is guaranteed to work with variables of
 type @code{SCM}, so you should only use macros and functions to work
 with @code{SCM} values.  Values are converted between C data types and
 the @code{SCM} type with utility functions and macros.
+@end deftp
+@cindex SCM data type
 
-@item
+@deftp {Data type} scm_t_bits
 @code{scm_t_bits} is an integral data type that is guaranteed to be
 large enough to hold all information that is required to represent any
 Scheme object.  While this data type is mostly used to implement Guile's
 internals, the use of this type is also necessary to write certain kinds
 of extensions to Guile.
-@end itemize
+@end deftp
 
 @menu
 * Relationship between SCM and scm_t_bits::

doc/ref/posix.texi

@@ -735,6 +735,17 @@ Close the directory stream @var{stream}.
 The return value is unspecified.
 @end deffn
 
+Here is an example showing how to display all the entries in a
+directory:
+
+@lisp
+(define dir (opendir "/usr/lib"))
+(do ((entry (readdir dir) (readdir dir)))
+    ((eof-object? entry))
+  (display entry)(newline))
+(closedir dir)
+@end lisp
+
 @deffn {Scheme Procedure} sync
 @deffnx {C Function} scm_sync ()
 Flush the operating system disk buffers.
@@ -791,6 +802,11 @@ Return the base name of the file name @var{filename}. The
 base name is the file name without any directory components.
 If @var{suffix} is provided, and is equal to the end of
 @var{basename}, it is removed also.
+
+@lisp
+(basename "/tmp/test.xml" ".xml")
+@result{} "test"
+@end lisp
 @end deffn
 
 
@@ -1021,6 +1037,11 @@ specifications introduced by a @code{%} character.  The formatting of
 month and day names is dependent on the current locale.  The value returned
 is the formatted string.
 @xref{Formatting Date and Time, , , libc, The GNU C Library Reference Manual}.)
+
+@lisp
+(strftime "%c" (localtime (current-time)))
+@result{} "Mon Mar 11 20:17:43 2002"
+@end lisp
 @end deffn
 
 @deffn {Scheme Procedure} strptime format string
@@ -1663,6 +1684,14 @@ be the value of @code{OPEN_READ} or @code{OPEN_WRITE}.
 
 @deffn {Scheme Procedure} open-input-pipe command
 Equivalent to @code{open-pipe} with mode @code{OPEN_READ}.
+
+@lisp
+(read-line (open-input-pipe "date"))
+@result{} "Mon Mar 11 20:10:44 GMT 2002"
+
+(waitpid WAIT_ANY)
+@result{} (24160 . 0)
+@end lisp
 @end deffn
 
 @deffn {Scheme Procedure} open-output-pipe command
@@ -1686,6 +1715,7 @@ close a pipe, but doesn't return the status.
 * Network Address Conversion::
 * Network Databases::
 * Network Sockets and Communication::
+* Internet Socket Examples::
 @end menu
 
 @node Network Address Conversion
@@ -1827,6 +1857,14 @@ found, an error will be thrown to one of the keys:
 @code{no-data}, corresponding to the equivalent @code{h_error} values.
 Unusual conditions may result in errors thrown to the
 @code{system-error} or @code{misc_error} keys.
+
+@lisp
+(gethost "www.gnu.org")
+@result{} #("www.gnu.org" () 2 4 (3353880842))
+
+(gethostbyname "www.emacs.org")
+@result{} #("emacs.org" ("www.emacs.org") 2 4 (1073448978))
+@end lisp
 @end deffn
 
 The following procedures may be used to step through the host
@@ -2000,6 +2038,14 @@ database does not match this name, a system error is signalled.
 The @code{getserv} procedure will take either a service name or number
 as its first argument; if given no arguments, it behaves like
 @code{getservent} (see below).
+
+@lisp
+(getserv "imap" "tcp")
+@result{} #("imap2" ("imap") 143 "tcp")
+
+(getservbyport 88 "udp")
+@result{} #("kerberos" ("kerberos5" "krb5") 88 "udp")
+@end lisp
 @end deffn
 
 The following procedures may be used to step through the service
@@ -2390,6 +2436,74 @@ These procedures are inconvenient to use at present, but consider:
       (ntohl (uniform-vector-ref v 0)))))
 @end example
 
+
+@node Internet Socket Examples
+@subsection Network Socket Examples
+
+The following sections give examples of how to use network sockets.
+
+@menu
+* Internet Socket Client::
+* Internet Socket Server::
+@end menu
+
+
+@node Internet Socket Client
+@subsubsection Internet Socket Client Example
+
+@cindex socket client example
+The following example demonstrates an Internet socket client.
+It connects to the HTTP daemon running on the local machine and
+returns the contents of the root index URL.
+
+@example
+(let ((s (socket AF_INET SOCK_STREAM 0)))
+  (connect s AF_INET (inet-aton "127.0.0.1") 80)
+  (display "GET / HTTP/1.0\r\n\r\n" s)
+
+  (do ((line (read-line s) (read-line s)))
+      ((eof-object? line))
+    (display line)
+    (newline)))
+@end example
+
+
+@node Internet Socket Server
+@subsubsection Internet Socket Server Example
+
+@cindex socket server example
+The following example shows a simple Internet server which listens on
+port 2904 for incoming connections and sends a greeting back to the
+client.
+
+@example
+(let ((s (socket AF_INET SOCK_STREAM 0)))
+  (setsockopt s SOL_SOCKET SO_REUSEADDR 1)
+  ;; Specific address?
+  ;; (bind s AF_INET (inet-aton "127.0.0.1") 2904)
+  (bind s AF_INET INADDR_ANY 2904)
+  (listen s 5)
+
+  (simple-format #t "Listening for clients in pid: ~S" (getpid))
+  (newline)
+
+  (while #t
+         (let* ((client-connection (accept s))
+                (client-details (cdr client-connection))
+                (client (car client-connection)))
+           (simple-format #t "Got new client connection: ~S"
+                          client-details)
+           (newline)
+           (simple-format #t "Client address: ~S"
+                          (gethostbyaddr
+                           (sockaddr:addr client-details)))
+           (newline)
+           ;; Send back the greeting to the client port
+           (display "Hello client\r\n" client)
+           (close client))))
+@end example
+
+
 @node System Identification
 @section System Identification
 

doc/ref/scheme-memory.texi

@@ -32,7 +32,7 @@ you must follow so that the garbage collector can do its job.
 @deffnx {C Function} scm_gc ()
 Scans all of SCM objects and reclaims for further use those that are
 no longer accessible.  You normally don't need to call this function
-explicitely.  It is called automatically when appropriate.
+explicitly.  It is called automatically when appropriate.
 @end deffn
 
 @deffn {Scheme Procedure} gc-stats

doc/ref/scheme-modules.texi

@@ -552,69 +552,60 @@ When using the low level procedures to do your dynamic linking, you have
 complete control over which library is loaded when and what gets done
 with it.
 
-@deffn {Scheme Procedure} dynamic-link filename
-@deffnx {C Function} scm_dynamic_link (filename)
-Find the shared object (shared library) denoted by
-@var{filename} and link it into the running Guile
-application.  The returned
-scheme object is a ``handle'' for the library which can
-be passed to @code{dynamic-func}, @code{dynamic-call} etc.
+@deffn {Scheme Procedure} dynamic-link library
+@deffnx {C Function} scm_dynamic_link (library)
+Find the shared library denoted by @var{library} (a string) and link it
+into the running Guile application.  When everything works out, return a
+Scheme object suitable for representing the linked object file.
+Otherwise an error is thrown.  How object files are searched is system
+dependent.
 
-Searching for object files is system dependent.  Normally,
-if @var{filename} does have an explicit directory it will
-be searched for in locations
-such as @file{/usr/lib} and @file{/usr/local/lib}.
+Normally, @var{library} is just the name of some shared library file
+that will be searched for in the places where shared libraries usually
+reside, such as in @file{/usr/lib} and @file{/usr/local/lib}.
 @end deffn
 
 @deffn {Scheme Procedure} dynamic-object? obj
 @deffnx {C Function} scm_dynamic_object_p (obj)
-Return @code{#t} if @var{obj} is a dynamic object handle,
-or @code{#f} otherwise.
+Return @code{#t} if @var{obj} is a dynamic library handle, or @code{#f}
+otherwise.
 @end deffn
 
 @deffn {Scheme Procedure} dynamic-unlink dobj
 @deffnx {C Function} scm_dynamic_unlink (dobj)
-Unlink a dynamic object from the application, if possible.  The
-object must have been linked by @code{dynamic-link}, with 
-@var{dobj} the corresponding handle.  After this procedure
-is called, the handle can no longer be used to access the
-object.
+Unlink the indicated object file from the application.  The
+argument @var{dobj} must have been obtained by a call to
+@code{dynamic-link}.  After @code{dynamic-unlink} has been
+called on @var{dobj}, its content is no longer accessible.
 @end deffn
 
 @deffn {Scheme Procedure} dynamic-func name dobj
 @deffnx {C Function} scm_dynamic_func (name, dobj)
-Return a ``handle'' for the function @var{name} in the
-shared object referred to by @var{dobj}.  The handle
-can be passed to @code{dynamic-call} to actually
-call the function.
+Search the dynamic object @var{dobj} for the C function
+indicated by the string @var{name} and return some Scheme
+handle that can later be used with @code{dynamic-call} to
+actually call the function.
 
-Regardless whether your C compiler prepends an underscore
-@samp{_} to the global names in a program, you should
-@strong{not} include this underscore in @var{name}
-since it will be added automatically when necessary.
+Regardless whether your C compiler prepends an underscore @samp{_} to
+the global names in a program, you should @strong{not} include this
+underscore in @var{function}.  Guile knows whether the underscore is
+needed or not and will add it when necessary.
 @end deffn
 
 @deffn {Scheme Procedure} dynamic-call func dobj
 @deffnx {C Function} scm_dynamic_call (func, dobj)
-Call a C function in a dynamic object.  Two styles of
-invocation are supported:
-
-@itemize @bullet
-@item @var{func} can be a function handle returned by
-@code{dynamic-func}.  In this case @var{dobj} is
-ignored
-@item @var{func} can be a string with the name of the
-function to call, with @var{dobj} the handle of the
-dynamic object in which to find the function.
-This is equivalent to
+Call the C function indicated by @var{func} and @var{dobj}.
+The function is passed no arguments and its return value is
+ignored.  When @var{function} is something returned by
+@code{dynamic-func}, call that function and ignore @var{dobj}.
+When @var{func} is a string , look it up in @var{dynobj}; this
+is equivalent to
 @smallexample
-
 (dynamic-call (dynamic-func @var{func} @var{dobj}) #f)
 @end smallexample
-@end itemize
 
-In either case, the function is passed no arguments
-and its return value is ignored.
+Interrupts are deferred while the C function is executing (with
+@code{SCM_DEFER_INTS}/@code{SCM_ALLOW_INTS}).
 @end deffn
 
 @deffn {Scheme Procedure} dynamic-args-call func dobj args
@@ -634,7 +625,10 @@ converted to a Scheme number and returned from the call to
 @code{dynamic-args-call}.
 @end deffn
 
-Here is a small example that may work on GNU/Linux:
+When dynamic linking is disabled or not supported on your system,
+the above functions throw errors, but they are still available.
+
+Here is a small example that works on GNU/Linux:
 
 @smallexample
 (define libc-obj (dynamic-link "libc.so"))