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

Possible fcntl doc glitch #15024

Closed
p5pRT opened this issue Nov 3, 2015 · 12 comments
Closed

Possible fcntl doc glitch #15024

p5pRT opened this issue Nov 3, 2015 · 12 comments

Comments

@p5pRT
Copy link

p5pRT commented Nov 3, 2015

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

Searchable as RT126544$

@p5pRT
Copy link
Author

p5pRT commented Nov 3, 2015

From @jimav

This is a bug report for perl from jim.avera@​gmail.com,
generated with the help of perlbug 1.40 running under perl 5.20.2.


perlfunc for fcntl starts with the following example​:

  use Fcntl;
  fcntl($filehandle, F_GETFL, $packed_return_buffer) or die...;

What is "$packed_return_buffer" ? It is not explained, and I suspect
it is bogus. A subsequent example is

  $flags = fcntl(REMOTE, F_GETFL, 0) or die...;

which passes zero for the third argument.



Flags​:
  category=core
  severity=low


Site configuration information for perl 5.20.2​:

Configured by Debian Project at Tue Mar 3 11​:42​:20 UTC 2015.

Summary of my perl5 (revision 5 version 20 subversion 2) configuration​:
 
  Platform​:
  osname=linux, osvers=3.2.0-58-generic, archname=x86_64-linux-gnu-thread-multi
  uname='linux kissel 3.2.0-58-generic #88-ubuntu smp tue dec 3 17​:37​:58 utc 2013 x86_64 x86_64 x86_64 gnulinux '
  config_args='-Dusethreads -Duselargefiles -Dccflags=-DDEBIAN -D_FORTIFY_SOURCE=2 -g -O2 -fstack-protector-strong -Wformat -Werror=format-security -Dldflags= -Wl,-Bsymbolic-functions -Wl,-z,relro -Dlddlflags=-shared -Wl,-Bsymbolic-functions -Wl,-z,relro -Dcccdlflags=-fPIC -Darchname=x86_64-linux-gnu -Dprefix=/usr -Dprivlib=/usr/share/perl/5.20 -Darchlib=/usr/lib/x86_64-linux-gnu/perl/5.20 -Dvendorprefix=/usr -Dvendorlib=/usr/share/perl5 -Dvendorarch=/usr/lib/x86_64-linux-gnu/perl5/5.20 -Dsiteprefix=/usr/local -Dsitelib=/usr/local/share/perl/5.20.2 -Dsitearch=/usr/local/lib/x86_64-linux-gnu/perl/5.20.2 -Dman1dir=/usr/share/man/man1 -Dman3dir=/usr/share/man/man3 -Dsiteman1dir=/usr/local/man/man1 -Dsiteman3dir=/usr/local/man/man3 -Duse64bitint -Dman1ext=1 -Dman3ext=3perl -Dpager=/usr/bin/sensible-pager -Uafs -Ud_csh -Ud_ualarm -Uusesfio -Uusenm -Ui_libutil -Uversiononly -DDEBUGGING=-g -Doptimize=-O2 -Duseshrplib -Dlibperl=libperl.so.5.20.2 -des'
  hint=recommended, useposix=true, d_sigaction=define
  useithreads=define, usemultiplicity=define
  use64bitint=define, use64bitall=define, uselongdouble=undef
  usemymalloc=n, bincompat5005=undef
  Compiler​:
  cc='cc', ccflags ='-D_REENTRANT -D_GNU_SOURCE -DDEBIAN -fwrapv -fno-strict-aliasing -pipe -I/usr/local/include -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64',
  optimize='-O2 -g',
  cppflags='-D_REENTRANT -D_GNU_SOURCE -DDEBIAN -fwrapv -fno-strict-aliasing -pipe -I/usr/local/include'
  ccversion='', gccversion='4.9.2', gccosandvers=''
  intsize=4, longsize=8, ptrsize=8, doublesize=8, byteorder=12345678
  d_longlong=define, longlongsize=8, d_longdbl=define, longdblsize=16
  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 -L/usr/local/lib'
  libpth=/usr/local/lib /usr/lib/gcc/x86_64-linux-gnu/4.9/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=-lgdbm -lgdbm_compat -ldb -ldl -lm -lpthread -lc -lcrypt
  perllibs=-ldl -lm -lpthread -lc -lcrypt
  libc=libc-2.19.so, so=so, useshrplib=true, libperl=libperl.so.5.20
  gnulibc_version='2.19'
  Dynamic Linking​:
  dlsrc=dl_dlopen.xs, dlext=so, d_dlsymun=undef, ccdlflags='-Wl,-E'
  cccdlflags='-fPIC', lddlflags='-shared -L/usr/local/lib -fstack-protector'

Locally applied patches​:
  DEBPKG​:debian/cpan_definstalldirs - Provide a sensible INSTALLDIRS default for modules installed from CPAN.
  DEBPKG​:debian/db_file_ver - http​://bugs.debian.org/340047 Remove overly restrictive DB_File version check.
  DEBPKG​:debian/doc_info - Replace generic man(1) instructions with Debian-specific information.
  DEBPKG​:debian/enc2xs_inc - http​://bugs.debian.org/290336 Tweak enc2xs to follow symlinks and ignore missing @​INC directories.
  DEBPKG​:debian/errno_ver - http​://bugs.debian.org/343351 Remove Errno version check due to upgrade problems with long-running processes.
  DEBPKG​:debian/libperl_embed_doc - http​://bugs.debian.org/186778 Note that libperl-dev package is required for embedded linking
  DEBPKG​:fixes/respect_umask - Respect umask during installation
  DEBPKG​:debian/writable_site_dirs - Set umask approproately for site install directories
  DEBPKG​:debian/extutils_set_libperl_path - EU​:MM​: set location of libperl.a under /usr/lib
  DEBPKG​:debian/no_packlist_perllocal - Don't install .packlist or perllocal.pod for perl or vendor
  DEBPKG​:debian/prefix_changes - Fiddle with *PREFIX and variables written to the makefile
  DEBPKG​:debian/fakeroot - Postpone LD_LIBRARY_PATH evaluation to the binary targets.
  DEBPKG​:debian/instmodsh_doc - Debian policy doesn't install .packlist files for core or vendor.
  DEBPKG​:debian/ld_run_path - Remove standard libs from LD_RUN_PATH as per Debian policy.
  DEBPKG​:debian/libnet_config_path - Set location of libnet.cfg to /etc/perl/Net as /usr may not be writable.
  DEBPKG​:debian/mod_paths - Tweak @​INC ordering for Debian
  DEBPKG​:debian/module_build_man_extensions - http​://bugs.debian.org/479460 Adjust Module​::Build manual page extensions for the Debian Perl policy
  DEBPKG​:debian/prune_libs - http​://bugs.debian.org/128355 Prune the list of libraries wanted to what we actually need.
  DEBPKG​:fixes/net_smtp_docs - [rt.cpan.org #36038] http​://bugs.debian.org/100195 Document the Net​::SMTP 'Port' option
  DEBPKG​:debian/perlivp - http​://bugs.debian.org/510895 Make perlivp skip include directories in /usr/local
  DEBPKG​:debian/deprecate-with-apt - http​://bugs.debian.org/747628 Point users to Debian packages of deprecated core modules
  DEBPKG​:debian/squelch-locale-warnings - http​://bugs.debian.org/508764 Squelch locale warnings in Debian package maintainer scripts
  DEBPKG​:debian/skip-upstream-git-tests - Skip tests specific to the upstream Git repository
  DEBPKG​:debian/patchlevel - http​://bugs.debian.org/567489 List packaged patches for 5.20.2-2 in patchlevel.h
  DEBPKG​:debian/skip-kfreebsd-crash - http​://bugs.debian.org/628493 [perl #96272] Skip a crashing test case in t/op/threads.t on GNU/kFreeBSD
  DEBPKG​:fixes/document_makemaker_ccflags - http​://bugs.debian.org/628522 [rt.cpan.org #68613] Document that CCFLAGS should include $Config{ccflags}
  DEBPKG​:debian/find_html2text - http​://bugs.debian.org/640479 Configure CPAN​::Distribution with correct name of html2text
  DEBPKG​:debian/perl5db-x-terminal-emulator.patch - http​://bugs.debian.org/668490 Invoke x-terminal-emulator rather than xterm in perl5db.pl
  DEBPKG​:debian/cpan-missing-site-dirs - http​://bugs.debian.org/688842 Fix CPAN​::FirstTime defaults with nonexisting site dirs if a parent is writable
  DEBPKG​:fixes/memoize_storable_nstore - [rt.cpan.org #77790] http​://bugs.debian.org/587650 Memoize​::Storable​: respect 'nstore' option not respected
  DEBPKG​:debian/regen-skip - Skip a regeneration check in unrelated git repositories
  DEBPKG​:fixes/regcomp-mips-optim - [perl #122817] http​://bugs.debian.org/754054 Downgrade the optimization of regcomp.c on mips and mipsel due to a gcc-4.9 bug
  DEBPKG​:debian/makemaker-pasthru - http​://bugs.debian.org/758471 Pass LD settings through to subdirectories
  DEBPKG​:fixes/perldoc-less-R - [rt.cpan.org #98636] http​://bugs.debian.org/758689 Tell the 'less' pager to allow terminal escape sequences
  DEBPKG​:fixes/pod_man_reproducible_date - http​://bugs.debian.org/759405 Support POD_MAN_DATE in Pod​::Man for the left-hand footer
  DEBPKG​:fixes/io_uncompress_gunzip_inmemory - http​://bugs.debian.org/747363 [rt.cpan.org #95494] Fix gunzip to in-memory file handle
  DEBPKG​:fixes/socket_test_recv_fix - http​://bugs.debian.org/758718 [perl #122657] Compare recv return value to peername in socket test
  DEBPKG​:fixes/hurd_socket_recv_todo - http​://bugs.debian.org/758718 [perl #122657] TODO checking the result of recv() on hurd
  DEBPKG​:fixes/regexp-performance - [0fa70a0] http​://bugs.debian.org/777556 [perl #123743] simpify and speed up /.*.../ handling


@​INC for perl 5.20.2​:
  /home/jima/lib/perl
  /home/jima/perl5/lib/perl5/x86_64-linux-gnu-thread-multi
  /home/jima/perl5/lib/perl5/x86_64-linux-gnu-thread-multi
  /home/jima/perl5/lib/perl5
  /etc/perl
  /usr/local/lib/x86_64-linux-gnu/perl/5.20.2
  /usr/local/share/perl/5.20.2
  /usr/lib/x86_64-linux-gnu/perl5/5.20
  /usr/share/perl5
  /usr/lib/x86_64-linux-gnu/perl/5.20
  /usr/share/perl/5.20
  /usr/local/lib/site_perl
  .


Environment for perl 5.20.2​:
  HOME=/home/jima
  LANG=en_US.UTF-8
  LANGUAGE=en_US
  LD_LIBRARY_PATH=/home/jima/local/lib
  LOGDIR (unset)
  PATH=/home/jima/perl5/bin​:/home/jima/bin​:/home/jima/local/bin​:/home/jima/jima_tools/x86_64/bin​:/home/jima/jima_tools/bin​:/opt/Adobe/Reader9/bin​:/usr/bin​:/bin​:/usr/sbin​:/sbin​:/usr/bin/X11​:/usr/local/sbin​:/usr/games​:/usr/local/games​:/usr/lib/jvm/java-7-oracle/bin​:/usr/lib/jvm/java-7-oracle/db/bin​:/usr/lib/jvm/java-7-oracle/jre/bin​:.
  PERL5LIB=/home/jima/lib/perl​:/home/jima/perl5/lib/perl5/x86_64-linux-gnu-thread-multi​:/home/jima/perl5/lib/perl5
  PERL_BADLANG (unset)
  PERL_LOCAL_LIB_ROOT=/home/jima/perl5
  PERL_MB_OPT=--install_base /home/jima/perl5
  PERL_MM_OPT=INSTALL_BASE=/home/jima/perl5
  SHELL=/bin/bash

@p5pRT
Copy link
Author

p5pRT commented Nov 3, 2015

From @mauke

Am 03.11.2015 um 03​:43 schrieb (via RT)​:

# New Ticket Created by
# Please include the string​: [perl #126544]
# in the subject line of all future correspondence about this issue.
# <URL​: https://rt-archive.perl.org/perl5/Ticket/Display.html?id=126544 >

This is a bug report for perl from jim.avera@​gmail.com,
generated with the help of perlbug 1.40 running under perl 5.20.2.

-----------------------------------------------------------------
perlfunc for fcntl starts with the following example​:

 use Fcntl;
 fcntl\($filehandle\, F\_GETFL\, $packed\_return\_buffer\) or die\.\.\.;

What is "$packed_return_buffer" ? It is not explained, and I suspect
it is bogus. A subsequent example is

  $flags = fcntl\(REMOTE\, F\_GETFL\, 0\) or die\.\.\.;

which passes zero for the third argument.

No, perldoc -f fcntl starts with​:

| Implements the fcntl(2) function. You'll probably have to say
|
| use Fcntl;
|
| first to get the correct constant definitions.

Following that (and immediately preceding your code) it says​:

| Argument processing and value returned work just like ioctl below. For
example​:

and indeed perldoc -f ioctl explains the semantics of the SCALAR argument.

--
Lukas Mai <plokinom@​gmail.com>

@p5pRT
Copy link
Author

p5pRT commented Nov 3, 2015

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

@p5pRT
Copy link
Author

p5pRT commented Nov 3, 2015

From @jkeenan

On Tue Nov 03 12​:23​:47 2015, plokinom@​gmail.com wrote​:

Am 03.11.2015 um 03​:43 schrieb (via RT)​:

# New Ticket Created by
# Please include the string​: [perl #126544]
# in the subject line of all future correspondence about this issue.
# <URL​: https://rt-archive.perl.org/perl5/Ticket/Display.html?id=126544 >

This is a bug report for perl from jim.avera@​gmail.com,
generated with the help of perlbug 1.40 running under perl 5.20.2.

-----------------------------------------------------------------
perlfunc for fcntl starts with the following example​:

 use Fcntl;
 fcntl\($filehandle\, F\_GETFL\, $packed\_return\_buffer\) or die\.\.\.;

What is "$packed_return_buffer" ? It is not explained, and I suspect
it is bogus. A subsequent example is

  $flags = fcntl\(REMOTE\, F\_GETFL\, 0\) or die\.\.\.;

which passes zero for the third argument.

No, perldoc -f fcntl starts with​:

| Implements the fcntl(2) function. You'll probably have to say
|
| use Fcntl;
|
| first to get the correct constant definitions.

Following that (and immediately preceding your code) it says​:

| Argument processing and value returned work just like ioctl below. For
example​:

and indeed perldoc -f ioctl explains the semantics of the SCALAR argument.

I do think that Jim Avera, the OP, has a point. I rarely say​:

#####
perldoc perlfunc
#####

Much more often I say

#####
perldoc -f <some_function>
#####

... and in the latter case the fact that I am actually paging through pod/perlfunc.pod is not self-evident.

If I *am* paging through pod/perlfunc.pod, then the phrase "just like C<ioctl> below" is, strictly speaking, true. That's because the section on 'fcntl' starts at line 2218 of pod/perlfunc.pod (blead), whereas the section on 'ioctl' starts at line 3087.

But that's the exception. If I'm only saying 'perldoc -f fcntl' I have no reliable way of knowing where "below" is.

Can anyone suggest wording that avoids this problem?

Thank you very much.
Jim Keenan

--
James E Keenan (jkeenan@​cpan.org)

@p5pRT
Copy link
Author

p5pRT commented Nov 4, 2015

From @jimav

I still don't understand why the first example in the fcntl POD is, or can be, correct​:

fcntl($filehandle, F_GETFL, $packed_return_buffer) or die...;

The ioctl pod does not explain it. It merely says that the
treatment of the SCALAR (3rd arg) "depends on the FUNCTION", and that at the C level
either a pointer to a string or an integer will be passed. Since the underlying
C fcntl function completely ignores the 3rd argument for F_GETFL, I don't see how
"$packed_return_buffer" can contain anything useful for F_GETFL either as input or output.

The later example in the fcntl POD is

$flags = fcntl(REMOTE, F_GETFL, 0) or die...;

and it *does* seem to work​:
  $ perl -MFcntl -we 'printf "%#x\n",fcntl(STDIN,F_GETFL,0),"\n"'
  0x8002 # this value is correct, what the same code in C returns

Here's what happens using the ioctl-ish example​:
  $ perl -MFcntl -we 'my $buf=0; fcntl(STDIN,F_GETFL,$buf); printf("%#x\n",$buf)';
  0

  $ perl -MData​::Dumper -MFcntl -we 'my $buf=""; fcntl(STDIN,F_GETFL,$buf); print "buf=", Dumper($buf);'
buf=$VAR1 = '<garbage non-ASCII characters>';

@p5pRT
Copy link
Author

p5pRT commented Nov 9, 2015

From @tonycoz

On Mon Nov 02 18​:43​:26 2015, jim.avera@​gmail.com wrote​:

perlfunc for fcntl starts with the following example​:

use Fcntl;
fcntl($filehandle, F_GETFL, $packed_return_buffer) or die...;

What is "$packed_return_buffer" ? It is not explained, and I suspect
it is bogus. A subsequent example is

$flags = fcntl(REMOTE, F_GETFL, 0) or die...;

which passes zero for the third argument.

Yes, the example is bogus, since F_GETFL ignores the third argument.

There are three cases that matter​:

- fcntl(2) ignores the third argument (F_GETFL)

- fcntl(2) accepts an integer (F_SETFL)

- fcntl(2) accepts a pointer to a structure (F_SETLK)

but none of the examples demonstrate that third case, and the "struct flock" type is kind of under-specified[1] to use for a portable example.

Maybe an example specifying it's Linux specific.

Tony

[1] POSIX only specifies that the flock structure has certain members and doesn't specify their order - it's different between NetBSD and Linux.

@p5pRT
Copy link
Author

p5pRT commented Nov 10, 2015

From @wolfsage

On Sun, Nov 8, 2015 at 11​:33 PM, Tony Cook via RT
<perlbug-followup@​perl.org> wrote​:

Yes, the example is bogus, since F_GETFL ignores the third argument.

Hrm, I think IPC​::Cmd is broken then?

  # prepare sockets to read from child

  $flags = 0;
  fcntl($child_stdout_socket, POSIX​::F_GETFL, $flags) ||
Carp​::confess "can't fnctl F_GETFL​: $!";
  $flags |= POSIX​::O_NONBLOCK;
  fcntl($child_stdout_socket, POSIX​::F_SETFL, $flags) ||
Carp​::confess "can't fnctl F_SETFL​: $!";

  $flags = 0;
  fcntl($child_stderr_socket, POSIX​::F_GETFL, $flags) ||
Carp​::confess "can't fnctl F_GETFL​: $!";
  $flags |= POSIX​::O_NONBLOCK;
  fcntl($child_stderr_socket, POSIX​::F_SETFL, $flags) ||
Carp​::confess "can't fnctl F_SETFL​: $!";

  $flags = 0;
  fcntl($child_info_socket, POSIX​::F_GETFL, $flags) ||
Carp​::confess "can't fnctl F_GETFL​: $!";
  $flags |= POSIX​::O_NONBLOCK;
  fcntl($child_info_socket, POSIX​::F_SETFL, $flags) ||
Carp​::confess "can't fnctl F_SETFL​: $!";

-- Matthew Horsfall (alh)

@p5pRT
Copy link
Author

p5pRT commented Jan 7, 2016

From @tonycoz

On Tue Nov 10 05​:29​:58 2015, alh wrote​:

On Sun, Nov 8, 2015 at 11​:33 PM, Tony Cook via RT
<perlbug-followup@​perl.org> wrote​:

Yes, the example is bogus, since F_GETFL ignores the third argument.

Hrm, I think IPC​::Cmd is broken then?

  \# prepare sockets to read from child

  $flags = 0;
  fcntl\($child\_stdout\_socket\, POSIX&#8203;::F\_GETFL\, $flags\) ||

Carp​::confess "can't fnctl F_GETFL​: $!";
$flags |= POSIX​::O_NONBLOCK;
fcntl($child_stdout_socket, POSIX​::F_SETFL, $flags) ||
Carp​::confess "can't fnctl F_SETFL​: $!";
...

Sorry, I thought I'd replied to this, yes, IPC​::Cmd is broken, but since for a socket/pipe only O_NONBLOCK is likely to be set, it turns out to be harmless.

It should be fixed though.

Tony

@p5pRT
Copy link
Author

p5pRT commented Feb 3, 2016

From @tonycoz

On Wed Jan 06 20​:07​:15 2016, tonyc wrote​:

On Tue Nov 10 05​:29​:58 2015, alh wrote​:

On Sun, Nov 8, 2015 at 11​:33 PM, Tony Cook via RT
<perlbug-followup@​perl.org> wrote​:

Yes, the example is bogus, since F_GETFL ignores the third
argument.

Hrm, I think IPC​::Cmd is broken then?

# prepare sockets to read from child

$flags = 0;
fcntl($child_stdout_socket, POSIX​::F_GETFL, $flags) ||
Carp​::confess "can't fnctl F_GETFL​: $!";
$flags |= POSIX​::O_NONBLOCK;
fcntl($child_stdout_socket, POSIX​::F_SETFL, $flags) ||
Carp​::confess "can't fnctl F_SETFL​: $!";
...

Sorry, I thought I'd replied to this, yes, IPC​::Cmd is broken, but
since for a socket/pipe only O_NONBLOCK is likely to be set, it turns
out to be harmless.

It should be fixed though.

Fixed in d5eedef.

I've created a pull request against IPC​::Cmd at

jib/ipc-cmd#17

Tony

@p5pRT
Copy link
Author

p5pRT commented Feb 3, 2016

@tonycoz - Status changed from 'open' to 'pending release'

@p5pRT
Copy link
Author

p5pRT commented May 13, 2016

From @khwilliamson

Thank you for submitting this report. You have helped make Perl better.
 
With the release of Perl 5.24.0 on May 9, 2016, this and 149 other issues have been resolved.

Perl 5.24.0 may be downloaded via https://metacpan.org/release/RJBS/perl-5.24.0

@p5pRT
Copy link
Author

p5pRT commented May 13, 2016

@khwilliamson - Status changed from 'pending release' to 'resolved'

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

No branches or pull requests

1 participant