Skip Menu |
Report information
Id: 132422
Status: open
Priority: 0/
Queue: perl5

Owner: Nobody
Requestors: capoeirab [at] cpan.org
Cc:
AdminCc:

Operating System: (no value)
PatchStatus: HasPatch
Severity: low
Type: library
Perl Version: 5.27.6
Fixed In: (no value)

Attachments
0001-Update-the-documentation-for-IO-Socket-to-be-a-bit-m.patch



CC: capoeirab [...] cpan.org
Subject: [PATCH] IO::Socket Documentation
Date: Thu, 9 Nov 2017 23:42:14 -0500 (EST)
From: cwhitener [...] gmail.com
To: perlbug [...] perl.org
Download (untitled) / with headers
text/plain 4.4k
This is a bug report for perl from capoeirab@cpan.org, generated with the help of perlbug 1.40 running under perl 5.27.6. ----------------------------------------------------------------- [Please describe your issue here] The documentation for IO::Socket hasn't been updated in quite some time. This patch goes through modernizing the documentation and providing many more examples. Next up will be IO::Socket::INET and IO::Socket::UNIX. Once all of the documentation has been updated, hopefully the updates will make their way back to the CPAN releases for the IO:: dist. [Please do not change anything below this line] ----------------------------------------------------------------- --- Flags: category=library severity=low Type=Patch PatchStatus=HasPatch module=IO::Socket --- Site configuration information for perl 5.27.6: Configured by cwhitener at Thu Nov 9 22:04:00 EST 2017. Summary of my perl5 (revision 5 version 27 subversion 6) configuration: Derived from: 29d69c3c41c7e93f884256b1087face64d5fdd1e Platform: osname=linux osvers=4.10.0-19-generic archname=x86_64-linux uname='linux lappy 4.10.0-19-generic #21-ubuntu smp thu apr 6 17:04:57 utc 2017 x86_64 x86_64 x86_64 gnulinux ' config_args='-des -Dusedevel' hint=recommended useposix=true d_sigaction=define useithreads=undef usemultiplicity=undef use64bitint=define use64bitall=define uselongdouble=undef usemymalloc=n default_inc_excludes_dot=define bincompat5005=undef Compiler: cc='cc' ccflags ='-fwrapv -fno-strict-aliasing -pipe -fstack-protector-strong -I/usr/local/include -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64' optimize='-O2' cppflags='-fwrapv -fno-strict-aliasing -pipe -fstack-protector-strong -I/usr/local/include' ccversion='' gccversion='7.2.0' gccosandvers='' intsize=4 longsize=8 ptrsize=8 doublesize=8 byteorder=12345678 doublekind=3 d_longlong=define longlongsize=8 d_longdbl=define longdblsize=16 longdblkind=3 ivtype='long' ivsize=8 nvtype='double' nvsize=8 Off_t='off_t' lseeksize=8 alignbytes=8 prototype=define Linker and Libraries: ld='cc' ldflags =' -fstack-protector-strong -L/usr/local/lib' libpth=/usr/local/lib /usr/lib/gcc/x86_64-linux-gnu/7/include-fixed /usr/include/x86_64-linux-gnu /usr/lib /lib/x86_64-linux-gnu /lib/../lib /usr/lib/x86_64-linux-gnu /usr/lib/../lib /lib libs=-lpthread -lnsl -lgdbm -ldb -ldl -lm -lcrypt -lutil -lc -lgdbm_compat perllibs=-lpthread -lnsl -ldl -lm -lcrypt -lutil -lc libc=libc-2.26.so so=so useshrplib=false libperl=libperl.a gnulibc_version='2.26' Dynamic Linking: dlsrc=dl_dlopen.xs dlext=so d_dlsymun=undef ccdlflags='-Wl,-E' cccdlflags='-fPIC' lddlflags='-shared -O2 -L/usr/local/lib -fstack-protector-strong' Locally applied patches: uncommitted-changes --- @INC for perl 5.27.6: lib /home/cwhitener/.perlbrew/libs/perl-5.26.1@normal/lib/perl5/x86_64-linux /home/cwhitener/.perlbrew/libs/perl-5.26.1@normal/lib/perl5 /usr/local/lib/perl5/site_perl/5.27.6/x86_64-linux /usr/local/lib/perl5/site_perl/5.27.6 /usr/local/lib/perl5/5.27.6/x86_64-linux /usr/local/lib/perl5/5.27.6 --- Environment for perl 5.27.6: HOME=/home/cwhitener LANG=en_US.UTF-8 LANGUAGE (unset) LD_LIBRARY_PATH (unset) LOGDIR (unset) PATH=/home/cwhitener/.perlbrew/libs/perl-5.26.1@normal/bin:/home/cwhitener/perl5/perlbrew/bin:/home/cwhitener/perl5/perlbrew/perls/perl-5.26.1/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin PERL5LIB=/home/cwhitener/.perlbrew/libs/perl-5.26.1@normal/lib/perl5 PERLBREW_BASHRC_VERSION=0.78 PERLBREW_HOME=/home/cwhitener/.perlbrew PERLBREW_LIB=normal PERLBREW_MANPATH=/home/cwhitener/.perlbrew/libs/perl-5.26.1@normal/man:/home/cwhitener/perl5/perlbrew/perls/perl-5.26.1/man PERLBREW_PATH=/home/cwhitener/.perlbrew/libs/perl-5.26.1@normal/bin:/home/cwhitener/perl5/perlbrew/bin:/home/cwhitener/perl5/perlbrew/perls/perl-5.26.1/bin PERLBREW_PERL=perl-5.26.1 PERLBREW_ROOT=/home/cwhitener/perl5/perlbrew PERLBREW_VERSION=0.78 PERL_BADLANG (unset) PERL_LOCAL_LIB_ROOT=/home/cwhitener/.perlbrew/libs/perl-5.26.1@normal PERL_MB_OPT=--install_base /home/cwhitener/.perlbrew/libs/perl-5.26.1@normal PERL_MM_OPT=INSTALL_BASE=/home/cwhitener/.perlbrew/libs/perl-5.26.1@normal SHELL=/bin/bash

Message body is not shown because sender requested not to inline it.

RT-Send-CC: perl5-porters [...] perl.org
Download (untitled) / with headers
text/plain 8.4k
On Fri, 10 Nov 2017 04:42:30 GMT, capoeirab@cpan.org wrote: Show quoted text
> This is a bug report for perl from capoeirab@cpan.org, > generated with the help of perlbug 1.40 running under perl 5.27.6. > > > ----------------------------------------------------------------- > [Please describe your issue here] > > The documentation for IO::Socket hasn't been updated in quite some > time. > This patch goes through modernizing the documentation and providing > many > more examples. Next up will be IO::Socket::INET and IO::Socket::UNIX. > > Once all of the documentation has been updated, hopefully the updates > will make their way back to the CPAN releases for the IO:: dist. > >
Thank you for taking the time to review the IO::Socket documentation and submit a patch. Because there are quite a lot of revisions in your patch, you should expect a certain amount of back-and-forth with respect to further revisions before this is applied to blead. I am not an expert on sockets, so I'm not going to attempt to review the entire patch here. I hope that other readers will contribute constructive comments. I will, however, comment on your revisions to the SYNOPSIS. Granted, the current synopsis is insufficient. However, we generally follow a style in which the synopsis focuses on terse descriptions of the most important methods or functions which a module provides. More detailed information on particular methods, including more fully fleshed-out examples should be deferred to the sections on those methods or, perhaps, to an EXAMPLES section later in the documentation. More specifically: =head1 SYNOPSIS - use IO::Socket; We don't need any of the next four lines in SYNOPSIS. + #!/usr/bin/env perl + use strict; + use warnings; + use feature 'say'; + + use IO::Socket qw(AF_INET AF_UNIX SOCK_STREAM SHUT_WR); + + # create a new AF_INET socket We don't need the 'my' in SYNOPSIS. + my $sock = IO::Socket->new(Domain => AF_INET); The next two lines should go in discussion of new(). + # which is the same as + $sock = IO::Socket::INET->new(); + + # create a new AF_UNIX socket + $sock = IO::Socket->new(Domain => AF_UNIX); Same as above. + # which is the same as + $sock = IO::Socket::UNIX->new(); + The balance of the revisions should be moved to an EXAMPLES section (once the code is verified). + # Let's create a TCP server on localhost:3333 + my $server = IO::Socket->new( + Domain => AF_INET, + Type => SOCK_STREAM, + Proto => 'tcp', + LocalHost => '0.0.0.0', + LocalPort => 3333, + ReusePort => 1, + Listen => 5, + ) || die "Can't open socket: $@"; + say "Waiting on 3333"; + + while (1) { + # waiting for a new client connection + my $client = $server->accept(); + + # get information about a newly connected client + my $client_address = $client->peerhost(); + my $client_port = $client->peerport(); + say "Connection from $client_address:$client_port"; + + # read up to 1024 characters from the connected client + my $data = ""; + $client->recv($data, 1024); + say "received data: $data"; + + # write response data to the connected client + $data = "ok"; + $client->send($data); + + # notify client that response has been sent + $client->shutdown(SHUT_WR); + } + + $server->close(); + + + # A client for such a server could be + my $client = IO::Socket->new( + Domain => AF_INET, + Type => SOCK_STREAM, + proto => 'tcp', + PeerPort => 3333, + PeerHost => '0.0.0.0', + ) || die "Can't open socket: $@"; + + say "Sending Hello World!"; + my $size = $client->send("Hello World!"); + say "Sent data of length: $size"; + + $client->shutdown(SHUT_WR); + + my $buffer; + $client->recv($buffer, 1024); + say "Got back $buffer"; + + $client->close(); The only IO::Socket methods you used in these examples apart from new() were accept() and close(). Are they used often enough -- not just in creation of servers -- to warrant their being placed in the SYNOPSIS? Are there any other IO::Socket methods whose importance warrants their being mentioned in the SYNOPSIS? Show quoted text
> [Please do not change anything below this line] > ----------------------------------------------------------------- > --- > Flags: > category=library > severity=low > Type=Patch > PatchStatus=HasPatch > module=IO::Socket > --- > Site configuration information for perl 5.27.6: > > Configured by cwhitener at Thu Nov 9 22:04:00 EST 2017. > > Summary of my perl5 (revision 5 version 27 subversion 6) > configuration: > Derived from: 29d69c3c41c7e93f884256b1087face64d5fdd1e > Platform: > osname=linux > osvers=4.10.0-19-generic > archname=x86_64-linux > uname='linux lappy 4.10.0-19-generic #21-ubuntu smp thu apr 6 > 17:04:57 utc 2017 x86_64 x86_64 x86_64 gnulinux ' > config_args='-des -Dusedevel' > hint=recommended > useposix=true > d_sigaction=define > useithreads=undef > usemultiplicity=undef > use64bitint=define > use64bitall=define > uselongdouble=undef > usemymalloc=n > default_inc_excludes_dot=define > bincompat5005=undef > Compiler: > cc='cc' > ccflags ='-fwrapv -fno-strict-aliasing -pipe -fstack-protector- > strong -I/usr/local/include -D_LARGEFILE_SOURCE > -D_FILE_OFFSET_BITS=64' > optimize='-O2' > cppflags='-fwrapv -fno-strict-aliasing -pipe -fstack-protector- > strong -I/usr/local/include' > ccversion='' > gccversion='7.2.0' > gccosandvers='' > intsize=4 > longsize=8 > ptrsize=8 > doublesize=8 > byteorder=12345678 > doublekind=3 > d_longlong=define > longlongsize=8 > d_longdbl=define > longdblsize=16 > longdblkind=3 > ivtype='long' > ivsize=8 > nvtype='double' > nvsize=8 > Off_t='off_t' > lseeksize=8 > alignbytes=8 > prototype=define > Linker and Libraries: > ld='cc' > ldflags =' -fstack-protector-strong -L/usr/local/lib' > libpth=/usr/local/lib /usr/lib/gcc/x86_64-linux-gnu/7/include- > fixed /usr/include/x86_64-linux-gnu /usr/lib /lib/x86_64-linux-gnu > /lib/../lib /usr/lib/x86_64-linux-gnu /usr/lib/../lib /lib > libs=-lpthread -lnsl -lgdbm -ldb -ldl -lm -lcrypt -lutil -lc > -lgdbm_compat > perllibs=-lpthread -lnsl -ldl -lm -lcrypt -lutil -lc > libc=libc-2.26.so > so=so > useshrplib=false > libperl=libperl.a > gnulibc_version='2.26' > Dynamic Linking: > dlsrc=dl_dlopen.xs > dlext=so > d_dlsymun=undef > ccdlflags='-Wl,-E' > cccdlflags='-fPIC' > lddlflags='-shared -O2 -L/usr/local/lib -fstack-protector-strong' > > Locally applied patches: > uncommitted-changes > > --- > @INC for perl 5.27.6: > lib > /home/cwhitener/.perlbrew/libs/perl- > 5.26.1@normal/lib/perl5/x86_64-linux > /home/cwhitener/.perlbrew/libs/perl-5.26.1@normal/lib/perl5 > /usr/local/lib/perl5/site_perl/5.27.6/x86_64-linux > /usr/local/lib/perl5/site_perl/5.27.6 > /usr/local/lib/perl5/5.27.6/x86_64-linux > /usr/local/lib/perl5/5.27.6 > > --- > Environment for perl 5.27.6: > HOME=/home/cwhitener > LANG=en_US.UTF-8 > LANGUAGE (unset) > LD_LIBRARY_PATH (unset) > LOGDIR (unset) > PATH=/home/cwhitener/.perlbrew/libs/perl- > 5.26.1@normal/bin:/home/cwhitener/perl5/perlbrew/bin:/home/cwhitener/perl5/perlbrew/perls/perl- > 5.26.1/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin > PERL5LIB=/home/cwhitener/.perlbrew/libs/perl- > 5.26.1@normal/lib/perl5 > PERLBREW_BASHRC_VERSION=0.78 > PERLBREW_HOME=/home/cwhitener/.perlbrew > PERLBREW_LIB=normal > PERLBREW_MANPATH=/home/cwhitener/.perlbrew/libs/perl- > 5.26.1@normal/man:/home/cwhitener/perl5/perlbrew/perls/perl-5.26.1/man > PERLBREW_PATH=/home/cwhitener/.perlbrew/libs/perl- > 5.26.1@normal/bin:/home/cwhitener/perl5/perlbrew/bin:/home/cwhitener/perl5/perlbrew/perls/perl- > 5.26.1/bin > PERLBREW_PERL=perl-5.26.1 > PERLBREW_ROOT=/home/cwhitener/perl5/perlbrew > PERLBREW_VERSION=0.78 > PERL_BADLANG (unset) > PERL_LOCAL_LIB_ROOT=/home/cwhitener/.perlbrew/libs/perl- > 5.26.1@normal > PERL_MB_OPT=--install_base /home/cwhitener/.perlbrew/libs/perl- > 5.26.1@normal > PERL_MM_OPT=INSTALL_BASE=/home/cwhitener/.perlbrew/libs/perl- > 5.26.1@normal > SHELL=/bin/bash
Thank you very much. -- James E Keenan (jkeenan@cpan.org)


This service is sponsored and maintained by Best Practical Solutions and runs on Perl.org infrastructure.

For issues related to this RT instance (aka "perlbug"), please contact perlbug-admin at perl.org