1 # VMS::Stdio - VMS extensions to Perl's stdio calls
3 # Author: Charles Bailey bailey@genetics.upenn.edu
10 use vars qw( $VERSION @EXPORT @EXPORT_OK %EXPORT_TAGS @ISA );
16 @ISA = qw( Exporter DynaLoader IO::File );
17 @EXPORT = qw( &O_APPEND &O_CREAT &O_EXCL &O_NDELAY &O_NOWAIT
18 &O_RDONLY &O_RDWR &O_TRUNC &O_WRONLY );
19 @EXPORT_OK = qw( &flush &getname &remove &rewind &sync &tmpnam
20 &vmsopen &vmssysopen &waitfh );
21 %EXPORT_TAGS = ( CONSTANTS => [ qw( &O_APPEND &O_CREAT &O_EXCL &O_NDELAY
22 &O_NOWAIT &O_RDONLY &O_RDWR &O_TRUNC
24 FUNCTIONS => [ qw( &flush &getname &remove &rewind &sync
25 &tmpnam &vmsopen &vmssysopen &waitfh ) ] );
27 bootstrap VMS::Stdio $VERSION;
30 my($constname) = $AUTOLOAD;
31 $constname =~ s/.*:://;
32 if ($constname =~ /^O_/) {
33 my($val) = constant($constname);
34 defined $val or croak("Unknown VMS::Stdio constant $constname");
35 *$AUTOLOAD = sub { val; }
37 else { # We don't know about it; hand off to IO::File
40 *$AUTOLOAD = eval "sub { shift->IO::File::$constname(\@_) }";
41 croak "Error autoloading IO::File::$constname: $@" if $@;
46 sub DESTROY { close($_[0]); }
49 ################################################################################
50 # Intercept calls to old VMS::stdio package, complain, and hand off
51 # This will be removed in a future version of VMS::Stdio
56 my($func) = $AUTOLOAD;
58 # Cheap trick: we know DynaLoader has required Carp.pm
59 Carp::carp("Old package VMS::stdio is now VMS::Stdio; please update your code");
60 if ($func eq 'vmsfopen') {
61 Carp::carp("Old function &vmsfopen is now &vmsopen");
62 goto &VMS::Stdio::vmsopen;
64 elsif ($func eq 'fgetname') {
65 Carp::carp("Old function &fgetname is now &getname");
66 goto &VMS::Stdio::getname;
68 else { goto &{"VMS::Stdio::$func"}; }
71 package VMS::Stdio; # in case we ever use AutoLoader
79 VMS::Stdio - standard I/O functions via VMS extensions
83 use VMS::Stdio qw( &flush &getname &remove &rewind &sync &tmpnam
84 &vmsopen &vmssysopen &waitfh );
86 $fh = vmsopen("my.file","rfm=var","alq=100",...) or die $!;
88 print $fh "Hello, world!\n";
93 undef $fh; # closes file
94 $fh = vmssysopen("another.file", O_RDONLY | O_NDELAY, 0, "ctx=bin");
95 sysread($fh,$data,128);
98 remove("another.file");
102 This package gives Perl scripts access via VMS extensions to several
103 C stdio operations not available through Perl's CORE I/O functions.
104 The specific routines are described below. These functions are
105 prototyped as unary operators, with the exception of C<vmsopen>
106 and C<vmssysopen>, which can take any number of arguments, and
107 C<tmpnam>, which takes none.
109 All of the routines are available for export, though none are
110 exported by default. All of the constants used by C<vmssysopen>
111 to specify access modes are exported by default. The routines
112 are associated with the Exporter tag FUNCTIONS, and the constants
113 are associated with the Exporter tag CONSTANTS, so you can more
114 easily choose what you'd like to import:
116 # import constants, but not functions
117 use VMS::Stdio; # same as use VMS::Stdio qw( :DEFAULT );
118 # import functions, but not constants
119 use VMS::Stdio qw( !:CONSTANTS :FUNCTIONS );
121 use VMS::Stdio qw( :CONSTANTS :FUNCTIONS );
125 Of course, you can also choose to import specific functions by
128 This package C<ISA> IO::File, so that you can call IO::File
129 methods on the handles returned by C<vmsopen> and C<vmssysopen>.
130 The IO::File package is not initialized, however, until you
131 actually call a method that VMS::Stdio doesn't provide. This
132 is doen to save startup time for users who don't wish to use
133 the IO::File methods.
135 B<Note:> In order to conform to naming conventions for Perl
136 extensions and functions, the name of this package has been
137 changed to VMS::Stdio as of Perl 5.002, and the names of some
138 routines have been changed. Calls to the old VMS::stdio routines
139 will generate a warning, and will be routed to the equivalent
140 VMS::Stdio function. This compatibility interface will be
141 removed in a future release of this extension, so please
142 update your code to use the new routines.
148 This function causes the contents of stdio buffers for the specified
149 file handle to be flushed. If C<undef> is used as the argument to
150 C<flush>, all currently open file handles are flushed. Like the CRTL
151 fflush() routine, it does not flush any underlying RMS buffers for the
152 file, so the data may not be flushed all the way to the disk. C<flush>
153 returns a true value if successful, and C<undef> if not.
157 The C<getname> function returns the file specification associated
158 with a Perl I/O handle. If an error occurs, it returns C<undef>.
162 This function deletes the file named in its argument, returning
163 a true value if successful and C<undef> if not. It differs from
164 the CORE Perl function C<unlink> in that it does not try to
165 reset file protection if the original protection does not give
166 you delete access to the file (cf. L<perlvms>). In other words,
167 C<remove> is equivalent to
169 unlink($file) if VMS::Filespec::candelete($file);
173 C<rewind> resets the current position of the specified file handle
174 to the beginning of the file. It's really just a convenience
175 method equivalent in effect to C<seek($fh,0,0)>. It returns a
176 true value if successful, and C<undef> if it fails.
180 This function flushes buffered data for the specified file handle
181 from stdio and RMS buffers all the way to disk. If successful, it
182 returns a true value; otherwise, it returns C<undef>.
186 The C<tmpnam> function returns a unique string which can be used
187 as a filename when creating temporary files. If, for some
188 reason, it is unable to generate a name, it returns C<undef>.
192 The C<vmsopen> function enables you to specify optional RMS arguments
193 to the VMS CRTL when opening a file. Its operation is similar to the built-in
194 Perl C<open> function (see L<perlfunc> for a complete description),
195 but it will only open normal files; it cannot open pipes or duplicate
196 existing I/O handles. Up to 8 optional arguments may follow the
197 file name. These arguments should be strings which specify
198 optional file characteristics as allowed by the CRTL. (See the
199 CRTL reference manual description of creat() and fopen() for details.)
200 If successful, C<vmsopen> returns a VMS::Stdio file handle; if an
201 error occurs, it returns C<undef>.
203 You can use the file handle returned by C<vmsopen> just as you
204 would any other Perl file handle. The class VMS::Stdio ISA
205 IO::File, so you can call IO::File methods using the handle
206 returned by C<vmsopen>. However, C<use>ing VMS::Stdio does not
207 automatically C<use> IO::File; you must do so explicitly in
208 your program if you want to call IO::File methods. This is
209 done to avoid the overhead of initializing the IO::File package
210 in programs which intend to use the handle returned by C<vmsopen>
211 as a normal Perl file handle only. When the scalar containing
212 a VMS::Stdio file handle is overwritten, C<undef>d, or goes
213 out of scope, the associated file is closed automatically.
217 This function bears the same relationship to the CORE function
218 C<sysopen> as C<vmsopen> does to C<open>. Its first three arguments
219 are the name, access flags, and permissions for the file. Like
220 C<vmsopen>, it takes up to 8 additional string arguments which
221 specify file characteristics. Its return value is identical to
224 The symbolic constants for the mode argument are exported by
225 VMS::Stdio by default, and are also exported by the Fcntl package.
229 This function causes Perl to wait for the completion of an I/O
230 operation on the file handle specified as its argument. It is
231 used with handles opened for asynchronous I/O, and performs its
232 task by calling the CRTL routine fwait().
236 This document was last revised on 10-Dec-1996, for Perl 5.004.