This is my patch patch.1h for perl5.001.
Andy Dougherty [Wed, 24 May 1995 22:49:37 +0000 (22:49 +0000)]
To apply, change to your perl directory, run the commands above, then
apply with
    patch -p1 -N  < thispatch.

After you apply this patch, you should apply patch.1i before
reConfiguring and rebuilding.

This patch just includes updates to the ext/ subdirectory.

Here are the highlights:
    Grand autoload patch.

    Embedded pods.

    DB_File and GDBM_File updates.

Patch and enjoy,
Andy Dougherty doughera@lafcol.lafayette.edu
Dept. of Physics
Lafayette College Easton, PA  18042

Here's the file-by-file breakdown of what's included:

ext/DB_File/DB_File.pm
    Updated to version 0.2

    Embedded pod.

ext/DB_File/DB_File.xs
    Updated to version 0.2

ext/DynaLoader/DynaLoader.pm
    Embedded pod.

ext/DynaLoader/README
    Updated to refer to pod documentation in DynaLoader.pm.

ext/Fcntl/Fcntl.pm
    Grand AutoLoader patch.

    Embedded pod.

ext/GDBM_File/GDBM_File.pm
    Grand AutoLoader patch.

    Embedded pod.

ext/GDBM_File/GDBM_File.xs
    Added gdbm_sync(), gdbm_exists(), and gdbm_setopt() functions.

ext/POSIX/POSIX.pm
    Grand AutoLoader patch.

    Embedded pod.

    move tan() into the .xs file.  (It didn't exist before.)

    Change usage message for chmod to reflect reality.

ext/POSIX/POSIX.xs
    move tan() into the .xs file.  (It didn't exist before.)

ext/SDBM_File/sdbm/sdbm.c
    Fix type of free prototype.

ext/Socket/Socket.pm
    Grand AutoLoader patch.

    Embedded pod.

13 files changed:
.dotest/last [new file with mode: 0644]
ext/DB_File/DB_File.pm
ext/DB_File/DB_File.xs
ext/DynaLoader/DynaLoader.doc [deleted file]
ext/DynaLoader/DynaLoader.pm
ext/DynaLoader/README
ext/Fcntl/Fcntl.pm
ext/GDBM_File/GDBM_File.pm
ext/GDBM_File/GDBM_File.xs
ext/POSIX/POSIX.pm
ext/POSIX/POSIX.xs
ext/SDBM_File/sdbm/sdbm.c
ext/Socket/Socket.pm

diff --git a/.dotest/last b/.dotest/last
new file mode 100644 (file)
index 0000000..e69de29
index 1a75f15..5b9fba7 100644 (file)
@@ -1,8 +1,343 @@
 # DB_File.pm -- Perl 5 interface to Berkeley DB 
 #
 # written by Paul Marquess (pmarquess@bfsec.bt.co.uk)
-# last modified 23rd June 1994
-# version 0.1
+# last modified 19th May 1995
+# version 0.2
+
+=head1 NAME
+
+DB_File - Perl5 access to Berkeley DB
+
+=head1 SYNOPSIS
+
+ use DB_File ;
+  
+ [$X =] tie %hash,  DB_File, $filename [, $flags, $mode, $DB_HASH] ;
+ [$X =] tie %hash,  DB_File, $filename, $flags, $mode, $DB_BTREE ;
+ [$X =] tie @array, DB_File, $filename, $flags, $mode, $DB_RECNO ;
+   
+ $status = $X->del($key [, $flags]) ;
+ $status = $X->put($key, $value [, $flags]) ;
+ $status = $X->get($key, $value [, $flags]) ;
+ $status = $X->seq($key, $value [, $flags]) ;
+ $status = $X->sync([$flags]) ;
+ $status = $X->fd ;
+    
+ untie %hash ;
+ untie @array ;
+
+=head1 DESCRIPTION
+
+B<DB_File> is a module which allows Perl programs to make use of 
+the facilities provided by Berkeley DB.  If you intend to use this
+module you should really have a copy of the Berkeley DB manual
+page at hand. The interface defined here
+mirrors the Berkeley DB interface closely.
+
+Berkeley DB is a C library which provides a consistent interface to a number of 
+database formats. 
+B<DB_File> provides an interface to all three of the database types currently
+supported by Berkeley DB.
+
+The file types are:
+
+=over 5
+
+=item DB_HASH
+
+This database type allows arbitrary key/data pairs to be stored in data files.
+This is equivalent to the functionality provided by 
+other hashing packages like DBM, NDBM, ODBM, GDBM, and SDBM.
+Remember though, the files created using DB_HASH are 
+not compatible with any of the other packages mentioned.
+
+A default hashing algorithm, which will be adequate for most applications, 
+is built into Berkeley DB.  
+If you do need to use your own hashing algorithm it is possible to write your
+own in Perl and have B<DB_File> use it instead.
+
+=item DB_BTREE
+
+The btree format allows arbitrary key/data pairs to be stored in a sorted, 
+balanced binary tree.
+
+As with the DB_HASH format, it is possible to provide a user defined Perl routine
+to perform the comparison of keys. By default, though, the keys are stored 
+in lexical order.
+
+=item DB_RECNO
+
+DB_RECNO allows both fixed-length and variable-length flat text files to be 
+manipulated using 
+the same key/value pair interface as in DB_HASH and DB_BTREE. 
+In this case the key will consist of a record (line) number. 
+
+=back
+
+=head2 How does DB_File interface to Berkeley DB?
+
+B<DB_File> allows access to Berkeley DB files using the tie() mechanism
+in Perl 5 (for full details, see L<perlfunc/tie()>).
+This facility allows B<DB_File> to access Berkeley DB files using
+either an associative array (for DB_HASH & DB_BTREE file types) or an
+ordinary array (for the DB_RECNO file type).
+
+In addition to the tie() interface, it is also possible to use most of the
+functions provided in the Berkeley DB API.
+
+=head2 Differences with Berkeley DB
+
+Berkeley DB uses the function dbopen() to open or create a 
+database. Below is the C prototype for dbopen().
+
+      DB*
+      dbopen (const char * file, int flags, int mode, 
+              DBTYPE type, const void * openinfo)
+
+The parameter C<type> is an enumeration which specifies which of the 3
+interface methods (DB_HASH, DB_BTREE or DB_RECNO) is to be used.
+Depending on which of these is actually chosen, the final parameter,
+I<openinfo> points to a data structure which allows tailoring of the
+specific interface method.
+
+This interface is handled 
+slightly differently in B<DB_File>. Here is an equivalent call using
+B<DB_File>.
+
+        tie %array, DB_File, $filename, $flags, $mode, $DB_HASH ;
+
+The C<filename>, C<flags> and C<mode> parameters are the direct equivalent 
+of their dbopen() counterparts. The final parameter $DB_HASH
+performs the function of both the C<type> and C<openinfo>
+parameters in dbopen().
+
+In the example above $DB_HASH is actually a reference to a hash object.
+B<DB_File> has three of these pre-defined references.
+Apart from $DB_HASH, there is also $DB_BTREE and $DB_RECNO.
+
+The keys allowed in each of these pre-defined references is limited to the names
+used in the equivalent C structure.
+So, for example, the $DB_HASH reference will only allow keys called C<bsize>,
+C<cachesize>, C<ffactor>, C<hash>, C<lorder> and C<nelem>. 
+
+To change one of these elements, just assign to it like this
+
+       $DB_HASH{cachesize} = 10000 ;
+
+
+=head2 RECNO
+
+
+In order to make RECNO more compatible with Perl the array offset for all
+RECNO arrays begins at 0 rather than 1 as in Berkeley DB.
+
+
+=head2 In Memory Databases
+
+Berkeley DB allows the creation of in-memory databases by using NULL (that is, a 
+C<(char *)0 in C) in 
+place of the filename. 
+B<DB_File> uses C<undef> instead of NULL to provide this functionality.
+
+
+=head2 Using the Berkeley DB Interface Directly
+
+As well as accessing Berkeley DB using a tied hash or array, it is also
+possible to make direct use of most of the functions defined in the Berkeley DB
+documentation.
+
+
+To do this you need to remember the return value from the tie.
+
+       $db = tie %hash, DB_File, "filename"
+
+Once you have done that, you can access the Berkeley DB API functions directly.
+
+       $db->put($key, $value, R_NOOVERWRITE) ;
+
+All the functions defined in L<dbx(3X)> are available except
+for close() and dbopen() itself.  
+The B<DB_File> interface to these functions have been implemented to mirror
+the the way Berkeley DB works. In particular note that all the functions return
+only a status value. Whenever a Berkeley DB function returns data via one of
+its parameters, the B<DB_File> equivalent does exactly the same.
+
+All the constants defined in L<dbopen> are also available.
+
+Below is a list of the functions available.
+
+=over 5
+
+=item get
+
+Same as in C<recno> except that the flags parameter is optional. 
+Remember the value
+associated with the key you request is returned in the $value parameter.
+
+=item put
+
+As usual the flags parameter is optional. 
+
+If you use either the R_IAFTER or
+R_IBEFORE flags, the key parameter will have the record number of the inserted
+key/value pair set.
+
+=item del
+
+The flags parameter is optional.
+
+=item fd
+
+As in I<recno>.
+
+=item seq
+
+The flags parameter is optional.
+
+Both the key and value parameters will be set.
+
+=item sync
+
+The flags parameter is optional.
+
+=back
+
+=head1 EXAMPLES
+
+It is always a lot easier to understand something when you see a real example.
+So here are a few.
+
+=head2 Using HASH
+
+       use DB_File ;
+       use Fcntl ;
+       
+       tie %h,  DB_File, "hashed", O_RDWR|O_CREAT, 0640, $DB_HASH ;
+       
+       # Add a key/value pair to the file
+       $h{"apple"} = "orange" ;
+       
+       # Check for existence of a key
+       print "Exists\n" if $h{"banana"} ;
+       
+       # Delete 
+       delete $h{"apple"} ;
+       
+       untie %h ;
+
+=head2 Using BTREE
+
+Here is sample of code which used BTREE. Just to make life more interesting
+the default comparision function will not be used. Instead a Perl sub, C<Compare()>,
+will be used to do a case insensitive comparison.
+
+        use DB_File ;
+        use Fcntl ;
+        
+       sub Compare
+        {
+           my ($key1, $key2) = @_ ;
+       
+           "\L$key1" cmp "\L$key2" ;
+       }
+       
+        $DB_BTREE->{compare} = 'Compare' ;
+        
+        tie %h,  DB_File, "tree", O_RDWR|O_CREAT, 0640, $DB_BTREE ;
+        
+        # Add a key/value pair to the file
+        $h{'Wall'} = 'Larry' ;
+        $h{'Smith'} = 'John' ;
+       $h{'mouse'} = 'mickey' ;
+       $h{'duck'}   = 'donald' ;
+        
+        # Delete
+        delete $h{"duck"} ;
+        
+       # Cycle through the keys printing them in order.
+       # Note it is not necessary to sort the keys as
+       # the btree will have kept them in order automatically.
+       foreach (keys %h)
+         { print "$_\n" }
+       
+        untie %h ;
+
+Here is the output from the code above.
+
+       mouse
+       Smith
+       Wall
+
+
+=head2 Using RECNO
+
+       use DB_File ;
+       use Fcntl ;
+       
+       $DB_RECNO->{psize} = 3000 ;
+       
+       tie @h,  DB_File, "text", O_RDWR|O_CREAT, 0640, $DB_RECNO ;
+       
+       # Add a key/value pair to the file
+       $h[0] = "orange" ;
+       
+       # Check for existence of a key
+       print "Exists\n" if $h[1] ;
+       
+       untie @h ;
+
+
+
+=head1 CHANGES
+
+=head2 0.1
+
+First Release.
+
+=head2 0.2
+
+When B<DB_File> is opening a database file it no longer terminates the
+process if I<dbopen> returned an error. This allows file protection
+errors to be caught at run time. Thanks to Judith Grass
+<grass@cybercash.com> for spotting the bug.
+
+=head1 WARNINGS
+
+If you happen find any other functions defined in the source for this module 
+that have not been mentioned in this document -- beware. 
+I may drop them at a moments notice.
+
+If you cannot find any, then either you didn't look very hard or the moment has
+passed and I have dropped them.
+
+=head1 BUGS
+
+Some older versions of Berkeley DB had problems with fixed length records
+using the RECNO file format. The newest version at the time of writing 
+was 1.85 - this seems to have fixed the problems with RECNO.
+
+I am sure there are bugs in the code. If you do find any, or can suggest any
+enhancements, I would welcome your comments.
+
+=head1 AVAILABILITY
+
+Berkeley DB is available via the hold C<ftp.cs.berkeley.edu> in the
+directory C</ucb/4bsd/db.tar.gz>.  It is I<not> under the GPL.
+
+=head1 SEE ALSO
+
+L<perl(1)>, L<dbopen(3)>, L<hash(3)>, L<recno(3)>, L<btree(3)> 
+
+Berkeley DB is available from F<ftp.cs.berkeley.edu> in the directory F</ucb/4bsd>.
+
+=head1 AUTHOR
+
+The DB_File interface was written by 
+Paul Marquess <pmarquess@bfsec.bt.co.uk>.
+Questions about the DB system itself may be addressed to
+Keith Bostic  <bostic@cs.berkeley.edu>.
+
+=cut
 
 package DB_File::HASHINFO ;
 use Carp;
@@ -177,7 +512,7 @@ $DB_RECNO = TIEHASH DB_File::RECNOINFO ;
 
 require TieHash;
 require Exporter;
-require AutoLoader;
+use AutoLoader;
 require DynaLoader;
 @ISA = qw(TieHash Exporter DynaLoader);
 @EXPORT = qw(
index 86c3b49..0541668 100644 (file)
@@ -3,11 +3,14 @@
  DB_File.xs -- Perl 5 interface to Berkeley DB 
 
  written by Paul Marquess (pmarquess@bfsec.bt.co.uk)
- last modified 23rd June 1994
- version 0.1
+ last modified 19th May 1995
+ version 0.2
 
  All comments/suggestions/problems are welcome
 
+ Changes:
+       0.1 - Initial Release
+       0.2 - No longer bombs out if dbopen returns an error.
 */
 
 #include "EXTERN.h"  
@@ -414,14 +417,11 @@ char * string ;
 
     RETVAL = dbopen(name, flags, mode, type, openinfo) ; 
 
-    if (RETVAL == 0)
-        croak("DB_File::%s failed, reason: %s", string, Strerror(errno)) ;
-
     /* kludge mode on: RETVAL->type for DB_RECNO is set to DB_BTREE
                       so remember a DB_RECNO by saving the address
                       of one of it's internal routines
     */
-    if (type == DB_RECNO)
+    if (RETVAL && type == DB_RECNO)
         DB_recno_close = RETVAL->close ;
 
 
diff --git a/ext/DynaLoader/DynaLoader.doc b/ext/DynaLoader/DynaLoader.doc
deleted file mode 100644 (file)
index 85d606f..0000000
+++ /dev/null
@@ -1,257 +0,0 @@
-=======================================================================
-Specification for the Generic Dynamic Linking 'DynaLoader' Module
-
-This specification defines a standard generic interface to the dynamic
-linking mechanisms available on many platforms. Its primary purpose is
-to implement automatic dynamic loading of perl modules.
-
-The DynaLoader is designed to be a very simple high-level
-interface that is sufficiently general to cover the requirements
-of SunOS, HP-UX, NeXT, Linux, VMS and other platforms.
-
-It is also hoped that the interface will cover the needs of OS/2,
-NT etc and allow pseudo-dynamic linking (using ld -A at runtime).
-
-This document serves as both a specification for anyone wishing to
-implement the DynaLoader for a new platform and as a guide for
-anyone wishing to use the DynaLoader directly in an application.
-
-It must be stressed that the DynaLoader, by itself, is practically
-useless for accessing non-perl libraries because it provides almost no
-perl-to-C 'glue'. There is, for example, no mechanism for calling a C
-library function or supplying arguments. It is anticipated that any
-glue that may be developed in the future will be implemented in a
-seperate dynamically loaded module.
-
-This interface is based on the work and comments of (in no particular
-order): Larry Wall, Robert Sanders, Dean Roehrich, Jeff Okamoto, Anno
-Siegel, Thomas Neumann, Paul Marquess, Charles Bailey and others.
-
-Larry Wall designed the elegant inherited bootstrap mechanism and
-implemented the first perl 5 dynamic loader using it.
-
-Tim Bunce
-11th August 1994
-
-----------------------------------------------------------------------
-DynaLoader Interface Summary
-
-  @dl_library_path
-  @dl_resolve_using
-  @dl_require_symbols
-  $dl_debug
-                                                  Implemented in:
-  bootstrap($modulename)                               Perl
-  @filepaths = dl_findfile(@names)                     Perl
-
-  $libref  = dl_load_file($filename)                   C
-  $symref  = dl_find_symbol($libref, $symbol)          C
-  @symbols = dl_undef_symbols()                        C
-  dl_install_xsub($name, $symref [, $filename])        C
-  $message = dl_error                                  C
-
-
-----------------------------------------------------------------------
-@dl_library_path
-
-The standard/default list of directories in which dl_findfile() will
-search for libraries etc. Directories are searched in order:
-$dl_library_path[0], [1], ... etc
-
-@dl_library_path is initialised to hold the list of 'normal' directories
-(/usr/lib etc) determined by Configure ($Config{'libpth'}).  This should
-ensure portability across a wide range of platforms.
-
-@dl_library_path should also be initialised with any other directories
-that can be determined from the environment at runtime (such as
-LD_LIBRARY_PATH for SunOS).
-
-After initialisation @dl_library_path can be manipulated by an
-application using push and unshift before calling dl_findfile().
-Unshift can be used to add directories to the front of the search order
-either to save search time or to override libraries with the same name
-in the 'normal' directories.
-
-The load function that dl_load_file() calls may require an absolute
-pathname.  The dl_findfile() function and @dl_library_path can be
-used to search for and return the absolute pathname for the
-library/object that you wish to load.
-
-
-----------------------------------------------------------------------
-@dl_resolve_using
-
-A list of additional libraries or other shared objects which can be
-used to resolve any undefined symbols that might be generated by a
-later call to load_file().
-
-This is only required on some platforms which do not handle dependent
-libraries automatically.  For example the Socket perl extension library
-(auto/Socket/Socket.so) contains references to many socket functions
-which need to be resolved when it's loaded. Most platforms will
-automatically know where to find the 'dependent' library (e.g.,
-/usr/lib/libsocket.so). A few platforms need to to be told the location
-of the dependent library explicitly. Use @dl_resolve_using for this.
-
-Example usage: @dl_resolve_using = dl_findfile('-lsocket');
-
-
-----------------------------------------------------------------------
-@dl_require_symbols
-
-A list of one or more symbol names that are in the library/object file
-to be dynamically loaded.  This is only required on some platforms.
-
-
-----------------------------------------------------------------------
-$message = dl_error
-
-Error message text from the last failed DynaLoader function. Note
-that, similar to errno in unix, a successful function call does not
-reset this message.
-
-Implementations should detect the error as soon as it occurs in any of
-the other functions and save the corresponding message for later
-retrieval. This will avoid problems on some platforms (such as SunOS)
-where the error message is very temporary (e.g., dlerror()).
-
-
-----------------------------------------------------------------------
-$dl_debug
-
-Internal debugging messages are enabled when $dl_debug is set true.
-Currently setting $dl_debug only affects the perl side of the
-DynaLoader. These messages should help an application developer to
-resolve any DynaLoader usage problems.
-
-$dl_debug is set to $ENV{'PERL_DL_DEBUG'} if defined.
-
-For the DynaLoader developer/porter there is a similar debugging
-variable added to the C code (see dlutils.c) and enabled if perl is
-compiled with the -DDEBUGGING flag.  This can also be set via the
-PERL_DL_DEBUG environment variable. Set to 1 for minimal information or
-higher for more.
-
-
-----------------------------------------------------------------------
-@filepaths = dl_findfile(@names)
-
-Determine the full paths (including file suffix) of one or more
-loadable files given their generic names and optionally one or more
-directories. Searches directories in @dl_library_path by default and
-returns an empty list if no files were found.
-
-Names can be specified in a variety of platform independent forms.  Any
-names in the form '-lname' are converted into 'libname.*', where .* is
-an appropriate suffix for the platform.
-
-If a name does not already have a suitable prefix and/or suffix then
-the corresponding file will be searched for by trying combinations of
-prefix and suffix appropriate to the platform: "$name.o", "lib$name.*"
-and "$name".
-
-If any directories are included in @names they are searched before
-@dl_library_path. Directories may be specified as -Ldir. Any other names
-are treated as filenames to be searched for.
-
-Using arguments of the form -Ldir and -lname is recommended.
-
-Example: @dl_resolve_using = dl_findfile(qw(-L/usr/5lib -lposix));
-
-
-----------------------------------------------------------------------
-$filepath = dl_expandspec($spec)
-
-Some unusual systems, such as VMS, require special filename handling in
-order to deal with symbolic names for files (i.e., VMS's Logical Names).
-
-To support these systems a dl_expandspec function can be implemented
-either in the dl_*.xs file or code can be added to the autoloadable
-dl_expandspec function in DynaLoader.pm. See DynaLoader.pm for more
-information.
-
-
-
-----------------------------------------------------------------------
-$libref = dl_load_file($filename)
-
-Dynamically load $filename, which must be the path to a shared object
-or library. An opaque 'library reference' is returned as a handle for
-the loaded object.  Returns undef on error.
-
-(On systems that provide a handle for the loaded object such as SunOS
-and HPUX, $libref will be that handle.  On other systems $libref will
-typically be $filename or a pointer to a buffer containing $filename.
-The application should not examine or alter $libref in any way.)
-
-This is function that does the real work. It should use the current
-values of @dl_require_symbols and @dl_resolve_using if required.
-
-SunOS: dlopen($filename)
-HP-UX: shl_load($filename)
-Linux: dld_create_reference(@dl_require_symbols); dld_link($filename)
-NeXT:  rld_load($filename, @dl_resolve_using)
-VMS:   lib$find_image_symbol($filename,$dl_require_symbols[0])
-
-
-----------------------------------------------------------------------
-$symref = dl_find_symbol($libref, $symbol)
-
-Return the address of the symbol $symbol or undef if not found. If the
-target system has separate functions to search for symbols of different
-types then dl_find_symbol should search for function symbols first and
-then other types.
-
-The exact manner in which the address is returned in $symref is not
-currently defined. The only initial requirement is that $symref can
-be passed to, and understood by, dl_install_xsub().
-
-SunOS: dlsym($libref, $symbol)
-HP-UX: shl_findsym($libref, $symbol)
-Linux: dld_get_func($symbol) and/or dld_get_symbol($symbol)
-NeXT:  rld_lookup("_$symbol")
-VMS:   lib$find_image_symbol($libref,$symbol)
-
-
-----------------------------------------------------------------------
-@symbols = dl_undef_symbols()
-
-Return a list of symbol names which remain undefined after load_file().
-Returns () if not known. Don't worry if your platform does not provide
-a mechanism for this. Most do not need it and hence do not provide it.
-
-
-----------------------------------------------------------------------
-dl_install_xsub($perl_name, $symref [, $filename])
-
-Create a new Perl external subroutine named $perl_name using $symref as
-a pointer to the function which implements the routine. This is simply
-a direct call to newXSUB(). Returns a reference to the installed
-function.
-
-The $filename parameter is used by Perl to identify the source file for
-the function if required by die(), caller() or the debugger. If
-$filename is not defined then "DynaLoader" will be used.
-
-
-----------------------------------------------------------------------
-bootstrap($module)
-
-This is the normal entry point for automatic dynamic loading in Perl.
-
-It performs the following actions:
- 1.  locates an auto/$module directory by searching @INC
- 2.  uses dl_findfile() to determine the filename to load
- 3.  sets @dl_require_symbols to ("boot_$module")
- 4.  executes an auto/$module/$^R/$module.bs file if it exists
-     (typically used to add to @dl_resolve_using any files which
-     are required to load the module on the current platform)
- 5.  calls dl_load_file() to load the file
- 6.  calls dl_undef_symbols() and warns if any symbols are undefined
- 7.  calls dl_find_symbol() for "boot_$module"
- 8.  calls dl_install_xsub() to install it as "${module}::bootstrap"
- 9.  calls &{"${module}::bootstrap"} to bootstrap the module
-
-
-======================================================================
-End.
index 2c375d0..82721d1 100644 (file)
@@ -1,5 +1,324 @@
 package DynaLoader;
 
+=head1 NAME
+
+DynaLoader - Dynamically load C libraries into Perl code
+
+dl_error(), dl_findfile(), dl_expandspec(), dl_load_file(), dl_find_symbol(), dl_undef_symbols(), dl_install_xsub(), boostrap() - routines used by DynaLoader modules
+
+=head1 SYNOPSIS
+
+    require DynaLoader;
+    push (@ISA, 'DynaLoader');
+
+
+=head1 DESCRIPTION
+
+This specification defines a standard generic interface to the dynamic
+linking mechanisms available on many platforms.  Its primary purpose is
+to implement automatic dynamic loading of Perl modules.
+
+The DynaLoader is designed to be a very simple high-level
+interface that is sufficiently general to cover the requirements
+of SunOS, HP-UX, NeXT, Linux, VMS and other platforms.
+
+It is also hoped that the interface will cover the needs of OS/2,
+NT etc and allow pseudo-dynamic linking (using C<ld -A> at runtime).
+
+This document serves as both a specification for anyone wishing to
+implement the DynaLoader for a new platform and as a guide for
+anyone wishing to use the DynaLoader directly in an application.
+
+It must be stressed that the DynaLoader, by itself, is practically
+useless for accessing non-Perl libraries because it provides almost no
+Perl-to-C 'glue'.  There is, for example, no mechanism for calling a C
+library function or supplying arguments.  It is anticipated that any
+glue that may be developed in the future will be implemented in a
+separate dynamically loaded module.
+
+DynaLoader Interface Summary
+
+  @dl_library_path
+  @dl_resolve_using
+  @dl_require_symbols
+  $dl_debug
+                                                  Implemented in:
+  bootstrap($modulename)                               Perl
+  @filepaths = dl_findfile(@names)                     Perl
+
+  $libref  = dl_load_file($filename)                   C
+  $symref  = dl_find_symbol($libref, $symbol)          C
+  @symbols = dl_undef_symbols()                        C
+  dl_install_xsub($name, $symref [, $filename])        C
+  $message = dl_error                                  C
+
+=over 4
+
+=item @dl_library_path
+
+The standard/default list of directories in which dl_findfile() will
+search for libraries etc.  Directories are searched in order:
+$dl_library_path[0], [1], ... etc
+
+@dl_library_path is initialised to hold the list of 'normal' directories
+(F</usr/lib>, etc) determined by B<Configure> (C<$Config{'libpth'}>).  This should
+ensure portability across a wide range of platforms.
+
+@dl_library_path should also be initialised with any other directories
+that can be determined from the environment at runtime (such as
+LD_LIBRARY_PATH for SunOS).
+
+After initialisation @dl_library_path can be manipulated by an
+application using push and unshift before calling dl_findfile().
+Unshift can be used to add directories to the front of the search order
+either to save search time or to override libraries with the same name
+in the 'normal' directories.
+
+The load function that dl_load_file() calls may require an absolute
+pathname.  The dl_findfile() function and @dl_library_path can be
+used to search for and return the absolute pathname for the
+library/object that you wish to load.
+
+=item @dl_resolve_using
+
+A list of additional libraries or other shared objects which can be
+used to resolve any undefined symbols that might be generated by a
+later call to load_file().
+
+This is only required on some platforms which do not handle dependent
+libraries automatically.  For example the Socket Perl extension library
+(F<auto/Socket/Socket.so>) contains references to many socket functions
+which need to be resolved when it's loaded.  Most platforms will
+automatically know where to find the 'dependent' library (e.g.,
+F</usr/lib/libsocket.so>).  A few platforms need to to be told the location
+of the dependent library explicitly.  Use @dl_resolve_using for this.
+
+Example usage:
+
+    @dl_resolve_using = dl_findfile('-lsocket');
+
+=item @dl_require_symbols
+
+A list of one or more symbol names that are in the library/object file
+to be dynamically loaded.  This is only required on some platforms.
+
+=item dl_error()
+
+Syntax:
+
+    $message = dl_error();
+
+Error message text from the last failed DynaLoader function.  Note
+that, similar to errno in unix, a successful function call does not
+reset this message.
+
+Implementations should detect the error as soon as it occurs in any of
+the other functions and save the corresponding message for later
+retrieval.  This will avoid problems on some platforms (such as SunOS)
+where the error message is very temporary (e.g., dlerror()).
+
+=item $dl_debug
+
+Internal debugging messages are enabled when $dl_debug is set true.
+Currently setting $dl_debug only affects the Perl side of the
+DynaLoader.  These messages should help an application developer to
+resolve any DynaLoader usage problems.
+
+$dl_debug is set to C<$ENV{'PERL_DL_DEBUG'}> if defined.
+
+For the DynaLoader developer/porter there is a similar debugging
+variable added to the C code (see dlutils.c) and enabled if Perl was
+built with the B<-DDEBUGGING> flag.  This can also be set via the
+PERL_DL_DEBUG environment variable.  Set to 1 for minimal information or
+higher for more.
+
+=item dl_findfile()
+
+Syntax:
+
+    @filepaths = dl_findfile(@names)
+
+Determine the full paths (including file suffix) of one or more
+loadable files given their generic names and optionally one or more
+directories.  Searches directories in @dl_library_path by default and
+returns an empty list if no files were found.
+
+Names can be specified in a variety of platform independent forms.  Any
+names in the form B<-lname> are converted into F<libname.*>, where F<.*> is
+an appropriate suffix for the platform.
+
+If a name does not already have a suitable prefix and/or suffix then
+the corresponding file will be searched for by trying combinations of
+prefix and suffix appropriate to the platform: "$name.o", "lib$name.*"
+and "$name".
+
+If any directories are included in @names they are searched before
+@dl_library_path.  Directories may be specified as B<-Ldir>.  Any other names
+are treated as filenames to be searched for.
+
+Using arguments of the form C<-Ldir> and C<-lname> is recommended.
+
+Example: 
+
+    @dl_resolve_using = dl_findfile(qw(-L/usr/5lib -lposix));
+
+
+=item dl_expandspec()
+
+Syntax:
+
+    $filepath = dl_expandspec($spec)
+
+Some unusual systems, such as VMS, require special filename handling in
+order to deal with symbolic names for files (i.e., VMS's Logical Names).
+
+To support these systems a dl_expandspec() function can be implemented
+either in the F<dl_*.xs> file or code can be added to the autoloadable
+dl_expandspec(0 function in F<DynaLoader.pm>).  See F<DynaLoader.pm> for more
+information.
+
+=item dl_load_file()
+
+Syntax:
+
+    $libref = dl_load_file($filename)
+
+Dynamically load $filename, which must be the path to a shared object
+or library.  An opaque 'library reference' is returned as a handle for
+the loaded object.  Returns undef on error.
+
+(On systems that provide a handle for the loaded object such as SunOS
+and HPUX, $libref will be that handle.  On other systems $libref will
+typically be $filename or a pointer to a buffer containing $filename.
+The application should not examine or alter $libref in any way.)
+
+This is function that does the real work.  It should use the current
+values of @dl_require_symbols and @dl_resolve_using if required.
+
+    SunOS: dlopen($filename)
+    HP-UX: shl_load($filename)
+    Linux: dld_create_reference(@dl_require_symbols); dld_link($filename)
+    NeXT:  rld_load($filename, @dl_resolve_using)
+    VMS:   lib$find_image_symbol($filename,$dl_require_symbols[0])
+
+
+=item dl_find_symbol()
+
+Syntax:
+
+    $symref = dl_find_symbol($libref, $symbol)
+
+Return the address of the symbol $symbol or C<undef> if not found.  If the
+target system has separate functions to search for symbols of different
+types then dl_find_symbol() should search for function symbols first and
+then other types.
+
+The exact manner in which the address is returned in $symref is not
+currently defined.  The only initial requirement is that $symref can
+be passed to, and understood by, dl_install_xsub().
+
+    SunOS: dlsym($libref, $symbol)
+    HP-UX: shl_findsym($libref, $symbol)
+    Linux: dld_get_func($symbol) and/or dld_get_symbol($symbol)
+    NeXT:  rld_lookup("_$symbol")
+    VMS:   lib$find_image_symbol($libref,$symbol)
+
+
+=item dl_undef_symbols()
+
+Example
+
+    @symbols = dl_undef_symbols()
+
+Return a list of symbol names which remain undefined after load_file().
+Returns C<()> if not known.  Don't worry if your platform does not provide
+a mechanism for this.  Most do not need it and hence do not provide it.
+
+
+=item dl_install_xsub()
+
+Syntax:
+
+    dl_install_xsub($perl_name, $symref [, $filename])
+
+Create a new Perl external subroutine named $perl_name using $symref as
+a pointer to the function which implements the routine.  This is simply
+a direct call to newXSUB().  Returns a reference to the installed
+function.
+
+The $filename parameter is used by Perl to identify the source file for
+the function if required by die(), caller() or the debugger.  If
+$filename is not defined then "DynaLoader" will be used.
+
+
+=item boostrap()
+
+Syntax:
+
+bootstrap($module)
+
+This is the normal entry point for automatic dynamic loading in Perl.
+
+It performs the following actions:
+
+=over 8
+
+=item *
+
+locates an auto/$module directory by searching @INC
+
+=item *
+
+uses dl_findfile() to determine the filename to load
+
+=item *
+
+sets @dl_require_symbols to C<("boot_$module")>
+
+=item *
+
+executes an F<auto/$module/$module.bs> file if it exists
+(typically used to add to @dl_resolve_using any files which
+are required to load the module on the current platform)
+
+=item *
+
+calls dl_load_file() to load the file
+
+=item *
+
+calls dl_undef_symbols() and warns if any symbols are undefined
+
+=item *
+
+calls dl_find_symbol() for "boot_$module"
+
+=item *
+
+calls dl_install_xsub() to install it as "${module}::bootstrap"
+
+=item *
+
+calls &{"${module}::bootstrap"} to bootstrap the module
+
+=back
+
+=back
+
+
+=head1 AUTHOR
+
+This interface is based on the work and comments of (in no particular
+order): Larry Wall, Robert Sanders, Dean Roehrich, Jeff Okamoto, Anno
+Siegel, Thomas Neumann, Paul Marquess, Charles Bailey, and others.
+
+Larry Wall designed the elegant inherited bootstrap mechanism and
+implemented the first Perl 5 dynamic loader using it.
+
+Tim Bunce, 11 August 1994.
+
+=cut
+
 #
 #   And Gandalf said: 'Many folk like to know beforehand what is to
 #   be set on the table; but those who have laboured to prepare the
index c4602d3..0551cf3 100644 (file)
@@ -1,11 +1,11 @@
 Perl 5 DynaLoader
 
-See DynaLoader.doc for detailed specification.
+See DynaLoader.pm for detailed specification.
 
 This module is very similar to the other Perl 5 modules except that
 Configure selects which dl_*.xs file to use.
 
-After Configure has been run the Makefile.SH will generate a Makefile
+After Configure has been run the Makefile.PL will generate a Makefile
 which will run xsubpp on a specific dl_*.xs file and write the output
 to DynaLoader.c
 
@@ -42,11 +42,11 @@ which is a good place to start if porting from scratch. For more complex
 platforms take a look at dl_dld.xs. The dlutils.c file holds some
 common definitions that are #included into the dl_*.xs files.
 
-After the initial implementation of a new DynaLoader dl_*.xs file
-you may need to edit or create ext/MODULE/MODULE.bs files to reflect
-the needs of your platform and linking software.
+After the initial implementation of a new DynaLoader dl_*.xs file you
+may need to edit or create ext/MODULE/MODULE.bs files (library bootstrap
+files) to reflect the needs of your platform and linking software.
 
-Refer to DynaLoader.doc, lib/ExtUtils/MakeMaker.pm and any existing
+Refer to DynaLoader.pm, lib/ExtUtils/MakeMaker.pm and any existing
 ext/MODULE/MODULE.bs files for more information.
 
 Tim Bunce.
index d3f73c4..b925150 100644 (file)
@@ -1,7 +1,30 @@
 package Fcntl;
 
+=head1 NAME
+
+Fcntl - load the C Fcntl.h defines
+
+=head1 SYNOPSIS
+
+    use Fcntl;
+
+=head1 DESCRIPTION
+
+This module is just a translation of the C F<fnctl.h> file.
+Unlike the old mechanism of requiring a translated F<fnctl.ph>
+file, this uses the B<h2xs> program (see the Perl source distribution)
+and your native C compiler.  This means that it has a 
+far more likely chance of getting the numbers right.
+
+=head1 NOTE
+
+Only C<#define> symbols get translated; you must still correctly
+pack up your own arguments to pass as args for locking functions, etc.
+
+=cut
+
 require Exporter;
-require AutoLoader;
+use AutoLoader;
 require DynaLoader;
 @ISA = qw(Exporter DynaLoader);
 # Items to export into callers namespace by default
index 646d749..73bcdbe 100644 (file)
@@ -3,7 +3,7 @@ package GDBM_File;
 require Carp;
 require TieHash;
 require Exporter;
-require AutoLoader;
+use AutoLoader;
 require DynaLoader;
 @ISA = qw(TieHash Exporter DynaLoader);
 @EXPORT = qw(
index 8c7276d..0a0b717 100644 (file)
@@ -216,3 +216,20 @@ int
 gdbm_reorganize(db)
        GDBM_File       db
 
+
+void
+gdbm_sync(db)
+       GDBM_File       db
+
+int
+gdbm_exists(db, key)
+       GDBM_File       db
+       datum           key
+
+int
+gdbm_setopt (db, optflag, optval, optlen)
+       GDBM_File       db
+       int             optflag
+       int             &optval
+       int             optlen
+
index b343200..10a67cb 100644 (file)
@@ -1,8 +1,64 @@
 package POSIX;
 
+=head1 NAME
+
+POSIX - Perl interface to IEEE 1003.1 namespace
+
+=head1 SYNOPSIS
+
+    use POSIX;
+    use POSIX 'strftime';
+
+=head1 DESCRIPTION
+
+The POSIX module permits you to access all (or nearly all) the standard
+POSIX 1003.1 identifiers.  Things which are C<#defines> in C, like EINTR
+or O_NDELAY, are automatically exported into your namespace.  All
+functions are only exported if you ask for them explicitly.  Most likely
+people will prefer to use the fully-qualified function names.
+
+To get a list of all the possible identifiers available to you--and
+their semantics--you should pick up a 1003.1 spec, or look in the
+F<POSIX.pm> module.
+
+=head1 EXAMPLES
+
+    printf "EINTR is %d\n", EINTR;
+
+    POSIX::setsid(0);
+
+    $fd = POSIX::open($path, O_CREAT|O_EXCL|O_WRONLY, 0644);
+       # note: that's a filedescriptor, *NOT* a filehandle
+
+=head1 NOTE
+
+The POSIX module is probably the most complex Perl module supplied with
+the standard distribution.  It incorporates autoloading, namespace games,
+and dynamic loading of code that's in Perl, C, or both.  It's a great
+source of wisdom.
+
+=head1 CAVEATS 
+
+A few functions are not implemented because they are C specific.  If you
+attempt to call these, they will print a message telling you that they
+aren't implemented, and suggest using the Perl equivalent should one
+exist.  For example, trying to access the setjmp() call will elicit the
+message "setjmp() is C-specific: use eval {} instead".
+
+Furthermore, some evil vendors will claim 1003.1 compliance, but in fact
+are not so: they will not pass the PCTS (POSIX Compliance Test Suites).
+For example, one vendor may not define EDEADLK, or the semantics of the
+errno values set by open(2) might not be quite right.  Perl does not
+attempt to verify POSIX compliance.  That means you can currently
+successfully say "use POSIX",  and then later in your program you find
+that your vendor has been lax and there's no usable ICANON macro after
+all.  This could be construed to be a bug.
+
+=cut
+
 use Carp;
 require Exporter;
-require AutoLoader;
+use AutoLoader;
 require DynaLoader;
 require Config;
 @ISA = qw(Exporter DynaLoader);
@@ -60,7 +116,7 @@ require Config;
                LC_TIME NULL localeconv setlocale)],
 
     math_h =>  [qw(HUGE_VAL acos asin atan ceil cosh fabs floor fmod
-               frexp ldexp log10 modf pow sinh tanh)],
+               frexp ldexp log10 modf pow sinh tan tanh)],
 
     pwd_h =>   [qw()],
 
@@ -152,7 +208,7 @@ Exporter::export_tags();
     closedir opendir readdir rewinddir
     fcntl open
     getgrgid getgrnam
-    atan2 cos exp log sin sqrt tan
+    atan2 cos exp log sin sqrt
     getpwnam getpwuid
     kill
     fileno getc printf rename sprintf
@@ -416,11 +472,6 @@ sub sqrt {
     sqrt($_[0]);
 }
 
-sub tan {
-    usage "tan(x)" if @_ != 1;
-    tan($_[0]);
-}
-
 sub getpwnam {
     usage "getpwnam(name)" if @_ != 1;
     getpwnam($_[0]);
@@ -808,7 +859,7 @@ sub strtok {
 }
 
 sub chmod {
-    usage "chmod(filename, mode)" if @_ != 2;
+    usage "chmod(mode, filename)" if @_ != 2;
     chmod($_[0], $_[1]);
 }
 
index 5c2fe24..3d68d91 100644 (file)
@@ -2727,6 +2727,10 @@ sinh(x)
        double          x
 
 double
+tan(x)
+       double          x
+
+double
 tanh(x)
        double          x
 
index d09adcc..d7014a6 100644 (file)
@@ -37,7 +37,7 @@ extern int errno;
 #endif
 
 extern Malloc_t malloc proto((MEM_SIZE));
-extern void free proto((void *));
+extern Free_t free proto((void *));
 extern Off_t lseek();
 
 /*
index 6c63fb5..86cc86c 100644 (file)
@@ -1,8 +1,35 @@
 package Socket;
+
+=head1 NAME
+
+Socket - load the C socket.h defines
+
+=head1 SYNOPSIS
+
+    use Socket;
+
+    $proto = (getprotobyname('udp'))[2];         
+    socket(Socket_Handle, PF_INET, SOCK_DGRAM, $proto); 
+
+=head1 DESCRIPTION
+
+This module is just a translation of the C F<socket.h> file.
+Unlike the old mechanism of requiring a translated F<socket.ph>
+file, this uses the B<h2xs> program (see the Perl source distribution)
+and your native C compiler.  This means that it has a 
+far more likely chance of getting the numbers right.
+
+=head1 NOTE
+
+Only C<#define> symbols get translated; you must still correctly
+pack up your own arguments to pass to bind(), etc.
+
+=cut
+
 use Carp;
 
 require Exporter;
-require AutoLoader;
+use AutoLoader;
 require DynaLoader;
 @ISA = qw(Exporter DynaLoader);
 @EXPORT = qw(