Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
p5pRT opened this issue Nov 1, 2014 · 5 comments
Closed

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

p5pRT opened this issue Nov 1, 2014 · 5 comments

Comments

@p5pRT
Copy link

p5pRT commented Nov 1, 2014

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

Searchable as RT123096$

@p5pRT
Copy link
Author

p5pRT commented Nov 1, 2014

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
Copy link
Author

p5pRT commented Nov 1, 2014

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
Copy link
Author

p5pRT commented Nov 3, 2014

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
Copy link
Author

p5pRT commented Nov 3, 2014

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

@p5pRT
Copy link
Author

p5pRT commented Nov 3, 2014

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant