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 |
9bc98430 |
20 | hesitate to drop a line to vmsperl@perl.org. |
a0d0e21e |
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 |
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 |
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 |
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. |
d7f8936a |
124 | For this reason if you are running a version of VMS prior |
773da73d |
125 | to V7.1 you shouldn't nest the source directory |
126 | too deeply in your directory structure lest you exceed RMS' |
c07a80fd |
127 | maximum of 8 levels of subdirectory in a filespec. (You |
128 | can use rooted logical names to get another 8 levels of |
129 | nesting, if you can't place the files near the top of |
130 | the physical directory structure.) |
e518068a |
131 | |
132 | VMS support for this process in the current release of Perl |
133 | is sufficient to handle most extensions. However, it does |
134 | not yet recognize extra libraries required to build shareable |
135 | images which are part of an extension, so these must be added |
136 | to the linker options file for the extension by hand. For |
137 | instance, if the F<PGPLOT> extension to Perl requires the |
138 | F<PGPLOTSHR.EXE> shareable image in order to properly link |
139 | the Perl extension, then the line C<PGPLOTSHR/Share> must |
140 | be added to the linker options file F<PGPLOT.Opt> produced |
141 | during the build process for the Perl extension. |
142 | |
773da73d |
143 | By default, the shareable image for an extension is placed in |
144 | the F<[.lib.site_perl.auto>I<Arch>.I<Extname>F<]> directory of the |
e518068a |
145 | installed Perl directory tree (where I<Arch> is F<VMS_VAX> or |
bbce6d69 |
146 | F<VMS_AXP>, and I<Extname> is the name of the extension, with |
147 | each C<::> translated to C<.>). (See the MakeMaker documentation |
148 | for more details on installation options for extensions.) |
4e592037 |
149 | However, it can be manually placed in any of several locations: |
773da73d |
150 | |
151 | =over 4 |
152 | |
153 | =item * |
154 | |
155 | the F<[.Lib.Auto.>I<Arch>I<$PVers>I<Extname>F<]> subdirectory |
156 | of one of the directories in C<@INC> (where I<PVers> |
157 | is the version of Perl you're using, as supplied in C<$]>, |
158 | with '.' converted to '_'), or |
159 | |
160 | =item * |
161 | |
162 | one of the directories in C<@INC>, or |
163 | |
164 | =item * |
165 | |
166 | a directory which the extensions Perl library module |
167 | passes to the DynaLoader when asking it to map |
168 | the shareable image, or |
169 | |
170 | =item * |
171 | |
172 | F<Sys$Share> or F<Sys$Library>. |
173 | |
174 | =back |
175 | |
748a9306 |
176 | If the shareable image isn't in any of these places, you'll need |
177 | to define a logical name I<Extshortname>, where I<Extshortname> |
178 | is the portion of the extension's name after the last C<::>, which |
179 | translates to the full file specification of the shareable image. |
180 | |
4e592037 |
181 | =head1 File specifications |
748a9306 |
182 | |
4e592037 |
183 | =head2 Syntax |
a0d0e21e |
184 | |
748a9306 |
185 | We have tried to make Perl aware of both VMS-style and Unix- |
a0d0e21e |
186 | style file specifications wherever possible. You may use |
187 | either style, or both, on the command line and in scripts, |
39aca757 |
188 | but you may not combine the two styles within a single file |
1c9f8daa |
189 | specification. VMS Perl interprets Unix pathnames in much |
190 | the same way as the CRTL (I<e.g.> the first component of |
191 | an absolute path is read as the device name for the |
192 | VMS file specification). There are a set of functions |
193 | provided in the C<VMS::Filespec> package for explicit |
194 | interconversion between VMS and Unix syntax; its |
195 | documentation provides more details. |
196 | |
197 | Filenames are, of course, still case-insensitive. For |
198 | consistency, most Perl routines return filespecs using |
199 | lower case letters only, regardless of the case used in |
200 | the arguments passed to them. (This is true only when |
201 | running under VMS; Perl respects the case-sensitivity |
202 | of OSs like Unix.) |
a0d0e21e |
203 | |
748a9306 |
204 | We've tried to minimize the dependence of Perl library |
a0d0e21e |
205 | modules on Unix syntax, but you may find that some of these, |
206 | as well as some scripts written for Unix systems, will |
207 | require that you use Unix syntax, since they will assume that |
4e592037 |
208 | '/' is the directory separator, I<etc.> If you find instances |
748a9306 |
209 | of this in the Perl distribution itself, please let us know, |
a0d0e21e |
210 | so we can try to work around them. |
211 | |
4e592037 |
212 | =head2 Wildcard expansion |
213 | |
214 | File specifications containing wildcards are allowed both on |
07698885 |
215 | the command line and within Perl globs (e.g. C<E<lt>*.cE<gt>>). If |
4e592037 |
216 | the wildcard filespec uses VMS syntax, the resultant |
217 | filespecs will follow VMS syntax; if a Unix-style filespec is |
218 | passed in, Unix-style filespecs will be returned. |
773da73d |
219 | Similar to the behavior of wildcard globbing for a Unix shell, |
220 | one can escape command line wildcards with double quotation |
221 | marks C<"> around a perl program command line argument. However, |
222 | owing to the stripping of C<"> characters carried out by the C |
223 | handling of argv you will need to escape a construct such as |
224 | this one (in a directory containing the files F<PERL.C>, F<PERL.EXE>, |
225 | F<PERL.H>, and F<PERL.OBJ>): |
226 | |
227 | $ perl -e "print join(' ',@ARGV)" perl.* |
228 | perl.c perl.exe perl.h perl.obj |
229 | |
230 | in the following triple quoted manner: |
231 | |
232 | $ perl -e "print join(' ',@ARGV)" """perl.*""" |
233 | perl.* |
4e592037 |
234 | |
773da73d |
235 | In both the case of unquoted command line arguments or in calls |
236 | to C<glob()> VMS wildcard expansion is performed. (csh-style |
aa779de1 |
237 | wildcard expansion is available if you use C<File::Glob::glob>.) |
4e592037 |
238 | If the wildcard filespec contains a device or directory |
239 | specification, then the resultant filespecs will also contain |
240 | a device and directory; otherwise, device and directory |
241 | information are removed. VMS-style resultant filespecs will |
242 | contain a full device and directory, while Unix-style |
243 | resultant filespecs will contain only as much of a directory |
244 | path as was present in the input filespec. For example, if |
245 | your default directory is Perl_Root:[000000], the expansion |
246 | of C<[.t]*.*> will yield filespecs like |
247 | "perl_root:[t]base.dir", while the expansion of C<t/*/*> will |
248 | yield filespecs like "t/base.dir". (This is done to match |
249 | the behavior of glob expansion performed by Unix shells.) |
250 | |
251 | Similarly, the resultant filespec will contain the file version |
252 | only if one was present in the input filespec. |
253 | |
254 | =head2 Pipes |
255 | |
256 | Input and output pipes to Perl filehandles are supported; the |
257 | "file name" is passed to lib$spawn() for asynchronous |
258 | execution. You should be careful to close any pipes you have |
259 | opened in a Perl script, lest you leave any "orphaned" |
260 | subprocesses around when Perl exits. |
261 | |
262 | You may also use backticks to invoke a DCL subprocess, whose |
263 | output is used as the return value of the expression. The |
aa779de1 |
264 | string between the backticks is handled as if it were the |
265 | argument to the C<system> operator (see below). In this case, |
266 | Perl will wait for the subprocess to complete before continuing. |
4e592037 |
267 | |
376ae1f1 |
268 | The mailbox (MBX) that perl can create to communicate with a pipe |
269 | defaults to a buffer size of 512. The default buffer size is |
1506e54c |
270 | adjustable via the logical name PERL_MBX_SIZE provided that the |
376ae1f1 |
271 | value falls between 128 and the SYSGEN parameter MAXBUF inclusive. |
272 | For example, to double the MBX size from the default within |
1506e54c |
273 | a Perl program, use C<$ENV{'PERL_MBX_SIZE'} = 1024;> and then |
376ae1f1 |
274 | open and use pipe constructs. An alternative would be to issue |
275 | the command: |
276 | |
277 | $ Define PERL_MBX_SIZE 1024 |
278 | |
279 | before running your wide record pipe program. A larger value may |
280 | improve performance at the expense of the BYTLM UAF quota. |
281 | |
4e592037 |
282 | =head1 PERL5LIB and PERLLIB |
283 | |
39aca757 |
284 | The PERL5LIB and PERLLIB logical names work as documented in L<perl>, |
4e592037 |
285 | except that the element separator is '|' instead of ':'. The |
286 | directory specifications may use either VMS or Unix syntax. |
287 | |
288 | =head1 Command line |
289 | |
290 | =head2 I/O redirection and backgrounding |
a0d0e21e |
291 | |
292 | Perl for VMS supports redirection of input and output on the |
293 | command line, using a subset of Bourne shell syntax: |
55497cff |
294 | |
773da73d |
295 | =over 4 |
07698885 |
296 | |
297 | =item * |
298 | |
299 | C<E<lt>file> reads stdin from C<file>, |
300 | |
301 | =item * |
302 | |
303 | C<E<gt>file> writes stdout to C<file>, |
304 | |
305 | =item * |
306 | |
307 | C<E<gt>E<gt>file> appends stdout to C<file>, |
308 | |
309 | =item * |
310 | |
2fde0ff0 |
311 | C<2E<gt>file> writes stderr to C<file>, |
07698885 |
312 | |
313 | =item * |
314 | |
2fde0ff0 |
315 | C<2E<gt>E<gt>file> appends stderr to C<file>, and |
316 | |
317 | =item * |
318 | |
319 | C<< 2>&1 >> redirects stderr to stdout. |
07698885 |
320 | |
321 | =back |
a0d0e21e |
322 | |
323 | In addition, output may be piped to a subprocess, using the |
324 | character '|'. Anything after this character on the command |
325 | line is passed to a subprocess for execution; the subprocess |
748a9306 |
326 | takes the output of Perl as its input. |
a0d0e21e |
327 | |
328 | Finally, if the command line ends with '&', the entire |
329 | command is run in the background as an asynchronous |
330 | subprocess. |
331 | |
4e592037 |
332 | =head2 Command line switches |
a0d0e21e |
333 | |
4e592037 |
334 | The following command line switches behave differently under |
335 | VMS than described in L<perlrun>. Note also that in order |
336 | to pass uppercase switches to Perl, you need to enclose |
337 | them in double-quotes on the command line, since the CRTL |
338 | downcases all unquoted strings. |
a0d0e21e |
339 | |
55497cff |
340 | =over 4 |
341 | |
edc7bc49 |
342 | =item -i |
343 | |
344 | If the C<-i> switch is present but no extension for a backup |
345 | copy is given, then inplace editing creates a new version of |
346 | a file; the existing copy is not deleted. (Note that if |
347 | an extension is given, an existing file is renamed to the backup |
348 | file, as is the case under other operating systems, so it does |
349 | not remain as a previous version under the original filename.) |
350 | |
4e592037 |
351 | =item -S |
a0d0e21e |
352 | |
376ae1f1 |
353 | If the C<"-S"> or C<-"S"> switch is present I<and> the script |
354 | name does not contain a directory, then Perl translates the |
355 | logical name DCL$PATH as a searchlist, using each translation |
356 | as a directory in which to look for the script. In addition, |
4e592037 |
357 | if no file type is specified, Perl looks in each directory |
358 | for a file matching the name specified, with a blank type, |
359 | a type of F<.pl>, and a type of F<.com>, in that order. |
a0d0e21e |
360 | |
4e592037 |
361 | =item -u |
748a9306 |
362 | |
4e592037 |
363 | The C<-u> switch causes the VMS debugger to be invoked |
364 | after the Perl program is compiled, but before it has |
365 | run. It does not create a core dump file. |
748a9306 |
366 | |
55497cff |
367 | =back |
368 | |
748a9306 |
369 | =head1 Perl functions |
a0d0e21e |
370 | |
371 | As of the time this document was last revised, the following |
748a9306 |
372 | Perl functions were implemented in the VMS port of Perl |
a0d0e21e |
373 | (functions marked with * are discussed in more detail below): |
374 | |
4fdae800 |
375 | file tests*, abs, alarm, atan, backticks*, binmode*, bless, |
a0d0e21e |
376 | caller, chdir, chmod, chown, chomp, chop, chr, |
c07a80fd |
377 | close, closedir, cos, crypt*, defined, delete, |
4e592037 |
378 | die, do, dump*, each, endpwent, eof, eval, exec*, |
41cbbefa |
379 | exists, exit, exp, fileno, getc, getlogin, getppid, |
4e592037 |
380 | getpwent*, getpwnam*, getpwuid*, glob, gmtime*, goto, |
381 | grep, hex, import, index, int, join, keys, kill*, |
382 | last, lc, lcfirst, length, local, localtime, log, m//, |
383 | map, mkdir, my, next, no, oct, open, opendir, ord, pack, |
c07a80fd |
384 | pipe, pop, pos, print, printf, push, q//, qq//, qw//, |
4fdae800 |
385 | qx//*, quotemeta, rand, read, readdir, redo, ref, rename, |
a0d0e21e |
386 | require, reset, return, reverse, rewinddir, rindex, |
e518068a |
387 | rmdir, s///, scalar, seek, seekdir, select(internal), |
388 | select (system call)*, setpwent, shift, sin, sleep, |
389 | sort, splice, split, sprintf, sqrt, srand, stat, |
390 | study, substr, sysread, system*, syswrite, tell, |
391 | telldir, tie, time, times*, tr///, uc, ucfirst, umask, |
392 | undef, unlink*, unpack, untie, unshift, use, utime*, |
393 | values, vec, wait, waitpid*, wantarray, warn, write, y/// |
a0d0e21e |
394 | |
395 | The following functions were not implemented in the VMS port, |
396 | and calling them produces a fatal error (usually) or |
397 | undefined behavior (rarely, we hope): |
398 | |
41cbbefa |
399 | chroot, dbmclose, dbmopen, flock, fork*, |
400 | getpgrp, getpriority, getgrent, getgrgid, |
c07a80fd |
401 | getgrnam, setgrent, endgrent, ioctl, link, lstat, |
402 | msgctl, msgget, msgsend, msgrcv, readlink, semctl, |
403 | semget, semop, setpgrp, setpriority, shmctl, shmget, |
bf99883d |
404 | shmread, shmwrite, socketpair, symlink, syscall |
405 | |
35b2760a |
406 | The following functions are available on Perls compiled with Dec C |
407 | 5.2 or greater and running VMS 7.0 or greater: |
bf99883d |
408 | |
409 | truncate |
a0d0e21e |
410 | |
35b2760a |
411 | The following functions are available on Perls built on VMS 7.2 or |
412 | greater: |
413 | |
414 | fcntl (without locking) |
415 | |
a0d0e21e |
416 | The following functions may or may not be implemented, |
417 | depending on what type of socket support you've built into |
748a9306 |
418 | your copy of Perl: |
4e592037 |
419 | |
a0d0e21e |
420 | accept, bind, connect, getpeername, |
421 | gethostbyname, getnetbyname, getprotobyname, |
422 | getservbyname, gethostbyaddr, getnetbyaddr, |
423 | getprotobynumber, getservbyport, gethostent, |
424 | getnetent, getprotoent, getservent, sethostent, |
425 | setnetent, setprotoent, setservent, endhostent, |
426 | endnetent, endprotoent, endservent, getsockname, |
c07a80fd |
427 | getsockopt, listen, recv, select(system call)*, |
428 | send, setsockopt, shutdown, socket |
a0d0e21e |
429 | |
55497cff |
430 | =over 4 |
a0d0e21e |
431 | |
432 | =item File tests |
433 | |
748a9306 |
434 | The tests C<-b>, C<-B>, C<-c>, C<-C>, C<-d>, C<-e>, C<-f>, |
435 | C<-o>, C<-M>, C<-s>, C<-S>, C<-t>, C<-T>, and C<-z> work as |
436 | advertised. The return values for C<-r>, C<-w>, and C<-x> |
437 | tell you whether you can actually access the file; this may |
438 | not reflect the UIC-based file protections. Since real and |
439 | effective UIC don't differ under VMS, C<-O>, C<-R>, C<-W>, |
440 | and C<-X> are equivalent to C<-o>, C<-r>, C<-w>, and C<-x>. |
441 | Similarly, several other tests, including C<-A>, C<-g>, C<-k>, |
442 | C<-l>, C<-p>, and C<-u>, aren't particularly meaningful under |
443 | VMS, and the values returned by these tests reflect whatever |
444 | your CRTL C<stat()> routine does to the equivalent bits in the |
445 | st_mode field. Finally, C<-d> returns true if passed a device |
446 | specification without an explicit directory (e.g. C<DUA1:>), as |
447 | well as if passed a directory. |
448 | |
4e592037 |
449 | Note: Some sites have reported problems when using the file-access |
450 | tests (C<-r>, C<-w>, and C<-x>) on files accessed via DEC's DFS. |
451 | Specifically, since DFS does not currently provide access to the |
452 | extended file header of files on remote volumes, attempts to |
453 | examine the ACL fail, and the file tests will return false, |
454 | with C<$!> indicating that the file does not exist. You can |
455 | use C<stat> on these files, since that checks UIC-based protection |
456 | only, and then manually check the appropriate bits, as defined by |
457 | your C compiler's F<stat.h>, in the mode value it returns, if you |
458 | need an approximation of the file's protections. |
459 | |
4fdae800 |
460 | =item backticks |
461 | |
462 | Backticks create a subprocess, and pass the enclosed string |
463 | to it for execution as a DCL command. Since the subprocess is |
464 | created directly via C<lib$spawn()>, any valid DCL command string |
465 | may be specified. |
466 | |
748a9306 |
467 | =item binmode FILEHANDLE |
468 | |
1c9f8daa |
469 | The C<binmode> operator will attempt to insure that no translation |
470 | of carriage control occurs on input from or output to this filehandle. |
471 | Since this involves reopening the file and then restoring its |
472 | file position indicator, if this function returns FALSE, the |
473 | underlying filehandle may no longer point to an open file, or may |
474 | point to a different position in the file than before C<binmode> |
475 | was called. |
476 | |
477 | Note that C<binmode> is generally not necessary when using normal |
478 | filehandles; it is provided so that you can control I/O to existing |
479 | record-structured files when necessary. You can also use the |
480 | C<vmsfopen> function in the VMS::Stdio extension to gain finer |
481 | control of I/O to files and devices with different record structures. |
a0d0e21e |
482 | |
c07a80fd |
483 | =item crypt PLAINTEXT, USER |
484 | |
485 | The C<crypt> operator uses the C<sys$hash_password> system |
486 | service to generate the hashed representation of PLAINTEXT. |
487 | If USER is a valid username, the algorithm and salt values |
488 | are taken from that user's UAF record. If it is not, then |
489 | the preferred algorithm and a salt of 0 are used. The |
490 | quadword encrypted value is returned as an 8-character string. |
491 | |
492 | The value returned by C<crypt> may be compared against |
493 | the encrypted password from the UAF returned by the C<getpw*> |
494 | functions, in order to authenticate users. If you're |
495 | going to do this, remember that the encrypted password in |
496 | the UAF was generated using uppercase username and |
497 | password strings; you'll have to upcase the arguments to |
498 | C<crypt> to insure that you'll get the proper value: |
499 | |
376ae1f1 |
500 | sub validate_passwd { |
501 | my($user,$passwd) = @_; |
502 | my($pwdhash); |
503 | if ( !($pwdhash = (getpwnam($user))[1]) || |
504 | $pwdhash ne crypt("\U$passwd","\U$name") ) { |
505 | intruder_alert($name); |
506 | } |
507 | return 1; |
c07a80fd |
508 | } |
c07a80fd |
509 | |
4e592037 |
510 | =item dump |
511 | |
512 | Rather than causing Perl to abort and dump core, the C<dump> |
513 | operator invokes the VMS debugger. If you continue to |
514 | execute the Perl program under the debugger, control will |
515 | be transferred to the label specified as the argument to |
516 | C<dump>, or, if no label was specified, back to the |
517 | beginning of the program. All other state of the program |
518 | (I<e.g.> values of variables, open file handles) are not |
519 | affected by calling C<dump>. |
520 | |
748a9306 |
521 | =item exec LIST |
a0d0e21e |
522 | |
41cbbefa |
523 | A call to C<exec> will cause Perl to exit, and to invoke the command |
524 | given as an argument to C<exec> via C<lib$do_command>. If the |
525 | argument begins with '@' or '$' (other than as part of a filespec), |
526 | then it is executed as a DCL command. Otherwise, the first token on |
527 | the command line is treated as the filespec of an image to run, and |
528 | an attempt is made to invoke it (using F<.Exe> and the process |
529 | defaults to expand the filespec) and pass the rest of C<exec>'s |
530 | argument to it as parameters. If the token has no file type, and |
531 | matches a file with null type, then an attempt is made to determine |
532 | whether the file is an executable image which should be invoked |
533 | using C<MCR> or a text file which should be passed to DCL as a |
534 | command procedure. |
a0d0e21e |
535 | |
536 | =item fork |
537 | |
41cbbefa |
538 | While in principle the C<fork> operator could be implemented via |
539 | (and with the same rather severe limitations as) the CRTL C<vfork()> |
540 | routine, and while some internal support to do just that is in |
541 | place, the implementation has never been completed, making C<fork> |
542 | currently unavailable. A true kernel C<fork()> is expected in a |
543 | future version of VMS, and the pseudo-fork based on interpreter |
544 | threads may be available in a future version of Perl on VMS (see |
545 | L<perlfork>). In the meantime, use C<system>, backticks, or piped |
546 | filehandles to create subprocesses. |
748a9306 |
547 | |
548 | =item getpwent |
c07a80fd |
549 | |
748a9306 |
550 | =item getpwnam |
c07a80fd |
551 | |
748a9306 |
552 | =item getpwuid |
553 | |
554 | These operators obtain the information described in L<perlfunc>, |
555 | if you have the privileges necessary to retrieve the named user's |
556 | UAF information via C<sys$getuai>. If not, then only the C<$name>, |
557 | C<$uid>, and C<$gid> items are returned. The C<$dir> item contains |
558 | the login directory in VMS syntax, while the C<$comment> item |
559 | contains the login directory in Unix syntax. The C<$gcos> item |
560 | contains the owner field from the UAF record. The C<$quota> |
561 | item is not used. |
a0d0e21e |
562 | |
e518068a |
563 | =item gmtime |
564 | |
565 | The C<gmtime> operator will function properly if you have a |
566 | working CRTL C<gmtime()> routine, or if the logical name |
567 | SYS$TIMEZONE_DIFFERENTIAL is defined as the number of seconds |
568 | which must be added to UTC to yield local time. (This logical |
569 | name is defined automatically if you are running a version of |
570 | VMS with built-in UTC support.) If neither of these cases is |
571 | true, a warning message is printed, and C<undef> is returned. |
572 | |
573 | =item kill |
574 | |
39aca757 |
575 | In most cases, C<kill> is implemented via the CRTL's C<kill()> |
e518068a |
576 | function, so it will behave according to that function's |
577 | documentation. If you send a SIGKILL, however, the $DELPRC system |
10a676f8 |
578 | service is called directly. This insures that the target |
e518068a |
579 | process is actually deleted, if at all possible. (The CRTL's C<kill()> |
580 | function is presently implemented via $FORCEX, which is ignored by |
581 | supervisor-mode images like DCL.) |
582 | |
583 | Also, negative signal values don't do anything special under |
584 | VMS; they're just converted to the corresponding positive value. |
585 | |
4fdae800 |
586 | =item qx// |
587 | |
588 | See the entry on C<backticks> above. |
589 | |
e518068a |
590 | =item select (system call) |
591 | |
592 | If Perl was not built with socket support, the system call |
593 | version of C<select> is not available at all. If socket |
594 | support is present, then the system call version of |
595 | C<select> functions only for file descriptors attached |
596 | to sockets. It will not provide information about regular |
597 | files or pipes, since the CRTL C<select()> routine does not |
598 | provide this functionality. |
599 | |
748a9306 |
600 | =item stat EXPR |
a0d0e21e |
601 | |
748a9306 |
602 | Since VMS keeps track of files according to a different scheme |
603 | than Unix, it's not really possible to represent the file's ID |
604 | in the C<st_dev> and C<st_ino> fields of a C<struct stat>. Perl |
605 | tries its best, though, and the values it uses are pretty unlikely |
606 | to be the same for two different files. We can't guarantee this, |
607 | though, so caveat scriptor. |
608 | |
609 | =item system LIST |
610 | |
611 | The C<system> operator creates a subprocess, and passes its |
a0d0e21e |
612 | arguments to the subprocess for execution as a DCL command. |
e518068a |
613 | Since the subprocess is created directly via C<lib$spawn()>, any |
aa779de1 |
614 | valid DCL command string may be specified. If the string begins with |
615 | '@', it is treated as a DCL command unconditionally. Otherwise, if |
616 | the first token contains a character used as a delimiter in file |
617 | specification (e.g. C<:> or C<]>), an attempt is made to expand it |
618 | using a default type of F<.Exe> and the process defaults, and if |
619 | successful, the resulting file is invoked via C<MCR>. This allows you |
620 | to invoke an image directly simply by passing the file specification |
c93fa817 |
621 | to C<system>, a common Unixish idiom. If the token has no file type, |
622 | and matches a file with null type, then an attempt is made to |
623 | determine whether the file is an executable image which should be |
624 | invoked using C<MCR> or a text file which should be passed to DCL |
625 | as a command procedure. |
626 | |
627 | If LIST consists of the empty string, C<system> spawns an |
a2293a43 |
628 | interactive DCL subprocess, in the same fashion as typing |
c93fa817 |
629 | B<SPAWN> at the DCL prompt. |
630 | |
748a9306 |
631 | Perl waits for the subprocess to complete before continuing |
4fdae800 |
632 | execution in the current process. As described in L<perlfunc>, |
633 | the return value of C<system> is a fake "status" which follows |
c6966fea |
634 | POSIX semantics unless the pragma C<use vmsish 'status'> is in |
1b0c4952 |
635 | effect; see the description of C<$?> in this document for more |
636 | detail. |
a0d0e21e |
637 | |
1c9f8daa |
638 | =item time |
639 | |
640 | The value returned by C<time> is the offset in seconds from |
641 | 01-JAN-1970 00:00:00 (just like the CRTL's times() routine), in order |
642 | to make life easier for code coming in from the POSIX/Unix world. |
643 | |
a0d0e21e |
644 | =item times |
645 | |
748a9306 |
646 | The array returned by the C<times> operator is divided up |
647 | according to the same rules the CRTL C<times()> routine. |
a0d0e21e |
648 | Therefore, the "system time" elements will always be 0, since |
649 | there is no difference between "user time" and "system" time |
39aca757 |
650 | under VMS, and the time accumulated by a subprocess may or may |
a0d0e21e |
651 | not appear separately in the "child time" field, depending on |
748a9306 |
652 | whether L<times> keeps track of subprocesses separately. Note |
653 | especially that the VAXCRTL (at least) keeps track only of |
654 | subprocesses spawned using L<fork> and L<exec>; it will not |
a2293a43 |
655 | accumulate the times of subprocesses spawned via pipes, L<system>, |
748a9306 |
656 | or backticks. |
657 | |
16d20bd9 |
658 | =item unlink LIST |
659 | |
660 | C<unlink> will delete the highest version of a file only; in |
661 | order to delete all versions, you need to say |
39aca757 |
662 | |
35b2760a |
663 | 1 while unlink LIST; |
39aca757 |
664 | |
16d20bd9 |
665 | You may need to make this change to scripts written for a |
666 | Unix system which expect that after a call to C<unlink>, |
667 | no files with the names passed to C<unlink> will exist. |
4633a7c4 |
668 | (Note: This can be changed at compile time; if you |
669 | C<use Config> and C<$Config{'d_unlink_all_versions'}> is |
670 | C<define>, then C<unlink> will delete all versions of a |
671 | file on the first call.) |
16d20bd9 |
672 | |
673 | C<unlink> will delete a file if at all possible, even if it |
674 | requires changing file protection (though it won't try to |
675 | change the protection of the parent directory). You can tell |
676 | whether you've got explicit delete access to a file by using the |
677 | C<VMS::Filespec::candelete> operator. For instance, in order |
678 | to delete only files to which you have delete access, you could |
679 | say something like |
4e592037 |
680 | |
16d20bd9 |
681 | sub safe_unlink { |
682 | my($file,$num); |
683 | foreach $file (@_) { |
684 | next unless VMS::Filespec::candelete($file); |
685 | $num += unlink $file; |
686 | } |
687 | $num; |
688 | } |
4e592037 |
689 | |
690 | (or you could just use C<VMS::Stdio::remove>, if you've installed |
691 | the VMS::Stdio extension distributed with Perl). If C<unlink> has to |
692 | change the file protection to delete the file, and you interrupt it |
693 | in midstream, the file may be left intact, but with a changed ACL |
694 | allowing you delete access. |
16d20bd9 |
695 | |
748a9306 |
696 | =item utime LIST |
697 | |
698 | Since ODS-2, the VMS file structure for disk files, does not keep |
699 | track of access times, this operator changes only the modification |
700 | time of the file (VMS revision date). |
701 | |
702 | =item waitpid PID,FLAGS |
703 | |
39aca757 |
704 | If PID is a subprocess started by a piped C<open()> (see L<open>), |
376ae1f1 |
705 | C<waitpid> will wait for that subprocess, and return its final status |
706 | value in C<$?>. If PID is a subprocess created in some other way (e.g. |
707 | SPAWNed before Perl was invoked), C<waitpid> will simply check once per |
708 | second whether the process has completed, and return when it has. (If |
709 | PID specifies a process that isn't a subprocess of the current process, |
710 | and you invoked Perl with the C<-w> switch, a warning will be issued.) |
35b2760a |
711 | |
712 | Returns PID on success, -1 on error. The FLAGS argument is ignored |
713 | in all cases. |
a0d0e21e |
714 | |
55497cff |
715 | =back |
716 | |
a5f75d66 |
717 | =head1 Perl variables |
718 | |
55497cff |
719 | The following VMS-specific information applies to the indicated |
720 | "special" Perl variables, in addition to the general information |
a2293a43 |
721 | in L<perlvar>. Where there is a conflict, this information |
55497cff |
722 | takes precedence. |
723 | |
724 | =over 4 |
725 | |
a5f75d66 |
726 | =item %ENV |
727 | |
f675dbe5 |
728 | The operation of the C<%ENV> array depends on the translation |
729 | of the logical name F<PERL_ENV_TABLES>. If defined, it should |
730 | be a search list, each element of which specifies a location |
731 | for C<%ENV> elements. If you tell Perl to read or set the |
732 | element C<$ENV{>I<name>C<}>, then Perl uses the translations of |
733 | F<PERL_ENV_TABLES> as follows: |
734 | |
735 | =over 4 |
736 | |
737 | =item CRTL_ENV |
738 | |
739 | This string tells Perl to consult the CRTL's internal C<environ> |
740 | array of key-value pairs, using I<name> as the key. In most cases, |
741 | this contains only a few keys, but if Perl was invoked via the C |
742 | C<exec[lv]e()> function, as is the case for CGI processing by some |
743 | HTTP servers, then the C<environ> array may have been populated by |
744 | the calling program. |
745 | |
746 | =item CLISYM_[LOCAL] |
747 | |
748 | A string beginning with C<CLISYM_>tells Perl to consult the CLI's |
749 | symbol tables, using I<name> as the name of the symbol. When reading |
750 | an element of C<%ENV>, the local symbol table is scanned first, followed |
751 | by the global symbol table.. The characters following C<CLISYM_> are |
752 | significant when an element of C<%ENV> is set or deleted: if the |
753 | complete string is C<CLISYM_LOCAL>, the change is made in the local |
39aca757 |
754 | symbol table; otherwise the global symbol table is changed. |
f675dbe5 |
755 | |
756 | =item Any other string |
757 | |
758 | If an element of F<PERL_ENV_TABLES> translates to any other string, |
759 | that string is used as the name of a logical name table, which is |
760 | consulted using I<name> as the logical name. The normal search |
761 | order of access modes is used. |
762 | |
763 | =back |
764 | |
765 | F<PERL_ENV_TABLES> is translated once when Perl starts up; any changes |
766 | you make while Perl is running do not affect the behavior of C<%ENV>. |
767 | If F<PERL_ENV_TABLES> is not defined, then Perl defaults to consulting |
768 | first the logical name tables specified by F<LNM$FILE_DEV>, and then |
769 | the CRTL C<environ> array. |
770 | |
771 | In all operations on %ENV, the key string is treated as if it |
772 | were entirely uppercase, regardless of the case actually |
773 | specified in the Perl expression. |
774 | |
775 | When an element of C<%ENV> is read, the locations to which |
776 | F<PERL_ENV_TABLES> points are checked in order, and the value |
777 | obtained from the first successful lookup is returned. If the |
778 | name of the C<%ENV> element contains a semi-colon, it and |
779 | any characters after it are removed. These are ignored when |
780 | the CRTL C<environ> array or a CLI symbol table is consulted. |
781 | However, the name is looked up in a logical name table, the |
782 | suffix after the semi-colon is treated as the translation index |
783 | to be used for the lookup. This lets you look up successive values |
784 | for search list logical names. For instance, if you say |
a5f75d66 |
785 | |
786 | $ Define STORY once,upon,a,time,there,was |
787 | $ perl -e "for ($i = 0; $i <= 6; $i++) " - |
740ce14c |
788 | _$ -e "{ print $ENV{'story;'.$i},' '}" |
a5f75d66 |
789 | |
f675dbe5 |
790 | Perl will print C<ONCE UPON A TIME THERE WAS>, assuming, of course, |
791 | that F<PERL_ENV_TABLES> is set up so that the logical name C<story> |
792 | is found, rather than a CLI symbol or CRTL C<environ> element with |
793 | the same name. |
794 | |
3eeba6fb |
795 | When an element of C<%ENV> is set to a defined string, the |
f675dbe5 |
796 | corresponding definition is made in the location to which the |
797 | first translation of F<PERL_ENV_TABLES> points. If this causes a |
798 | logical name to be created, it is defined in supervisor mode. |
3eeba6fb |
799 | (The same is done if an existing logical name was defined in |
800 | executive or kernel mode; an existing user or supervisor mode |
801 | logical name is reset to the new value.) If the value is an empty |
802 | string, the logical name's translation is defined as a single NUL |
803 | (ASCII 00) character, since a logical name cannot translate to a |
804 | zero-length string. (This restriction does not apply to CLI symbols |
805 | or CRTL C<environ> values; they are set to the empty string.) |
f675dbe5 |
806 | An element of the CRTL C<environ> array can be set only if your |
807 | copy of Perl knows about the CRTL's C<setenv()> function. (This is |
808 | present only in some versions of the DECCRTL; check C<$Config{d_setenv}> |
809 | to see whether your copy of Perl was built with a CRTL that has this |
810 | function.) |
39aca757 |
811 | |
3eeba6fb |
812 | When an element of C<%ENV> is set to C<undef>, |
f675dbe5 |
813 | the element is looked up as if it were being read, and if it is |
814 | found, it is deleted. (An item "deleted" from the CRTL C<environ> |
815 | array is set to the empty string; this can only be done if your |
816 | copy of Perl knows about the CRTL C<setenv()> function.) Using |
817 | C<delete> to remove an element from C<%ENV> has a similar effect, |
818 | but after the element is deleted, another attempt is made to |
819 | look up the element, so an inner-mode logical name or a name in |
820 | another location will replace the logical name just deleted. |
3eeba6fb |
821 | In either case, only the first value found searching PERL_ENV_TABLES |
822 | is altered. It is not possible at present to define a search list |
823 | logical name via %ENV. |
f675dbe5 |
824 | |
825 | The element C<$ENV{DEFAULT}> is special: when read, it returns |
826 | Perl's current default device and directory, and when set, it |
827 | resets them, regardless of the definition of F<PERL_ENV_TABLES>. |
828 | It cannot be cleared or deleted; attempts to do so are silently |
829 | ignored. |
b7b1864f |
830 | |
831 | Note that if you want to pass on any elements of the |
832 | C-local environ array to a subprocess which isn't |
833 | started by fork/exec, or isn't running a C program, you |
834 | can "promote" them to logical names in the current |
835 | process, which will then be inherited by all subprocesses, |
836 | by saying |
837 | |
838 | foreach my $key (qw[C-local keys you want promoted]) { |
376ae1f1 |
839 | my $temp = $ENV{$key}; # read from C-local array |
840 | $ENV{$key} = $temp; # and define as logical name |
b7b1864f |
841 | } |
842 | |
843 | (You can't just say C<$ENV{$key} = $ENV{$key}>, since the |
844 | Perl optimizer is smart enough to elide the expression.) |
a5f75d66 |
845 | |
6be8f7a6 |
846 | Don't try to clear C<%ENV> by saying C<%ENV = ();>, it will throw |
847 | a fatal error. This is equivalent to doing the following from DCL: |
848 | |
849 | DELETE/LOGICAL * |
850 | |
851 | You can imagine how bad things would be if, for example, the SYS$MANAGER |
852 | or SYS$SYSTEM logicals were deleted. |
4a0d0822 |
853 | |
740ce14c |
854 | At present, the first time you iterate over %ENV using |
edc7bc49 |
855 | C<keys>, or C<values>, you will incur a time penalty as all |
856 | logical names are read, in order to fully populate %ENV. |
857 | Subsequent iterations will not reread logical names, so they |
858 | won't be as slow, but they also won't reflect any changes |
f675dbe5 |
859 | to logical name tables caused by other programs. |
860 | |
861 | You do need to be careful with the logicals representing process-permanent |
862 | files, such as C<SYS$INPUT> and C<SYS$OUTPUT>. The translations for these |
863 | logicals are prepended with a two-byte binary value (0x1B 0x00) that needs to be |
39aca757 |
864 | stripped off if you want to use it. (In previous versions of Perl it wasn't |
f675dbe5 |
865 | possible to get the values of these logicals, as the null byte acted as an |
866 | end-of-string marker) |
a5f75d66 |
867 | |
a5f75d66 |
868 | =item $! |
869 | |
870 | The string value of C<$!> is that returned by the CRTL's |
871 | strerror() function, so it will include the VMS message for |
872 | VMS-specific errors. The numeric value of C<$!> is the |
873 | value of C<errno>, except if errno is EVMSERR, in which |
874 | case C<$!> contains the value of vaxc$errno. Setting C<$!> |
4e592037 |
875 | always sets errno to the value specified. If this value is |
876 | EVMSERR, it also sets vaxc$errno to 4 (NONAME-F-NOMSG), so |
877 | that the string value of C<$!> won't reflect the VMS error |
878 | message from before C<$!> was set. |
879 | |
880 | =item $^E |
881 | |
882 | This variable provides direct access to VMS status values |
883 | in vaxc$errno, which are often more specific than the |
884 | generic Unix-style error messages in C<$!>. Its numeric value |
885 | is the value of vaxc$errno, and its string value is the |
886 | corresponding VMS message string, as retrieved by sys$getmsg(). |
887 | Setting C<$^E> sets vaxc$errno to the value specified. |
888 | |
4fdae800 |
889 | =item $? |
890 | |
891 | The "status value" returned in C<$?> is synthesized from the |
892 | actual exit status of the subprocess in a way that approximates |
893 | POSIX wait(5) semantics, in order to allow Perl programs to |
894 | portably test for successful completion of subprocesses. The |
895 | low order 8 bits of C<$?> are always 0 under VMS, since the |
896 | termination status of a process may or may not have been |
897 | generated by an exception. The next 8 bits are derived from |
39aca757 |
898 | the severity portion of the subprocess' exit status: if the |
4fdae800 |
899 | severity was success or informational, these bits are all 0; |
9bc98430 |
900 | if the severity was warning, they contain a value of 1; if the |
901 | severity was error or fatal error, they contain the actual |
902 | severity bits, which turns out to be a value of 2 for error |
903 | and 4 for fatal error. |
904 | |
4fdae800 |
905 | As a result, C<$?> will always be zero if the subprocess' exit |
906 | status indicated successful completion, and non-zero if a |
9bc98430 |
907 | warning or error occurred. Conversely, when setting C<$?> in |
908 | an END block, an attempt is made to convert the POSIX value |
909 | into a native status intelligible to the operating system upon |
910 | exiting Perl. What this boils down to is that setting C<$?> |
911 | to zero results in the generic success value SS$_NORMAL, and |
912 | setting C<$?> to a non-zero value results in the generic |
913 | failure status SS$_ABORT. See also L<perlport/exit>. |
4fdae800 |
914 | |
1b0c4952 |
915 | The pragma C<use vmsish 'status'> makes C<$?> reflect the actual |
9bc98430 |
916 | VMS exit status instead of the default emulation of POSIX status |
917 | described above. This pragma also disables the conversion of |
918 | non-zero values to SS$_ABORT when setting C<$?> in an END |
919 | block (but zero will still be converted to SS$_NORMAL). |
4fdae800 |
920 | |
4e592037 |
921 | =item $| |
922 | |
923 | Setting C<$|> for an I/O stream causes data to be flushed |
924 | all the way to disk on each write (I<i.e.> not just to |
925 | the underlying RMS buffers for a file). In other words, |
926 | it's equivalent to calling fflush() and fsync() from C. |
a5f75d66 |
927 | |
55497cff |
928 | =back |
929 | |
bf99883d |
930 | =head1 Standard modules with VMS-specific differences |
931 | |
932 | =head2 SDBM_File |
933 | |
270c2ced |
934 | SDBM_File works properly on VMS. It has, however, one minor |
4a4eefd0 |
935 | difference. The database directory file created has a F<.sdbm_dir> |
936 | extension rather than a F<.dir> extension. F<.dir> files are VMS filesystem |
bf99883d |
937 | directory files, and using them for other purposes could cause unacceptable |
938 | problems. |
939 | |
748a9306 |
940 | =head1 Revision date |
a0d0e21e |
941 | |
1506e54c |
942 | This document was last updated on 01-May-2002, for Perl 5, |
9bc98430 |
943 | patchlevel 8. |
e518068a |
944 | |
945 | =head1 AUTHOR |
946 | |
376ae1f1 |
947 | Charles Bailey bailey@cor.newman.upenn.edu |
948 | Craig Berry craigberry@mac.com |
949 | Dan Sugalski dan@sidhe.org |