Possible fcntl doc glitch

[p5pRT]

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

Searchable as RT126544$

[p5pRT]

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]

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]

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

[p5pRT]

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]

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]

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]

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]

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​::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]

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]

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

[p5pRT]

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]

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