X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=vms%2Fperlvms.pod;h=377d97f6feb4182b979af41b30b554bc54267d7b;hb=d896966de2ebabc4abc3d080ae3c7ee77c51781e;hp=e7f811e0a81ac66ec34b2fa75f07f7ada4ece214;hpb=748a93069b3d16374a9859d1456065dd3ae11394;p=p5sagit%2Fp5-mst-13.2.git diff --git a/vms/perlvms.pod b/vms/perlvms.pod index e7f811e..377d97f 100644 --- a/vms/perlvms.pod +++ b/vms/perlvms.pod @@ -1,4 +1,8 @@ -=head1 Notes on Perl 5 for VMS +=head1 NAME + +perlvms - VMS-specific documentation for Perl + +=head1 DESCRIPTION Gathered below are notes describing details of Perl 5's behavior on VMS. They are a supplement to the regular Perl 5 @@ -15,9 +19,9 @@ sleep when writing Perl scripts on VMS. If you find we've missed something you think should appear here, please don't hesitate to drop a line to vmsperl@genetics.upenn.edu. -=head1 Organization of Perl +=head1 Organization of Perl Images -=head2 Perl Images +=head2 Core Images During the installation process, three Perl images are produced. F is an executable image which contains all of @@ -75,7 +79,7 @@ for the extension, and F, a Perl script which uses the C library modules supplied with Perl to generate a F file for the extension. -=head3 Installing static extensions +=head2 Installing static extensions Since static extensions are incorporated directly into F, you'll have to rebuild Perl to incorporate a @@ -94,32 +98,49 @@ of the extension, with all C<::> replaced by C<.> (e.g. the library module for extension Foo::Bar would be copied to a F<[.Foo.Bar]> subdirectory). -=head3 Installic dynamic extensions - -First, you'll need to compile the XS code into a shareable image, -either by hand or using the F supplied with the -extension. If you're building the shareable image by hand, please -note the following points: - - The shareable image must be linked to F, so it - has access to Perl's global variables and routines. In - order to specify the correct attributes for psects in - F, you should include the linker options file - F in the Link command. (This file is - generated when F is built, and is found in the - main Perl source directory. - - The entry point for the CI routine (where - I is the name of the extension, with all C<::> - replaced by C<__>) must be a universal symbol. No other - universal symbols are required to use the shareable image - with Perl, though you may want to include additional - universal symbols if you plan to share code or data among - different extensions. -The shareable image can be placed in any of several locations: - - the F<[.Auto.>IF<]> subdirectory of one of - the directories in C<@INC>, where I is the - name of the extension, with each C<::> translated to C<.> - (e.g. for extension Foo::Bar, you would use the - F<[.Auto.Foo.Bar]> subdirectory), or +=head2 Installing dynamic extensions + +In general, the distributed kit for a Perl extension includes +a file named Makefile.PL, which is a Perl program which is used +to create a F file which can be used to build and +install the files required by the extension. The kit should be +unpacked into a directory tree B under the main Perl source +directory, and the procedure for building the extension is simply + + $ perl Makefile.PL ! Create Descrip.MMS + $ mmk ! Build necessary files + $ mmk test ! Run test code, if supplied + $ mmk install ! Install into public Perl tree + +I The procedure by which extensions are built and +tested creates several levels (at least 4) under the +directory in which the extension's source files live. +For this reason, you shouldn't nest the source directory +too deeply in your directory structure, lest you eccedd RMS' +maximum of 8 levels of subdirectory in a filespec. (You +can use rooted logical names to get another 8 levels of +nesting, if you can't place the files near the top of +the physical directory structure.) + +VMS support for this process in the current release of Perl +is sufficient to handle most extensions. However, it does +not yet recognize extra libraries required to build shareable +images which are part of an extension, so these must be added +to the linker options file for the extension by hand. For +instance, if the F extension to Perl requires the +F shareable image in order to properly link +the Perl extension, then the line C must +be added to the linker options file F produced +during the build process for the Perl extension. + +By default, the shareable image for an extension is placed +in the F<[.Lib.Auto.I.I]> directory of the +installed Perl directory tree (where I is F or +F, and I is the name of the extension, with +each C<::> translated to C<.>). However, it can be manually +placed in any of several locations: + - the F<[.Lib.Auto.I]> subdirectory of one of + the directories in C<@INC>, or - one of the directories in C<@INC>, or - a directory which the extensions Perl library module passes to the DynaLoader when asking it to map @@ -130,10 +151,6 @@ to define a logical name I, where I is the portion of the extension's name after the last C<::>, which translates to the full file specification of the shareable image. -Once you've got the shareable image set up, you should copy the -extension's Perl library module to the appropriate library directory -(see the section above on installing static extensions). - =head1 Installation Directions for building and installing Perl 5 can be found in @@ -225,30 +242,6 @@ documented L, except that the element separator is '|' instead of ':'. The directory specifications may use either VMS or Unix syntax. -=head1 %ENV - -Reading the elements of the %ENV array returns the -translation of the logical name specified by the key, -according to the normal search order of access modes and -logical name tables. In addition, the keys C, -C,C, and C return the CRTL "environment -variables" of the same names. The key C returns the -current default device and directory specification. - -Setting an element of %ENV defines a supervisor-mode logical -name in the process logical name table. Cing or -Cing an element of %ENV deletes the equivalent user- -mode or supervisor-mode logical name from the process logical -name table. If you use C, the %ENV element remains -empty. If you use C, another attempt is made at -logical name translation after the deletion, so an inner-mode -logical name or a name in another logical name table will -replace the logical name just deleted. - -In all operations on %ENV, the key string is treated as if it -were entirely uppercase, regardless of the case actually -specified in the Perl expression. - =head1 Perl functions As of the time this document was last revised, the following @@ -257,36 +250,34 @@ Perl functions were implemented in the VMS port of Perl file tests*, abs, alarm, atan, binmode*, bless, caller, chdir, chmod, chown, chomp, chop, chr, - close, closedir, cos, defined, delete, die, do, - each, endpwent, eof, eval, exec*, exists, exit, - exp, fileno, fork*, getc, getpwent*, getpwnam*, - getpwuid*, glob, goto, grep, hex, import, index, - int, join, keys, kill, last, lc, lcfirst, length, - local, localtime, log, m//, map, mkdir, my, next, - no, oct, open, opendir, ord, pack, pipe, pop, pos, - print, printf, push, q//, qq//, qw//, qx//, - quotemeta, rand, read, readdir, redo, ref, rename, + close, closedir, cos, crypt*, defined, delete, + die, do, each, endpwent, eof, eval, exec*, exists, + exit, exp, fileno, fork*, getc, getlogin, getpwent*, + getpwnam*, getpwuid*, glob, gmtime*, goto, grep, hex, + import, index, int, join, keys, kill*, last, lc, + lcfirst, length, local, localtime, log, m//, map, + mkdir, my, next, no, oct, open, opendir, ord, pack, + pipe, pop, pos, print, printf, push, q//, qq//, qw//, + qx//, quotemeta, rand, read, readdir, redo, ref, rename, require, reset, return, reverse, rewinddir, rindex, - rmdir, s///, scalar, seek, seekdir, select(internal)*, - setpwent, shift, sin, sleep, sort, splice, split, - sprintf, sqrt, srand, stat, study, substr, sysread, - system*, syswrite, tell, telldir, tie, time, times*, - tr///, uc, ucfirst, umask, undef, unlink, unpack, - untie, unshift, use, utime*, values, vec, wait, - waitpid*, wantarray, warn, write, y/// + rmdir, s///, scalar, seek, seekdir, select(internal), + select (system call)*, setpwent, shift, sin, sleep, + sort, splice, split, sprintf, sqrt, srand, stat, + study, substr, sysread, system*, syswrite, tell, + telldir, tie, time, times*, tr///, uc, ucfirst, umask, + undef, unlink*, unpack, untie, unshift, use, utime*, + values, vec, wait, waitpid*, wantarray, warn, write, y/// The following functions were not implemented in the VMS port, and calling them produces a fatal error (usually) or undefined behavior (rarely, we hope): - chroot, crypt, dbmclose, dbmopen, dump, fcntl, - flock, getlogin, getpgrp, getppid, getpriority, - getgrent, kill, getgrgid, getgrnam, setgrent, - endgrent, gmtime, ioctl, link, lstst, msgctl, - msgget, msgsend, msgrcv, readlink, - select(system call), semctl, semget, semop, - setpgrp, setpriority, shmctl, shmget, shmread, - shmwrite, socketpair, symlink, syscall, truncate + chroot, dbmclose, dbmopen, dump, fcntl, flock, + getpgrp, getppid, getpriority, getgrent, getgrgid, + getgrnam, setgrent, endgrent, ioctl, link, lstat, + msgctl, msgget, msgsend, msgrcv, readlink, semctl, + semget, semop, setpgrp, setpriority, shmctl, shmget, + shmread, shmwrite, socketpair, symlink, syscall, truncate The following functions may or may not be implemented, depending on what type of socket support you've built into @@ -298,8 +289,8 @@ your copy of Perl: getnetent, getprotoent, getservent, sethostent, setnetent, setprotoent, setservent, endhostent, endnetent, endprotoent, endservent, getsockname, - getsockopt, listen, recv, send, setsockopt, - shutdown, socket + getsockopt, listen, recv, select(system call)*, + send, setsockopt, shutdown, socket =item File tests @@ -325,6 +316,33 @@ The C operator has no effect under VMS. It will return TRUE whenever called, but will not affect I/O operations on the filehandle given as its argument. +=item crypt PLAINTEXT, USER + +The C operator uses the C system +service to generate the hashed representation of PLAINTEXT. +If USER is a valid username, the algorithm and salt values +are taken from that user's UAF record. If it is not, then +the preferred algorithm and a salt of 0 are used. The +quadword encrypted value is returned as an 8-character string. + +The value returned by C may be compared against +the encrypted password from the UAF returned by the C +functions, in order to authenticate users. If you're +going to do this, remember that the encrypted password in +the UAF was generated using uppercase username and +password strings; you'll have to upcase the arguments to +C to insure that you'll get the proper value: + + sub validate_passwd { + my($user,$passwd) = @_; + my($pwdhash); + if ( !($pwdhash = (getpwnam($user))[1]) || + $pwdhash ne crypt("\U$passwd","\U$name") ) { + intruder_alert($name); + } + return 1; + } + =item exec LIST The C operator behaves in one of two different ways. @@ -368,7 +386,9 @@ subprocess is not recommended under VMS; wherever possible, use the C operator or piped filehandles instead. =item getpwent + =item getpwnam + =item getpwuid These operators obtain the information described in L, @@ -380,6 +400,39 @@ contains the login directory in Unix syntax. The C<$gcos> item contains the owner field from the UAF record. The C<$quota> item is not used. +=item gmtime + +The C operator will function properly if you have a +working CRTL C routine, or if the logical name +SYS$TIMEZONE_DIFFERENTIAL is defined as the number of seconds +which must be added to UTC to yield local time. (This logical +name is defined automatically if you are running a version of +VMS with built-in UTC support.) If neither of these cases is +true, a warning message is printed, and C is returned. + +=item kill + +In most cases, C kill is implemented via the CRTL's C +function, so it will behave according to that function's +documentation. If you send a SIGKILL, however, the $DELPRC system +service is is called directly. This insures that the target +process is actually deleted, if at all possible. (The CRTL's C +function is presently implemented via $FORCEX, which is ignored by +supervisor-mode images like DCL.) + +Also, negative signal values don't do anything special under +VMS; they're just converted to the corresponding positive value. + +=item select (system call) + +If Perl was not built with socket support, the system call +version of C functions only for file descriptors attached +to sockets. It will not provide information about regular +files or pipes, since the CRTL C routine does not +provide this functionality. + =item stat EXPR Since VMS keeps track of files according to a different scheme @@ -393,7 +446,7 @@ though, so caveat scriptor. The C operator creates a subprocess, and passes its arguments to the subprocess for execution as a DCL command. -Since the subprocess is created directly via lib$spawn, any +Since the subprocess is created directly via C, any valid DCL command string may be specified. If LIST consists of the empty string, C spawns an interactive DCL subprocess, in the same fashion as typiing B at the DCL prompt. @@ -414,6 +467,39 @@ subprocesses spawned using L and L; it will not accumulate the times of suprocesses spawned via pipes, L, or backticks. +=item unlink LIST + +C will delete the highest version of a file only; in +order to delete all versions, you need to say + 1 while (unlink LIST); +You may need to make this change to scripts written for a +Unix system which expect that after a call to C, +no files with the names passed to C will exist. +(Note: This can be changed at compile time; if you +C and C<$Config{'d_unlink_all_versions'}> is +C, then C will delete all versions of a +file on the first call.) + +C will delete a file if at all possible, even if it +requires changing file protection (though it won't try to +change the protection of the parent directory). You can tell +whether you've got explicit delete access to a file by using the +C operator. For instance, in order +to delete only files to which you have delete access, you could +say something like + sub safe_unlink { + my($file,$num); + foreach $file (@_) { + next unless VMS::Filespec::candelete($file); + $num += unlink $file; + } + $num; + } +Finally, if C has to change the file protection to +delete the file, and you interrupt it in midstream, the file +may be left intact, but with a changed ACL allowing you delete +access. + =item utime LIST Since ODS-2, the VMS file structure for disk files, does not keep @@ -433,7 +519,73 @@ and you invoked Perl with the C<-w> switch, a warning will be issued.) The FLAGS argument is ignored in all cases. +=head1 Perl variables + +=item %ENV + +Reading the elements of the %ENV array returns the +translation of the logical name specified by the key, +according to the normal search order of access modes and +logical name tables. If you append a semicolon to the +logical name, followed by an integer, that integer is +used as the translation index for the logical name, +so that you can look up successive values for search +list logical names. For instance, if you say + + $ Define STORY once,upon,a,time,there,was + $ perl -e "for ($i = 0; $i <= 6; $i++) " - + _$ -e "{ print $ENV{'foo'.$i},' '}" + +Perl will print C. + +The %ENV keys C, C,C, and C +return the CRTL "environment variables" of the same +names, if these logical names are not defined. The +key C returns the current default device +and directory specification, regardless of whether +there is a logical name DEFAULT defined.. + +Setting an element of %ENV defines a supervisor-mode logical +name in the process logical name table. Cing or +Cing an element of %ENV deletes the equivalent user- +mode or supervisor-mode logical name from the process logical +name table. If you use C, the %ENV element remains +empty. If you use C, another attempt is made at +logical name translation after the deletion, so an inner-mode +logical name or a name in another logical name table will +replace the logical name just deleted. It is not possible +at present to define a search list logical name via %ENV. + +In all operations on %ENV, the key string is treated as if it +were entirely uppercase, regardless of the case actually +specified in the Perl expression. + +=item $? + +Since VMS status values are 32 bits wide, the value of C<$?> +is simply the final status value of the last subprocess to +complete. This differs from the behavior of C<$?> under Unix, +and under VMS' POSIX environment, in that the low-order 8 bits +of C<$?> do not specify whether the process terminated normally +or due to a signal, and you do not need to shift C<$?> 8 bits +to the right in order to find the process' exit status. + +=item $! + +The string value of C<$!> is that returned by the CRTL's +strerror() function, so it will include the VMS message for +VMS-specific errors. The numeric value of C<$!> is the +value of C, except if errno is EVMSERR, in which +case C<$!> contains the value of vaxc$errno. Setting C<$!> +always sets errno to the value specified, and sets vaxc$errno +to 4 (NONAME-F-NOMSG). + =head1 Revision date This document was last updated on 16-Dec-1994, for Perl 5, -patchlevel 0. +patchlevel 2. + +=head1 AUTHOR + +Charles Bailey bailey@genetics.upenn.edu +