[PATCH] posix.texi: added additional examples

[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

-@node Conventions
+@node 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

-@node Ports and File Descriptors
+@node 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

-@node File System
+@node 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:
+@example
+(define dir (opendir "/usr/lib"))
+(do ((entry (readdir dir) (readdir dir)))
+    ((eof-object? entry))
+  (display entry)(newline))
+(closedir dir)
+@end 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.
+
+@lisp
+(basename "/tmp/test.xml" ".xml")
+@result{}"test"
+@end lisp
  @end deffn


-@node User Information
+@node 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


-@node Time
+@node 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}.)
+
+@lisp
+(strftime "%c" (localtime (current-time)))
+@result{}"Mon Mar 11 20:17:43 2002"
+@end lisp
  @end deffn

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

-@node Runtime Environment
+@node Runtime Environment, Processes, Time, POSIX
  @section Runtime Environment

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


-@node Processes
+@node Processes, Signals, Runtime Environment, POSIX
  @section Processes

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


-@node Signals
+@node Signals, Terminals and Ptys, Processes, POSIX
  @section Signals

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


-@node Terminals and Ptys
+@node 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

-@node Pipes
+@node 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}.
+
+@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 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

-@node Networking
+@node 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

-@node Network Address Conversion
+@node 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


-@node Network Databases
+@node 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.
+
+@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
@@ -1874,6 +1910,14 @@
  @code{getservent} (see below).
  @end deffn

+@lisp
+(getserv "imap" "tcp")
+@result{}#("imap2" ("imap") 143 "tcp")
+(getservbyport 88 "udp")
+@result{}#("kerberos" ("kerberos5" "krb5") 88 "udp")
+@end 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

-@node Network Sockets and Communication
+@node 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

-@node System Identification
+@node Internet Socket Examples,  , Network Sockets and Communication, 
Networking
+@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, Internet Socket Server, Internet Socket 
Examples, Internet Socket Examples
+@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,  , Internet Socket Client, Internet 
Socket Examples
+@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, 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

-@node Locales
+@node 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

-@node Encryption
+@node Encryption,  , Locales, POSIX
  @section Encryption

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


_______________________________________________
Bug-guile mailing list
Bug-guile@gnu.org
http://mail.gnu.org/mailman/listinfo/bug-guile

Re: [PATCH] posix.texi: added additional examples

[Neil Jerram]

>>>>> "Ian" == Ian Sheldon <is+guile@kaidea.freeserve.co.uk> writes:

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

Thanks!  I'd love to commit this, but there are two problems.

1. The patch contains a lot of spurious diffs in @node lines:
   presumably your environment likes to make node lines completely
   explicit, whereas the CVS source doesn't do this.  Could you
   possibly make a new diff without these changes?

2. After removing the spurious diffs, the patch may still be
   significant enough that we would need paperwork (copyright
   assignment) from you.  Do you already have any agreements in place
   with the FSF that would cover this work?

Thanks again,

        Neil


_______________________________________________
Bug-guile mailing list
Bug-guile@gnu.org
http://mail.gnu.org/mailman/listinfo/bug-guile

Re: [PATCH] posix.texi: added additional examples

[Ian Sheldon]

No problems.  Here's the patch without the extra @node updates.

I haven't signed any papers with the FSF so if the patch is considered 
too big to incorporate without signing copyright papers then I'd be 
happy to.

* 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	Mon Mar 18 22:41:52 2002
@@ -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:
+@example
+(define dir (opendir "/usr/lib"))
+(do ((entry (readdir dir) (readdir dir)))
+    ((eof-object? entry))
+  (display entry)(newline))
+(closedir dir)
+@end example
+
  @end deffn

  @deffn primitive sync
@@ -753,6 +763,11 @@
  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


@@ -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}.)
+
+@lisp
+(strftime "%c" (localtime (current-time)))
+@result{}"Mon Mar 11 20:17:43 2002"
+@end lisp
  @end deffn

  @deffn primitive strptime format string
@@ -1549,6 +1569,13 @@

  @deffn 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 procedure open-output-pipe command
@@ -1572,6 +1599,7 @@
  * Network Address Conversion::
  * Network Databases::
  * Network Sockets and Communication::
+* Internet Socket Examples::
  @end menu

  @node Network Address Conversion
@@ -1705,6 +1733,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.
+
+@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
@@ -1874,6 +1909,14 @@
  @code{getservent} (see below).
  @end deffn

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

@@ -2241,6 +2284,68 @@
        (uniform-vector-read! v port)
        (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




_______________________________________________
Bug-guile mailing list
Bug-guile@gnu.org
http://mail.gnu.org/mailman/listinfo/bug-guile

Re: [PATCH] posix.texi: added additional examples

[Neil Jerram]

>>>>> "Ian" == Ian Sheldon <is+guile@kaidea.freeserve.co.uk> writes:

    Ian> No problems.  Here's the patch without the extra @node
    Ian> updates.
Many thanks.

    Ian> I haven't signed any papers with the FSF so if the patch is considered
    Ian> too big to incorporate without signing copyright papers then I'd be
    Ian> happy to.

I don't know.  It's not huge, but it is rather longer than the `about
10 lines' guideline that I've heard mentioned before.

Marius, can you advise?

        Neil


_______________________________________________
Bug-guile mailing list
Bug-guile@gnu.org
http://mail.gnu.org/mailman/listinfo/bug-guile

Re: [PATCH] posix.texi: added additional examples

[Rob Browning]

Neil Jerram <neil@ossau.uklinux.net> writes:

> I don't know.  It's not huge, but it is rather longer than the `about
> 10 lines' guideline that I've heard mentioned before.
>
> Marius, can you advise?

Ian, if you think you're going to want to work on guile more, and you
don't mind, the easiest thing would be for you to get paperwork on
record for your guile related work at the FSF.  Then you can just send
patches whenever you feel like it.  If you're interested, just mail
fsf-records@gnu.org and they can set you up.

Thanks a lot for your efforts.

-- 
Rob Browning
rlb @defaultvalue.org, @linuxdevel.com, and @debian.org
Previously @cs.utexas.edu
GPG=1C58 8B2C FB5E 3F64 EA5C  64AE 78FE E5FE F0CB A0AD

_______________________________________________
Bug-guile mailing list
Bug-guile@gnu.org
http://mail.gnu.org/mailman/listinfo/bug-guile

Re: [PATCH] posix.texi: added additional examples

[Marius Vollmer]

Neil Jerram <neil@ossau.uklinux.net> writes:

> I don't know.  It's not huge, but it is rather longer than the `about
> 10 lines' guideline that I've heard mentioned before.
> 
> Marius, can you advise?

Hmm, well, I'm no expert on this but here are some thoughts (with a
conclusion., even :).

The FSF requires copyright assignments to guard against the case that
someone contributes something that he is not allowed to contribute,
and we might be forced to remove the contributions again.

So I tend to see this as a risk assessment, more or less.  How high is
the risk that the contribution will be revoked?  How much damage will
it cause?

In this case, the risk is very low, and the damage is very small.  So,
in my view, it is OK to include the patch without 'the papers'.

However, it can't hurt to ask the contributor anyway (like Rob did).

_______________________________________________
Bug-guile mailing list
Bug-guile@gnu.org
http://mail.gnu.org/mailman/listinfo/bug-guile