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