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