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