X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=vms%2Fperlvms.pod;h=89c4bbf62312a10dacb583267df0252a2fe8ebf9;hb=c2da85bab803bec3ca5fa4521a7396803c18a76d;hp=f15bd77cfe164eb599576efdc13c09696064b243;hpb=edc7bc4959621ea7da76262c92da0b8af51b93fe;p=p5sagit%2Fp5-mst-13.2.git diff --git a/vms/perlvms.pod b/vms/perlvms.pod index f15bd77..89c4bbf 100644 --- a/vms/perlvms.pod +++ b/vms/perlvms.pod @@ -58,7 +58,7 @@ define a foreign command to invoke this image. Perl extensions are packages which provide both XS and Perl code to add new functionality to perl. (XS is a meta-language which simplifies writing C code which interacts with Perl, see -L for more details.) The Perl code for an +L for more details.) The Perl code for an extension is treated like any other library module - it's made available in your script through the appropriate C or C statement, and usually defines a Perl @@ -140,13 +140,16 @@ 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.IF<]> directory of the +F<[.lib.site_perl.auto>I.IF<]> directory of the installed Perl directory tree (where I is F or -F, followed by the Perl version number, and I -is the name of the extension, with each C<::> translated to C<.>). +F, and I is the name of the extension, with +each C<::> translated to C<.>). (See the MakeMaker documentation +for more details on installation options for extensions.) However, it can be manually placed in any of several locations: - - the F<[.Lib.Auto.>IF<]> subdirectory of one of - the directories in C<@INC>, or + - the F<[.Lib.Auto.>II<$PVers>IF<]> subdirectory + of one of the directories in C<@INC> (where I + is the version of Perl you're using, as supplied in C<$]>, + with '.' converted to '_'), 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 @@ -238,6 +241,7 @@ directory specifications may use either VMS or Unix syntax. Perl for VMS supports redirection of input and output on the command line, using a subset of Bourne shell syntax: + reads stdin from F, >F writes stdout to F, >>F appends stdout to F, @@ -261,6 +265,8 @@ to pass uppercase switches to Perl, you need to enclose them in double-quotes on the command line, since the CRTL downcases all unquoted strings. +=over 4 + =item -i If the C<-i> switch is present but no extension for a backup @@ -286,13 +292,15 @@ The C<-u> switch causes the VMS debugger to be invoked after the Perl program is compiled, but before it has run. It does not create a core dump file. +=back + =head1 Perl functions As of the time this document was last revised, the following Perl functions were implemented in the VMS port of Perl (functions marked with * are discussed in more detail below): - file tests*, abs, alarm, atan, binmode*, bless, + file tests*, abs, alarm, atan, backticks*, binmode*, bless, caller, chdir, chmod, chown, chomp, chop, chr, close, closedir, cos, crypt*, defined, delete, die, do, dump*, each, endpwent, eof, eval, exec*, @@ -302,7 +310,7 @@ Perl functions were implemented in the VMS port of Perl 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, + qx//*, quotemeta, rand, read, readdir, redo, ref, rename, require, reset, return, reverse, rewinddir, rindex, rmdir, s///, scalar, seek, seekdir, select(internal), select (system call)*, setpwent, shift, sin, sleep, @@ -321,7 +329,12 @@ undefined behavior (rarely, we hope): getgrnam, setgrent, endgrent, ioctl, link, lstat, msgctl, msgget, msgsend, msgrcv, readlink, semctl, semget, semop, setpgrp, setpriority, shmctl, shmget, - shmread, shmwrite, socketpair, symlink, syscall, truncate + shmread, shmwrite, socketpair, symlink, syscall + +The following functions are available on Perls compiled with Dec C 5.2 or +greater and running VMS 7.0 or greater + + truncate The following functions may or may not be implemented, depending on what type of socket support you've built into @@ -337,6 +350,7 @@ your copy of Perl: getsockopt, listen, recv, select(system call)*, send, setsockopt, shutdown, socket +=over 4 =item File tests @@ -366,6 +380,13 @@ only, and then manually check the appropriate bits, as defined by your C compiler's F, in the mode value it returns, if you need an approximation of the file's protections. +=item backticks + +Backticks create a subprocess, and pass the enclosed string +to it for execution as a DCL command. Since the subprocess is +created directly via C, any valid DCL command string +may be specified. + =item binmode FILEHANDLE The C operator will attempt to insure that no translation @@ -492,7 +513,7 @@ true, a warning message is printed, and C is returned. 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 +service 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.) @@ -500,6 +521,10 @@ 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 qx// + +See the entry on C above. + =item select (system call) If Perl was not built with socket support, the system call @@ -528,7 +553,12 @@ 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. Perl waits for the subprocess to complete before continuing -execution in the current process. +execution in the current process. As described in L, +the return value of C is a fake "status" which follows +POSIX semantics; see the description of C<$?> in this document +for more detail. The actual VMS exit status of the subprocess +is available in C<$^S> (as long as you haven't used another Perl +function that resets C<$?> and C<$^S> in the meantime). =item time @@ -605,8 +635,17 @@ and you invoked Perl with the C<-w> switch, a warning will be issued.) The FLAGS argument is ignored in all cases. +=back + =head1 Perl variables +The following VMS-specific information applies to the indicated +"special" Perl variables, in addition to the general information +in L. Where there is a conflict, this infrmation +takes precedence. + +=over 4 + =item %ENV Reading the elements of the %ENV array returns the @@ -624,12 +663,20 @@ list logical names. For instance, if you say 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 +The key C returns the current default device and directory specification, regardless of whether -there is a logical name DEFAULT defined.. +there is a logical name DEFAULT defined. If you try to +read an element of %ENV for which there is no corresponding +logical name, and for which no corresponding CLI symbol +exists (this is to identify "blocking" symbols only; to +manipulate CLI symbols, see L) then the key +will be looked up in the CRTL-local environment array, and +the corresponding value, if any returned. This lets you +get at C-specific keys like C, C,C, and +C, as well as other keys which may have been passed +directly into the C-specific array if Perl was called from +another C program using the version of execve() or execle() +present in recent revisions of the DECCRTL. Setting an element of %ENV defines a supervisor-mode logical name in the process logical name table. Cing or @@ -641,6 +688,23 @@ 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. +It is also not possible to delete an element from the +C-local environ array. + +Note that if you want to pass on any elements of the +C-local environ array to a subprocess which isn't +started by fork/exec, or isn't running a C program, you +can "promote" them to logical names in the current +process, which will then be inherited by all subprocesses, +by saying + + foreach my $key (qw[C-local keys you want promoted]) { + my $temp = $ENV{$key}; # read from C-local array + $ENV{$key} = $temp; # and define as logical name + } + +(You can't just say C<$ENV{$key} = $ENV{$key}>, since the +Perl optimizer is smart enough to elide the expression.) At present, the first time you iterate over %ENV using C, or C, you will incur a time penalty as all @@ -661,16 +725,6 @@ 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 @@ -692,6 +746,30 @@ is the value of vaxc$errno, and its string value is the corresponding VMS message string, as retrieved by sys$getmsg(). Setting C<$^E> sets vaxc$errno to the value specified. +=item $? + +The "status value" returned in C<$?> is synthesized from the +actual exit status of the subprocess in a way that approximates +POSIX wait(5) semantics, in order to allow Perl programs to +portably test for successful completion of subprocesses. The +low order 8 bits of C<$?> are always 0 under VMS, since the +termination status of a process may or may not have been +generated by an exception. The next 8 bits are derived from +severity portion of the subprocess' exit status: if the +severity was success or informational, these bits are all 0; +otherwise, they contain the severity value shifted left one bit. +As a result, C<$?> will always be zero if the subprocess' exit +status indicated successful completion, and non-zero if a +warning or error occurred. The actual VMS exit status may +be found in C<$^S> (q.v.). + +=item $^S + +Under VMS, this is the 32-bit VMS status value returned by the +last subprocess to complete. Unlink C<$?>, no manipulation +is done to make this look like a POSIX wait(5) value, so it +may be treated as a normal VMS status value. + =item $| Setting C<$|> for an I/O stream causes data to be flushed @@ -699,12 +777,25 @@ all the way to disk on each write (I not just to the underlying RMS buffers for a file). In other words, it's equivalent to calling fflush() and fsync() from C. +=back + +=head1 Standard modules with VMS-specific differences + +=head2 SDBM_File + +SDBM_File works peroperly on VMS. It has, however, one minor +difference. The database directory file created has a L<.sdbm_dir> +extension rather than a L<.dir> extension. L<.dir> files are VMS filesystem +directory files, and using them for other purposes could cause unacceptable +problems. + =head1 Revision date -This document was last updated on 28-Feb-1996, for Perl 5, -patchlevel 2. +This document was last updated on 26-Feb-1998, for Perl 5, +patchlevel 5. =head1 AUTHOR -Charles Bailey bailey@genetics.upenn.edu +Charles Bailey bailey@cor.newman.upenn.edu +Last revision by Dan Sugalski sugalskd@ous.edu