[Patch] Improve IO::Socket::connected() documentation

[p5pRT]

Migrated from rt.perl.org#123096 (status was 'resolved')

Searchable as RT123096$

[p5pRT]

From gdg@zplane.com

Created by gdg@zplane.com

Attached doc patch for IO​::Socket​::connected() is the eventual disposition of
this thread​:

  http​://www.nntp.perl.org/group/perl.perl5.porters/2014/08/msg218522.html

It is essentially identical to the suggested wording posted here​:

  http​://www.nntp.perl.org/group/perl.perl5.porters/2014/10/msg221699.html

the only differences being some minor wordsmithing.

Perl Info

Flags:
    category=library
    severity=low
    Type=Patch
    PatchStatus=HasPatch
    module=IO::Socket

Site configuration information for perl 5.21.6:

Configured by gdg at Fri Oct 31 18:22:39 MDT 2014.

Summary of my perl5 (revision 5 version 21 subversion 6) configuration:
  Local Commit: 1b346f7bfbfcf3107b3b89c8208bf0bf00ac0840
  Ancestor: df8d57333de0f29a6161f8306687739b123fc1f1
  Platform:
    osname=linux, osvers=3.16.4-1-arch, archname=i686-linux-thread-multi
    uname='linux huh 3.16.4-1-arch #1 smp preempt mon oct 6 08:23:49 cest 2014 i686 gnulinux '
    config_args='-des -Dusedevel -Uversiononly -Dusethreads -DDEBUGGING -Dman1dir=none -Dman3dir=none -Dprefix=/tmp/blead-v5.21.5-124-g1b346f7'
    hint=recommended, useposix=true, d_sigaction=define
    useithreads=define, usemultiplicity=define
    use64bitint=undef, use64bitall=undef, uselongdouble=undef
    usemymalloc=n, bincompat5005=undef
  Compiler:
    cc='cc', ccflags ='-D_REENTRANT -D_GNU_SOURCE -fwrapv -DDEBUGGING -fno-strict-aliasing -pipe -fstack-protector-strong -I/usr/local/include -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64 -D_FORTIFY_SOURCE=2',
    optimize='-O2 -g',
    cppflags='-D_REENTRANT -D_GNU_SOURCE -fwrapv -DDEBUGGING -fno-strict-aliasing -pipe -fstack-protector-strong -I/usr/local/include'
    ccversion='', gccversion='4.9.1 20140903 (prerelease)', gccosandvers=''
    intsize=4, longsize=4, ptrsize=4, doublesize=8, byteorder=1234
    d_longlong=define, longlongsize=8, d_longdbl=define, longdblsize=12, longdblkind=3
    ivtype='long', ivsize=4, nvtype='double', nvsize=8, Off_t='off_t', lseeksize=8
    alignbytes=4, prototype=define
  Linker and Libraries:
    ld='cc', ldflags =' -fstack-protector-strong -L/usr/local/lib'
    libpth=/usr/local/lib /usr/lib/gcc/i686-pc-linux-gnu/4.9.1/include-fixed /usr/lib /lib
    libs=-lnsl -lgdbm -ldb -ldl -lm -lcrypt -lutil -lpthread -lc -lgdbm_compat
    perllibs=-lnsl -ldl -lm -lcrypt -lutil -lpthread -lc
    libc=libc-2.20.so, so=so, useshrplib=false, libperl=libperl.a
    gnulibc_version='2.20'
  Dynamic Linking:
    dlsrc=dl_dlopen.xs, dlext=so, d_dlsymun=undef, ccdlflags='-Wl,-E'
    cccdlflags='-fPIC', lddlflags='-shared -O2 -g -L/usr/local/lib -fstack-protector-strong'

Locally applied patches:
    1b346f7bfbfcf3107b3b89c8208bf0bf00ac0840


@INC for perl 5.21.6:
    lib
    /home/gdg/locperl/lib/perl5/i686-linux-thread-multi
    /home/gdg/locperl/lib/perl5
    /home/gdg/lib/perllib
    /tmp/blead-v5.21.5-124-g1b346f7/lib/perl5/site_perl/5.21.6/i686-linux-thread-multi
    /tmp/blead-v5.21.5-124-g1b346f7/lib/perl5/site_perl/5.21.6
    /tmp/blead-v5.21.5-124-g1b346f7/lib/perl5/5.21.6/i686-linux-thread-multi
    /tmp/blead-v5.21.5-124-g1b346f7/lib/perl5/5.21.6
    .


Environment for perl 5.21.6:
    HOME=/home/gdg
    LANG=en_US.UTF-8
    LANGUAGE (unset)
    LC_ALL=en_US
    LD_LIBRARY_PATH (unset)
    LOGDIR (unset)
    PATH=/home/gdg/bin:/usr/local/bin:/usr/bin:.:/usr/bin/core_perl:/usr/bin/vendor_perl:/opt/bin32-jre/jre/bin
    PERL5LIB=/home/gdg/locperl/lib/perl5:/home/gdg/lib/perllib
    PERL_BADLANG (unset)
    SHELL=/bin/bash

[p5pRT]

From gdg@zplane.com

0001-Improve-connected-doc.patch

From 1b346f7bfbfcf3107b3b89c8208bf0bf00ac0840 Mon Sep 17 00:00:00 2001
From: "Glenn D. Golden" <gdg@zplane.com>
Date: Tue, 28 Oct 2014 04:24:04 -0600
Subject: [PATCH] Improve connected() doc

---
 dist/IO/lib/IO/Socket.pm | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)

diff --git a/dist/IO/lib/IO/Socket.pm b/dist/IO/lib/IO/Socket.pm
index 625c71a..c98ea0b 100644
--- a/dist/IO/lib/IO/Socket.pm
+++ b/dist/IO/lib/IO/Socket.pm
@@ -499,8 +499,23 @@ C<use> declaration will fail at compile time.
 
 =item connected
 
-If the socket is in a connected state the peer address is returned.
-If the socket is not in a connected state then undef will be returned.
+If the socket is in a connected state, the peer address is returned. If the
+socket is not in a connected state, undef is returned.
+
+Note that connected() considers a half-open TCP socket to be "in a connected
+state".  Specifically, connected() does not distinguish between the
+B<ESTABLISHED> and B<CLOSE-WAIT> TCP states; it returns the peer address,
+rather than undef, in either case.  Thus, in general, connected() cannot
+be used to reliably learn whether the peer has initiated a graceful shutdown
+because in most cases (see below) the local TCP state machine remains in
+B<CLOSE-WAIT> until the local application calls shutdown() or close();
+only at that point does connected() return undef.
+
+The "in most cases" hedge is because local TCP state machine behavior may
+depend on the peer's socket options. In particular, if the peer socket has
+SO_LINGER enabled with a zero timeout, then the peer's close() will generate
+a RST segment, upon receipt of which the local TCP transitions immediately to
+B<CLOSED>, and in that state, connected() I<will> return undef.
 
 =item protocol
 
-- 
2.1.3

[p5pRT]

From @tonycoz

On Sat Nov 01 10​:20​:26 2014, gdg@​zplane.com wrote​:

Attached doc patch for IO​::Socket​::connected() is the eventual
disposition of
this thread​:

http​://www.nntp.perl.org/group/perl.perl5.porters/2014/08/msg218522.html

It is essentially identical to the suggested wording posted here​:

http​://www.nntp.perl.org/group/perl.perl5.porters/2014/10/msg221699.html

the only differences being some minor wordsmithing.

Thanks, applied as 7eb3f2c.

Tony

[p5pRT]

The RT System itself - Status changed from 'new' to 'open'

[p5pRT]

@tonycoz - Status changed from 'open' to 'resolved'