This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Re: smart match: array ~~ hash
[perl5.git] / vms / perlvms.pod
CommitLineData
e518068a 1=head1 NAME
2
3perlvms - VMS-specific documentation for Perl
4
5=head1 DESCRIPTION
a0d0e21e 6
748a9306
LW
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.
a0d0e21e
LW
16
17We hope these notes will save you from confusion and lost
748a9306 18sleep when writing Perl scripts on VMS. If you find we've
a0d0e21e 19missed something you think should appear here, please don't
9bc98430 20hesitate to drop a line to vmsperl@perl.org.
a0d0e21e 21
4e592037 22=head1 Installation
23
24Directions for building and installing Perl 5 can be found in
25the file F<README.vms> in the main source directory of the
26Perl distribution..
27
e518068a 28=head1 Organization of Perl Images
748a9306 29
e518068a 30=head2 Core Images
748a9306
LW
31
32During the installation process, three Perl images are produced.
33F<Miniperl.Exe> is an executable image which contains all of
34the basic functionality of Perl, but cannot take advantage of
35Perl extensions. It is used to generate several files needed
36to build the complete Perl and various extensions. Once you've
37finished installing Perl, you can delete this image.
38
39Most of the complete Perl resides in the shareable image
40F<PerlShr.Exe>, which provides a core to which the Perl executable
41image and all Perl extensions are linked. You should place this
42image in F<Sys$Share>, or define the logical name F<PerlShr> to
43translate to the full file specification of this image. It should
44be world readable. (Remember that if a user has execute only access
45to F<PerlShr>, VMS will treat it as if it were a privileged shareable
46image, and will therefore require all downstream shareable images to be
47INSTALLed, etc.)
48
49
50Finally, F<Perl.Exe> is an executable image containing the main
51entry point for Perl, as well as some initialization code. It
52should be placed in a public directory, and made world executable.
53In order to run Perl with command line arguments, you should
54define a foreign command to invoke this image.
55
56=head2 Perl Extensions
57
58Perl extensions are packages which provide both XS and Perl code
59to add new functionality to perl. (XS is a meta-language which
60simplifies writing C code which interacts with Perl, see
2ceaccd7 61L<perlxs> for more details.) The Perl code for an
748a9306
LW
62extension is treated like any other library module - it's
63made available in your script through the appropriate
64C<use> or C<require> statement, and usually defines a Perl
65package containing the extension.
66
67The portion of the extension provided by the XS code may be
68connected to the rest of Perl in either of two ways. In the
69B<static> configuration, the object code for the extension is
70linked directly into F<PerlShr.Exe>, and is initialized whenever
71Perl is invoked. In the B<dynamic> configuration, the extension's
72machine code is placed into a separate shareable image, which is
73mapped by Perl's DynaLoader when the extension is C<use>d or
74C<require>d in your script. This allows you to maintain the
75extension as a separate entity, at the cost of keeping track of the
76additional shareable image. Most extensions can be set up as either
77static or dynamic.
78
79The source code for an extension usually resides in its own
80directory. At least three files are generally provided:
81I<Extshortname>F<.xs> (where I<Extshortname> is the portion of
82the extension's name following the last C<::>), containing
83the XS code, I<Extshortname>F<.pm>, the Perl library module
84for the extension, and F<Makefile.PL>, a Perl script which uses
85the C<MakeMaker> library modules supplied with Perl to generate
86a F<Descrip.MMS> file for the extension.
87
e518068a 88=head2 Installing static extensions
748a9306
LW
89
90Since static extensions are incorporated directly into
91F<PerlShr.Exe>, you'll have to rebuild Perl to incorporate a
92new extension. You should edit the main F<Descrip.MMS> or F<Makefile>
93you use to build Perl, adding the extension's name to the C<ext>
94macro, and the extension's object file to the C<extobj> macro.
95You'll also need to build the extension's object file, either
96by adding dependencies to the main F<Descrip.MMS>, or using a
97separate F<Descrip.MMS> for the extension. Then, rebuild
98F<PerlShr.Exe> to incorporate the new code.
99
100Finally, you'll need to copy the extension's Perl library
101module to the F<[.>I<Extname>F<]> subdirectory under one
102of the directories in C<@INC>, where I<Extname> is the name
103of the extension, with all C<::> replaced by C<.> (e.g.
104the library module for extension Foo::Bar would be copied
105to a F<[.Foo.Bar]> subdirectory).
106
e518068a 107=head2 Installing dynamic extensions
108
109In general, the distributed kit for a Perl extension includes
110a file named Makefile.PL, which is a Perl program which is used
111to create a F<Descrip.MMS> file which can be used to build and
112install the files required by the extension. The kit should be
c07a80fd 113unpacked into a directory tree B<not> under the main Perl source
e518068a 114directory, and the procedure for building the extension is simply
115
e518068a 116 $ perl Makefile.PL ! Create Descrip.MMS
117 $ mmk ! Build necessary files
118 $ mmk test ! Run test code, if supplied
119 $ mmk install ! Install into public Perl tree
120
c07a80fd 121I<N.B.> The procedure by which extensions are built and
122tested creates several levels (at least 4) under the
123directory in which the extension's source files live.
d7f8936a 124For this reason if you are running a version of VMS prior
773da73d
JH
125to V7.1 you shouldn't nest the source directory
126too deeply in your directory structure lest you exceed RMS'
c07a80fd 127maximum of 8 levels of subdirectory in a filespec. (You
128can use rooted logical names to get another 8 levels of
129nesting, if you can't place the files near the top of
130the physical directory structure.)
e518068a 131
132VMS support for this process in the current release of Perl
133is sufficient to handle most extensions. However, it does
134not yet recognize extra libraries required to build shareable
135images which are part of an extension, so these must be added
136to the linker options file for the extension by hand. For
137instance, if the F<PGPLOT> extension to Perl requires the
138F<PGPLOTSHR.EXE> shareable image in order to properly link
139the Perl extension, then the line C<PGPLOTSHR/Share> must
140be added to the linker options file F<PGPLOT.Opt> produced
141during the build process for the Perl extension.
142
773da73d
JH
143By default, the shareable image for an extension is placed in
144the F<[.lib.site_perl.auto>I<Arch>.I<Extname>F<]> directory of the
e518068a 145installed Perl directory tree (where I<Arch> is F<VMS_VAX> or
bbce6d69 146F<VMS_AXP>, and I<Extname> is the name of the extension, with
147each C<::> translated to C<.>). (See the MakeMaker documentation
148for more details on installation options for extensions.)
4e592037 149However, it can be manually placed in any of several locations:
773da73d
JH
150
151=over 4
152
153=item *
154
155the F<[.Lib.Auto.>I<Arch>I<$PVers>I<Extname>F<]> subdirectory
156of one of the directories in C<@INC> (where I<PVers>
157is the version of Perl you're using, as supplied in C<$]>,
158with '.' converted to '_'), or
159
160=item *
161
162one of the directories in C<@INC>, or
163
164=item *
165
166a directory which the extensions Perl library module
167passes to the DynaLoader when asking it to map
168the shareable image, or
169
170=item *
171
172F<Sys$Share> or F<Sys$Library>.
173
174=back
175
748a9306
LW
176If the shareable image isn't in any of these places, you'll need
177to define a logical name I<Extshortname>, where I<Extshortname>
178is the portion of the extension's name after the last C<::>, which
179translates to the full file specification of the shareable image.
180
4e592037 181=head1 File specifications
748a9306 182
4e592037 183=head2 Syntax
a0d0e21e 184
748a9306 185We have tried to make Perl aware of both VMS-style and Unix-
a0d0e21e
LW
186style file specifications wherever possible. You may use
187either style, or both, on the command line and in scripts,
39aca757 188but you may not combine the two styles within a single file
1c9f8daa 189specification. VMS Perl interprets Unix pathnames in much
190the same way as the CRTL (I<e.g.> the first component of
191an absolute path is read as the device name for the
192VMS file specification). There are a set of functions
193provided in the C<VMS::Filespec> package for explicit
194interconversion between VMS and Unix syntax; its
195documentation provides more details.
196
9296fdfa 197Perl is now in the process of evolving to follow the setting of
fb38d079 198the DECC$* feature logical names in the interpretation of UNIX pathnames.
9296fdfa
JM
199This is still a work in progress.
200
201For handling extended characters, and case sensitivity, as long as
202DECC$POSIX_COMPLIANT_PATHNAMES, DECC$FILENAME_UNIX_REPORT, and
203DECC$FILENAME_UNIX_ONLY are not set, then the older Perl behavior
204for conversions of file specifications from UNIX to VMS is followed,
fb38d079 205except that VMS paths with concealed rooted logical names are now
9296fdfa
JM
206translated correctly to UNIX paths.
207
208With those features set, then new routines may handle the translation,
209because some of the rules are different. The presence of ./.../
210in a UNIX path is no longer translated to the VMS [...]. It will
211translate to [.^.^.^.]. To be compatible with what MakeMaker expects,
212if a VMS path can not be translated to a UNIX path when unixify
213is called, it is passed through unchanged. So unixify("[...]") will
214return "[...]".
215
216The handling of extended characters will also be better with the
217newer translation routines. But more work is needed to fully support
218extended file syntax names. In particular, at this writing Pathtools
219can not deal with directories containing some extended characters.
220
221There are several ambiguous cases where a conversion routine can not
222determine if an input filename is in UNIX format or in VMS format,
223since now both VMS UNIX file specifications can have characters in
224them that could be mistaken for syntax delimiters of the other type.
225So some pathnames simply can not be used in a mode that allows either
226type of pathname to be present.
227
228Perl will tend to assume that an ambiguous filename is in UNIX format.
229
230Allowing "." as a version delimiter is simply incompatible with
231determining if a pathname is already VMS format or UNIX with the
232extended file syntax. There is no way to know if "perl-5.8.6" that
233TAR produces is a UNIX "perl-5.8.6" or a VMS "perl-5.8;6" when
234passing it to unixify() or vmsify().
235
236The DECC$FILENAME_UNIX_REPORT or the DECC$FILENAME_UNIX_ONLY logical
237names control how Perl interprets filenames.
238
239The DECC$FILENAME_UNIX_ONLY setting has not been tested at this time.
240Perl uses traditional OpenVMS file specifications internally and in
241the test harness, so this mode may have limited use, or require more
242changes to make usable.
243
244Everything about DECC$FILENAME_UNIX_REPORT should be assumed to apply
245to DECC$FILENAME_UNIX_ONLY mode. The DECC$FILENAME_UNIX_ONLY differs
246in that it expects all filenames passed to the C runtime to be already
247in UNIX format.
248
249Again, currently most of the core Perl modules have not yet been updated
250to understand that VMS is not as limited as it use to be. Fixing that
251is a work in progress.
252
253The logical name DECC$POSIX_COMPLIANT_PATHNAMES is new with the
254RMS Symbolic Link SDK. This version of Perl does not support it being set.
255
256
257Filenames are case-insensitive on VAX, and on ODS-2 formatted
258volumes on ALPHA and I64.
259
260On ODS-5 volumes filenames are case preserved and on newer
261versions of OpenVMS can be optionally case sensitive.
262
263On ALPHA and I64, Perl is in the process of being changed to follow the
264process case sensitivity setting to report if the file system is case
265sensitive.
266
267Perl programs should not assume that VMS is case blind, or that
268filenames will be in lowercase.
269
270Programs should use the File::Spec:case_tolerant setting to determine
271the state, and not the $^O setting.
272
273For consistency, when the above feature is clear and when not
fb38d079 274otherwise overridden by DECC feature logical names, most Perl routines
9296fdfa
JM
275return file specifications using lower case letters only,
276regardless of the case used in the arguments passed to them.
277(This is true only when running under VMS; Perl respects the
278case-sensitivity of OSs like Unix.)
a0d0e21e 279
748a9306 280We've tried to minimize the dependence of Perl library
a0d0e21e
LW
281modules on Unix syntax, but you may find that some of these,
282as well as some scripts written for Unix systems, will
283require that you use Unix syntax, since they will assume that
4e592037 284'/' is the directory separator, I<etc.> If you find instances
748a9306 285of this in the Perl distribution itself, please let us know,
a0d0e21e
LW
286so we can try to work around them.
287
9296fdfa
JM
288Also when working on Perl programs on VMS, if you need a syntax
289in a specific operating system format, then you need to either
290check the appropriate DECC$ feature logical, or call a conversion
291routine to force it to that format.
292
4e592037 293=head2 Wildcard expansion
294
295File specifications containing wildcards are allowed both on
07698885 296the command line and within Perl globs (e.g. C<E<lt>*.cE<gt>>). If
4e592037 297the wildcard filespec uses VMS syntax, the resultant
298filespecs will follow VMS syntax; if a Unix-style filespec is
299passed in, Unix-style filespecs will be returned.
773da73d
JH
300Similar to the behavior of wildcard globbing for a Unix shell,
301one can escape command line wildcards with double quotation
302marks C<"> around a perl program command line argument. However,
303owing to the stripping of C<"> characters carried out by the C
304handling of argv you will need to escape a construct such as
305this one (in a directory containing the files F<PERL.C>, F<PERL.EXE>,
306F<PERL.H>, and F<PERL.OBJ>):
307
308 $ perl -e "print join(' ',@ARGV)" perl.*
309 perl.c perl.exe perl.h perl.obj
310
311in the following triple quoted manner:
312
313 $ perl -e "print join(' ',@ARGV)" """perl.*"""
314 perl.*
4e592037 315
773da73d
JH
316In both the case of unquoted command line arguments or in calls
317to C<glob()> VMS wildcard expansion is performed. (csh-style
aa779de1 318wildcard expansion is available if you use C<File::Glob::glob>.)
4e592037 319If the wildcard filespec contains a device or directory
320specification, then the resultant filespecs will also contain
321a device and directory; otherwise, device and directory
322information are removed. VMS-style resultant filespecs will
323contain a full device and directory, while Unix-style
324resultant filespecs will contain only as much of a directory
325path as was present in the input filespec. For example, if
326your default directory is Perl_Root:[000000], the expansion
327of C<[.t]*.*> will yield filespecs like
328"perl_root:[t]base.dir", while the expansion of C<t/*/*> will
329yield filespecs like "t/base.dir". (This is done to match
330the behavior of glob expansion performed by Unix shells.)
331
332Similarly, the resultant filespec will contain the file version
333only if one was present in the input filespec.
334
9296fdfa 335
4e592037 336=head2 Pipes
337
338Input and output pipes to Perl filehandles are supported; the
339"file name" is passed to lib$spawn() for asynchronous
340execution. You should be careful to close any pipes you have
341opened in a Perl script, lest you leave any "orphaned"
342subprocesses around when Perl exits.
343
344You may also use backticks to invoke a DCL subprocess, whose
345output is used as the return value of the expression. The
aa779de1
CB
346string between the backticks is handled as if it were the
347argument to the C<system> operator (see below). In this case,
348Perl will wait for the subprocess to complete before continuing.
4e592037 349
376ae1f1
PP
350The mailbox (MBX) that perl can create to communicate with a pipe
351defaults to a buffer size of 512. The default buffer size is
1506e54c 352adjustable via the logical name PERL_MBX_SIZE provided that the
376ae1f1
PP
353value falls between 128 and the SYSGEN parameter MAXBUF inclusive.
354For example, to double the MBX size from the default within
1506e54c 355a Perl program, use C<$ENV{'PERL_MBX_SIZE'} = 1024;> and then
376ae1f1
PP
356open and use pipe constructs. An alternative would be to issue
357the command:
358
359 $ Define PERL_MBX_SIZE 1024
360
361before running your wide record pipe program. A larger value may
362improve performance at the expense of the BYTLM UAF quota.
363
4e592037 364=head1 PERL5LIB and PERLLIB
365
39aca757 366The PERL5LIB and PERLLIB logical names work as documented in L<perl>,
4e592037 367except that the element separator is '|' instead of ':'. The
368directory specifications may use either VMS or Unix syntax.
369
17d4810c
JM
370=head1 The Perl Forked Debugger
371
372The Perl forked debugger places the debugger commands and output in a
373separate X-11 terminal window so that commands and output from multiple
374processes are not mixed together.
375
376Perl on VMS supports an emulation of the forked debugger when Perl is
377run on a VMS system that has X11 support installed.
378
379To use the forked debugger, you need to have the default display set to an
380X-11 Server and some environment variables set that Unix expects.
381
382The forked debugger requires the environment variable C<TERM> to be C<xterm>,
383and the environment variable C<DISPLAY> to exist. C<xterm> must be in
384lower case.
385
386 $define TERM "xterm"
387
388 $define DISPLAY "hostname:0.0"
389
390Currently the value of C<DISPLAY> is ignored. It is recommended that it be set
391to be the hostname of the display, the server and screen in UNIX notation. In
392the future the value of DISPLAY may be honored by Perl instead of using the
393default display.
394
395It may be helpful to always use the forked debugger so that script I/O is
396separated from debugger I/O. You can force the debugger to be forked by
397assigning a value to the logical name <PERLDB_PIDS> that is not a process
398identification number.
399
400 $define PERLDB_PIDS XXXX
401
402
9c1171d1
JM
403=head1 PERL_VMS_EXCEPTION_DEBUG
404
405The PERL_VMS_EXCEPTION_DEBUG being defined as "ENABLE" will cause the VMS
406debugger to be invoked if a fatal exception that is not otherwise
407handled is raised. The purpose of this is to allow debugging of
408internal Perl problems that would cause such a condition.
409
410This allows the programmer to look at the execution stack and variables to
411find out the cause of the exception. As the debugger is being invoked as
412the Perl interpreter is about to do a fatal exit, continuing the execution
413in debug mode is usally not practical.
414
415Starting Perl in the VMS debugger may change the program execution
416profile in a way that such problems are not reproduced.
417
418The C<kill> function can be used to test this functionality from within
419a program.
420
421In typical VMS style, only the first letter of the value of this logical
422name is actually checked in a case insensitive mode, and it is considered
423enabled if it is the value "T","1" or "E".
424
425This logical name must be defined before Perl is started.
426
4e592037 427=head1 Command line
428
429=head2 I/O redirection and backgrounding
a0d0e21e
LW
430
431Perl for VMS supports redirection of input and output on the
432command line, using a subset of Bourne shell syntax:
55497cff 433
773da73d 434=over 4
07698885
RGS
435
436=item *
437
438C<E<lt>file> reads stdin from C<file>,
439
440=item *
441
442C<E<gt>file> writes stdout to C<file>,
443
444=item *
445
446C<E<gt>E<gt>file> appends stdout to C<file>,
447
448=item *
449
2fde0ff0 450C<2E<gt>file> writes stderr to C<file>,
07698885
RGS
451
452=item *
453
2fde0ff0
RGS
454C<2E<gt>E<gt>file> appends stderr to C<file>, and
455
456=item *
457
458C<< 2>&1 >> redirects stderr to stdout.
07698885
RGS
459
460=back
a0d0e21e
LW
461
462In addition, output may be piped to a subprocess, using the
463character '|'. Anything after this character on the command
464line is passed to a subprocess for execution; the subprocess
748a9306 465takes the output of Perl as its input.
a0d0e21e
LW
466
467Finally, if the command line ends with '&', the entire
468command is run in the background as an asynchronous
469subprocess.
470
4e592037 471=head2 Command line switches
a0d0e21e 472
4e592037 473The following command line switches behave differently under
474VMS than described in L<perlrun>. Note also that in order
475to pass uppercase switches to Perl, you need to enclose
476them in double-quotes on the command line, since the CRTL
477downcases all unquoted strings.
a0d0e21e 478
9296fdfa
JM
479On newer 64 bit versions of OpenVMS, a process setting now
480controls if the quoting is needed to preserve the case of
481command line arguments.
482
55497cff 483=over 4
484
edc7bc49
CB
485=item -i
486
487If the C<-i> switch is present but no extension for a backup
488copy is given, then inplace editing creates a new version of
489a file; the existing copy is not deleted. (Note that if
490an extension is given, an existing file is renamed to the backup
491file, as is the case under other operating systems, so it does
492not remain as a previous version under the original filename.)
493
4e592037 494=item -S
a0d0e21e 495
376ae1f1
PP
496If the C<"-S"> or C<-"S"> switch is present I<and> the script
497name does not contain a directory, then Perl translates the
498logical name DCL$PATH as a searchlist, using each translation
499as a directory in which to look for the script. In addition,
4e592037 500if no file type is specified, Perl looks in each directory
501for a file matching the name specified, with a blank type,
502a type of F<.pl>, and a type of F<.com>, in that order.
a0d0e21e 503
4e592037 504=item -u
748a9306 505
4e592037 506The C<-u> switch causes the VMS debugger to be invoked
507after the Perl program is compiled, but before it has
508run. It does not create a core dump file.
748a9306 509
55497cff 510=back
511
748a9306 512=head1 Perl functions
a0d0e21e
LW
513
514As of the time this document was last revised, the following
748a9306 515Perl functions were implemented in the VMS port of Perl
a0d0e21e
LW
516(functions marked with * are discussed in more detail below):
517
4fdae800 518 file tests*, abs, alarm, atan, backticks*, binmode*, bless,
a0d0e21e 519 caller, chdir, chmod, chown, chomp, chop, chr,
c07a80fd 520 close, closedir, cos, crypt*, defined, delete,
4e592037 521 die, do, dump*, each, endpwent, eof, eval, exec*,
41cbbefa 522 exists, exit, exp, fileno, getc, getlogin, getppid,
4e592037 523 getpwent*, getpwnam*, getpwuid*, glob, gmtime*, goto,
524 grep, hex, import, index, int, join, keys, kill*,
525 last, lc, lcfirst, length, local, localtime, log, m//,
526 map, mkdir, my, next, no, oct, open, opendir, ord, pack,
c07a80fd 527 pipe, pop, pos, print, printf, push, q//, qq//, qw//,
4fdae800 528 qx//*, quotemeta, rand, read, readdir, redo, ref, rename,
a0d0e21e 529 require, reset, return, reverse, rewinddir, rindex,
e518068a 530 rmdir, s///, scalar, seek, seekdir, select(internal),
531 select (system call)*, setpwent, shift, sin, sleep,
532 sort, splice, split, sprintf, sqrt, srand, stat,
533 study, substr, sysread, system*, syswrite, tell,
534 telldir, tie, time, times*, tr///, uc, ucfirst, umask,
535 undef, unlink*, unpack, untie, unshift, use, utime*,
536 values, vec, wait, waitpid*, wantarray, warn, write, y///
a0d0e21e
LW
537
538The following functions were not implemented in the VMS port,
539and calling them produces a fatal error (usually) or
540undefined behavior (rarely, we hope):
541
41cbbefa
CB
542 chroot, dbmclose, dbmopen, flock, fork*,
543 getpgrp, getpriority, getgrent, getgrgid,
c07a80fd 544 getgrnam, setgrent, endgrent, ioctl, link, lstat,
545 msgctl, msgget, msgsend, msgrcv, readlink, semctl,
546 semget, semop, setpgrp, setpriority, shmctl, shmget,
bf99883d
HM
547 shmread, shmwrite, socketpair, symlink, syscall
548
35b2760a
CB
549The following functions are available on Perls compiled with Dec C
5505.2 or greater and running VMS 7.0 or greater:
bf99883d
HM
551
552 truncate
a0d0e21e 553
35b2760a
CB
554The following functions are available on Perls built on VMS 7.2 or
555greater:
556
557 fcntl (without locking)
558
a0d0e21e
LW
559The following functions may or may not be implemented,
560depending on what type of socket support you've built into
748a9306 561your copy of Perl:
4e592037 562
a0d0e21e
LW
563 accept, bind, connect, getpeername,
564 gethostbyname, getnetbyname, getprotobyname,
565 getservbyname, gethostbyaddr, getnetbyaddr,
566 getprotobynumber, getservbyport, gethostent,
567 getnetent, getprotoent, getservent, sethostent,
568 setnetent, setprotoent, setservent, endhostent,
569 endnetent, endprotoent, endservent, getsockname,
c07a80fd 570 getsockopt, listen, recv, select(system call)*,
571 send, setsockopt, shutdown, socket
a0d0e21e 572
9296fdfa
JM
573The following function is available on Perls built on 64 bit OpenVMS 8.2
574with hard links enabled on an ODS-5 formatted build disk. If someone with
575an OpenVMS 7.3-1 system were to modify configure.com and test the results,
576this feature can be brought back to OpenVMS 7.3-1 and later. Hardlinks
577must be enabled on the build disk because if the build procedure sees
578this feature enabled, it uses it.
579
580 link
581
582The following functions are available on Perls built on 64 bit OpenVMS
5838.2 and can be implemented on OpenVMS 7.3-2 if someone were to modify
584configure.com and test the results. (While in the build, at the time
585of this writing, they have not been specifically tested.)
586
587 getgrgid, getgrnam, getpwnam, getpwuid,
588 setgrent, ttyname
589
590The following functions are available on Perls built on 64 bit OpenVMS 8.2
591and later. (While in the build, at the time of this writing, they have
592not been specifically tested.)
593
594 statvfs, socketpair
595
c73b03b7
JM
596The following functions are available on Perls built on 64 bit OpenVMS 8.3.
597The target for a symbolic link needs to be in Unix format if it is intended to
598resolve to a valid path. The POSIX root must also be set up and there must be
599a path from that POSIX root to the symbolic link target.
9296fdfa
JM
600
601 lchown, link, lstat, readlink, symlink
52e64fc8 602
55497cff 603=over 4
a0d0e21e
LW
604
605=item File tests
606
748a9306
LW
607The tests C<-b>, C<-B>, C<-c>, C<-C>, C<-d>, C<-e>, C<-f>,
608C<-o>, C<-M>, C<-s>, C<-S>, C<-t>, C<-T>, and C<-z> work as
609advertised. The return values for C<-r>, C<-w>, and C<-x>
610tell you whether you can actually access the file; this may
611not reflect the UIC-based file protections. Since real and
612effective UIC don't differ under VMS, C<-O>, C<-R>, C<-W>,
613and C<-X> are equivalent to C<-o>, C<-r>, C<-w>, and C<-x>.
614Similarly, several other tests, including C<-A>, C<-g>, C<-k>,
615C<-l>, C<-p>, and C<-u>, aren't particularly meaningful under
616VMS, and the values returned by these tests reflect whatever
617your CRTL C<stat()> routine does to the equivalent bits in the
618st_mode field. Finally, C<-d> returns true if passed a device
619specification without an explicit directory (e.g. C<DUA1:>), as
620well as if passed a directory.
621
fb38d079 622There are DECC feature logical names AND ODS-5 volume attributes that
9296fdfa
JM
623also control what values are returned for the date fields.
624
4e592037 625Note: Some sites have reported problems when using the file-access
626tests (C<-r>, C<-w>, and C<-x>) on files accessed via DEC's DFS.
627Specifically, since DFS does not currently provide access to the
628extended file header of files on remote volumes, attempts to
629examine the ACL fail, and the file tests will return false,
630with C<$!> indicating that the file does not exist. You can
631use C<stat> on these files, since that checks UIC-based protection
632only, and then manually check the appropriate bits, as defined by
633your C compiler's F<stat.h>, in the mode value it returns, if you
634need an approximation of the file's protections.
635
4fdae800 636=item backticks
637
638Backticks create a subprocess, and pass the enclosed string
639to it for execution as a DCL command. Since the subprocess is
640created directly via C<lib$spawn()>, any valid DCL command string
641may be specified.
642
748a9306
LW
643=item binmode FILEHANDLE
644
1c9f8daa 645The C<binmode> operator will attempt to insure that no translation
646of carriage control occurs on input from or output to this filehandle.
647Since this involves reopening the file and then restoring its
648file position indicator, if this function returns FALSE, the
649underlying filehandle may no longer point to an open file, or may
650point to a different position in the file than before C<binmode>
651was called.
652
653Note that C<binmode> is generally not necessary when using normal
654filehandles; it is provided so that you can control I/O to existing
655record-structured files when necessary. You can also use the
656C<vmsfopen> function in the VMS::Stdio extension to gain finer
657control of I/O to files and devices with different record structures.
a0d0e21e 658
c07a80fd 659=item crypt PLAINTEXT, USER
660
661The C<crypt> operator uses the C<sys$hash_password> system
662service to generate the hashed representation of PLAINTEXT.
663If USER is a valid username, the algorithm and salt values
664are taken from that user's UAF record. If it is not, then
665the preferred algorithm and a salt of 0 are used. The
666quadword encrypted value is returned as an 8-character string.
667
668The value returned by C<crypt> may be compared against
669the encrypted password from the UAF returned by the C<getpw*>
670functions, in order to authenticate users. If you're
671going to do this, remember that the encrypted password in
672the UAF was generated using uppercase username and
673password strings; you'll have to upcase the arguments to
674C<crypt> to insure that you'll get the proper value:
675
376ae1f1
PP
676 sub validate_passwd {
677 my($user,$passwd) = @_;
678 my($pwdhash);
679 if ( !($pwdhash = (getpwnam($user))[1]) ||
680 $pwdhash ne crypt("\U$passwd","\U$name") ) {
681 intruder_alert($name);
682 }
683 return 1;
c07a80fd 684 }
c07a80fd 685
6ac6a52b
JM
686
687=item die
688
689C<die> will force the native VMS exit status to be an SS$_ABORT code
690if neither of the $! or $? status values are ones that would cause
691the native status to be interpreted as being what VMS classifies as
692SEVERE_ERROR severity for DCL error handling.
693
52e64fc8
JM
694When the future POSIX_EXIT mode is active, C<die>, the native VMS exit
695status value will have either one of the C<$!> or C<$?> or C<$^E> or
696the UNIX value 255 encoded into it in a way that the effective original
697value can be decoded by other programs written in C, including Perl
698and the GNV package. As per the normal non-VMS behavior of C<die> if
699either C<$!> or C<$?> are non-zero, one of those values will be
700encoded into a native VMS status value. If both of the UNIX status
701values are 0, and the C<$^E> value is set one of ERROR or SEVERE_ERROR
702severity, then the C<$^E> value will be used as the exit code as is.
703If none of the above apply, the UNIX value of 255 will be encoded into
704a native VMS exit status value.
705
706Please note a significant difference in the behavior of C<die> in
707the future POSIX_EXIT mode is that it does not force a VMS
708SEVERE_ERROR status on exit. The UNIX exit values of 2 through
709255 will be encoded in VMS status values with severity levels of
710SUCCESS. The UNIX exit value of 1 will be encoded in a VMS status
711value with a severity level of ERROR. This is to be compatible with
712how the VMS C library encodes these values.
713
714The minimum severity level set by C<die> in a future POSIX_EXIT mode
715may be changed to be ERROR or higher before that mode becomes fully active
716depending on the results of testing and further review. If this is
717done, the behavior of c<DIE> in the future POSIX_EXIT will close enough
718to the default mode that most DCL shell scripts will probably not notice
719a difference.
720
721See C<$?> for a description of the encoding of the UNIX value to
722produce a native VMS status containing it.
723
6ac6a52b 724
4e592037 725=item dump
726
727Rather than causing Perl to abort and dump core, the C<dump>
728operator invokes the VMS debugger. If you continue to
729execute the Perl program under the debugger, control will
730be transferred to the label specified as the argument to
731C<dump>, or, if no label was specified, back to the
732beginning of the program. All other state of the program
733(I<e.g.> values of variables, open file handles) are not
734affected by calling C<dump>.
735
748a9306 736=item exec LIST
a0d0e21e 737
41cbbefa
CB
738A call to C<exec> will cause Perl to exit, and to invoke the command
739given as an argument to C<exec> via C<lib$do_command>. If the
740argument begins with '@' or '$' (other than as part of a filespec),
741then it is executed as a DCL command. Otherwise, the first token on
742the command line is treated as the filespec of an image to run, and
743an attempt is made to invoke it (using F<.Exe> and the process
744defaults to expand the filespec) and pass the rest of C<exec>'s
745argument to it as parameters. If the token has no file type, and
746matches a file with null type, then an attempt is made to determine
747whether the file is an executable image which should be invoked
748using C<MCR> or a text file which should be passed to DCL as a
749command procedure.
a0d0e21e
LW
750
751=item fork
752
41cbbefa
CB
753While in principle the C<fork> operator could be implemented via
754(and with the same rather severe limitations as) the CRTL C<vfork()>
755routine, and while some internal support to do just that is in
756place, the implementation has never been completed, making C<fork>
757currently unavailable. A true kernel C<fork()> is expected in a
758future version of VMS, and the pseudo-fork based on interpreter
759threads may be available in a future version of Perl on VMS (see
760L<perlfork>). In the meantime, use C<system>, backticks, or piped
761filehandles to create subprocesses.
748a9306
LW
762
763=item getpwent
c07a80fd 764
748a9306 765=item getpwnam
c07a80fd 766
748a9306
LW
767=item getpwuid
768
769These operators obtain the information described in L<perlfunc>,
770if you have the privileges necessary to retrieve the named user's
771UAF information via C<sys$getuai>. If not, then only the C<$name>,
772C<$uid>, and C<$gid> items are returned. The C<$dir> item contains
773the login directory in VMS syntax, while the C<$comment> item
774contains the login directory in Unix syntax. The C<$gcos> item
775contains the owner field from the UAF record. The C<$quota>
776item is not used.
a0d0e21e 777
e518068a 778=item gmtime
779
780The C<gmtime> operator will function properly if you have a
781working CRTL C<gmtime()> routine, or if the logical name
782SYS$TIMEZONE_DIFFERENTIAL is defined as the number of seconds
783which must be added to UTC to yield local time. (This logical
784name is defined automatically if you are running a version of
785VMS with built-in UTC support.) If neither of these cases is
786true, a warning message is printed, and C<undef> is returned.
787
788=item kill
789
39aca757 790In most cases, C<kill> is implemented via the CRTL's C<kill()>
e518068a 791function, so it will behave according to that function's
792documentation. If you send a SIGKILL, however, the $DELPRC system
10a676f8 793service is called directly. This insures that the target
e518068a 794process is actually deleted, if at all possible. (The CRTL's C<kill()>
795function is presently implemented via $FORCEX, which is ignored by
796supervisor-mode images like DCL.)
797
798Also, negative signal values don't do anything special under
799VMS; they're just converted to the corresponding positive value.
800
4fdae800 801=item qx//
802
803See the entry on C<backticks> above.
804
e518068a 805=item select (system call)
806
807If Perl was not built with socket support, the system call
808version of C<select> is not available at all. If socket
809support is present, then the system call version of
810C<select> functions only for file descriptors attached
811to sockets. It will not provide information about regular
812files or pipes, since the CRTL C<select()> routine does not
813provide this functionality.
814
748a9306 815=item stat EXPR
a0d0e21e 816
748a9306
LW
817Since VMS keeps track of files according to a different scheme
818than Unix, it's not really possible to represent the file's ID
819in the C<st_dev> and C<st_ino> fields of a C<struct stat>. Perl
820tries its best, though, and the values it uses are pretty unlikely
821to be the same for two different files. We can't guarantee this,
822though, so caveat scriptor.
823
824=item system LIST
825
826The C<system> operator creates a subprocess, and passes its
a0d0e21e 827arguments to the subprocess for execution as a DCL command.
e518068a 828Since the subprocess is created directly via C<lib$spawn()>, any
aa779de1
CB
829valid DCL command string may be specified. If the string begins with
830'@', it is treated as a DCL command unconditionally. Otherwise, if
831the first token contains a character used as a delimiter in file
832specification (e.g. C<:> or C<]>), an attempt is made to expand it
833using a default type of F<.Exe> and the process defaults, and if
834successful, the resulting file is invoked via C<MCR>. This allows you
835to invoke an image directly simply by passing the file specification
c93fa817
GS
836to C<system>, a common Unixish idiom. If the token has no file type,
837and matches a file with null type, then an attempt is made to
838determine whether the file is an executable image which should be
839invoked using C<MCR> or a text file which should be passed to DCL
840as a command procedure.
841
842If LIST consists of the empty string, C<system> spawns an
a2293a43 843interactive DCL subprocess, in the same fashion as typing
c93fa817
GS
844B<SPAWN> at the DCL prompt.
845
748a9306 846Perl waits for the subprocess to complete before continuing
4fdae800 847execution in the current process. As described in L<perlfunc>,
848the return value of C<system> is a fake "status" which follows
c6966fea 849POSIX semantics unless the pragma C<use vmsish 'status'> is in
1b0c4952
CB
850effect; see the description of C<$?> in this document for more
851detail.
a0d0e21e 852
1c9f8daa 853=item time
854
855The value returned by C<time> is the offset in seconds from
85601-JAN-1970 00:00:00 (just like the CRTL's times() routine), in order
857to make life easier for code coming in from the POSIX/Unix world.
858
a0d0e21e
LW
859=item times
860
748a9306
LW
861The array returned by the C<times> operator is divided up
862according to the same rules the CRTL C<times()> routine.
a0d0e21e
LW
863Therefore, the "system time" elements will always be 0, since
864there is no difference between "user time" and "system" time
39aca757 865under VMS, and the time accumulated by a subprocess may or may
a0d0e21e 866not appear separately in the "child time" field, depending on
748a9306
LW
867whether L<times> keeps track of subprocesses separately. Note
868especially that the VAXCRTL (at least) keeps track only of
869subprocesses spawned using L<fork> and L<exec>; it will not
a2293a43 870accumulate the times of subprocesses spawned via pipes, L<system>,
748a9306
LW
871or backticks.
872
16d20bd9
AD
873=item unlink LIST
874
875C<unlink> will delete the highest version of a file only; in
876order to delete all versions, you need to say
39aca757 877
35b2760a 878 1 while unlink LIST;
39aca757 879
16d20bd9
AD
880You may need to make this change to scripts written for a
881Unix system which expect that after a call to C<unlink>,
882no files with the names passed to C<unlink> will exist.
4633a7c4
LW
883(Note: This can be changed at compile time; if you
884C<use Config> and C<$Config{'d_unlink_all_versions'}> is
885C<define>, then C<unlink> will delete all versions of a
886file on the first call.)
16d20bd9
AD
887
888C<unlink> will delete a file if at all possible, even if it
889requires changing file protection (though it won't try to
890change the protection of the parent directory). You can tell
891whether you've got explicit delete access to a file by using the
892C<VMS::Filespec::candelete> operator. For instance, in order
893to delete only files to which you have delete access, you could
894say something like
4e592037 895
16d20bd9
AD
896 sub safe_unlink {
897 my($file,$num);
898 foreach $file (@_) {
899 next unless VMS::Filespec::candelete($file);
900 $num += unlink $file;
901 }
902 $num;
903 }
4e592037 904
905(or you could just use C<VMS::Stdio::remove>, if you've installed
906the VMS::Stdio extension distributed with Perl). If C<unlink> has to
907change the file protection to delete the file, and you interrupt it
908in midstream, the file may be left intact, but with a changed ACL
909allowing you delete access.
16d20bd9 910
fb38d079
JM
911This behavior of C<unlink> is to be compatible with POSIX behavior
912and not traditional VMS behavior.
913
748a9306
LW
914=item utime LIST
915
941b3de1
CB
916This operator changes only the modification time of the file (VMS
917revision date) on ODS-2 volumes and ODS-5 volumes without access
918dates enabled. On ODS-5 volumes with access dates enabled, the
919true access time is modified.
748a9306
LW
920
921=item waitpid PID,FLAGS
922
39aca757 923If PID is a subprocess started by a piped C<open()> (see L<open>),
376ae1f1
PP
924C<waitpid> will wait for that subprocess, and return its final status
925value in C<$?>. If PID is a subprocess created in some other way (e.g.
926SPAWNed before Perl was invoked), C<waitpid> will simply check once per
927second whether the process has completed, and return when it has. (If
928PID specifies a process that isn't a subprocess of the current process,
929and you invoked Perl with the C<-w> switch, a warning will be issued.)
35b2760a
CB
930
931Returns PID on success, -1 on error. The FLAGS argument is ignored
932in all cases.
a0d0e21e 933
55497cff 934=back
935
a5f75d66
AD
936=head1 Perl variables
937
55497cff 938The following VMS-specific information applies to the indicated
939"special" Perl variables, in addition to the general information
a2293a43 940in L<perlvar>. Where there is a conflict, this information
55497cff 941takes precedence.
942
943=over 4
944
a5f75d66
AD
945=item %ENV
946
f675dbe5
CB
947The operation of the C<%ENV> array depends on the translation
948of the logical name F<PERL_ENV_TABLES>. If defined, it should
949be a search list, each element of which specifies a location
950for C<%ENV> elements. If you tell Perl to read or set the
951element C<$ENV{>I<name>C<}>, then Perl uses the translations of
952F<PERL_ENV_TABLES> as follows:
953
954=over 4
955
956=item CRTL_ENV
957
958This string tells Perl to consult the CRTL's internal C<environ>
959array of key-value pairs, using I<name> as the key. In most cases,
960this contains only a few keys, but if Perl was invoked via the C
961C<exec[lv]e()> function, as is the case for CGI processing by some
962HTTP servers, then the C<environ> array may have been populated by
963the calling program.
964
965=item CLISYM_[LOCAL]
966
967A string beginning with C<CLISYM_>tells Perl to consult the CLI's
968symbol tables, using I<name> as the name of the symbol. When reading
969an element of C<%ENV>, the local symbol table is scanned first, followed
970by the global symbol table.. The characters following C<CLISYM_> are
971significant when an element of C<%ENV> is set or deleted: if the
972complete string is C<CLISYM_LOCAL>, the change is made in the local
39aca757 973symbol table; otherwise the global symbol table is changed.
f675dbe5
CB
974
975=item Any other string
976
977If an element of F<PERL_ENV_TABLES> translates to any other string,
978that string is used as the name of a logical name table, which is
979consulted using I<name> as the logical name. The normal search
980order of access modes is used.
981
982=back
983
984F<PERL_ENV_TABLES> is translated once when Perl starts up; any changes
985you make while Perl is running do not affect the behavior of C<%ENV>.
986If F<PERL_ENV_TABLES> is not defined, then Perl defaults to consulting
987first the logical name tables specified by F<LNM$FILE_DEV>, and then
988the CRTL C<environ> array.
989
990In all operations on %ENV, the key string is treated as if it
991were entirely uppercase, regardless of the case actually
992specified in the Perl expression.
993
994When an element of C<%ENV> is read, the locations to which
995F<PERL_ENV_TABLES> points are checked in order, and the value
996obtained from the first successful lookup is returned. If the
997name of the C<%ENV> element contains a semi-colon, it and
998any characters after it are removed. These are ignored when
999the CRTL C<environ> array or a CLI symbol table is consulted.
1000However, the name is looked up in a logical name table, the
1001suffix after the semi-colon is treated as the translation index
1002to be used for the lookup. This lets you look up successive values
1003for search list logical names. For instance, if you say
a5f75d66
AD
1004
1005 $ Define STORY once,upon,a,time,there,was
1006 $ perl -e "for ($i = 0; $i <= 6; $i++) " -
740ce14c 1007 _$ -e "{ print $ENV{'story;'.$i},' '}"
a5f75d66 1008
f675dbe5
CB
1009Perl will print C<ONCE UPON A TIME THERE WAS>, assuming, of course,
1010that F<PERL_ENV_TABLES> is set up so that the logical name C<story>
1011is found, rather than a CLI symbol or CRTL C<environ> element with
1012the same name.
1013
3eeba6fb 1014When an element of C<%ENV> is set to a defined string, the
f675dbe5
CB
1015corresponding definition is made in the location to which the
1016first translation of F<PERL_ENV_TABLES> points. If this causes a
1017logical name to be created, it is defined in supervisor mode.
3eeba6fb
CB
1018(The same is done if an existing logical name was defined in
1019executive or kernel mode; an existing user or supervisor mode
1020logical name is reset to the new value.) If the value is an empty
1021string, the logical name's translation is defined as a single NUL
1022(ASCII 00) character, since a logical name cannot translate to a
1023zero-length string. (This restriction does not apply to CLI symbols
1024or CRTL C<environ> values; they are set to the empty string.)
f675dbe5
CB
1025An element of the CRTL C<environ> array can be set only if your
1026copy of Perl knows about the CRTL's C<setenv()> function. (This is
1027present only in some versions of the DECCRTL; check C<$Config{d_setenv}>
1028to see whether your copy of Perl was built with a CRTL that has this
1029function.)
39aca757 1030
3eeba6fb 1031When an element of C<%ENV> is set to C<undef>,
f675dbe5
CB
1032the element is looked up as if it were being read, and if it is
1033found, it is deleted. (An item "deleted" from the CRTL C<environ>
1034array is set to the empty string; this can only be done if your
1035copy of Perl knows about the CRTL C<setenv()> function.) Using
1036C<delete> to remove an element from C<%ENV> has a similar effect,
1037but after the element is deleted, another attempt is made to
1038look up the element, so an inner-mode logical name or a name in
1039another location will replace the logical name just deleted.
3eeba6fb
CB
1040In either case, only the first value found searching PERL_ENV_TABLES
1041is altered. It is not possible at present to define a search list
1042logical name via %ENV.
f675dbe5
CB
1043
1044The element C<$ENV{DEFAULT}> is special: when read, it returns
1045Perl's current default device and directory, and when set, it
1046resets them, regardless of the definition of F<PERL_ENV_TABLES>.
1047It cannot be cleared or deleted; attempts to do so are silently
1048ignored.
b7b1864f
CB
1049
1050Note that if you want to pass on any elements of the
1051C-local environ array to a subprocess which isn't
1052started by fork/exec, or isn't running a C program, you
1053can "promote" them to logical names in the current
1054process, which will then be inherited by all subprocesses,
1055by saying
1056
1057 foreach my $key (qw[C-local keys you want promoted]) {
376ae1f1
PP
1058 my $temp = $ENV{$key}; # read from C-local array
1059 $ENV{$key} = $temp; # and define as logical name
b7b1864f
CB
1060 }
1061
1062(You can't just say C<$ENV{$key} = $ENV{$key}>, since the
1063Perl optimizer is smart enough to elide the expression.)
a5f75d66 1064
6be8f7a6
JH
1065Don't try to clear C<%ENV> by saying C<%ENV = ();>, it will throw
1066a fatal error. This is equivalent to doing the following from DCL:
1067
1068 DELETE/LOGICAL *
1069
1070You can imagine how bad things would be if, for example, the SYS$MANAGER
fb38d079 1071or SYS$SYSTEM logical names were deleted.
4a0d0822 1072
740ce14c 1073At present, the first time you iterate over %ENV using
edc7bc49
CB
1074C<keys>, or C<values>, you will incur a time penalty as all
1075logical names are read, in order to fully populate %ENV.
1076Subsequent iterations will not reread logical names, so they
1077won't be as slow, but they also won't reflect any changes
f675dbe5
CB
1078to logical name tables caused by other programs.
1079
fb38d079
JM
1080You do need to be careful with the logical names representing
1081process-permanent files, such as C<SYS$INPUT> and C<SYS$OUTPUT>.
1082The translations for these logical names are prepended with a
1083two-byte binary value (0x1B 0x00) that needs to be stripped off
1084if you wantto use it. (In previous versions of Perl it wasn't
1085possible to get the values of these logical names, as the null
1086byte acted as an end-of-string marker)
a5f75d66 1087
a5f75d66
AD
1088=item $!
1089
1090The string value of C<$!> is that returned by the CRTL's
1091strerror() function, so it will include the VMS message for
1092VMS-specific errors. The numeric value of C<$!> is the
1093value of C<errno>, except if errno is EVMSERR, in which
1094case C<$!> contains the value of vaxc$errno. Setting C<$!>
4e592037 1095always sets errno to the value specified. If this value is
1096EVMSERR, it also sets vaxc$errno to 4 (NONAME-F-NOMSG), so
1097that the string value of C<$!> won't reflect the VMS error
1098message from before C<$!> was set.
1099
1100=item $^E
1101
1102This variable provides direct access to VMS status values
1103in vaxc$errno, which are often more specific than the
1104generic Unix-style error messages in C<$!>. Its numeric value
1105is the value of vaxc$errno, and its string value is the
1106corresponding VMS message string, as retrieved by sys$getmsg().
1107Setting C<$^E> sets vaxc$errno to the value specified.
1108
9296fdfa
JM
1109While Perl attempts to keep the vaxc$errno value to be current, if
1110errno is not EVMSERR, it may not be from the current operation.
1111
4fdae800 1112=item $?
1113
1114The "status value" returned in C<$?> is synthesized from the
1115actual exit status of the subprocess in a way that approximates
1116POSIX wait(5) semantics, in order to allow Perl programs to
1117portably test for successful completion of subprocesses. The
1118low order 8 bits of C<$?> are always 0 under VMS, since the
1119termination status of a process may or may not have been
9296fdfa
JM
1120generated by an exception.
1121
1122The next 8 bits contain the termination status of the program.
1123
1124If the child process follows the convention of C programs
1125compiled with the _POSIX_EXIT macro set, the status value will
1126contain the actual value of 0 to 255 returned by that program
1127on a normal exit.
1128
52e64fc8
JM
1129With the _POSIX_EXIT macro set, the UNIX exit value of zero is
1130represented as a VMS native status of 1, and the UNIX values
1131from 2 to 255 are encoded by the equation:
1132
1133 VMS_status = 0x35a000 + (unix_value * 8) + 1.
1134
1135And in the special case of unix value 1 the encoding is:
1136
1137 VMS_status = 0x35a000 + 8 + 2 + 0x10000000.
9296fdfa
JM
1138
1139For other termination statuses, the severity portion of the
52e64fc8 1140subprocess' exit status is used: if the severity was success or
9296fdfa
JM
1141informational, these bits are all 0; if the severity was
1142warning, they contain a value of 1; if the severity was
1143error or fatal error, they contain the actual severity bits,
52e64fc8
JM
1144which turns out to be a value of 2 for error and 4 for severe_error.
1145Fatal is another term for the severe_error status.
9bc98430 1146
4fdae800 1147As a result, C<$?> will always be zero if the subprocess' exit
1148status indicated successful completion, and non-zero if a
9296fdfa
JM
1149warning or error occurred or a program compliant with encoding
1150_POSIX_EXIT values was run and set a status.
1151
52e64fc8
JM
1152How can you tell the difference between a non-zero status that is
1153the result of a VMS native error status or an encoded UNIX status?
1154You can not unless you look at the ${^CHILD_ERROR_NATIVE} value.
1155The ${^CHILD_ERROR_NATIVE} value returns the actual VMS status value
1156and check the severity bits. If the severity bits are equal to 1,
1157then if the numeric value for C<$?> is between 2 and 255 or 0, then
1158C<$?> accurately reflects a value passed back from a UNIX application.
1159If C<$?> is 1, and the severity bits indicate a VMS error (2), then
1160C<$?> is from a UNIX application exit value.
9296fdfa
JM
1161
1162In practice, Perl scripts that call programs that return _POSIX_EXIT
52e64fc8
JM
1163type status values will be expecting those values, and programs that
1164call traditional VMS programs will either be expecting the previous
1165behavior or just checking for a non-zero status.
9296fdfa 1166
52e64fc8 1167And success is always the value 0 in all behaviors.
9296fdfa 1168
fb38d079 1169When the actual VMS termination status of the child is an error,
52e64fc8
JM
1170internally the C<$!> value will be set to the closest UNIX errno
1171value to that error so that Perl scripts that test for error
1172messages will see the expected UNIX style error message instead
1173of a VMS message.
fb38d079 1174
9296fdfa
JM
1175Conversely, when setting C<$?> in an END block, an attempt is made
1176to convert the POSIX value into a native status intelligible to
1177the operating system upon exiting Perl. What this boils down to
1178is that setting C<$?> to zero results in the generic success value
1179SS$_NORMAL, and setting C<$?> to a non-zero value results in the
1180generic failure status SS$_ABORT. See also L<perlport/exit>.
4fdae800 1181
6ac6a52b 1182With the future POSIX_EXIT mode set, setting C<$?> will cause the
52e64fc8
JM
1183new value to also be encoded into C<$^E> so that the either the
1184original parent or child exit status values of 0 to 255
1185can be automatically recovered by C programs expecting _POSIX_EXIT
1186behavior. If both a parent and a child exit value are non-zero, then it
1187will be assumed that this is actually a VMS native status value to
1188be passed through. The special value of 0xFFFF is almost a NOOP as
1189it will cause the current native VMS status in the C library to
1190become the current native Perl VMS status, and is handled this way
1191as consequence of it known to not be a valid native VMS status value.
1192It is recommend that only values in range of normal UNIX parent or
1193child status numbers, 0 to 255 are used.
6ac6a52b 1194
1b0c4952 1195The pragma C<use vmsish 'status'> makes C<$?> reflect the actual
9bc98430
CB
1196VMS exit status instead of the default emulation of POSIX status
1197described above. This pragma also disables the conversion of
1198non-zero values to SS$_ABORT when setting C<$?> in an END
1199block (but zero will still be converted to SS$_NORMAL).
4fdae800 1200
6ac6a52b 1201Do not use the pragma C<use vmsish 'status'> with the future
52e64fc8
JM
1202POSIX_EXIT mode, as they are at times requesting conflicting
1203actions and the consequence of ignoring this advice will be
1204undefined to allow future improvements in the POSIX exit handling.
6ac6a52b 1205
4e592037 1206=item $|
1207
1208Setting C<$|> for an I/O stream causes data to be flushed
1209all the way to disk on each write (I<i.e.> not just to
1210the underlying RMS buffers for a file). In other words,
1211it's equivalent to calling fflush() and fsync() from C.
a5f75d66 1212
55497cff 1213=back
1214
bf99883d
HM
1215=head1 Standard modules with VMS-specific differences
1216
1217=head2 SDBM_File
1218
270c2ced 1219SDBM_File works properly on VMS. It has, however, one minor
4a4eefd0
GS
1220difference. The database directory file created has a F<.sdbm_dir>
1221extension rather than a F<.dir> extension. F<.dir> files are VMS filesystem
bf99883d
HM
1222directory files, and using them for other purposes could cause unacceptable
1223problems.
1224
748a9306 1225=head1 Revision date
a0d0e21e 1226
9296fdfa 1227This document was last updated on 14-Oct-2005, for Perl 5,
9bc98430 1228patchlevel 8.
e518068a 1229
1230=head1 AUTHOR
1231
376ae1f1
PP
1232Charles Bailey bailey@cor.newman.upenn.edu
1233Craig Berry craigberry@mac.com
1234Dan Sugalski dan@sidhe.org
9296fdfa 1235John Malmberg wb8tyw@qsl.net