X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=vms%2Fperlvms.pod;h=c599e5834cd1dd13801b84719e1bb113aeffd983;hb=e92c4225b24535b7128dd90f6a3e01d0abc79a1d;hp=b7804f0b421671c7267e0f95985a1590e0c4b2d7;hpb=1c9f8daada8b588a614aea510638b830b9cad417;p=p5sagit%2Fp5-mst-13.2.git diff --git a/vms/perlvms.pod b/vms/perlvms.pod index b7804f0..c599e58 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,17 @@ 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 +copy is given, then inplace editing creates a new version of +a file; the existing copy is not deleted. (Note that if +an extension is given, an existing file is renamed to the backup +file, as is the case under other operating systems, so it does +not remain as a previous version under the original filename.) + =item -S If the C<-S> switch is present I the script name does @@ -277,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*, @@ -293,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, @@ -328,6 +345,7 @@ your copy of Perl: getsockopt, listen, recv, select(system call)*, send, setsockopt, shutdown, socket +=over 4 =item File tests @@ -357,6 +375,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 @@ -483,7 +508,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.) @@ -491,6 +516,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 @@ -519,7 +548,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 @@ -596,8 +630,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 @@ -611,7 +654,7 @@ 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},' '}" + _$ -e "{ print $ENV{'story;'.$i},' '}" Perl will print C. @@ -633,20 +676,25 @@ 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. +At present, the first time you iterate over %ENV using +C, or C, you will incur a time penalty as all +logical names are read, in order to fully populate %ENV. +Subsequent iterations will not reread logical names, so they +won't be as slow, but they also won't reflect any changes +to logical name tables caused by other programs. The C +operator is special: it returns each element I in +%ENV, but doesn't go out and look for more. Therefore, if +you've previously used C or C, you'll see all +the logical names visible to your process, and if not, you'll +see only the names you've looked up so far. (This is a +consequence of the way C is implemented now, and it +may change in the future, so it wouldn't be a good idea +to rely on it too much.) + 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 @@ -668,6 +716,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 @@ -675,6 +747,8 @@ 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 Revision date This document was last updated on 28-Feb-1996, for Perl 5,