| 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 |