[PATCH] posix.texi: added additional examples

[Ian Sheldon]

I've added some examples to the doc/ref/posix.texi file from 
guile-core-20020225 to help show the results of some of the procedures. 
 I also did an update nodes/menus.  Hope it is useful.

Ian.


* posix.texi: Added more examples of usage and a sample TCP/IP 
client/server.



--- doc/ref/posix.texi.orig     Sun Mar 10 20:49:59 2002
+++ doc/ref/posix.texi  Tue Mar 12 18:49:27 2002
@@ -16,10 +16,10 @@
 * Networking::                  gethostbyaddr, getnetent, socket, 
bind, listen.
 * System Identification::       Obtaining information about the system.
 * Locales::                     setlocale, etc.
-* Encryption::
+* Encryption::
 @end menu

address@hidden Conventions
address@hidden Conventions, Ports and File Descriptors, POSIX, POSIX
 @section POSIX Interface Conventions

 These interfaces provide access to operating system facilities.
@@ -92,7 +92,7 @@
      (newline))))
 @end example

address@hidden Ports and File Descriptors
address@hidden Ports and File Descriptors, File System, Conventions, POSIX
 @section Ports and File Descriptors

 Conventions generally follow those of scsh, @ref{The Scheme shell (scsh)}.
@@ -490,7 +490,7 @@
 An additional @code{select!} interface is provided.
 @end deffn

address@hidden File System
address@hidden File System, User Information, Ports and File Descriptors, POSIX
 @section File System

 These procedures allow querying and setting file system attributes
@@ -701,6 +701,16 @@
 @deffn primitive closedir port
 Close the directory stream @var{stream}.
 The return value is unspecified.
+
+To display all the entries in a directory:
address@hidden
+(define dir (opendir "/usr/lib"))
+(do ((entry (readdir dir) (readdir dir)))
+    ((eof-object? entry))
+  (display entry)(newline))
+(closedir dir)
address@hidden example
+
 @end deffn

 @deffn primitive sync
@@ -753,10 +763,15 @@
 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.
+
address@hidden
+(basename "/tmp/test.xml" ".xml")
address@hidden"test"
address@hidden lisp
 @end deffn


address@hidden User Information
address@hidden User Information, Time, File System, POSIX
 @section User Information

 The facilities in this section provide an interface to the user and
@@ -884,7 +899,7 @@
 @end deffn


address@hidden Time
address@hidden Time, Runtime Environment, User Information, POSIX
 @section Time

 @deffn primitive current-time
@@ -970,6 +985,11 @@
 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}.)
+
address@hidden
+(strftime "%c" (localtime (current-time)))
address@hidden"Mon Mar 11 20:17:43 2002"
address@hidden lisp
 @end deffn

 @deffn primitive strptime format string
@@ -1025,7 +1045,7 @@
 included but subprocesses are not.
 @end deffn

address@hidden Runtime Environment
address@hidden Runtime Environment, Processes, Time, POSIX
 @section Runtime Environment

 @deffn primitive program-arguments
@@ -1080,7 +1100,7 @@
 @end deffn


address@hidden Processes
address@hidden Processes, Signals, Runtime Environment, POSIX
 @section Processes

 @findex cd
@@ -1353,7 +1373,7 @@
 @end deffn


address@hidden Signals
address@hidden Signals, Terminals and Ptys, Processes, POSIX
 @section Signals

 Procedures to raise, handle and wait for signals.
@@ -1489,7 +1509,7 @@
 @end deffn


address@hidden Terminals and Ptys
address@hidden Terminals and Ptys, Pipes, Signals, POSIX
 @section Terminals and Ptys

 @deffn primitive isatty? port
@@ -1528,7 +1548,7 @@
 controlling terminal.  The return value is unspecified.
 @end deffn

address@hidden Pipes
address@hidden Pipes, Networking, Terminals and Ptys, POSIX
 @section Pipes

 The following procedures provide an interface to the @code{popen} and
@@ -1549,8 +1569,16 @@

 @deffn procedure open-input-pipe command
 Equivalent to @code{open-pipe} with mode @code{OPEN_READ}.
+
address@hidden
+(read-line (open-input-pipe "date"))
address@hidden"Mon Mar 11 20:10:44 GMT 2002"
+(waitpid WAIT_ANY)
address@hidden(24160 . 0)
address@hidden lisp
 @end deffn

+
 @deffn procedure open-output-pipe command
 Equivalent to @code{open-pipe} with mode @code{OPEN_WRITE}.
 @end deffn
@@ -1565,16 +1593,17 @@
 close a pipe, but doesn't return the status.
 @end deffn

address@hidden Networking
address@hidden Networking, System Identification, Pipes, POSIX
 @section Networking

 @menu
-* Network Address Conversion::
-* Network Databases::
-* Network Sockets and Communication::
+* Network Address Conversion::
+* Network Databases::
+* Network Sockets and Communication::
+* Internet Socket Examples::
 @end menu

address@hidden Network Address Conversion
address@hidden Network Address Conversion, Network Databases, Networking, 
Networking
 @subsection Network Address Conversion

 This section describes procedures which convert internet addresses
@@ -1658,7 +1687,7 @@
 @end deffn


address@hidden Network Databases
address@hidden Network Databases, Network Sockets and Communication, Network 
Address Conversion, Networking
 @subsection Network Databases

 This section describes procedures which query various network databases.
@@ -1705,6 +1734,13 @@
 @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.
+
address@hidden
+(gethost "www.gnu.org")
address@hidden("www.gnu.org" () 2 4 (3353880842))
+(gethostbyname "www.emacs.org")
address@hidden("emacs.org" ("www.emacs.org") 2 4 (1073448978))
address@hidden lisp
 @end deffn

 The following procedures may be used to step through the host
@@ -1874,6 +1910,14 @@
 @code{getservent} (see below).
 @end deffn

address@hidden
+(getserv "imap" "tcp")
address@hidden("imap2" ("imap") 143 "tcp")
+(getservbyport 88 "udp")
address@hidden("kerberos" ("kerberos5" "krb5") 88 "udp")
address@hidden lisp
+
+
 The following procedures may be used to step through the service
 database from beginning to end.

@@ -1899,7 +1943,7 @@
 Otherwise it is equivalent to @code{setservent stayopen}.
 @end deffn

address@hidden Network Sockets and Communication
address@hidden Network Sockets and Communication, Internet Socket Examples, 
Network Databases, Networking
 @subsection Network Sockets and Communication

 Socket ports can be created using @code{socket} and @code{socketpair}.
@@ -2242,7 +2286,69 @@
       (ntohl (uniform-vector-ref v 0)))))
 @end example

address@hidden System Identification
address@hidden Internet Socket Examples,  , Network Sockets and Communication, 
Networking
address@hidden Network Socket Examples
+The following sections give examples of how to use network sockets.
+
address@hidden
+* Internet Socket Client::
+* Internet Socket Server::
address@hidden menu
+
address@hidden Internet Socket Client, Internet Socket Server, Internet Socket 
Examples, Internet Socket Examples
address@hidden Internet Socket Client Example
address@hidden 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.
+
address@hidden
+(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)))
address@hidden example
+
address@hidden Internet Socket Server,  , Internet Socket Client, Internet 
Socket Examples
address@hidden Internet Socket Server Example
address@hidden 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.
+
address@hidden
+(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))))
address@hidden example
+
+
+
address@hidden System Identification, Locales, Networking, POSIX
 @section System Identification

 This section lists the various procedures Guile provides for accessing
@@ -2293,7 +2399,7 @@
 no other easy or unambiguous way of detecting such features.
 @end deffn

address@hidden Locales
address@hidden Locales, Encryption, System Identification, POSIX
 @section Locales

 @deffn primitive setlocale category [locale]
@@ -2308,7 +2414,7 @@
 the locale will be set using environment variables.
 @end deffn

address@hidden Encryption
address@hidden Encryption,  , Locales, POSIX
 @section Encryption

 Please note that the procedures in this section are not suited for