diff options
Diffstat (limited to 'ext')
| -rw-r--r-- | ext/DB_File/DB_File.pm | 341 | ||||
| -rw-r--r-- | ext/DB_File/DB_File.xs | 12 | ||||
| -rw-r--r-- | ext/DynaLoader/DynaLoader.doc | 257 | ||||
| -rw-r--r-- | ext/DynaLoader/DynaLoader.pm | 319 | ||||
| -rw-r--r-- | ext/DynaLoader/README | 12 | ||||
| -rw-r--r-- | ext/Fcntl/Fcntl.pm | 25 | ||||
| -rw-r--r-- | ext/GDBM_File/GDBM_File.pm | 2 | ||||
| -rw-r--r-- | ext/GDBM_File/GDBM_File.xs | 17 | ||||
| -rw-r--r-- | ext/POSIX/POSIX.pm | 69 | ||||
| -rw-r--r-- | ext/POSIX/POSIX.xs | 4 | ||||
| -rw-r--r-- | ext/SDBM_File/sdbm/sdbm.c | 2 | ||||
| -rw-r--r-- | ext/Socket/Socket.pm | 29 |
12 files changed, 804 insertions, 285 deletions
diff --git a/ext/DB_File/DB_File.pm b/ext/DB_File/DB_File.pm index 1a75f155b4..5b9fba7765 100644 --- a/ext/DB_File/DB_File.pm +++ b/ext/DB_File/DB_File.pm @@ -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( diff --git a/ext/DB_File/DB_File.xs b/ext/DB_File/DB_File.xs index 86c3b4937c..0541668e24 100644 --- a/ext/DB_File/DB_File.xs +++ b/ext/DB_File/DB_File.xs @@ -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 index 85d606ff9b..0000000000 --- a/ext/DynaLoader/DynaLoader.doc +++ /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. diff --git a/ext/DynaLoader/DynaLoader.pm b/ext/DynaLoader/DynaLoader.pm index 2c375d0fd5..82721d1936 100644 --- a/ext/DynaLoader/DynaLoader.pm +++ b/ext/DynaLoader/DynaLoader.pm @@ -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 diff --git a/ext/DynaLoader/README b/ext/DynaLoader/README index c4602d3c39..0551cf375c 100644 --- a/ext/DynaLoader/README +++ b/ext/DynaLoader/README @@ -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. diff --git a/ext/Fcntl/Fcntl.pm b/ext/Fcntl/Fcntl.pm index d3f73c4cd7..b9251509db 100644 --- a/ext/Fcntl/Fcntl.pm +++ b/ext/Fcntl/Fcntl.pm @@ -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 diff --git a/ext/GDBM_File/GDBM_File.pm b/ext/GDBM_File/GDBM_File.pm index 646d7490ec..73bcdbeb24 100644 --- a/ext/GDBM_File/GDBM_File.pm +++ b/ext/GDBM_File/GDBM_File.pm @@ -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( diff --git a/ext/GDBM_File/GDBM_File.xs b/ext/GDBM_File/GDBM_File.xs index 8c7276dd2f..0a0b71779e 100644 --- a/ext/GDBM_File/GDBM_File.xs +++ b/ext/GDBM_File/GDBM_File.xs @@ -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 + diff --git a/ext/POSIX/POSIX.pm b/ext/POSIX/POSIX.pm index b343200971..10a67cb630 100644 --- a/ext/POSIX/POSIX.pm +++ b/ext/POSIX/POSIX.pm @@ -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]); } diff --git a/ext/POSIX/POSIX.xs b/ext/POSIX/POSIX.xs index 5c2fe2400e..3d68d91b03 100644 --- a/ext/POSIX/POSIX.xs +++ b/ext/POSIX/POSIX.xs @@ -2727,6 +2727,10 @@ sinh(x) double x double +tan(x) + double x + +double tanh(x) double x diff --git a/ext/SDBM_File/sdbm/sdbm.c b/ext/SDBM_File/sdbm/sdbm.c index d09adccdd3..d7014a6769 100644 --- a/ext/SDBM_File/sdbm/sdbm.c +++ b/ext/SDBM_File/sdbm/sdbm.c @@ -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(); /* diff --git a/ext/Socket/Socket.pm b/ext/Socket/Socket.pm index 6c63fb5fe3..86cc86c6b7 100644 --- a/ext/Socket/Socket.pm +++ b/ext/Socket/Socket.pm @@ -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( |