This is a live mirror of the Perl 5 development currently hosted at
perl 5.002_01: vms/
[perl5.git] / vms / perlvms.pod
e518068a 1=head1 NAME
3perlvms - VMS-specific documentation for Perl
a0d0e21e 6
7Gathered below are notes describing details of Perl 5's
8behavior on VMS. They are a supplement to the regular Perl 5
9documentation, so we have focussed on the ways in which Perl
105 functions differently under VMS than it does under Unix,
11and on the interactions between Perl and the rest of the
a0d0e21e 12operating system. We haven't tried to duplicate complete
748a9306 13descriptions of Perl features from the main Perl
a0d0e21e 14documentation, which can be found in the F<[.pod]>
748a9306 15subdirectory of the Perl distribution.
17We hope these notes will save you from confusion and lost
748a9306 18sleep when writing Perl scripts on VMS. If you find we've
19missed something you think should appear here, please don't
20hesitate to drop a line to
e518068a 22=head1 Organization of Perl Images
748a9306 23
e518068a 24=head2 Core Images
26During the installation process, three Perl images are produced.
27F<Miniperl.Exe> is an executable image which contains all of
28the basic functionality of Perl, but cannot take advantage of
29Perl extensions. It is used to generate several files needed
30to build the complete Perl and various extensions. Once you've
31finished installing Perl, you can delete this image.
33Most of the complete Perl resides in the shareable image
34F<PerlShr.Exe>, which provides a core to which the Perl executable
35image and all Perl extensions are linked. You should place this
36image in F<Sys$Share>, or define the logical name F<PerlShr> to
37translate to the full file specification of this image. It should
38be world readable. (Remember that if a user has execute only access
39to F<PerlShr>, VMS will treat it as if it were a privileged shareable
40image, and will therefore require all downstream shareable images to be
41INSTALLed, etc.)
44Finally, F<Perl.Exe> is an executable image containing the main
45entry point for Perl, as well as some initialization code. It
46should be placed in a public directory, and made world executable.
47In order to run Perl with command line arguments, you should
48define a foreign command to invoke this image.
50=head2 Perl Extensions
52Perl extensions are packages which provide both XS and Perl code
53to add new functionality to perl. (XS is a meta-language which
54simplifies writing C code which interacts with Perl, see
55L<perlapi> for more details.) The Perl code for an
56extension is treated like any other library module - it's
57made available in your script through the appropriate
58C<use> or C<require> statement, and usually defines a Perl
59package containing the extension.
61The portion of the extension provided by the XS code may be
62connected to the rest of Perl in either of two ways. In the
63B<static> configuration, the object code for the extension is
64linked directly into F<PerlShr.Exe>, and is initialized whenever
65Perl is invoked. In the B<dynamic> configuration, the extension's
66machine code is placed into a separate shareable image, which is
67mapped by Perl's DynaLoader when the extension is C<use>d or
68C<require>d in your script. This allows you to maintain the
69extension as a separate entity, at the cost of keeping track of the
70additional shareable image. Most extensions can be set up as either
71static or dynamic.
73The source code for an extension usually resides in its own
74directory. At least three files are generally provided:
75I<Extshortname>F<.xs> (where I<Extshortname> is the portion of
76the extension's name following the last C<::>), containing
77the XS code, I<Extshortname>F<.pm>, the Perl library module
78for the extension, and F<Makefile.PL>, a Perl script which uses
79the C<MakeMaker> library modules supplied with Perl to generate
80a F<Descrip.MMS> file for the extension.
e518068a 82=head2 Installing static extensions
84Since static extensions are incorporated directly into
85F<PerlShr.Exe>, you'll have to rebuild Perl to incorporate a
86new extension. You should edit the main F<Descrip.MMS> or F<Makefile>
87you use to build Perl, adding the extension's name to the C<ext>
88macro, and the extension's object file to the C<extobj> macro.
89You'll also need to build the extension's object file, either
90by adding dependencies to the main F<Descrip.MMS>, or using a
91separate F<Descrip.MMS> for the extension. Then, rebuild
92F<PerlShr.Exe> to incorporate the new code.
94Finally, you'll need to copy the extension's Perl library
95module to the F<[.>I<Extname>F<]> subdirectory under one
96of the directories in C<@INC>, where I<Extname> is the name
97of the extension, with all C<::> replaced by C<.> (e.g.
98the library module for extension Foo::Bar would be copied
99to a F<[.Foo.Bar]> subdirectory).
e518068a 101=head2 Installing dynamic extensions
103In general, the distributed kit for a Perl extension includes
104a file named Makefile.PL, which is a Perl program which is used
105to create a F<Descrip.MMS> file which can be used to build and
106install the files required by the extension. The kit should be
c07a80fd 107unpacked into a directory tree B<not> under the main Perl source
e518068a 108directory, and the procedure for building the extension is simply
e518068a 110 $ perl Makefile.PL ! Create Descrip.MMS
111 $ mmk ! Build necessary files
112 $ mmk test ! Run test code, if supplied
113 $ mmk install ! Install into public Perl tree
c07a80fd 115I<N.B.> The procedure by which extensions are built and
116tested creates several levels (at least 4) under the
117directory in which the extension's source files live.
118For this reason, you shouldn't nest the source directory
119too deeply in your directory structure, lest you eccedd RMS'
120maximum of 8 levels of subdirectory in a filespec. (You
121can use rooted logical names to get another 8 levels of
122nesting, if you can't place the files near the top of
123the physical directory structure.)
e518068a 124
125VMS support for this process in the current release of Perl
126is sufficient to handle most extensions. However, it does
127not yet recognize extra libraries required to build shareable
128images which are part of an extension, so these must be added
129to the linker options file for the extension by hand. For
130instance, if the F<PGPLOT> extension to Perl requires the
131F<PGPLOTSHR.EXE> shareable image in order to properly link
132the Perl extension, then the line C<PGPLOTSHR/Share> must
133be added to the linker options file F<PGPLOT.Opt> produced
134during the build process for the Perl extension.
136By default, the shareable image for an extension is placed
137in the F<[.Lib.Auto.I<Arch>.I<Extname>]> directory of the
138installed Perl directory tree (where I<Arch> is F<VMS_VAX> or
139F<VMS_AXP>, and I<Extname> is the name of the extension, with
140each C<::> translated to C<.>). However, it can be manually
141placed in any of several locations:
142 - the F<[.Lib.Auto.I<Extname>]> subdirectory of one of
143 the directories in C<@INC>, or
144 - one of the directories in C<@INC>, or
145 - a directory which the extensions Perl library module
146 passes to the DynaLoader when asking it to map
147 the shareable image, or
148 - F<Sys$Share> or F<Sys$Library>.
149If the shareable image isn't in any of these places, you'll need
150to define a logical name I<Extshortname>, where I<Extshortname>
151is the portion of the extension's name after the last C<::>, which
152translates to the full file specification of the shareable image.
154=head1 Installation
156Directions for building and installing Perl 5 can be found in
a0d0e21e 157the file F<ReadMe.VMS> in the main source directory of the
748a9306 158Perl distribution..
a0d0e21e 159
748a9306 160=head1 File specifications
a0d0e21e 161
748a9306 162We have tried to make Perl aware of both VMS-style and Unix-
163style file specifications wherever possible. You may use
164either style, or both, on the command line and in scripts,
165but you may not combine the two styles within a single fle
166specfication. Filenames are, of course, still case-
748a9306 167insensitive. For consistency, most Perl routines return
168filespecs using lower case latters only, regardless of the
169case used in the arguments passed to them. (This is true
748a9306 170only when running under VMS; Perl respects the case-
171sensitivity of OSs like Unix.)
748a9306 173We've tried to minimize the dependence of Perl library
174modules on Unix syntax, but you may find that some of these,
175as well as some scripts written for Unix systems, will
176require that you use Unix syntax, since they will assume that
177'/' is the directory separator, etc. If you find instances
748a9306 178of this in the Perl distribution itself, please let us know,
179so we can try to work around them.
748a9306 181=head1 Command line redirection
183Perl for VMS supports redirection of input and output on the
184command line, using a subset of Bourne shell syntax:
185 <F<file> reads stdin from F<file>,
186 >F<file> writes stdout to F<file>,
187 >>F<file> appends stdout to F<file>,
748a9306 188 2>F<file> writes stderr to F<file>, and
189 2>>F<file> appends stderr to F<file>.
191In addition, output may be piped to a subprocess, using the
192character '|'. Anything after this character on the command
193line is passed to a subprocess for execution; the subprocess
748a9306 194takes the output of Perl as its input.
196Finally, if the command line ends with '&', the entire
197command is run in the background as an asynchronous
748a9306 200=head1 Pipes
a0d0e21e 201
748a9306 202Input and output pipes to Perl filehandles are supported; the
203"file name" is passed to lib$spawn() for asynchronous
204execution. You should be careful to close any pipes you have
205opened in a Perl script, lest you leave any "orphaned"
206subprocesses around when Perl exits.
208You may also use backticks to invoke a DCL subprocess, whose
209output is used as the return value of the expression. The
210string between the backticks is passed directly to lib$spawn
748a9306 211as the command to execute. In this case, Perl will wait for
212the subprocess to complete before continuing.
748a9306 214=head1 Wildcard expansion
216File specifications containing wildcards are allowed both on
748a9306 217the command line and within Perl globs (e.g. <C<*.c>>). If
218the wildcard filespec uses VMS syntax, the resultant
219filespecs will follow VMS syntax; if a Unix-style filespec is
220passed in, Unix-style filespecs will be returned..
222If the wildcard filespec contains a device or directory
223specification, then the resultant filespecs will also contain
224a device and directory; otherwise, device and directory
225information are removed. VMS-style resultant filespecs will
226contain a full device and directory, while Unix-style
227resultant filespecs will contain only as much of a directory
228path as was present in the input filespec. For example, if
229your default directory is Perl_Root:[000000], the expansion
230of C<[.t]*.*> will yield filespecs like
231"perl_root:[t]base.dir", while the expansion of C<t/*/*> will
232yield filespecs like "t/base.dir". (This is done to match
233the behavior of glob expansion performed by Unix shells.)
235Similarly, the resultant filespec will the file version only
236if one was present in the input filespec.
238=head1 PERL5LIB and PERLLIB
240The PERL5LIB and PERLLIB logical names work as
241documented L<perl>, except that the element
242separator is '|' instead of ':'. The directory
243specifications may use either VMS or Unix syntax.
748a9306 245=head1 Perl functions
247As of the time this document was last revised, the following
748a9306 248Perl functions were implemented in the VMS port of Perl
249(functions marked with * are discussed in more detail below):
251 file tests*, abs, alarm, atan, binmode*, bless,
252 caller, chdir, chmod, chown, chomp, chop, chr,
c07a80fd 253 close, closedir, cos, crypt*, defined, delete,
254 die, do, each, endpwent, eof, eval, exec*, exists,
255 exit, exp, fileno, fork*, getc, getlogin, getpwent*,
256 getpwnam*, getpwuid*, glob, gmtime*, goto, grep, hex,
257 import, index, int, join, keys, kill*, last, lc,
258 lcfirst, length, local, localtime, log, m//, map,
259 mkdir, my, next, no, oct, open, opendir, ord, pack,
260 pipe, pop, pos, print, printf, push, q//, qq//, qw//,
261 qx//, quotemeta, rand, read, readdir, redo, ref, rename,
a0d0e21e 262 require, reset, return, reverse, rewinddir, rindex,
e518068a 263 rmdir, s///, scalar, seek, seekdir, select(internal),
264 select (system call)*, setpwent, shift, sin, sleep,
265 sort, splice, split, sprintf, sqrt, srand, stat,
266 study, substr, sysread, system*, syswrite, tell,
267 telldir, tie, time, times*, tr///, uc, ucfirst, umask,
268 undef, unlink*, unpack, untie, unshift, use, utime*,
269 values, vec, wait, waitpid*, wantarray, warn, write, y///
271The following functions were not implemented in the VMS port,
272and calling them produces a fatal error (usually) or
273undefined behavior (rarely, we hope):
c07a80fd 275 chroot, dbmclose, dbmopen, dump, fcntl, flock,
276 getpgrp, getppid, getpriority, getgrent, getgrgid,
277 getgrnam, setgrent, endgrent, ioctl, link, lstat,
278 msgctl, msgget, msgsend, msgrcv, readlink, semctl,
279 semget, semop, setpgrp, setpriority, shmctl, shmget,
280 shmread, shmwrite, socketpair, symlink, syscall, truncate
282The following functions may or may not be implemented,
283depending on what type of socket support you've built into
748a9306 284your copy of Perl:
285 accept, bind, connect, getpeername,
286 gethostbyname, getnetbyname, getprotobyname,
287 getservbyname, gethostbyaddr, getnetbyaddr,
288 getprotobynumber, getservbyport, gethostent,
289 getnetent, getprotoent, getservent, sethostent,
290 setnetent, setprotoent, setservent, endhostent,
291 endnetent, endprotoent, endservent, getsockname,
c07a80fd 292 getsockopt, listen, recv, select(system call)*,
293 send, setsockopt, shutdown, socket
296=item File tests
298The tests C<-b>, C<-B>, C<-c>, C<-C>, C<-d>, C<-e>, C<-f>,
299C<-o>, C<-M>, C<-s>, C<-S>, C<-t>, C<-T>, and C<-z> work as
300advertised. The return values for C<-r>, C<-w>, and C<-x>
301tell you whether you can actually access the file; this may
302not reflect the UIC-based file protections. Since real and
303effective UIC don't differ under VMS, C<-O>, C<-R>, C<-W>,
304and C<-X> are equivalent to C<-o>, C<-r>, C<-w>, and C<-x>.
305Similarly, several other tests, including C<-A>, C<-g>, C<-k>,
306C<-l>, C<-p>, and C<-u>, aren't particularly meaningful under
307VMS, and the values returned by these tests reflect whatever
308your CRTL C<stat()> routine does to the equivalent bits in the
309st_mode field. Finally, C<-d> returns true if passed a device
310specification without an explicit directory (e.g. C<DUA1:>), as
311well as if passed a directory.
313=item binmode FILEHANDLE
315The C<binmode> operator has no effect under VMS. It will
316return TRUE whenever called, but will not affect I/O
317operations on the filehandle given as its argument.
c07a80fd 319=item crypt PLAINTEXT, USER
321The C<crypt> operator uses the C<sys$hash_password> system
322service to generate the hashed representation of PLAINTEXT.
323If USER is a valid username, the algorithm and salt values
324are taken from that user's UAF record. If it is not, then
325the preferred algorithm and a salt of 0 are used. The
326quadword encrypted value is returned as an 8-character string.
328The value returned by C<crypt> may be compared against
329the encrypted password from the UAF returned by the C<getpw*>
330functions, in order to authenticate users. If you're
331going to do this, remember that the encrypted password in
332the UAF was generated using uppercase username and
333password strings; you'll have to upcase the arguments to
334C<crypt> to insure that you'll get the proper value:
336 sub validate_passwd {
337 my($user,$passwd) = @_;
338 my($pwdhash);
339 if ( !($pwdhash = (getpwnam($user))[1]) ||
340 $pwdhash ne crypt("\U$passwd","\U$name") ) {
341 intruder_alert($name);
342 }
343 return 1;
344 }
748a9306 346=item exec LIST
a0d0e21e 347
348The C<exec> operator behaves in one of two different ways.
349If called after a call to C<fork>, it will invoke the CRTL
350C<execv()> routine, passing its arguments to the subprocess
351created by C<fork> for execution. In this case, it is
352subject to all limitations that affect C<execv()>. (In
353particular, this usually means that the command executed in
354the subprocess must be an image compiled from C source code,
355and that your options for passing file descriptors and signal
356handlers to the subprocess are limited.)
358If the call to C<exec> does not follow a call to C<fork>, it
359will cause Perl to exit, and to invoke the command given as
360an argument to C<exec> via C<lib$do_command>. If the argument
361begins with a '$' (other than as part of a filespec), then it
362is executed as a DCL command. Otherwise, the first token on
363the command line is treated as the filespec of an image to
364run, and an attempt is made to invoke it (using F<.Exe> and
365the process defaults to expand the filespec) and pass the
748a9306 366rest of C<exec>'s argument to it as parameters.
a0d0e21e 367
368You can use C<exec> in both ways within the same script, as
369long as you call C<fork> and C<exec> in pairs. Perl
370keeps track of how many times C<fork> and C<exec> have been
371called, and will call the CRTL C<execv()> routine if there have
372previously been more calls to C<fork> than to C<exec>.
374=item fork
376The C<fork> operator works in the same way as the CRTL
377C<vfork()> routine, which is quite different under VMS than
378under Unix. Specifically, while C<fork> returns 0 after it
379is called and the subprocess PID after C<exec> is called, in
380both cases the thread of execution is within the parent
381process, so there is no opportunity to perform operations in
748a9306 382the subprocess before calling C<exec>.
a0d0e21e 383
748a9306 384In general, the use of C<fork> and C<exec> to create
a0d0e21e 385subprocess is not recommended under VMS; wherever possible,
386use the C<system> operator or piped filehandles instead.
388=item getpwent
c07a80fd 389
748a9306 390=item getpwnam
c07a80fd 391
392=item getpwuid
394These operators obtain the information described in L<perlfunc>,
395if you have the privileges necessary to retrieve the named user's
396UAF information via C<sys$getuai>. If not, then only the C<$name>,
397C<$uid>, and C<$gid> items are returned. The C<$dir> item contains
398the login directory in VMS syntax, while the C<$comment> item
399contains the login directory in Unix syntax. The C<$gcos> item
400contains the owner field from the UAF record. The C<$quota>
401item is not used.
a0d0e21e 402
e518068a 403=item gmtime
405The C<gmtime> operator will function properly if you have a
406working CRTL C<gmtime()> routine, or if the logical name
407SYS$TIMEZONE_DIFFERENTIAL is defined as the number of seconds
408which must be added to UTC to yield local time. (This logical
409name is defined automatically if you are running a version of
410VMS with built-in UTC support.) If neither of these cases is
411true, a warning message is printed, and C<undef> is returned.
413=item kill
415In most cases, C<kill> kill is implemented via the CRTL's C<kill()>
416function, so it will behave according to that function's
417documentation. If you send a SIGKILL, however, the $DELPRC system
418service is is called directly. This insures that the target
419process is actually deleted, if at all possible. (The CRTL's C<kill()>
420function is presently implemented via $FORCEX, which is ignored by
421supervisor-mode images like DCL.)
423Also, negative signal values don't do anything special under
424VMS; they're just converted to the corresponding positive value.
426=item select (system call)
428If Perl was not built with socket support, the system call
429version of C<select> is not available at all. If socket
430support is present, then the system call version of
431C<select> functions only for file descriptors attached
432to sockets. It will not provide information about regular
433files or pipes, since the CRTL C<select()> routine does not
434provide this functionality.
748a9306 436=item stat EXPR
a0d0e21e 437
438Since VMS keeps track of files according to a different scheme
439than Unix, it's not really possible to represent the file's ID
440in the C<st_dev> and C<st_ino> fields of a C<struct stat>. Perl
441tries its best, though, and the values it uses are pretty unlikely
442to be the same for two different files. We can't guarantee this,
443though, so caveat scriptor.
445=item system LIST
447The C<system> operator creates a subprocess, and passes its
a0d0e21e 448arguments to the subprocess for execution as a DCL command.
e518068a 449Since the subprocess is created directly via C<lib$spawn()>, any
450valid DCL command string may be specified. If LIST consists
451of the empty string, C<system> spawns an interactive DCL subprocess,
452in the same fashion as typiing B<SPAWN> at the DCL prompt.
453Perl waits for the subprocess to complete before continuing
454execution in the current process.
456=item times
458The array returned by the C<times> operator is divided up
459according to the same rules the CRTL C<times()> routine.
460Therefore, the "system time" elements will always be 0, since
461there is no difference between "user time" and "system" time
462under VMS, and the time accumulated by subprocess may or may
463not appear separately in the "child time" field, depending on
464whether L<times> keeps track of subprocesses separately. Note
465especially that the VAXCRTL (at least) keeps track only of
466subprocesses spawned using L<fork> and L<exec>; it will not
467accumulate the times of suprocesses spawned via pipes, L<system>,
468or backticks.
470=item unlink LIST
472C<unlink> will delete the highest version of a file only; in
473order to delete all versions, you need to say
474 1 while (unlink LIST);
475You may need to make this change to scripts written for a
476Unix system which expect that after a call to C<unlink>,
477no files with the names passed to C<unlink> will exist.
478(Note: This can be changed at compile time; if you
479C<use Config> and C<$Config{'d_unlink_all_versions'}> is
480C<define>, then C<unlink> will delete all versions of a
481file on the first call.)
483C<unlink> will delete a file if at all possible, even if it
484requires changing file protection (though it won't try to
485change the protection of the parent directory). You can tell
486whether you've got explicit delete access to a file by using the
487C<VMS::Filespec::candelete> operator. For instance, in order
488to delete only files to which you have delete access, you could
489say something like
490 sub safe_unlink {
491 my($file,$num);
492 foreach $file (@_) {
493 next unless VMS::Filespec::candelete($file);
494 $num += unlink $file;
495 }
496 $num;
497 }
498Finally, if C<unlink> has to change the file protection to
499delete the file, and you interrupt it in midstream, the file
500may be left intact, but with a changed ACL allowing you delete
503=item utime LIST
505Since ODS-2, the VMS file structure for disk files, does not keep
506track of access times, this operator changes only the modification
507time of the file (VMS revision date).
509=item waitpid PID,FLAGS
511If PID is a subprocess started by a piped L<open>, C<waitpid>
512will wait for that subprocess, and return its final
513status value. If PID is a subprocess created in some other way
514(e.g. SPAWNed before Perl was invoked), or is not a subprocess of
515the current process, C<waitpid> will check once per second whether
516the process has completed, and when it has, will return 0. (If PID
517specifies a process that isn't a subprocess of the current process,
518and you invoked Perl with the C<-w> switch, a warning will be issued.)
520The FLAGS argument is ignored in all cases.
a0d0e21e 521
522=head1 Perl variables
524=item %ENV
526Reading the elements of the %ENV array returns the
527translation of the logical name specified by the key,
528according to the normal search order of access modes and
529logical name tables. If you append a semicolon to the
530logical name, followed by an integer, that integer is
531used as the translation index for the logical name,
532so that you can look up successive values for search
533list logical names. For instance, if you say
535 $ Define STORY once,upon,a,time,there,was
536 $ perl -e "for ($i = 0; $i <= 6; $i++) " -
537 _$ -e "{ print $ENV{'foo'.$i},' '}"
539Perl will print C<ONCE UPON A TIME THERE WAS>.
541The %ENV keys C<home>, C<path>,C<term>, and C<user>
542return the CRTL "environment variables" of the same
543names, if these logical names are not defined. The
544key C<default> returns the current default device
545and directory specification, regardless of whether
546there is a logical name DEFAULT defined..
548Setting an element of %ENV defines a supervisor-mode logical
549name in the process logical name table. C<Undef>ing or
550C<delete>ing an element of %ENV deletes the equivalent user-
551mode or supervisor-mode logical name from the process logical
552name table. If you use C<undef>, the %ENV element remains
553empty. If you use C<delete>, another attempt is made at
554logical name translation after the deletion, so an inner-mode
555logical name or a name in another logical name table will
556replace the logical name just deleted. It is not possible
557at present to define a search list logical name via %ENV.
559In all operations on %ENV, the key string is treated as if it
560were entirely uppercase, regardless of the case actually
561specified in the Perl expression.
563=item $?
565Since VMS status values are 32 bits wide, the value of C<$?>
566is simply the final status value of the last subprocess to
567complete. This differs from the behavior of C<$?> under Unix,
568and under VMS' POSIX environment, in that the low-order 8 bits
569of C<$?> do not specify whether the process terminated normally
570or due to a signal, and you do not need to shift C<$?> 8 bits
571to the right in order to find the process' exit status.
573=item $!
575The string value of C<$!> is that returned by the CRTL's
576strerror() function, so it will include the VMS message for
577VMS-specific errors. The numeric value of C<$!> is the
578value of C<errno>, except if errno is EVMSERR, in which
579case C<$!> contains the value of vaxc$errno. Setting C<$!>
580always sets errno to the value specified, and sets vaxc$errno
581to 4 (NONAME-F-NOMSG).
748a9306 583=head1 Revision date
a0d0e21e 584
748a9306 585This document was last updated on 16-Dec-1994, for Perl 5,
e518068a 586patchlevel 2.
588=head1 AUTHOR
590Charles Bailey