[SCM] gawk branch, gawk-5.1-stable, updated. gawk-4.1.0-4188-ge4f1018

[Arnold Robbins]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "gawk".

The branch, gawk-5.1-stable has been updated
       via  e4f1018b3b4ff27d109832210a2e5914e62f9bf9 (commit)
      from  b778eb8fb6dce8b94323f796955cb581eb3ad294 (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
http://git.sv.gnu.org/cgit/gawk.git/commit/?id=e4f1018b3b4ff27d109832210a2e5914e62f9bf9

commit e4f1018b3b4ff27d109832210a2e5914e62f9bf9
Author: Arnold D. Robbins <arnold@skeeve.com>
Date:   Sat Dec 26 22:03:21 2020 +0200

    Update datetime client in gawkinet.texi.

diff --git a/awklib/eg/network/daytimeclient.awk 
b/awklib/eg/network/daytimeclient.awk
new file mode 100644
index 0000000..c17000b
--- /dev/null
+++ b/awklib/eg/network/daytimeclient.awk
@@ -0,0 +1,9 @@
+BEGIN {
+  daytime_server     = "time-a-g.nist.gov"
+  daytime_connection = "/inet/tcp/0/" daytime_server "/daytime"
+  daytime_connection |& getline
+  print $0
+  daytime_connection |& getline
+  print $0
+  close(daytime_connection)
+}
diff --git a/doc/ChangeLog b/doc/ChangeLog
index b895545..ee055f3 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,7 @@
+2020-12-26         Juergen Kahrs         <Juergen.Kahrs@googlemail.com>
+
+       * gawkinet.texi: Update datetime client.
+
 2020-12-26         Arnold D. Robbins     <arnold@skeeve.com>
 
        * gawktexi.in (More CSV): Add indexing and reference to
diff --git a/doc/gawkinet.info b/doc/gawkinet.info
index 7172491..16313b6 100644
--- a/doc/gawkinet.info
+++ b/doc/gawkinet.info
@@ -700,22 +700,26 @@ File: gawkinet.info,  Node: TCP Connecting,  Next: 
Troubleshooting,  Prev: Gawk
 
 Let's observe a network connection at work.  Type in the following
 program and watch the output.  Within a second, it connects via TCP
-('/inet/tcp') to the machine it is running on ('localhost') and asks the
-service 'daytime' on the machine what time it is:
+('/inet/tcp') to a remote server and asks the service 'daytime' on the
+machine what time it is:
 
      BEGIN {
-       "/inet/tcp/0/localhost/daytime" |& getline
+       daytime_server     = "time-a-g.nist.gov"
+       daytime_connection = "/inet/tcp/0/" daytime_server "/daytime"
+       daytime_connection |& getline
        print $0
-       close("/inet/tcp/0/localhost/daytime")
+       daytime_connection |& getline
+       print $0
+       close(daytime_connection)
      }
 
-   Even experienced 'awk' users will find the second line strange in two
-respects:
+   Even experienced 'awk' users will find the fourth and sixth line
+strange in two respects:
 
-   * A special file is used as a shell command that pipes its output
-     into 'getline'.  One would rather expect to see the special file
-     being read like any other file ('getline <
-     "/inet/tcp/0/localhost/daytime"').
+   * A string containg the name of a special file is used as a shell
+     command that pipes its output into 'getline'.  One would rather
+     expect to see the special file being read like any other file
+     ('getline < "/inet/tcp/0/time-a-g.nist.gov/daytime"').
 
    * The operator '|&' has not been part of any 'awk' implementation
      (until now).  It is actually the only extension of the 'awk'
@@ -738,12 +742,26 @@ operator except for two additions:
      written to, just like a full-duplex network connection.
 
    In the earlier example, the '|&' operator tells 'getline' to read a
-line from the special file '/inet/tcp/0/localhost/daytime'.  We could
-also have printed a line into the special file.  But instead we just
-read a line with the time, printed it, and closed the connection.
-(While we could just let 'gawk' close the connection by finishing the
-program, in this Info file we are pedantic and always explicitly close
-the connections.)
+line from the special file '/inet/tcp/0/time-a-g.nist.gov/daytime'.  We
+could also have printed a line into the special file.  But instead we
+just consumed an empty leading line, printed it, then read a line with
+the time, printed that, and closed the connection.  (While we could just
+let 'gawk' close the connection by finishing the program, in this Info
+file we are pedantic and always explicitly close the connections.)
+
+   Network services like 'daytime' are not really useful because there
+are so many better ways to print the current time.  In the early days of
+TCP networking, such a service may have looked like a good idea for
+testing purposes.  Later, simple TCP services like these have been used
+to teach TCP/IP networking and therefore you can still find much
+educational material of good quality on the Internet about such outdated
+services.  The list of servers (https://tf.nist.gov/tf-cgi/servers.cgi)
+that still support the legacy service daytime
+(https://en.wikipedia.org/wiki/Daytime_Protocol) can be found at
+Wikipedia.  We hesitated to use this service in this manual because it
+is hard to find servers that still support services like 'daytime'
+openly to the Internet.  Later on we will see that some of these
+nostalgic protocols have turned into security risks.
 
 
 File: gawkinet.info,  Node: Troubleshooting,  Next: Interacting,  Prev: TCP 
Connecting,  Up: Using Networking
@@ -4179,7 +4197,7 @@ Index
 * /inet/ files (gawk):                   Gawk Special Files.  (line  34)
 * /inet/tcp special files (gawk):        File /inet/tcp.      (line   6)
 * /inet/udp special files (gawk):        File /inet/udp.      (line   6)
-* | (vertical bar), |& operator (I/O):   TCP Connecting.      (line  25)
+* | (vertical bar), |& operator (I/O):   TCP Connecting.      (line  29)
 * advanced features, network connections: Troubleshooting.    (line   6)
 * agent:                                 Challenges.          (line  75)
 * agent <1>:                             MOBAGWHO.            (line   6)
@@ -4283,7 +4301,7 @@ Index
 * Perl:                                  Using Networking.    (line  14)
 * Perl, gawk networking and:             Using Networking.    (line  24)
 * Perlis, Alan:                          MAZE.                (line   6)
-* pipes, networking and:                 TCP Connecting.      (line  30)
+* pipes, networking and:                 TCP Connecting.      (line  34)
 * PNG image format:                      Web page.            (line  45)
 * PNG image format <1>:                  STATIST.             (line   6)
 * POP (Post Office Protocol):            Email.               (line   6)
@@ -4342,7 +4360,7 @@ Index
 * UDP (User Datagram Protocol), TCP and: Interacting.         (line  48)
 * Unix, network ports and:               Setting Up.          (line  37)
 * URLCHK program:                        URLCHK.              (line   6)
-* vertical bar (|), |& operator (I/O):   TCP Connecting.      (line  25)
+* vertical bar (|), |& operator (I/O):   TCP Connecting.      (line  29)
 * VRML:                                  MAZE.                (line   6)
 * web pages:                             Web page.            (line   6)
 * web pages, images in:                  Interacting Service. (line 190)
@@ -4381,40 +4399,40 @@ Node: File /inet/tcp26947
 Node: File /inet/udp27933
 Ref: File /inet/udp-Footnote-129645
 Node: TCP Connecting29899
-Node: Troubleshooting32245
-Ref: Troubleshooting-Footnote-135073
-Node: Interacting36030
-Node: Setting Up38754
-Node: Email42726
-Node: Web page45109
-Ref: Web page-Footnote-147929
-Ref: Web page-Footnote-248127
-Node: Primitive Service48621
-Node: Interacting Service51355
-Ref: Interacting Service-Footnote-160510
-Node: CGI Lib60542
-Node: Simple Server67542
-Ref: Simple Server-Footnote-175344
-Node: Caveats75445
-Node: Challenges76588
-Ref: Challenges-Footnote-185330
-Node: Some Applications and Techniques85431
-Node: PANIC87892
-Node: GETURL89618
-Node: REMCONF92251
-Node: URLCHK97747
-Node: WEBGRAB101591
-Node: STATIST106055
-Ref: STATIST-Footnote-1119203
-Node: MAZE119646
-Node: MOBAGWHO125871
-Ref: MOBAGWHO-Footnote-1139773
-Node: STOXPRED139841
-Node: PROTBASE154133
-Ref: PROTBASE-Footnote-1167300
-Node: Links167415
-Node: GNU Free Documentation License170306
-Node: Index195426
+Node: Troubleshooting33332
+Ref: Troubleshooting-Footnote-136160
+Node: Interacting37117
+Node: Setting Up39841
+Node: Email43813
+Node: Web page46196
+Ref: Web page-Footnote-149016
+Ref: Web page-Footnote-249214
+Node: Primitive Service49708
+Node: Interacting Service52442
+Ref: Interacting Service-Footnote-161597
+Node: CGI Lib61629
+Node: Simple Server68629
+Ref: Simple Server-Footnote-176431
+Node: Caveats76532
+Node: Challenges77675
+Ref: Challenges-Footnote-186417
+Node: Some Applications and Techniques86518
+Node: PANIC88979
+Node: GETURL90705
+Node: REMCONF93338
+Node: URLCHK98834
+Node: WEBGRAB102678
+Node: STATIST107142
+Ref: STATIST-Footnote-1120290
+Node: MAZE120733
+Node: MOBAGWHO126958
+Ref: MOBAGWHO-Footnote-1140860
+Node: STOXPRED140928
+Node: PROTBASE155220
+Ref: PROTBASE-Footnote-1168387
+Node: Links168502
+Node: GNU Free Documentation License171393
+Node: Index196513
 
 End Tag Table
 
diff --git a/doc/gawkinet.texi b/doc/gawkinet.texi
index a2454e3..e648283 100644
--- a/doc/gawkinet.texi
+++ b/doc/gawkinet.texi
@@ -234,6 +234,8 @@ Arnold Robbins @*
 Nof Ayalon, ISRAEL @*
 March, 2001
 
+@c system if test ! -d eg         ; then mkdir eg         ; fi
+@c system if test ! -d eg/network ; then mkdir eg/network ; fi
 @node Introduction, Using Networking, Preface, Top
 @chapter Networking Concepts
 
@@ -867,27 +869,33 @@ the original versions of NFS.
 @cindex @command{gawk} @subentry networking @subentry connections
 Let's observe a network connection at work. Type in the following program
 and watch the output. Within a second, it connects via TCP (@file{/inet/tcp})
-to the machine it is running on (@samp{localhost}) and asks the service
+to a remote server and asks the service
 @samp{daytime} on the machine what time it is:
 
 @cindex @code{getline} command
 @example
+@c file eg/network/daytimeclient.awk
 BEGIN @{
-  "/inet/tcp/0/localhost/daytime" |& getline
+  daytime_server     = "time-a-g.nist.gov"
+  daytime_connection = "/inet/tcp/0/" daytime_server "/daytime"
+  daytime_connection |& getline
   print $0
-  close("/inet/tcp/0/localhost/daytime")
+  daytime_connection |& getline
+  print $0
+  close(daytime_connection)
 @}
+@c endfile
 @end example
 
-Even experienced @command{awk} users will find the second line strange in two
-respects:
+Even experienced @command{awk} users will find the fourth and sixth line
+strange in two respects:
 
 @itemize @bullet
 @item
-A special file is used as a shell command that pipes its output
+A string containg the name of a special file is used as a shell command that 
pipes its output
 into @code{getline}. One would rather expect to see the special file
 being read like any other file (@samp{getline <
-"/inet/tcp/0/localhost/daytime"}).
+"/inet/tcp/0/time-a-g.nist.gov/daytime"}).
 
 @item
 @cindex @code{|} (vertical bar), @code{|&} operator (I/O)
@@ -919,13 +927,30 @@ like a full-duplex network connection.
 @end itemize
 
 In the earlier example, the @samp{|&} operator tells @code{getline}
-to read a line from the special file @file{/inet/tcp/0/localhost/daytime}.
+to read a line from the special file 
@file{/inet/tcp/0/time-a-g.nist.gov/daytime}.
 We could also have printed a line into the special file. But instead we just
-read a line with the time, printed it, and closed the connection.
+consumed an empty leading line, printed it, then read a line with the time,
+printed that, and closed the connection.
 (While we could just let @command{gawk} close the connection by finishing
 the program, in this @value{DOCUMENT}
 we are pedantic and always explicitly close the connections.)
 
+Network services like @file{daytime} are not really useful because
+there are so many better ways to print the current time.
+In the early days of TCP networking, such a service may have looked
+like a good idea for testing purposes. Later, simple TCP services
+like these have been used to teach TCP/IP networking and therefore
+you can still find much educational material of good quality on the
+Internet about such outdated services. The
+@uref{https://tf.nist.gov/tf-cgi/servers.cgi, list of servers}
+that still support the legacy service 
+@uref{https://en.wikipedia.org/wiki/Daytime_Protocol, daytime}
+can be found at Wikipedia. We hesitated to use this service in
+this manual because it is hard to find servers that still support
+services like @file{daytime} openly to the Internet.
+Later on we will see that some of these nostalgic
+protocols have turned into security risks.
+
 @node Troubleshooting, Interacting, TCP Connecting, Using Networking
 @section Troubleshooting Connection Problems
 @cindex advanced features, network connections
@@ -1028,8 +1053,6 @@ so-called @command{finger} service if a user of the 
machine is logged in. When
 testing this program, try to change @samp{localhost} to
 some other machine name in your local network:
 
-@c system if test ! -d eg         ; then mkdir eg         ; fi
-@c system if test ! -d eg/network ; then mkdir eg/network ; fi
 @example
 @c file eg/network/fingerclient.awk
 BEGIN @{

-----------------------------------------------------------------------

Summary of changes:
 awklib/eg/network/daytimeclient.awk |   9 +++
 doc/ChangeLog                       |   4 ++
 doc/gawkinet.info                   | 124 +++++++++++++++++++++---------------
 doc/gawkinet.texi                   |  45 +++++++++----
 4 files changed, 118 insertions(+), 64 deletions(-)
 create mode 100644 awklib/eg/network/daytimeclient.awk


hooks/post-receive
-- 
gawk