Commit | Line | Data |
---|---|---|
e518068a | 1 | =head1 NAME |
2 | ||
3 | perlvms - VMS-specific documentation for Perl | |
4 | ||
5 | =head1 DESCRIPTION | |
a0d0e21e | 6 | |
748a9306 LW |
7 | Gathered below are notes describing details of Perl 5's |
8 | behavior on VMS. They are a supplement to the regular Perl 5 | |
9 | documentation, so we have focussed on the ways in which Perl | |
10 | 5 functions differently under VMS than it does under Unix, | |
11 | and on the interactions between Perl and the rest of the | |
a0d0e21e | 12 | operating system. We haven't tried to duplicate complete |
748a9306 | 13 | descriptions of Perl features from the main Perl |
a0d0e21e | 14 | documentation, which can be found in the F<[.pod]> |
748a9306 | 15 | subdirectory of the Perl distribution. |
a0d0e21e LW |
16 | |
17 | We hope these notes will save you from confusion and lost | |
748a9306 | 18 | sleep when writing Perl scripts on VMS. If you find we've |
a0d0e21e LW |
19 | missed something you think should appear here, please don't |
20 | hesitate to drop a line to vmsperl@genetics.upenn.edu. | |
21 | ||
4e592037 | 22 | =head1 Installation |
23 | ||
24 | Directions for building and installing Perl 5 can be found in | |
25 | the file F<README.vms> in the main source directory of the | |
26 | Perl distribution.. | |
27 | ||
e518068a | 28 | =head1 Organization of Perl Images |
748a9306 | 29 | |
e518068a | 30 | =head2 Core Images |
748a9306 LW |
31 | |
32 | During the installation process, three Perl images are produced. | |
33 | F<Miniperl.Exe> is an executable image which contains all of | |
34 | the basic functionality of Perl, but cannot take advantage of | |
35 | Perl extensions. It is used to generate several files needed | |
36 | to build the complete Perl and various extensions. Once you've | |
37 | finished installing Perl, you can delete this image. | |
38 | ||
39 | Most of the complete Perl resides in the shareable image | |
40 | F<PerlShr.Exe>, which provides a core to which the Perl executable | |
41 | image and all Perl extensions are linked. You should place this | |
42 | image in F<Sys$Share>, or define the logical name F<PerlShr> to | |
43 | translate to the full file specification of this image. It should | |
44 | be world readable. (Remember that if a user has execute only access | |
45 | to F<PerlShr>, VMS will treat it as if it were a privileged shareable | |
46 | image, and will therefore require all downstream shareable images to be | |
47 | INSTALLed, etc.) | |
48 | ||
49 | ||
50 | Finally, F<Perl.Exe> is an executable image containing the main | |
51 | entry point for Perl, as well as some initialization code. It | |
52 | should be placed in a public directory, and made world executable. | |
53 | In order to run Perl with command line arguments, you should | |
54 | define a foreign command to invoke this image. | |
55 | ||
56 | =head2 Perl Extensions | |
57 | ||
58 | Perl extensions are packages which provide both XS and Perl code | |
59 | to add new functionality to perl. (XS is a meta-language which | |
60 | simplifies writing C code which interacts with Perl, see | |
2ceaccd7 | 61 | L<perlxs> for more details.) The Perl code for an |
748a9306 LW |
62 | extension is treated like any other library module - it's |
63 | made available in your script through the appropriate | |
64 | C<use> or C<require> statement, and usually defines a Perl | |
65 | package containing the extension. | |
66 | ||
67 | The portion of the extension provided by the XS code may be | |
68 | connected to the rest of Perl in either of two ways. In the | |
69 | B<static> configuration, the object code for the extension is | |
70 | linked directly into F<PerlShr.Exe>, and is initialized whenever | |
71 | Perl is invoked. In the B<dynamic> configuration, the extension's | |
72 | machine code is placed into a separate shareable image, which is | |
73 | mapped by Perl's DynaLoader when the extension is C<use>d or | |
74 | C<require>d in your script. This allows you to maintain the | |
75 | extension as a separate entity, at the cost of keeping track of the | |
76 | additional shareable image. Most extensions can be set up as either | |
77 | static or dynamic. | |
78 | ||
79 | The source code for an extension usually resides in its own | |
80 | directory. At least three files are generally provided: | |
81 | I<Extshortname>F<.xs> (where I<Extshortname> is the portion of | |
82 | the extension's name following the last C<::>), containing | |
83 | the XS code, I<Extshortname>F<.pm>, the Perl library module | |
84 | for the extension, and F<Makefile.PL>, a Perl script which uses | |
85 | the C<MakeMaker> library modules supplied with Perl to generate | |
86 | a F<Descrip.MMS> file for the extension. | |
87 | ||
e518068a | 88 | =head2 Installing static extensions |
748a9306 LW |
89 | |
90 | Since static extensions are incorporated directly into | |
91 | F<PerlShr.Exe>, you'll have to rebuild Perl to incorporate a | |
92 | new extension. You should edit the main F<Descrip.MMS> or F<Makefile> | |
93 | you use to build Perl, adding the extension's name to the C<ext> | |
94 | macro, and the extension's object file to the C<extobj> macro. | |
95 | You'll also need to build the extension's object file, either | |
96 | by adding dependencies to the main F<Descrip.MMS>, or using a | |
97 | separate F<Descrip.MMS> for the extension. Then, rebuild | |
98 | F<PerlShr.Exe> to incorporate the new code. | |
99 | ||
100 | Finally, you'll need to copy the extension's Perl library | |
101 | module to the F<[.>I<Extname>F<]> subdirectory under one | |
102 | of the directories in C<@INC>, where I<Extname> is the name | |
103 | of the extension, with all C<::> replaced by C<.> (e.g. | |
104 | the library module for extension Foo::Bar would be copied | |
105 | to a F<[.Foo.Bar]> subdirectory). | |
106 | ||
e518068a | 107 | =head2 Installing dynamic extensions |
108 | ||
109 | In general, the distributed kit for a Perl extension includes | |
110 | a file named Makefile.PL, which is a Perl program which is used | |
111 | to create a F<Descrip.MMS> file which can be used to build and | |
112 | install the files required by the extension. The kit should be | |
c07a80fd | 113 | unpacked into a directory tree B<not> under the main Perl source |
e518068a | 114 | directory, 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 | 121 | I<N.B.> The procedure by which extensions are built and |
122 | tested creates several levels (at least 4) under the | |
123 | directory in which the extension's source files live. | |
124 | For this reason, you shouldn't nest the source directory | |
125 | too deeply in your directory structure, lest you eccedd RMS' | |
126 | maximum of 8 levels of subdirectory in a filespec. (You | |
127 | can use rooted logical names to get another 8 levels of | |
128 | nesting, if you can't place the files near the top of | |
129 | the physical directory structure.) | |
e518068a | 130 | |
131 | VMS support for this process in the current release of Perl | |
132 | is sufficient to handle most extensions. However, it does | |
133 | not yet recognize extra libraries required to build shareable | |
134 | images which are part of an extension, so these must be added | |
135 | to the linker options file for the extension by hand. For | |
136 | instance, if the F<PGPLOT> extension to Perl requires the | |
137 | F<PGPLOTSHR.EXE> shareable image in order to properly link | |
138 | the Perl extension, then the line C<PGPLOTSHR/Share> must | |
139 | be added to the linker options file F<PGPLOT.Opt> produced | |
140 | during the build process for the Perl extension. | |
141 | ||
142 | By default, the shareable image for an extension is placed | |
bbce6d69 | 143 | F<[.lib.site_perl.auto>I<Arch>.I<Extname>F<]> directory of the |
e518068a | 144 | installed Perl directory tree (where I<Arch> is F<VMS_VAX> or |
bbce6d69 | 145 | F<VMS_AXP>, and I<Extname> is the name of the extension, with |
146 | each C<::> translated to C<.>). (See the MakeMaker documentation | |
147 | for more details on installation options for extensions.) | |
4e592037 | 148 | However, it can be manually placed in any of several locations: |
bbce6d69 | 149 | - the F<[.Lib.Auto.>I<Arch>I<$PVers>I<Extname>F<]> subdirectory |
150 | of one of the directories in C<@INC> (where I<PVers> | |
151 | is the version of Perl you're using, as supplied in C<$]>, | |
152 | with '.' converted to '_'), or | |
748a9306 LW |
153 | - one of the directories in C<@INC>, or |
154 | - a directory which the extensions Perl library module | |
155 | passes to the DynaLoader when asking it to map | |
156 | the shareable image, or | |
157 | - F<Sys$Share> or F<Sys$Library>. | |
158 | If the shareable image isn't in any of these places, you'll need | |
159 | to define a logical name I<Extshortname>, where I<Extshortname> | |
160 | is the portion of the extension's name after the last C<::>, which | |
161 | translates to the full file specification of the shareable image. | |
162 | ||
4e592037 | 163 | =head1 File specifications |
748a9306 | 164 | |
4e592037 | 165 | =head2 Syntax |
a0d0e21e | 166 | |
748a9306 | 167 | We have tried to make Perl aware of both VMS-style and Unix- |
a0d0e21e LW |
168 | style file specifications wherever possible. You may use |
169 | either style, or both, on the command line and in scripts, | |
170 | but you may not combine the two styles within a single fle | |
1c9f8daa | 171 | specification. VMS Perl interprets Unix pathnames in much |
172 | the same way as the CRTL (I<e.g.> the first component of | |
173 | an absolute path is read as the device name for the | |
174 | VMS file specification). There are a set of functions | |
175 | provided in the C<VMS::Filespec> package for explicit | |
176 | interconversion between VMS and Unix syntax; its | |
177 | documentation provides more details. | |
178 | ||
179 | Filenames are, of course, still case-insensitive. For | |
180 | consistency, most Perl routines return filespecs using | |
181 | lower case letters only, regardless of the case used in | |
182 | the arguments passed to them. (This is true only when | |
183 | running under VMS; Perl respects the case-sensitivity | |
184 | of OSs like Unix.) | |
a0d0e21e | 185 | |
748a9306 | 186 | We've tried to minimize the dependence of Perl library |
a0d0e21e LW |
187 | modules on Unix syntax, but you may find that some of these, |
188 | as well as some scripts written for Unix systems, will | |
189 | require that you use Unix syntax, since they will assume that | |
4e592037 | 190 | '/' is the directory separator, I<etc.> If you find instances |
748a9306 | 191 | of this in the Perl distribution itself, please let us know, |
a0d0e21e LW |
192 | so we can try to work around them. |
193 | ||
4e592037 | 194 | =head2 Wildcard expansion |
195 | ||
196 | File specifications containing wildcards are allowed both on | |
197 | the command line and within Perl globs (e.g. <CE<lt>*.cE<gt>>). If | |
198 | the wildcard filespec uses VMS syntax, the resultant | |
199 | filespecs will follow VMS syntax; if a Unix-style filespec is | |
200 | passed in, Unix-style filespecs will be returned. | |
201 | ||
202 | If the wildcard filespec contains a device or directory | |
203 | specification, then the resultant filespecs will also contain | |
204 | a device and directory; otherwise, device and directory | |
205 | information are removed. VMS-style resultant filespecs will | |
206 | contain a full device and directory, while Unix-style | |
207 | resultant filespecs will contain only as much of a directory | |
208 | path as was present in the input filespec. For example, if | |
209 | your default directory is Perl_Root:[000000], the expansion | |
210 | of C<[.t]*.*> will yield filespecs like | |
211 | "perl_root:[t]base.dir", while the expansion of C<t/*/*> will | |
212 | yield filespecs like "t/base.dir". (This is done to match | |
213 | the behavior of glob expansion performed by Unix shells.) | |
214 | ||
215 | Similarly, the resultant filespec will contain the file version | |
216 | only if one was present in the input filespec. | |
217 | ||
218 | =head2 Pipes | |
219 | ||
220 | Input and output pipes to Perl filehandles are supported; the | |
221 | "file name" is passed to lib$spawn() for asynchronous | |
222 | execution. You should be careful to close any pipes you have | |
223 | opened in a Perl script, lest you leave any "orphaned" | |
224 | subprocesses around when Perl exits. | |
225 | ||
226 | You may also use backticks to invoke a DCL subprocess, whose | |
227 | output is used as the return value of the expression. The | |
228 | string between the backticks is passed directly to lib$spawn | |
229 | as the command to execute. In this case, Perl will wait for | |
230 | the subprocess to complete before continuing. | |
231 | ||
232 | =head1 PERL5LIB and PERLLIB | |
233 | ||
234 | The PERL5LIB and PERLLIB logical names work as documented L<perl>, | |
235 | except that the element separator is '|' instead of ':'. The | |
236 | directory specifications may use either VMS or Unix syntax. | |
237 | ||
238 | =head1 Command line | |
239 | ||
240 | =head2 I/O redirection and backgrounding | |
a0d0e21e LW |
241 | |
242 | Perl for VMS supports redirection of input and output on the | |
243 | command line, using a subset of Bourne shell syntax: | |
55497cff | 244 | |
a0d0e21e LW |
245 | <F<file> reads stdin from F<file>, |
246 | >F<file> writes stdout to F<file>, | |
247 | >>F<file> appends stdout to F<file>, | |
748a9306 | 248 | 2>F<file> writes stderr to F<file>, and |
a0d0e21e LW |
249 | 2>>F<file> appends stderr to F<file>. |
250 | ||
251 | In addition, output may be piped to a subprocess, using the | |
252 | character '|'. Anything after this character on the command | |
253 | line is passed to a subprocess for execution; the subprocess | |
748a9306 | 254 | takes the output of Perl as its input. |
a0d0e21e LW |
255 | |
256 | Finally, if the command line ends with '&', the entire | |
257 | command is run in the background as an asynchronous | |
258 | subprocess. | |
259 | ||
4e592037 | 260 | =head2 Command line switches |
a0d0e21e | 261 | |
4e592037 | 262 | The following command line switches behave differently under |
263 | VMS than described in L<perlrun>. Note also that in order | |
264 | to pass uppercase switches to Perl, you need to enclose | |
265 | them in double-quotes on the command line, since the CRTL | |
266 | downcases all unquoted strings. | |
a0d0e21e | 267 | |
55497cff | 268 | =over 4 |
269 | ||
edc7bc49 CB |
270 | =item -i |
271 | ||
272 | If the C<-i> switch is present but no extension for a backup | |
273 | copy is given, then inplace editing creates a new version of | |
274 | a file; the existing copy is not deleted. (Note that if | |
275 | an extension is given, an existing file is renamed to the backup | |
276 | file, as is the case under other operating systems, so it does | |
277 | not remain as a previous version under the original filename.) | |
278 | ||
4e592037 | 279 | =item -S |
a0d0e21e | 280 | |
4e592037 | 281 | If the C<-S> switch is present I<and> the script name does |
282 | not contain a directory, then Perl translates the logical | |
283 | name DCL$PATH as a searchlist, using each translation as | |
284 | a directory in which to look for the script. In addition, | |
285 | if no file type is specified, Perl looks in each directory | |
286 | for a file matching the name specified, with a blank type, | |
287 | a type of F<.pl>, and a type of F<.com>, in that order. | |
a0d0e21e | 288 | |
4e592037 | 289 | =item -u |
748a9306 | 290 | |
4e592037 | 291 | The C<-u> switch causes the VMS debugger to be invoked |
292 | after the Perl program is compiled, but before it has | |
293 | run. It does not create a core dump file. | |
748a9306 | 294 | |
55497cff | 295 | =back |
296 | ||
748a9306 | 297 | =head1 Perl functions |
a0d0e21e LW |
298 | |
299 | As of the time this document was last revised, the following | |
748a9306 | 300 | Perl functions were implemented in the VMS port of Perl |
a0d0e21e LW |
301 | (functions marked with * are discussed in more detail below): |
302 | ||
4fdae800 | 303 | file tests*, abs, alarm, atan, backticks*, binmode*, bless, |
a0d0e21e | 304 | caller, chdir, chmod, chown, chomp, chop, chr, |
c07a80fd | 305 | close, closedir, cos, crypt*, defined, delete, |
4e592037 | 306 | die, do, dump*, each, endpwent, eof, eval, exec*, |
307 | exists, exit, exp, fileno, fork*, getc, getlogin, | |
308 | getpwent*, getpwnam*, getpwuid*, glob, gmtime*, goto, | |
309 | grep, hex, import, index, int, join, keys, kill*, | |
310 | last, lc, lcfirst, length, local, localtime, log, m//, | |
311 | map, mkdir, my, next, no, oct, open, opendir, ord, pack, | |
c07a80fd | 312 | pipe, pop, pos, print, printf, push, q//, qq//, qw//, |
4fdae800 | 313 | qx//*, quotemeta, rand, read, readdir, redo, ref, rename, |
a0d0e21e | 314 | require, reset, return, reverse, rewinddir, rindex, |
e518068a | 315 | rmdir, s///, scalar, seek, seekdir, select(internal), |
316 | select (system call)*, setpwent, shift, sin, sleep, | |
317 | sort, splice, split, sprintf, sqrt, srand, stat, | |
318 | study, substr, sysread, system*, syswrite, tell, | |
319 | telldir, tie, time, times*, tr///, uc, ucfirst, umask, | |
320 | undef, unlink*, unpack, untie, unshift, use, utime*, | |
321 | values, vec, wait, waitpid*, wantarray, warn, write, y/// | |
a0d0e21e LW |
322 | |
323 | The following functions were not implemented in the VMS port, | |
324 | and calling them produces a fatal error (usually) or | |
325 | undefined behavior (rarely, we hope): | |
326 | ||
4e592037 | 327 | chroot, dbmclose, dbmopen, fcntl, flock, |
c07a80fd | 328 | getpgrp, getppid, getpriority, getgrent, getgrgid, |
329 | getgrnam, setgrent, endgrent, ioctl, link, lstat, | |
330 | msgctl, msgget, msgsend, msgrcv, readlink, semctl, | |
331 | semget, semop, setpgrp, setpriority, shmctl, shmget, | |
bf99883d HM |
332 | shmread, shmwrite, socketpair, symlink, syscall |
333 | ||
334 | The following functions are available on Perls compiled with Dec C 5.2 or | |
335 | greater and running VMS 7.0 or greater | |
336 | ||
337 | truncate | |
a0d0e21e LW |
338 | |
339 | The following functions may or may not be implemented, | |
340 | depending on what type of socket support you've built into | |
748a9306 | 341 | your copy of Perl: |
4e592037 | 342 | |
a0d0e21e LW |
343 | accept, bind, connect, getpeername, |
344 | gethostbyname, getnetbyname, getprotobyname, | |
345 | getservbyname, gethostbyaddr, getnetbyaddr, | |
346 | getprotobynumber, getservbyport, gethostent, | |
347 | getnetent, getprotoent, getservent, sethostent, | |
348 | setnetent, setprotoent, setservent, endhostent, | |
349 | endnetent, endprotoent, endservent, getsockname, | |
c07a80fd | 350 | getsockopt, listen, recv, select(system call)*, |
351 | send, setsockopt, shutdown, socket | |
a0d0e21e | 352 | |
55497cff | 353 | =over 4 |
a0d0e21e LW |
354 | |
355 | =item File tests | |
356 | ||
748a9306 LW |
357 | The tests C<-b>, C<-B>, C<-c>, C<-C>, C<-d>, C<-e>, C<-f>, |
358 | C<-o>, C<-M>, C<-s>, C<-S>, C<-t>, C<-T>, and C<-z> work as | |
359 | advertised. The return values for C<-r>, C<-w>, and C<-x> | |
360 | tell you whether you can actually access the file; this may | |
361 | not reflect the UIC-based file protections. Since real and | |
362 | effective UIC don't differ under VMS, C<-O>, C<-R>, C<-W>, | |
363 | and C<-X> are equivalent to C<-o>, C<-r>, C<-w>, and C<-x>. | |
364 | Similarly, several other tests, including C<-A>, C<-g>, C<-k>, | |
365 | C<-l>, C<-p>, and C<-u>, aren't particularly meaningful under | |
366 | VMS, and the values returned by these tests reflect whatever | |
367 | your CRTL C<stat()> routine does to the equivalent bits in the | |
368 | st_mode field. Finally, C<-d> returns true if passed a device | |
369 | specification without an explicit directory (e.g. C<DUA1:>), as | |
370 | well as if passed a directory. | |
371 | ||
4e592037 | 372 | Note: Some sites have reported problems when using the file-access |
373 | tests (C<-r>, C<-w>, and C<-x>) on files accessed via DEC's DFS. | |
374 | Specifically, since DFS does not currently provide access to the | |
375 | extended file header of files on remote volumes, attempts to | |
376 | examine the ACL fail, and the file tests will return false, | |
377 | with C<$!> indicating that the file does not exist. You can | |
378 | use C<stat> on these files, since that checks UIC-based protection | |
379 | only, and then manually check the appropriate bits, as defined by | |
380 | your C compiler's F<stat.h>, in the mode value it returns, if you | |
381 | need an approximation of the file's protections. | |
382 | ||
4fdae800 | 383 | =item backticks |
384 | ||
385 | Backticks create a subprocess, and pass the enclosed string | |
386 | to it for execution as a DCL command. Since the subprocess is | |
387 | created directly via C<lib$spawn()>, any valid DCL command string | |
388 | may be specified. | |
389 | ||
748a9306 LW |
390 | =item binmode FILEHANDLE |
391 | ||
1c9f8daa | 392 | The C<binmode> operator will attempt to insure that no translation |
393 | of carriage control occurs on input from or output to this filehandle. | |
394 | Since this involves reopening the file and then restoring its | |
395 | file position indicator, if this function returns FALSE, the | |
396 | underlying filehandle may no longer point to an open file, or may | |
397 | point to a different position in the file than before C<binmode> | |
398 | was called. | |
399 | ||
400 | Note that C<binmode> is generally not necessary when using normal | |
401 | filehandles; it is provided so that you can control I/O to existing | |
402 | record-structured files when necessary. You can also use the | |
403 | C<vmsfopen> function in the VMS::Stdio extension to gain finer | |
404 | control of I/O to files and devices with different record structures. | |
a0d0e21e | 405 | |
c07a80fd | 406 | =item crypt PLAINTEXT, USER |
407 | ||
408 | The C<crypt> operator uses the C<sys$hash_password> system | |
409 | service to generate the hashed representation of PLAINTEXT. | |
410 | If USER is a valid username, the algorithm and salt values | |
411 | are taken from that user's UAF record. If it is not, then | |
412 | the preferred algorithm and a salt of 0 are used. The | |
413 | quadword encrypted value is returned as an 8-character string. | |
414 | ||
415 | The value returned by C<crypt> may be compared against | |
416 | the encrypted password from the UAF returned by the C<getpw*> | |
417 | functions, in order to authenticate users. If you're | |
418 | going to do this, remember that the encrypted password in | |
419 | the UAF was generated using uppercase username and | |
420 | password strings; you'll have to upcase the arguments to | |
421 | C<crypt> to insure that you'll get the proper value: | |
422 | ||
423 | sub validate_passwd { | |
424 | my($user,$passwd) = @_; | |
425 | my($pwdhash); | |
426 | if ( !($pwdhash = (getpwnam($user))[1]) || | |
427 | $pwdhash ne crypt("\U$passwd","\U$name") ) { | |
428 | intruder_alert($name); | |
429 | } | |
430 | return 1; | |
431 | } | |
432 | ||
4e592037 | 433 | =item dump |
434 | ||
435 | Rather than causing Perl to abort and dump core, the C<dump> | |
436 | operator invokes the VMS debugger. If you continue to | |
437 | execute the Perl program under the debugger, control will | |
438 | be transferred to the label specified as the argument to | |
439 | C<dump>, or, if no label was specified, back to the | |
440 | beginning of the program. All other state of the program | |
441 | (I<e.g.> values of variables, open file handles) are not | |
442 | affected by calling C<dump>. | |
443 | ||
748a9306 | 444 | =item exec LIST |
a0d0e21e | 445 | |
748a9306 LW |
446 | The C<exec> operator behaves in one of two different ways. |
447 | If called after a call to C<fork>, it will invoke the CRTL | |
448 | C<execv()> routine, passing its arguments to the subprocess | |
449 | created by C<fork> for execution. In this case, it is | |
450 | subject to all limitations that affect C<execv()>. (In | |
a0d0e21e LW |
451 | particular, this usually means that the command executed in |
452 | the subprocess must be an image compiled from C source code, | |
453 | and that your options for passing file descriptors and signal | |
454 | handlers to the subprocess are limited.) | |
455 | ||
748a9306 LW |
456 | If the call to C<exec> does not follow a call to C<fork>, it |
457 | will cause Perl to exit, and to invoke the command given as | |
458 | an argument to C<exec> via C<lib$do_command>. If the argument | |
a0d0e21e LW |
459 | begins with a '$' (other than as part of a filespec), then it |
460 | is executed as a DCL command. Otherwise, the first token on | |
461 | the command line is treated as the filespec of an image to | |
462 | run, and an attempt is made to invoke it (using F<.Exe> and | |
463 | the process defaults to expand the filespec) and pass the | |
748a9306 | 464 | rest of C<exec>'s argument to it as parameters. |
a0d0e21e | 465 | |
748a9306 LW |
466 | You can use C<exec> in both ways within the same script, as |
467 | long as you call C<fork> and C<exec> in pairs. Perl | |
468 | keeps track of how many times C<fork> and C<exec> have been | |
469 | called, and will call the CRTL C<execv()> routine if there have | |
470 | previously been more calls to C<fork> than to C<exec>. | |
a0d0e21e LW |
471 | |
472 | =item fork | |
473 | ||
748a9306 LW |
474 | The C<fork> operator works in the same way as the CRTL |
475 | C<vfork()> routine, which is quite different under VMS than | |
476 | under Unix. Specifically, while C<fork> returns 0 after it | |
477 | is called and the subprocess PID after C<exec> is called, in | |
a0d0e21e LW |
478 | both cases the thread of execution is within the parent |
479 | process, so there is no opportunity to perform operations in | |
748a9306 | 480 | the subprocess before calling C<exec>. |
a0d0e21e | 481 | |
748a9306 | 482 | In general, the use of C<fork> and C<exec> to create |
a0d0e21e | 483 | subprocess is not recommended under VMS; wherever possible, |
748a9306 LW |
484 | use the C<system> operator or piped filehandles instead. |
485 | ||
486 | =item getpwent | |
c07a80fd | 487 | |
748a9306 | 488 | =item getpwnam |
c07a80fd | 489 | |
748a9306 LW |
490 | =item getpwuid |
491 | ||
492 | These operators obtain the information described in L<perlfunc>, | |
493 | if you have the privileges necessary to retrieve the named user's | |
494 | UAF information via C<sys$getuai>. If not, then only the C<$name>, | |
495 | C<$uid>, and C<$gid> items are returned. The C<$dir> item contains | |
496 | the login directory in VMS syntax, while the C<$comment> item | |
497 | contains the login directory in Unix syntax. The C<$gcos> item | |
498 | contains the owner field from the UAF record. The C<$quota> | |
499 | item is not used. | |
a0d0e21e | 500 | |
e518068a | 501 | =item gmtime |
502 | ||
503 | The C<gmtime> operator will function properly if you have a | |
504 | working CRTL C<gmtime()> routine, or if the logical name | |
505 | SYS$TIMEZONE_DIFFERENTIAL is defined as the number of seconds | |
506 | which must be added to UTC to yield local time. (This logical | |
507 | name is defined automatically if you are running a version of | |
508 | VMS with built-in UTC support.) If neither of these cases is | |
509 | true, a warning message is printed, and C<undef> is returned. | |
510 | ||
511 | =item kill | |
512 | ||
513 | In most cases, C<kill> kill is implemented via the CRTL's C<kill()> | |
514 | function, so it will behave according to that function's | |
515 | documentation. If you send a SIGKILL, however, the $DELPRC system | |
10a676f8 | 516 | service is called directly. This insures that the target |
e518068a | 517 | process is actually deleted, if at all possible. (The CRTL's C<kill()> |
518 | function is presently implemented via $FORCEX, which is ignored by | |
519 | supervisor-mode images like DCL.) | |
520 | ||
521 | Also, negative signal values don't do anything special under | |
522 | VMS; they're just converted to the corresponding positive value. | |
523 | ||
4fdae800 | 524 | =item qx// |
525 | ||
526 | See the entry on C<backticks> above. | |
527 | ||
e518068a | 528 | =item select (system call) |
529 | ||
530 | If Perl was not built with socket support, the system call | |
531 | version of C<select> is not available at all. If socket | |
532 | support is present, then the system call version of | |
533 | C<select> functions only for file descriptors attached | |
534 | to sockets. It will not provide information about regular | |
535 | files or pipes, since the CRTL C<select()> routine does not | |
536 | provide this functionality. | |
537 | ||
748a9306 | 538 | =item stat EXPR |
a0d0e21e | 539 | |
748a9306 LW |
540 | Since VMS keeps track of files according to a different scheme |
541 | than Unix, it's not really possible to represent the file's ID | |
542 | in the C<st_dev> and C<st_ino> fields of a C<struct stat>. Perl | |
543 | tries its best, though, and the values it uses are pretty unlikely | |
544 | to be the same for two different files. We can't guarantee this, | |
545 | though, so caveat scriptor. | |
546 | ||
547 | =item system LIST | |
548 | ||
549 | The C<system> operator creates a subprocess, and passes its | |
a0d0e21e | 550 | arguments to the subprocess for execution as a DCL command. |
e518068a | 551 | Since the subprocess is created directly via C<lib$spawn()>, any |
748a9306 LW |
552 | valid DCL command string may be specified. If LIST consists |
553 | of the empty string, C<system> spawns an interactive DCL subprocess, | |
554 | in the same fashion as typiing B<SPAWN> at the DCL prompt. | |
555 | Perl waits for the subprocess to complete before continuing | |
4fdae800 | 556 | execution in the current process. As described in L<perlfunc>, |
557 | the return value of C<system> is a fake "status" which follows | |
558 | POSIX semantics; see the description of C<$?> in this document | |
559 | for more detail. The actual VMS exit status of the subprocess | |
560 | is available in C<$^S> (as long as you haven't used another Perl | |
561 | function that resets C<$?> and C<$^S> in the meantime). | |
a0d0e21e | 562 | |
1c9f8daa | 563 | =item time |
564 | ||
565 | The value returned by C<time> is the offset in seconds from | |
566 | 01-JAN-1970 00:00:00 (just like the CRTL's times() routine), in order | |
567 | to make life easier for code coming in from the POSIX/Unix world. | |
568 | ||
a0d0e21e LW |
569 | =item times |
570 | ||
748a9306 LW |
571 | The array returned by the C<times> operator is divided up |
572 | according to the same rules the CRTL C<times()> routine. | |
a0d0e21e LW |
573 | Therefore, the "system time" elements will always be 0, since |
574 | there is no difference between "user time" and "system" time | |
575 | under VMS, and the time accumulated by subprocess may or may | |
576 | not appear separately in the "child time" field, depending on | |
748a9306 LW |
577 | whether L<times> keeps track of subprocesses separately. Note |
578 | especially that the VAXCRTL (at least) keeps track only of | |
579 | subprocesses spawned using L<fork> and L<exec>; it will not | |
580 | accumulate the times of suprocesses spawned via pipes, L<system>, | |
581 | or backticks. | |
582 | ||
16d20bd9 AD |
583 | =item unlink LIST |
584 | ||
585 | C<unlink> will delete the highest version of a file only; in | |
586 | order to delete all versions, you need to say | |
587 | 1 while (unlink LIST); | |
588 | You may need to make this change to scripts written for a | |
589 | Unix system which expect that after a call to C<unlink>, | |
590 | no files with the names passed to C<unlink> will exist. | |
4633a7c4 LW |
591 | (Note: This can be changed at compile time; if you |
592 | C<use Config> and C<$Config{'d_unlink_all_versions'}> is | |
593 | C<define>, then C<unlink> will delete all versions of a | |
594 | file on the first call.) | |
16d20bd9 AD |
595 | |
596 | C<unlink> will delete a file if at all possible, even if it | |
597 | requires changing file protection (though it won't try to | |
598 | change the protection of the parent directory). You can tell | |
599 | whether you've got explicit delete access to a file by using the | |
600 | C<VMS::Filespec::candelete> operator. For instance, in order | |
601 | to delete only files to which you have delete access, you could | |
602 | say something like | |
4e592037 | 603 | |
16d20bd9 AD |
604 | sub safe_unlink { |
605 | my($file,$num); | |
606 | foreach $file (@_) { | |
607 | next unless VMS::Filespec::candelete($file); | |
608 | $num += unlink $file; | |
609 | } | |
610 | $num; | |
611 | } | |
4e592037 | 612 | |
613 | (or you could just use C<VMS::Stdio::remove>, if you've installed | |
614 | the VMS::Stdio extension distributed with Perl). If C<unlink> has to | |
615 | change the file protection to delete the file, and you interrupt it | |
616 | in midstream, the file may be left intact, but with a changed ACL | |
617 | allowing you delete access. | |
16d20bd9 | 618 | |
748a9306 LW |
619 | =item utime LIST |
620 | ||
621 | Since ODS-2, the VMS file structure for disk files, does not keep | |
622 | track of access times, this operator changes only the modification | |
623 | time of the file (VMS revision date). | |
624 | ||
625 | =item waitpid PID,FLAGS | |
626 | ||
627 | If PID is a subprocess started by a piped L<open>, C<waitpid> | |
628 | will wait for that subprocess, and return its final | |
629 | status value. If PID is a subprocess created in some other way | |
630 | (e.g. SPAWNed before Perl was invoked), or is not a subprocess of | |
631 | the current process, C<waitpid> will check once per second whether | |
632 | the process has completed, and when it has, will return 0. (If PID | |
633 | specifies a process that isn't a subprocess of the current process, | |
634 | and you invoked Perl with the C<-w> switch, a warning will be issued.) | |
635 | ||
636 | The FLAGS argument is ignored in all cases. | |
a0d0e21e | 637 | |
55497cff | 638 | =back |
639 | ||
a5f75d66 AD |
640 | =head1 Perl variables |
641 | ||
55497cff | 642 | The following VMS-specific information applies to the indicated |
643 | "special" Perl variables, in addition to the general information | |
644 | in L<perlvar>. Where there is a conflict, this infrmation | |
645 | takes precedence. | |
646 | ||
647 | =over 4 | |
648 | ||
a5f75d66 AD |
649 | =item %ENV |
650 | ||
651 | Reading the elements of the %ENV array returns the | |
652 | translation of the logical name specified by the key, | |
653 | according to the normal search order of access modes and | |
654 | logical name tables. If you append a semicolon to the | |
655 | logical name, followed by an integer, that integer is | |
656 | used as the translation index for the logical name, | |
657 | so that you can look up successive values for search | |
658 | list logical names. For instance, if you say | |
659 | ||
660 | $ Define STORY once,upon,a,time,there,was | |
661 | $ perl -e "for ($i = 0; $i <= 6; $i++) " - | |
740ce14c | 662 | _$ -e "{ print $ENV{'story;'.$i},' '}" |
a5f75d66 AD |
663 | |
664 | Perl will print C<ONCE UPON A TIME THERE WAS>. | |
665 | ||
666 | The %ENV keys C<home>, C<path>,C<term>, and C<user> | |
667 | return the CRTL "environment variables" of the same | |
668 | names, if these logical names are not defined. The | |
669 | key C<default> returns the current default device | |
670 | and directory specification, regardless of whether | |
671 | there is a logical name DEFAULT defined.. | |
672 | ||
673 | Setting an element of %ENV defines a supervisor-mode logical | |
674 | name in the process logical name table. C<Undef>ing or | |
675 | C<delete>ing an element of %ENV deletes the equivalent user- | |
676 | mode or supervisor-mode logical name from the process logical | |
677 | name table. If you use C<undef>, the %ENV element remains | |
678 | empty. If you use C<delete>, another attempt is made at | |
679 | logical name translation after the deletion, so an inner-mode | |
680 | logical name or a name in another logical name table will | |
681 | replace the logical name just deleted. It is not possible | |
682 | at present to define a search list logical name via %ENV. | |
683 | ||
740ce14c | 684 | At present, the first time you iterate over %ENV using |
edc7bc49 CB |
685 | C<keys>, or C<values>, you will incur a time penalty as all |
686 | logical names are read, in order to fully populate %ENV. | |
687 | Subsequent iterations will not reread logical names, so they | |
688 | won't be as slow, but they also won't reflect any changes | |
689 | to logical name tables caused by other programs. The C<each> | |
690 | operator is special: it returns each element I<already> in | |
691 | %ENV, but doesn't go out and look for more. Therefore, if | |
692 | you've previously used C<keys> or C<values>, you'll see all | |
693 | the logical names visible to your process, and if not, you'll | |
694 | see only the names you've looked up so far. (This is a | |
695 | consequence of the way C<each> is implemented now, and it | |
696 | may change in the future, so it wouldn't be a good idea | |
697 | to rely on it too much.) | |
740ce14c | 698 | |
a5f75d66 AD |
699 | In all operations on %ENV, the key string is treated as if it |
700 | were entirely uppercase, regardless of the case actually | |
701 | specified in the Perl expression. | |
702 | ||
a5f75d66 AD |
703 | =item $! |
704 | ||
705 | The string value of C<$!> is that returned by the CRTL's | |
706 | strerror() function, so it will include the VMS message for | |
707 | VMS-specific errors. The numeric value of C<$!> is the | |
708 | value of C<errno>, except if errno is EVMSERR, in which | |
709 | case C<$!> contains the value of vaxc$errno. Setting C<$!> | |
4e592037 | 710 | always sets errno to the value specified. If this value is |
711 | EVMSERR, it also sets vaxc$errno to 4 (NONAME-F-NOMSG), so | |
712 | that the string value of C<$!> won't reflect the VMS error | |
713 | message from before C<$!> was set. | |
714 | ||
715 | =item $^E | |
716 | ||
717 | This variable provides direct access to VMS status values | |
718 | in vaxc$errno, which are often more specific than the | |
719 | generic Unix-style error messages in C<$!>. Its numeric value | |
720 | is the value of vaxc$errno, and its string value is the | |
721 | corresponding VMS message string, as retrieved by sys$getmsg(). | |
722 | Setting C<$^E> sets vaxc$errno to the value specified. | |
723 | ||
4fdae800 | 724 | =item $? |
725 | ||
726 | The "status value" returned in C<$?> is synthesized from the | |
727 | actual exit status of the subprocess in a way that approximates | |
728 | POSIX wait(5) semantics, in order to allow Perl programs to | |
729 | portably test for successful completion of subprocesses. The | |
730 | low order 8 bits of C<$?> are always 0 under VMS, since the | |
731 | termination status of a process may or may not have been | |
732 | generated by an exception. The next 8 bits are derived from | |
733 | severity portion of the subprocess' exit status: if the | |
734 | severity was success or informational, these bits are all 0; | |
735 | otherwise, they contain the severity value shifted left one bit. | |
736 | As a result, C<$?> will always be zero if the subprocess' exit | |
737 | status indicated successful completion, and non-zero if a | |
738 | warning or error occurred. The actual VMS exit status may | |
739 | be found in C<$^S> (q.v.). | |
740 | ||
741 | =item $^S | |
742 | ||
743 | Under VMS, this is the 32-bit VMS status value returned by the | |
744 | last subprocess to complete. Unlink C<$?>, no manipulation | |
745 | is done to make this look like a POSIX wait(5) value, so it | |
746 | may be treated as a normal VMS status value. | |
747 | ||
4e592037 | 748 | =item $| |
749 | ||
750 | Setting C<$|> for an I/O stream causes data to be flushed | |
751 | all the way to disk on each write (I<i.e.> not just to | |
752 | the underlying RMS buffers for a file). In other words, | |
753 | it's equivalent to calling fflush() and fsync() from C. | |
a5f75d66 | 754 | |
55497cff | 755 | =back |
756 | ||
bf99883d HM |
757 | =head1 Standard modules with VMS-specific differences |
758 | ||
759 | =head2 SDBM_File | |
760 | ||
761 | SDBM_File works peroperly on VMS. It has, however, one minor | |
762 | difference. The database directory file created has a L<.sdbm_dir> | |
763 | extension rather than a L<.dir> extension. L<.dir> files are VMS filesystem | |
764 | directory files, and using them for other purposes could cause unacceptable | |
765 | problems. | |
766 | ||
748a9306 | 767 | =head1 Revision date |
a0d0e21e | 768 | |
bf99883d HM |
769 | This document was last updated on 26-Feb-1998, for Perl 5, |
770 | patchlevel 5. | |
e518068a | 771 | |
772 | =head1 AUTHOR | |
773 | ||
bf99883d | 774 | Charles Bailey bailey@cor.newman.upenn.edu |
e518068a | 775 | |
bf99883d | 776 | Last revision by Dan Sugalski sugalskd@ous.edu |