perl 5.003_02: [no incremental changelog available]

4 files changed, 426 insertions, 16 deletions

diff --git a/pod/Makefile.PL b/pod/Makefile.PL
new file mode 100644
index 0000000000..911bff83e3
--- /dev/null
+++ b/pod/Makefile.PL
@@ -0,0 +1,133 @@
+#!/usr/local/bin/perl
+
+use Config;
+use File::Basename qw(&basename &dirname);
+
+# List explicitly here the variables you want Configure to
+# generate.  Metaconfig only looks for shell variables, so you
+# have to mention them as if they were shell variables, not
+# %Config entries.  Thus you write
+#  $startperl
+# to ensure Configure will look for $Config{startperl}.
+
+# This forces PL files to create target in same directory as PL file.
+# This is so that make depend always knows where to find PL derivatives.
+chdir(dirname($0));
+($file = basename($0)) =~ s/\.PL$//;
+$file =~ s/\.pl$//
+	if ($Config{'osname'} eq 'VMS' or
+	    $Config{'osname'} eq 'OS2');  # "case-forgiving"
+
+open OUT,">$file" or die "Can't create $file: $!";
+
+print "Extracting $file (with variable substitutions)\n";
+
+# In this section, perl variables will be expanded during extraction.
+# You can use $Config{...} to use Configure variables.
+
+print OUT <<"!GROK!THIS!";
+!GROK!THIS!
+
+# In the following, perl variables are not expanded during extraction.
+
+print OUT <<'!NO!SUBS!';
+CONVERTERS = pod2html pod2latex pod2man pod2text
+
+all: $(CONVERTERS) man
+!NO!SUBS!
+
+if (-x '../miniperl') {
+    print OUT "PERL = ..\/miniperl\n\n";
+}
+else {
+    print OUT "PERL = ../miniperl\n\n";
+}
+
+@pods = <*.pod>;
+
+print OUT 'POD = ';
+foreach (@pods) {
+    # Remove .pod suffix.  Each section should add its own suffix.
+    s/\.pod$//;  
+    print OUT "\t\\\n\t$_.pod";
+}
+print OUT "\n\n";
+
+print OUT 'MAN = ';
+foreach (@pods) {
+    print OUT "\t\\\n\t$_.man";
+}
+print OUT "\n\n";
+
+print OUT 'HTML = ';
+foreach (@pods) {
+    print OUT "\t\\\n\t$_.html";
+}
+print OUT "\n\n";
+
+print OUT 'TEX = ';
+foreach (@pods) {
+    s/\.pod/.tex/;
+    print OUT "\t\\\n\t$_.tex";
+}
+print OUT "\n\n";
+
+print OUT <<'!NO!SUBS!';
+man:  pod2man $(MAN)
+
+# pod2html normally runs on all the pods at once in order to build up
+# cross-references.
+html: pod2html
+	$(PERL) -I../lib pod2html $(POD)
+
+tex:	pod2latex $(TEX)
+
+.SUFFIXES: .pm .pod .man
+
+.pm.man:     pod2man
+	$(PERL) -I../lib pod2man $*.pm >$*.man
+
+.pod.man:     pod2man
+	$(PERL) -I../lib pod2man $*.pod >$*.man
+
+.SUFFIXES: .mp .pod .html
+
+.pm.html:    pod2html
+	$(PERL) -I../lib pod2html $*.pod
+
+.pod.html:    pod2html
+	$(PERL) -I../lib pod2html $*.pod
+
+.SUFFIXES: .pm .pod .tex
+
+.pod.tex: pod2latex
+	$(PERL) -I../lib pod2latex $*.pod
+
+.pm.tex: pod2latex
+	$(PERL) -I../lib pod2latex $*.pod
+
+clean:
+	rm -f $(MAN) $(HTML) $(TEX)
+
+realclean:	clean
+	rm -f $(CONVERTERS)
+
+distclean:	realclean
+
+# Dependencies.
+pod2latex:	pod2latex.PL ../lib/Config.pm
+	$(PERL) -I../lib pod2latex.PL
+
+pod2html:	pod2html.PL ../lib/Config.pm
+	$(PERL) -I ../lib pod2html.PL
+
+pod2man:	pod2man.PL ../lib/Config.pm
+	$(PERL) -I ../lib pod2man.PL
+
+pod2text:	pod2text.PL ../lib/Config.pm
+	$(PERL) -I ../lib pod2text.PL
+!NO!SUBS!
+
+close OUT or die "Can't close $file: $!";
+chmod 0644, $file or die "Can't reset permissions for $file: $!\n";
+exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';
diff --git a/pod/perl.pod b/pod/perl.pod
index 725f473d8d..61aa1f4771 100644
--- a/pod/perl.pod
+++ b/pod/perl.pod
@@ -20,6 +20,7 @@ of sections:
 
     perl	Perl overview (this section)
     perltoc	Perl documentation table of contents
+
     perldata	Perl data structures
     perlsyn	Perl syntax
     perlop	Perl operators and precedence
@@ -29,26 +30,31 @@ of sections:
     perlvar	Perl predefined variables
     perlsub	Perl subroutines
     perlmod	Perl modules
+    perlform	Perl formats
+
     perlref	Perl references 
     perldsc	Perl data structures intro
     perllol	Perl data structures: lists of lists
     perlobj	Perl objects
     perltie	Perl objects hidden behind simple variables
     perlbot	Perl OO tricks and examples
+    perlipc	Perl interprocess communication
+
     perldebug	Perl debugging
     perldiag	Perl diagnostic messages
-    perlform	Perl formats
-    perlipc	Perl interprocess communication
     perlsec	Perl security
     perltrap	Perl traps for the unwary
     perlstyle	Perl style guide
+
+    perlpod	Perl plain old documentation
+    perlbook	Perl book information
+
+    perlembed	Perl how to embed perl in your C or C++ app
+    perlapio	Perl internal IO abstraction interface
     perlxs	Perl XS application programming interface
     perlxstut	Perl XS tutorial
     perlguts	Perl internal functions for those doing extensions 
     perlcall	Perl calling conventions from C
-    perlembed	Perl how to embed perl in your C or C++ app
-    perlpod	Perl plain old documentation
-    perlbook	Perl book information
 
 (If you're intending to read these straight through for the first time,
 the suggested order will tend to reduce the number of forward references.)
@@ -59,7 +65,7 @@ Perl, but you'll also find third-party modules there.  You should be able
 to view this with your man(1) program by including the proper directories
 in the appropriate start-up files.  To find out where these are, type:
 
-    perl -le 'use Config; print "@Config{man1dir,man3dir}"'
+    perl -V:man.dir
 
 If the directories were F</usr/local/man/man1> and F</usr/local/man/man3>,
 you would only need to add F</usr/local/man> to your MANPATH.  If 
diff --git a/pod/perlapio.pod b/pod/perlapio.pod
new file mode 100644
index 0000000000..85900f157c
--- /dev/null
+++ b/pod/perlapio.pod
@@ -0,0 +1,274 @@
+=head1 NAME
+
+perlio - perl's IO abstraction interface.
+
+=head1 SYNOPSIS
+
+    PerlIO *PerlIO_stdin(void);
+    PerlIO *PerlIO_stdout(void);
+    PerlIO *PerlIO_stderr(void);
+    
+    PerlIO *PerlIO_open(const char *,const char *);
+    int     PerlIO_close(PerlIO *);
+
+    int     PerlIO_stdoutf(const char *,...)
+    int     PerlIO_puts(PerlIO *,const char *);
+    int     PerlIO_putc(PerlIO *,int);
+    int     PerlIO_write(PerlIO *,const void *,size_t); 
+    int     PerlIO_printf(PerlIO *, const char *,...);
+    int     PerlIO_vprintf(PerlIO *, const char *, va_list); 
+    int     PerlIO_flush(PerlIO *);
+
+    int     PerlIO_eof(PerlIO *);
+    int     PerlIO_error(PerlIO *);
+    void    PerlIO_clearerr(PerlIO *);
+
+    int     PerlIO_getc(PerlIO *);
+    int     PerlIO_ungetc(PerlIO *,int);
+    int     PerlIO_read(PerlIO *,void *,size_t); 
+
+    int     PerlIO_fileno(PerlIO *);
+    PerlIO *PerlIO_fdopen(int, const char *);
+    PerlIO *PerlIO_importFILE(FILE *);
+    FILE   *PerlIO_exportFILE(PerlIO *);
+    FILE   *PerlIO_findFILE(PerlIO *);
+    void    PerlIO_releaseFILE(PerlIO *,FILE *);
+
+    void    PerlIO_setlinebuf(PerlIO *); 
+
+    long    PerlIO_tell(PerlIO *);
+    int     PerlIO_seek(PerlIO *,off_t,int);
+    int     PerlIO_getpos(PerlIO *,Fpos_t *) 
+    int     PerlIO_setpos(PerlIO *,Fpos_t *) 
+    void    PerlIO_rewind(PerlIO *);
+     
+    int     PerlIO_has_base(PerlIO *); 
+    int     PerlIO_has_cntptr(PerlIO *); 
+    int     PerlIO_fast_gets(PerlIO *); 
+    int     PerlIO_canset_cnt(PerlIO *); 
+
+    char   *PerlIO_get_ptr(PerlIO *); 
+    int     PerlIO_get_cnt(PerlIO *); 
+    void    PerlIO_set_cnt(PerlIO *,int); 
+    void    PerlIO_set_ptrcnt(PerlIO *,char *,int); 
+    char   *PerlIO_get_base(PerlIO *); 
+    int     PerlIO_get_bufsiz(PerlIO *); 
+
+=head1 DESCRIPTION
+
+Perl's source code should use the above functions instead of those
+defined in ANSI C's I<stdio.h>,  I<perlio.h> will the C<#define> them to 
+the I/O mechanism selected at Configure time.
+
+The functions are modeled on those in I<stdio.h>, but parameter order
+has been "tidied up a little".
+
+=over 4
+
+=item B<PerlIO *>
+
+This takes the place of FILE *. Unlike FILE * it should be treated as 
+opaque (it is probably safe to assume it is a pointer to something).
+
+=item B<PerlIO_stdin()>, B<PerlIO_stdout()>, B<PerlIO_stderr()>
+
+Use these rather than C<stdin>, C<stdout>, C<stderr>. They are written
+to look like "function calls" rather than variables because this makes
+it easier to I<make them> function calls if platform cannot export data 
+to loaded modules, or if (say) different "threads" might have different 
+values.
+
+=item B<PerlIO_open(path, mode)>, B<PerlIO_fdopen(fd,mode)>
+
+These correspond to fopen()/fdopen() arguments are the same.
+
+=item B<PerlIO_printf(f,fmt,...)>, B<PerlIO_vprintf(f,fmt,a)>
+
+These are is fprintf()/vfprintf equivalents.
+
+=item B<PerlIO_stdoutf(fmt,...)>
+
+This is printf() equivalent. printf is #defined to this function,
+so it is (currently) legal to use printf(fmt,...) in perl sources.
+
+=item B<PerlIO_read(f,buf,count)>, B<PerlIO_write(f,buf,count)>
+
+These correspond to fread() and fwrite(). Note that arguments 
+are different, there is only one "count" and order has
+"file" first.
+
+=item B<PerlIO_close(f)>
+
+=item B<PerlIO_puts(s,f)>, B<PerlIO_putc(c,f)>
+
+These correspond to fputs() and fputc(). 
+Note that arguments have been revised to have "file" first.
+
+=item B<PerlIO_ungetc(c,f)>
+
+This corresponds to ungetc().
+Note that arguments have been revised to have "file" first.
+
+=item B<PerlIO_getc(f)>
+
+This corresponds to getc().
+
+=item B<PerlIO_eof(f)>
+
+This corresponds to feof().
+
+=item B<PerlIO_error(f)>
+
+This corresponds to ferror().
+
+=item B<PerlIO_fileno(f)>
+
+This corresponds to fileno(), note that on some platforms, 
+the meaning of "fileno" may not match UNIX.
+
+=item B<PerlIO_clearerr(f)>
+
+This corresponds to clearerr(), i.e. clears 'eof' and 'error'
+flags for the "stream".
+
+=item B<PerlIO_flush(f)>
+
+This corresponds to fflush().
+
+=item B<PerlIO_tell(f)>
+
+This corresponds to ftell().
+
+=item B<PerlIO_seek(f,o,w)>
+
+This corresponds to fseek().
+
+=item B<PerlIO_getpos(f,p)>, B<PerlIO_setpos(f,p)>
+
+These correspond to fgetpos() and fsetpos(). If platform does not 
+have the stdio calls then they are implemeted in terms of PerlIO_tell()
+and PerlIO_seek().
+
+=item B<PerlIO_rewind(f)>
+
+This corresponds to rewind(). Note may be redefined
+in terms of PerlIO_seek() at some point.
+
+=item B<PerlIO_tmpfile()>
+
+This corresponds to tmpfile(), i.e. returns an anonymous
+PerlIO which will automatically be deleted when closed.
+
+=back 
+
+=head2 Co-existance with stdio
+
+There is outline support for co-existance of PerlIO with stdio.
+Obviously if PerlIO is implemented in terms of stdio there is 
+no problem. However if perlio is implemented on top of (say) sfio
+then mechanisms must exist to create a FILE * which can be passed 
+to library code which is going to use stdio calls.
+
+=over 4
+
+=item B<PerlIO_importFILE(f,flags)>
+
+Used to get a PerlIO * from a FILE *.
+May need additional arguments, interface under review.
+
+=item B<PerlIO_exportFILE(f,flags)>
+
+Given an PerlIO * return a 'native' FILE * suitable for
+passing to code expecting to be compiled and linked with 
+ANSI C I<stdio.h>.
+
+The fact that such a FILE * has been 'exported' is recorded,
+and may affect future PerlIO operations on the original 
+PerlIO *. 
+
+=item B<PerlIO_findFILE(f)>
+
+Returns previously 'exported' FILE * (if any).
+Place holder until interface is fully defined.
+
+=item B<PerlIO_releaseFILE(p,f)>
+
+Calling PerlIO_releaseFILE informs PerlIO that all use
+of FILE * is complete. It is removed from list of 'exported'
+FILE *s, and associated PerlIO * should revert to original 
+behaviour.
+
+=item B<PerlIO_setlinebuf(f)>
+
+This corresponds to setlinebuf(). Use is deprecated pending
+further discussion. (Perl core I<only> uses it when "dumping"
+is has nothing to do with $| auto-flush.)
+
+=back
+
+In addition to user API above there is an "implementation" interface
+which allows perl to get at internals of PerlIO.
+The following calls correspond to the various FILE_xxx macros determined
+by Configure. This section is really only of interest to those
+concerned with detailed perl-core behaviour or implementing a
+PerlIO mapping.
+
+=over 4
+
+=item B<PerlIO_has_cntptr(f)>
+
+Implementation can return pointer to current position in the "buffer" and
+a count of bytes available in the buffer.
+
+=item B<PerlIO_get_ptr(f)>
+
+Return pointer to next readable byte in buffer.
+
+=item B<PerlIO_get_cnt(f)>
+
+Return count of readable bytes in the buffer.
+
+=item B<PerlIO_canset_cnt(f)>
+
+Implementation can adjust its idea of number of 
+bytes in the buffer.
+
+=item B<PerlIO_fast_gets(f)>
+
+Implementation has all the interfaces required to 
+allow perls fast code to handle <FILE> mechanism.
+
+  PerlIO_fast_gets(f) = PerlIO_has_cntptr(f) && \ 
+                        PerlIO_canset_cnt(f) && \
+                        `Can set pointer into buffer'
+
+=item B<PerlIO_set_ptrcnt(f,p,c)>
+
+Set pointer into buffer, and a count of bytes still in the 
+buffer. Should only be used to set
+pointer to within range implied by previous calls
+to C<PerlIO_get_ptr> and C<PerlIO_get_cnt>.
+
+=item B<PerlIO_set_cnt(f,c)>
+
+Obscure - set count of bytes in the buffer. Deprecated.
+Currently only used in doio.c to force count < -1 to -1.
+Perhaps should be PerlIO_set_empty or similar.
+This call may actually do nothing if "count" is deduced from pointer
+and a "limit". 
+
+=item B<PerlIO_has_base(f)>
+
+Implementation has a buffer, and can return pointer
+to whole buffer and its size. Used by perl for B<-T> / B<-B> tests.
+Other uses would be very obscure...
+
+=item B<PerlIO_get_base(f)>
+
+Return I<start> of buffer.
+
+=item B<PerlIO_get_bufsiz(f)>
+
+Return I<total size> of buffer.
+
+=back 
diff --git a/pod/perlobj.pod b/pod/perlobj.pod
index 994edfe00e..acbd5314c8 100644
--- a/pod/perlobj.pod
+++ b/pod/perlobj.pod
@@ -295,11 +295,14 @@ C<can> checks to see if its object has a method called C<METHOD>,
 if it does then a reference to the sub is returned, if it does not then
 I<undef> is returned.
 
-=item require_version ( VERSION )
+=item VERSION ( [ VERSION ] )
+
+C<VERSION> returns the VERSION number of the class (package). If
+an argument is given then it will check that the current version is not 
+less that the given argument. This method is normally called as a static
+method. This method is also called when the C<VERSION> form of C<use> is
+used.
 
-C<require_version> will check that the current version of the package
-is greater than C<VERSION>. This method is normally called as a static method.
-This method is also called when the C<VERSION> form of C<use> is used.
 
     use A 1.2 qw(some imported subs);
     
@@ -322,12 +325,6 @@ class, false if its object is the class (package) itself. Example
     $ref = bless [], 'A';
     $ref->is_instance();    # True
 
-=item require_version ( [ VERSION ] )
-
-C<require_version> returns the VERSION number of the class (package). If
-an argument is given then it will check that the current version is not 
-less that the given argument.
-
 =back
 
 B<NOTE:> C<can> directly uses Perl's internal code for method lookup, and