Commit | Line | Data |
---|---|---|
0d7e20a5 | 1 | # VMS::Stdio - VMS extensions to Perl's stdio calls |
748a9306 LW |
2 | # |
3 | # Author: Charles Bailey bailey@genetics.upenn.edu | |
17f28c40 CB |
4 | # Version: 2.1 |
5 | # Revised: 24-Mar-1998 | |
0d7e20a5 | 6 | |
7 | package VMS::Stdio; | |
8 | ||
9 | require 5.002; | |
10 | use vars qw( $VERSION @EXPORT @EXPORT_OK %EXPORT_TAGS @ISA ); | |
11 | use Carp '&croak'; | |
12 | use DynaLoader (); | |
13 | use Exporter (); | |
14 | ||
17f28c40 | 15 | $VERSION = '2.1'; |
740ce14c | 16 | @ISA = qw( Exporter DynaLoader IO::File ); |
0d7e20a5 | 17 | @EXPORT = qw( &O_APPEND &O_CREAT &O_EXCL &O_NDELAY &O_NOWAIT |
18 | &O_RDONLY &O_RDWR &O_TRUNC &O_WRONLY ); | |
17f28c40 CB |
19 | @EXPORT_OK = qw( &flush &getname &remove &rewind &sync &setdef &tmpnam |
20 | &vmsopen &vmssysopen &waitfh &writeof ); | |
0d7e20a5 | 21 | %EXPORT_TAGS = ( CONSTANTS => [ qw( &O_APPEND &O_CREAT &O_EXCL &O_NDELAY |
22 | &O_NOWAIT &O_RDONLY &O_RDWR &O_TRUNC | |
23 | &O_WRONLY ) ], | |
17f28c40 CB |
24 | FUNCTIONS => [ qw( &flush &getname &remove &rewind &setdef |
25 | &sync &tmpnam &vmsopen &vmssysopen | |
26 | &waitfh &writeof ) ] ); | |
0d7e20a5 | 27 | |
28 | bootstrap VMS::Stdio $VERSION; | |
29 | ||
30 | sub AUTOLOAD { | |
31 | my($constname) = $AUTOLOAD; | |
32 | $constname =~ s/.*:://; | |
33 | if ($constname =~ /^O_/) { | |
34 | my($val) = constant($constname); | |
35 | defined $val or croak("Unknown VMS::Stdio constant $constname"); | |
09b7f37c | 36 | *$AUTOLOAD = sub { $val; } |
0d7e20a5 | 37 | } |
740ce14c | 38 | else { # We don't know about it; hand off to IO::File |
39 | require IO::File; | |
55497cff | 40 | |
5f05dabc | 41 | *$AUTOLOAD = eval "sub { shift->IO::File::$constname(\@_) }"; |
42 | croak "Error autoloading IO::File::$constname: $@" if $@; | |
0d7e20a5 | 43 | } |
44 | goto &$AUTOLOAD; | |
45 | } | |
46 | ||
47 | sub DESTROY { close($_[0]); } | |
48 | ||
49 | ||
50 | ################################################################################ | |
51 | # Intercept calls to old VMS::stdio package, complain, and hand off | |
52 | # This will be removed in a future version of VMS::Stdio | |
53 | ||
54 | package VMS::stdio; | |
55 | ||
56 | sub AUTOLOAD { | |
57 | my($func) = $AUTOLOAD; | |
58 | $func =~ s/.*:://; | |
59 | # Cheap trick: we know DynaLoader has required Carp.pm | |
60 | Carp::carp("Old package VMS::stdio is now VMS::Stdio; please update your code"); | |
61 | if ($func eq 'vmsfopen') { | |
62 | Carp::carp("Old function &vmsfopen is now &vmsopen"); | |
63 | goto &VMS::Stdio::vmsopen; | |
64 | } | |
65 | elsif ($func eq 'fgetname') { | |
66 | Carp::carp("Old function &fgetname is now &getname"); | |
67 | goto &VMS::Stdio::getname; | |
68 | } | |
69 | else { goto &{"VMS::Stdio::$func"}; } | |
70 | } | |
71 | ||
72 | package VMS::Stdio; # in case we ever use AutoLoader | |
73 | ||
74 | 1; | |
75 | ||
76 | __END__ | |
748a9306 LW |
77 | |
78 | =head1 NAME | |
79 | ||
2ceaccd7 | 80 | VMS::Stdio - standard I/O functions via VMS extensions |
748a9306 LW |
81 | |
82 | =head1 SYNOPSIS | |
83 | ||
17f28c40 CB |
84 | use VMS::Stdio qw( &flush &getname &remove &rewind &setdef &sync &tmpnam |
85 | &vmsopen &vmssysopen &waitfh &writeof ); | |
86 | setdef("new:[default.dir]"); | |
0d7e20a5 | 87 | $uniquename = tmpnam; |
88 | $fh = vmsopen("my.file","rfm=var","alq=100",...) or die $!; | |
89 | $name = getname($fh); | |
90 | print $fh "Hello, world!\n"; | |
91 | flush($fh); | |
92 | sync($fh); | |
93 | rewind($fh); | |
94 | $line = <$fh>; | |
95 | undef $fh; # closes file | |
96 | $fh = vmssysopen("another.file", O_RDONLY | O_NDELAY, 0, "ctx=bin"); | |
97 | sysread($fh,$data,128); | |
98 | waitfh($fh); | |
99 | close($fh); | |
100 | remove("another.file"); | |
17f28c40 | 101 | writeof($pipefh); |
748a9306 LW |
102 | =head1 DESCRIPTION |
103 | ||
2ceaccd7 | 104 | This package gives Perl scripts access via VMS extensions to several |
0d7e20a5 | 105 | C stdio operations not available through Perl's CORE I/O functions. |
106 | The specific routines are described below. These functions are | |
107 | prototyped as unary operators, with the exception of C<vmsopen> | |
108 | and C<vmssysopen>, which can take any number of arguments, and | |
109 | C<tmpnam>, which takes none. | |
110 | ||
111 | All of the routines are available for export, though none are | |
112 | exported by default. All of the constants used by C<vmssysopen> | |
113 | to specify access modes are exported by default. The routines | |
114 | are associated with the Exporter tag FUNCTIONS, and the constants | |
115 | are associated with the Exporter tag CONSTANTS, so you can more | |
116 | easily choose what you'd like to import: | |
117 | ||
118 | # import constants, but not functions | |
119 | use VMS::Stdio; # same as use VMS::Stdio qw( :DEFAULT ); | |
120 | # import functions, but not constants | |
121 | use VMS::Stdio qw( !:CONSTANTS :FUNCTIONS ); | |
122 | # import both | |
123 | use VMS::Stdio qw( :CONSTANTS :FUNCTIONS ); | |
124 | # import neither | |
125 | use VMS::Stdio (); | |
126 | ||
127 | Of course, you can also choose to import specific functions by | |
128 | name, as usual. | |
129 | ||
740ce14c | 130 | This package C<ISA> IO::File, so that you can call IO::File |
0d7e20a5 | 131 | methods on the handles returned by C<vmsopen> and C<vmssysopen>. |
740ce14c | 132 | The IO::File package is not initialized, however, until you |
0d7e20a5 | 133 | actually call a method that VMS::Stdio doesn't provide. This |
134 | is doen to save startup time for users who don't wish to use | |
740ce14c | 135 | the IO::File methods. |
0d7e20a5 | 136 | |
137 | B<Note:> In order to conform to naming conventions for Perl | |
138 | extensions and functions, the name of this package has been | |
139 | changed to VMS::Stdio as of Perl 5.002, and the names of some | |
140 | routines have been changed. Calls to the old VMS::stdio routines | |
141 | will generate a warning, and will be routed to the equivalent | |
142 | VMS::Stdio function. This compatibility interface will be | |
143 | removed in a future release of this extension, so please | |
144 | update your code to use the new routines. | |
145 | ||
2ceaccd7 LV |
146 | =over |
147 | ||
0d7e20a5 | 148 | =item flush |
149 | ||
150 | This function causes the contents of stdio buffers for the specified | |
151 | file handle to be flushed. If C<undef> is used as the argument to | |
152 | C<flush>, all currently open file handles are flushed. Like the CRTL | |
153 | fflush() routine, it does not flush any underlying RMS buffers for the | |
154 | file, so the data may not be flushed all the way to the disk. C<flush> | |
155 | returns a true value if successful, and C<undef> if not. | |
156 | ||
157 | =item getname | |
158 | ||
159 | The C<getname> function returns the file specification associated | |
740ce14c | 160 | with a Perl I/O handle. If an error occurs, it returns C<undef>. |
748a9306 | 161 | |
0d7e20a5 | 162 | =item remove |
748a9306 | 163 | |
0d7e20a5 | 164 | This function deletes the file named in its argument, returning |
165 | a true value if successful and C<undef> if not. It differs from | |
166 | the CORE Perl function C<unlink> in that it does not try to | |
167 | reset file protection if the original protection does not give | |
168 | you delete access to the file (cf. L<perlvms>). In other words, | |
169 | C<remove> is equivalent to | |
170 | ||
171 | unlink($file) if VMS::Filespec::candelete($file); | |
748a9306 | 172 | |
0d7e20a5 | 173 | =item rewind |
174 | ||
175 | C<rewind> resets the current position of the specified file handle | |
176 | to the beginning of the file. It's really just a convenience | |
177 | method equivalent in effect to C<seek($fh,0,0)>. It returns a | |
178 | true value if successful, and C<undef> if it fails. | |
179 | ||
17f28c40 CB |
180 | =item setdef |
181 | ||
182 | This function sets the default device and directory for the process. | |
183 | It is identical to the built-in chdir() operator, except that the change | |
184 | persists after Perl exits. It returns a true value on success, and | |
185 | C<undef> if it encounters and error. | |
186 | ||
0d7e20a5 | 187 | =item sync |
188 | ||
189 | This function flushes buffered data for the specified file handle | |
190 | from stdio and RMS buffers all the way to disk. If successful, it | |
191 | returns a true value; otherwise, it returns C<undef>. | |
192 | ||
193 | =item tmpnam | |
748a9306 LW |
194 | |
195 | The C<tmpnam> function returns a unique string which can be used | |
196 | as a filename when creating temporary files. If, for some | |
197 | reason, it is unable to generate a name, it returns C<undef>. | |
198 | ||
0d7e20a5 | 199 | =item vmsopen |
748a9306 | 200 | |
0d7e20a5 | 201 | The C<vmsopen> function enables you to specify optional RMS arguments |
5f05dabc | 202 | to the VMS CRTL when opening a file. Its operation is similar to the built-in |
0d7e20a5 | 203 | Perl C<open> function (see L<perlfunc> for a complete description), |
5f05dabc | 204 | but it will only open normal files; it cannot open pipes or duplicate |
740ce14c | 205 | existing I/O handles. Up to 8 optional arguments may follow the |
748a9306 | 206 | file name. These arguments should be strings which specify |
0d7e20a5 | 207 | optional file characteristics as allowed by the CRTL. (See the |
208 | CRTL reference manual description of creat() and fopen() for details.) | |
209 | If successful, C<vmsopen> returns a VMS::Stdio file handle; if an | |
210 | error occurs, it returns C<undef>. | |
211 | ||
5f05dabc | 212 | You can use the file handle returned by C<vmsopen> just as you |
0d7e20a5 | 213 | would any other Perl file handle. The class VMS::Stdio ISA |
740ce14c | 214 | IO::File, so you can call IO::File methods using the handle |
0d7e20a5 | 215 | returned by C<vmsopen>. However, C<use>ing VMS::Stdio does not |
740ce14c | 216 | automatically C<use> IO::File; you must do so explicitly in |
217 | your program if you want to call IO::File methods. This is | |
218 | done to avoid the overhead of initializing the IO::File package | |
0d7e20a5 | 219 | in programs which intend to use the handle returned by C<vmsopen> |
220 | as a normal Perl file handle only. When the scalar containing | |
221 | a VMS::Stdio file handle is overwritten, C<undef>d, or goes | |
222 | out of scope, the associated file is closed automatically. | |
223 | ||
224 | =item vmssysopen | |
225 | ||
226 | This function bears the same relationship to the CORE function | |
227 | C<sysopen> as C<vmsopen> does to C<open>. Its first three arguments | |
228 | are the name, access flags, and permissions for the file. Like | |
229 | C<vmsopen>, it takes up to 8 additional string arguments which | |
230 | specify file characteristics. Its return value is identical to | |
231 | that of C<vmsopen>. | |
232 | ||
233 | The symbolic constants for the mode argument are exported by | |
234 | VMS::Stdio by default, and are also exported by the Fcntl package. | |
235 | ||
236 | =item waitfh | |
237 | ||
238 | This function causes Perl to wait for the completion of an I/O | |
239 | operation on the file handle specified as its argument. It is | |
240 | used with handles opened for asynchronous I/O, and performs its | |
241 | task by calling the CRTL routine fwait(). | |
748a9306 | 242 | |
17f28c40 CB |
243 | =item writeof |
244 | ||
245 | This function writes an EOF to a file handle, if the device driver | |
246 | supports this operation. Its primary use is to send an EOF to a | |
247 | subprocess through a pipe opened for writing without closing the | |
248 | pipe. It returns a true value if successful, and C<undef> if | |
249 | it encounters an error. | |
250 | ||
748a9306 LW |
251 | =head1 REVISION |
252 | ||
5f05dabc | 253 | This document was last revised on 10-Dec-1996, for Perl 5.004. |
748a9306 LW |
254 | |
255 | =cut |