[perl #77680] [PATCH] document list of special subs in perlsub

# New Ticket Created by  Zsban Ambrus 
# Please include the string:  [perl #77680]
# in the subject line of all future correspondence about this issue. 
# <URL: http://rt.perl.org/rt3/Ticket/Display.html?id=77680 >


This is a bug report for perl from ambrus@math.bme.hu,
generated with the help of perlbug 1.39 running under perl 5.12.1.


-----------------------------------------------------------------
[Please describe your issue here]


The core documentation perlsub.pod already mentions that all-uppercase
sub names such as DESTROY can be called by the runtime system, and
refers to some other documentation for such subs.  This patch tries to
list all such special subs that exist currently, and give a pointer to
their documentation.

Here are the details.  I added CLONE_SKIP which wasn't previously
mentioned here.  I added pointers to where DESTROY and CLONE are
documented.  I listed all the special subs from perltie and PerlIO::via
(except for any I missed).  I mentioned subs reserved for overloading.
Finally, I fixed an oversight in perltie.

You might  want to change the formatting of the list, because I'm not
quite satisfied with it.

The patch is based on the current perl from git.  The patch is
attached and inlined, but the inlined one won't work because the email
client will break long lines.



diff --git a/pod/perlsub.pod b/pod/perlsub.pod
index 325c823..40a1ebc 100644
--- a/pod/perlsub.pod
+++ b/pod/perlsub.pod
@@ -223,10 +223,46 @@ DESCRIPTION
 Subroutines whose names are in all upper case are reserved to the Perl
 core, as are modules whose names are in all lower case.  A subroutine in
 all capitals is a loosely-held convention meaning it will be called
 indirectly by the run-time system itself, usually due to a triggered event.
-Subroutines that do special, pre-defined things include C<AUTOLOAD>, C<CLONE>,
-C<DESTROY> plus all functions mentioned in L<perltie> and L<PerlIO::via>.
+Subroutines whose name start with a left parenthesis are also reserved the
+same way. The following is a list of some subroutines that currently do
+special, pre-defined things.
+
+=over
+
+=item documented later in this document
+
+C<AUTOLOAD>
+
+=item documented in L<perlmod>
+
+C<CLONE>, C<CLONE_SKIP>,
+
+=item documented in L<perlobj>
+
+C<DESTROY>
+
+=item documented in L<perltie>
+
+C<BINMODE>, C<CLEAR>, C<CLOSE>, C<DELETE>, C<DESTROY>, C<EOF>, C<EXISTS>,
+C<EXTEND>, C<FETCH>, C<FETCHSIZE>, C<FILENO>, C<FIRSTKEY>, C<GETC>,
+C<NEXTKEY>, C<OPEN>, C<POP>, C<PRINT>, C<PRINTF>, C<PUSH>, C<READ>,
+C<READLINE>, C<SCALAR>, C<SEEK>, C<SHIFT>, C<SPLICE>, C<STORE>,
+C<STORESIZE>, C<TELL>, C<TIEARRAY>, C<TIEHANDLE>, C<TIEHASH>,
+C<TIESCALAR>, C<UNSHIFT>, C<UNTIE>, C<WRITE>
+
+=item documented in L<PerlIO::via>
+
+C<BINMODE>, C<CLEARERR>, C<CLOSE>, C<EOF>, C<ERROR>, C<FDOPEN>, C<FILENO>,
+C<FILL>, C<FLUSH>, C<OPEN>, C<POPPED>, C<PUSHED>, C<READ>, C<SEEK>,
+C<SETLINEBUF>, C<SYSOPEN>, C<TELL>, C<UNREAD>, C<UTF8>, C<WRITE>
+
+=item undocumented, used internally by the L<overload> feature
+
+any starting with C<(>
+
+=back

 The C<BEGIN>, C<UNITCHECK>, C<CHECK>, C<INIT> and C<END> subroutines
 are not so much subroutines as named special code blocks, of which you
 can have more than one in a package, and which you can B<not> call
diff --git a/pod/perltie.pod b/pod/perltie.pod
index 791753d..d4fd87c 100644
--- a/pod/perltie.pod
+++ b/pod/perltie.pod
@@ -194,9 +194,10 @@
 =head2 Tying Arrays
 X<array, tying>

 A class implementing a tied ordinary array should define the following
-methods: TIEARRAY, FETCH, STORE, FETCHSIZE, STORESIZE and perhaps
UNTIE and/or DESTROY.
+methods: TIEARRAY, FETCH, STORE, FETCHSIZE, STORESIZE, CLEAR
+and perhaps UNTIE and/or DESTROY.

 FETCHSIZE and STORESIZE are used to provide C<$#array> and
 equivalent C<scalar(@array)> access.





[Please do not change anything below this line]
-----------------------------------------------------------------
---
Flags:
    category=docs
    severity=low
---
Site configuration information for perl 5.12.1:

Configured by ambrus at Mon May 24 22:14:58 CEST 2010.

Summary of my perl5 (revision 5 version 12 subversion 1) configuration:

  Platform:
    osname=linux, osvers=2.6.33, archname=x86_64-linux
    uname='linux king 2.6.33 #1 smp sun may 9 18:30:35 cest 2010
x86_64 gnulinux '
    config_args=''
    hint=recommended, useposix=true, d_sigaction=define
    useithreads=undef, usemultiplicity=undef
    useperlio=define, d_sfio=undef, uselargefiles=define, usesocks=undef
    use64bitint=define, use64bitall=define, uselongdouble=undef
    usemymalloc=n, bincompat5005=undef
  Compiler:
    cc='cc', ccflags ='-fno-strict-aliasing -pipe -fstack-protector
-I/usr/local/include -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64',
    optimize='-O2',
    cppflags='-fno-strict-aliasing -pipe -fstack-protector -I/usr/local/include'
    ccversion='', gccversion='4.4.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 /lib /usr/lib /lib64 /usr/lib64 /usr/local/lib64
    libs=-lnsl -ldl -lm -lcrypt -lutil -lc
    perllibs=-lnsl -ldl -lm -lcrypt -lutil -lc
    libc=/lib/libc-2.7.so, so=so, useshrplib=false, libperl=libperl.a
    gnulibc_version='2.7'
  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'

Locally applied patches:


---
@INC for perl 5.12.1:
    /usr/local/lib/perl5/site_perl/5.12.1/x86_64-linux
    /usr/local/lib/perl5/site_perl/5.12.1
    /usr/local/lib/perl5/5.12.1/x86_64-linux
    /usr/local/lib/perl5/5.12.1
    /usr/local/lib/perl5/site_perl/5.12.0/x86_64-linux
    /usr/local/lib/perl5/site_perl/5.12.0
    /usr/local/lib/perl5/site_perl
    .

---
Environment for perl 5.12.1:
    HOME=/home/ambrus
    LANG (unset)
    LANGUAGE (unset)
    LC_CTYPE=hu_HU
    LD_LIBRARY_PATH=/home/ambrus/local/lib/
    LOGDIR (unset)
    PATH=/home/ambrus/local/bin:/usr/local/bin:/usr/bin:/bin:/usr/bin/X11:/usr/games
    PERL_BADLANG (unset)
    SHELL=/usr/local/bin/bash

• [perl #77680] [PATCH] document list of special subs in perlsub by Zsban Ambrus