summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--doc/ref/ChangeLog8
-rw-r--r--doc/ref/data-rep.texi17
-rw-r--r--doc/ref/posix.texi114
-rw-r--r--doc/ref/scheme-memory.texi2
-rw-r--r--doc/ref/scheme-modules.texi82
5 files changed, 170 insertions, 53 deletions
diff --git a/doc/ref/ChangeLog b/doc/ref/ChangeLog
index 2e25bec97..a2e3a2269 100644
--- a/doc/ref/ChangeLog
+++ b/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.
diff --git a/doc/ref/data-rep.texi b/doc/ref/data-rep.texi
index 30fcee6c6..107c14209 100644
--- a/doc/ref/data-rep.texi
+++ b/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::
diff --git a/doc/ref/posix.texi b/doc/ref/posix.texi
index 8a9fc280e..f43eb148c 100644
--- a/doc/ref/posix.texi
+++ b/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
diff --git a/doc/ref/scheme-memory.texi b/doc/ref/scheme-memory.texi
index ea3f8bfd1..5f19bcb38 100644
--- a/doc/ref/scheme-memory.texi
+++ b/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
diff --git a/doc/ref/scheme-modules.texi b/doc/ref/scheme-modules.texi
index c9279258c..46c02172d 100644
--- a/doc/ref/scheme-modules.texi
+++ b/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.
-
-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}.
+@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.
+
+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.
-
-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.
+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{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"))