From 0cb68aa767f2457c65b8cbc4d27c29545da80744 Mon Sep 17 00:00:00 2001
From: dkf <donal.k.fellows@manchester.ac.uk>
Date: Fri, 28 May 2004 12:23:50 +0000
Subject: Added example

---
 doc/fblocked.n | 38 ++++++++++++++++++++++++++++++++++++--
 doc/pwd.n      | 16 +++++++++++++++-
 2 files changed, 51 insertions(+), 3 deletions(-)

diff --git a/doc/fblocked.n b/doc/fblocked.n
index 7f8fe54..0132a7b 100644
--- a/doc/fblocked.n
+++ b/doc/fblocked.n
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-'\" RCS: @(#) $Id: fblocked.n,v 1.4 2001/09/14 19:20:40 andreas_kupries Exp $
+'\" RCS: @(#) $Id: fblocked.n,v 1.5 2004/05/28 12:23:50 dkf Exp $
 .so man.macros
 .TH fblocked n 7.5 Tcl "Tcl Built-In Commands"
 .BS
@@ -31,9 +31,43 @@ Tcl standard channel (\fBstdin\fR, \fBstdout\fR, or \fBstderr\fR),
 the return value from an invocation of \fBopen\fR or \fBsocket\fR, or
 the result of a channel creation command provided by a Tcl extension.
 .VE
+.SH EXAMPLE
+The \fBfblocked\fR command is particularly useful when writing network
+servers, as it allows you to write your code in a line-by-line style
+without preventing the servicing of other connections.  This can be
+seen in this simple echo-service:
+
+.CS
+# This is called whenever a new client connects to the server
+proc connect {chan host port} {
+    set clientName [format <%s:%d> $host $port]
+    puts "connection from $clientName"
+    fconfigure $chan -blocking 0 -buffering line
+    fileevent $chan readable [list echoLine $chan $clientName]
+}
+
+# This is called whenever either at least one byte of input
+# data is available, or the channel was closed by the client.
+proc echoLine {chan clientName} {
+    gets $chan line
+    if {[eof $chan]} {
+        puts "finishing connection from $clientName"
+        close $chan
+    } elseif {![\fBfblocked\fR $chan]} {
+        # Didn't block waiting for end-of-line
+        puts "$clientName - $line"
+        puts $chan $line
+    }
+}
+
+# Create the server socket and enter the event-loop to wait
+# for incoming connections...
+socket -server connect 12345
+vwait forever
+.CE
 
 .SH "SEE ALSO"
-gets(n), open(n), read(n), Tcl_StandardChannels(3)
+gets(n), open(n), read(n), socket(n), Tcl_StandardChannels(3)
 
 .SH KEYWORDS
 blocking, nonblocking
diff --git a/doc/pwd.n b/doc/pwd.n
index 22ec376..ac86847 100644
--- a/doc/pwd.n
+++ b/doc/pwd.n
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: pwd.n,v 1.3 2000/09/07 14:27:50 poenitz Exp $
+'\" RCS: @(#) $Id: pwd.n,v 1.4 2004/05/28 12:30:04 dkf Exp $
 '\" 
 .so man.macros
 .TH pwd n "" Tcl "Tcl Built-In Commands"
@@ -20,6 +20,20 @@ pwd \- Return the current working directory
 .SH DESCRIPTION
 .PP
 Returns the path name of the current working directory.
+.SH EXAMPLE
+Sometimes it is useful to change to a known directory when running
+some external command using \fBexec\fR, but it is important to keep
+the application usually running in the directory that it was started
+in (unless the user specifies otherwise) since that minimises user
+confusion. The way to do this is to save the current directory while
+the external command is being run:
+.CS
+set tarFile [file normalize somefile.tar]
+set savedDir [\fBpwd\fR]
+cd /tmp
+exec tar -xf $tarFile
+cd $savedDir
+.CE
 
 .SH "SEE ALSO"
 file(n), cd(n), glob(n), filename(n)
-- 
cgit v0.12