This is a live mirror of the Perl 5 development currently hosted at
perl5.000 patch.0o: [address] a few more Configure and build nits.
[perl5.git] / vms / perlvms.pod
1=head1 Notes on Perl5 for VMS
3Gathered below are notes describing details of perl 5's
4behavior on VMS. They are a supplement to the regular perl 5
5documentation, so we have focussed on the ways in which perl
65 functions differently under VMS thatn it does under Unix,
7and on teh interactions between perl and the rest of the
8operating system. We haven't tried to duplicate complete
9descriptions of perl5 features from the main perl
10documentation, which can be found in the F<[.pod]>
11subdirectory of the perl 5 distribution.
13We hope these notes will save you from confusion and lost
14sleep when writing perl scripts on VMS. If you find we've
15missed something you think should appear here, please don't
16hesitate to drop a line to
18=head2 Installation
20Directions for building and installing perl 5 can be found in
21the file F<ReadMe.VMS> in the main source directory of the
22perl5 distribution..
24=head2 File specifications
26We have tried to make perl aware of both VMS-style and Unix-
27style file specifications wherever possible. You may use
28either style, or both, on the command line and in scripts,
29but you may not combine the two styles within a single fle
30specfication. Filenames are, of course, still case-
31insensitive. For consistency, most perl5 routines return
32filespecs using lower case latters only, regardless of the
33case used in the arguments passed to them. (This is true
34only when running under VMS; perl5 respects the case-
35sensitivity of OSs like Unix.)
37We've tried to minimize the dependence of perl library
38modules on Unix syntax, but you may find that some of these,
39as well as some scripts written for Unix systems, will
40require that you use Unix syntax, since they will assume that
41'/' is the directory separator, etc. If you find instances
42of this in the perl distribution itself, please let us know,
43so we can try to work around them.
45=head2 Command line redirection
47Perl for VMS supports redirection of input and output on the
48command line, using a subset of Bourne shell syntax:
49 <F<file> reads stdin from F<file>,
50 >F<file> writes stdout to F<file>,
51 >>F<file> appends stdout to F<file>,
52 2>F<file> wrtits stderr to F<file>, and
53 2>>F<file> appends stderr to F<file>.
55In addition, output may be piped to a subprocess, using the
56character '|'. Anything after this character on the command
57line is passed to a subprocess for execution; the subprocess
58takes the output of perl as its input.
60Finally, if the command line ends with '&', the entire
61command is run in the background as an asynchronous
64=head2 Pipes
66Input and output pipes to perl filehandles are supported; the
67"file name" is passed to lib$spawn() for asynchronous
68execution. You should be careful to close any pipes you have
69opened in a perl script, lest you leave any "orphaned"
70subprocesses around when perl exits.
72You may also use backticks to invoke a DCL subprocess, whose
73output is used as the return value of the expression. The
74string between the backticks is passed directly to lib$spawn
75as the command to execute. In this case, perl will wait for
76the subprocess to complete before continuing.
78=head2 Wildcard expansion
80File specifications containing wildcards are allowed both on
81the command line and within perl globs (e.g. <C<*.c>>). If
82the wildcard filespec uses VMS syntax, the resultant
83filespecs will follow VMS syntax; if a Unix-style filespec is
84passed in, Unix-style filespecs will be returned..
86If the wildcard filespec contains a device or directory
87specification, then the resultant filespecs will also contain
88a device and directory; otherwise, device and directory
89information are removed. VMS-style resultant filespecs will
90contain a full device and directory, while Unix-style
91resultant filespecs will contain only as much of a directory
92path as was present in the input filespec. For example, if
93your default directory is Perl_Root:[000000], the expansion
94of C<[.t]*.*> will yield filespecs like
95"perl_root:[t]base.dir", while the expansion of C<t/*/*> will
96yield filespecs like "t/base.dir". (This is done to match
97the behavior of glob expansion performed by Unix shells.)
99Similarly, the resultant filespec will the file version only
100if one was present in the input filespec.
102=head2 %ENV
104Reading the elements of the %ENV array returns the
105translation of the logical name specified by the key,
106according to the normal search order of access modes and
107logical name tables. In addition, the keys C<home>,
108C<path>,C<term>, and C<user> return the CRTL "environment
109variables" of the same names. The key C<default> returns the
110current default device and directory specification.
112Setting an element of %ENV defines a supervisor-mode logical
113name in the process logical name table. B<Undef>ing or
114B<delete>ing an element of %ENV deletes the equivalent user-
115mode or supervisor-mode logical name from the process logical
116name table. If you use B<undef>, the %ENV element remains
117empty. If you use B<delete>, another attempt is made at
118logical name translation after the deletion, so an inner-mode
119logical name or a name in another logical name table will
120replace the logical name just deleted.
122In all operations on %ENV, the key string is treated as if it
123were entirely uppercase, regardless of the case actually
124specified in the perl expression.
126=head2 Perl functions
128As of the time this document was last revised, the following
129perl functions were implemented in the VMS port of perl
130(functions marked with * are discussed in more detail below):
132 file tests*, abs, alarm, atan, binmode*, bless,
133 caller, chdir, chmod, chown, chomp, chop, chr,
134 close, closedir, cos, defined, delete, die, do,
135 each, eof, eval, exec*, exists, exit, exp, fileno,
136 fork*, getc, glob, goto, grep, hex, import, index,
137 int, join, keys, kill, last, lc, lcfirst, length,
138 local, localtime, log, m//, map, mkdir, my, next,
139 no, oct, open, opendir, ord, pack, pipe, pop, pos,
140 print, printf, push, q//, qq//, qw//, qx//,
141 quotemeta, rand, read, readdir, redo, ref, rename,
142 require, reset, return, reverse, rewinddir, rindex,
143 rmdir, s///, scalar, seek, seekdir, select(internal)*,
144 shift, sin, sleep, sort, splice, split, sprintf,
145 sqrt, srand, stat, study, substr, sysread, system*,
146 syswrite, tell, telldir, tie, time, times*, tr///,
147 uc, ucfirst, umask, undef, unlink, unpack, untie,
148 unshift, use, values, vec, wait, wantarray, warn,
149 write, y///
151The following functions were not implemented in the VMS port,
152and calling them produces a fatal error (usually) or
153undefined behavior (rarely, we hope):
155 chroot, crypt, dbmclose, dbmopen, dump, fcntl,
156 flock, getlogin, getpgrp, getppid, getpriority,
157 getpwent, getgrent, kill, getgrgid, getgrnam,
158 getpwnam, getpwuid, setpwent, setgrent,
159 endpwent, endgrent, gmtime, ioctl, link, lstst,
160 msgctl, msgget, msgsend, msgrcv, readlink,
161 select(system call), semctl, semget, semop,
162 setpgrp, setpriority, shmctl, shmget, shmread,
163 shmwrite, socketpair, symlink, syscall, truncate,
164 utime, waitpid
166The following functions may or may not be implemented,
167depending on what type of socket support you've built into
168your copy of perl:
169 accept, bind, connect, getpeername,
170 gethostbyname, getnetbyname, getprotobyname,
171 getservbyname, gethostbyaddr, getnetbyaddr,
172 getprotobynumber, getservbyport, gethostent,
173 getnetent, getprotoent, getservent, sethostent,
174 setnetent, setprotoent, setservent, endhostent,
175 endnetent, endprotoent, endservent, getsockname,
176 getsockopt, listen, recv, send, setsockopt,
177 shutdown, socket
180=item File tests
182The tests -b, -B, -c, -C, -d, -e, -f, -o, -M, -s, -S, -t, -T,
183and -z work as advertised. The return values for -r, -w, and
184-x tell you whether you can actually access the file; this
185may mot reflect the UIC-based file protections. Since real
186and effective UIC don't differ under VMS, -O, -R, -W, and -X
187are equivalent to -o, -r, -w, and -x. Similarly, several
188other tests, including -A, -g, -k, -l,-p, and -u, aren't
189particularly meaningful under VMS, and the values returned by
190these tests reflect whatever your CRTL stat() routine does to
191the equivalent bits in the st_mode field.
193=item binmode
195The B<binmode> operator has no effect under VMS. It will
196return TRUE whenever called, but will not affect I/O
197operations on the filehandle given as its argument.
199=item exec
201The B<exec> operator behaves in one of two different ways.
202If called after a call to B<fork>, it will invoke the CRTL
203L<execv()> routine, passing its arguments to the subprocess
204created by B<fork> for execution. In this case, it is
205subject to all limitation that affect L<execv>. (In
206particular, this usually means that the command executed in
207the subprocess must be an image compiled from C source code,
208and that your options for passing file descriptors and signal
209handlers to the subprocess are limited.)
211If the call to B<exec> does not follow a call to B<fork>, it
212will cause perl to exit, and to invoke the command given as
213an argument to B<exec> via lib$do_command. If the argument
214begins with a '$' (other than as part of a filespec), then it
215is executed as a DCL command. Otherwise, the first token on
216the command line is treated as the filespec of an image to
217run, and an attempt is made to invoke it (using F<.Exe> and
218the process defaults to expand the filespec) and pass the
219rest of B<exec>'s argument to it as parameters.
221You can use B<exec> in both ways within the same script, as
222long as you call B<fork> and B<exec> in pairs. Perl only
223keeps track of whether B<fork> has been called since the last
224call to B<exec> when figuring out what to do, so multiple
225calls to B<fork> do not generate multiple levels of "fork
228=item fork
230The B<fork> operator works in the same way as the CRTL
231L<fork()> routine, which is quite different under VMS than
232under Unix. Sepcifically, while B<fork> returns 0 after it
233is called and the subprocess PID after B<exec> is called, in
234both cases the thread of execution is within the parent
235process, so there is no opportunity to perform operations in
236the subprocess before calling B<exec>.
238In general, the use of B<fork> and B<exec> to create
239subprocess is not recommended under VMS; wherever possible,
240use the B<system> operator or piped filehandles instead.
242=item system
244The B<system> operator creates a subprocess, and passes its
245arguments to the subprocess for execution as a DCL command.
246Since the subprocess is created directly via lib$spawn, any
247valid DCL command string may be specified. Perl waits for
248the subprocess to complete before continuing execution in the
249current process.
251=item times
253The array returned by the B<times> operator is divided up
254according to the same rules the CRTL L<times()> routine.
255Therefore, the "system time" elements will always be 0, since
256there is no difference between "user time" and "system" time
257under VMS, and the time accumulated by subprocess may or may
258not appear separately in the "child time" field, depending on
259whether L<times> keeps track of subprocesses separately.
261=head2 Revision date
263This document was last updated on 16-Oct-1994, for perl 5,
264patchlevel 0.