VMS::Stdio - standard I/O functions via VMS extensions
use VMS::Stdio qw( &flush &getname &remove &rewind &setdef &sync &tmpnam &vmsopen &vmssysopen &waitfh &writeof ); setdef("new:[default.dir]"); $uniquename = tmpnam; $fh = vmsopen("my.file","rfm=var","alq=100",...) or die $!; $name = getname($fh); print $fh "Hello, world!\n"; flush($fh); sync($fh); rewind($fh); $line = <$fh>; undef $fh; # closes file $fh = vmssysopen("another.file", O_RDONLY | O_NDELAY, 0, "ctx=bin"); sysread($fh,$data,128); waitfh($fh); close($fh); remove("another.file"); writeof($pipefh); =head1 DESCRIPTION
This package gives Perl scripts access via VMS extensions to several C stdio operations not available through Perl's CORE I/O functions.
The specific routines are described below.
These functions are prototyped as unary operators,
with the exception of
which can take any number of arguments,
which takes none.
All of the routines are available for export,
though none are exported by default.
All of the constants used by
vmssysopen to specify access modes are exported by default.
The routines are associated with the Exporter tag FUNCTIONS,
and the constants are associated with the Exporter tag CONSTANTS,
so you can more easily choose what you'd like to import:
# import constants, but not functions use VMS::Stdio; # same as use VMS::Stdio qw( :DEFAULT ); # import functions, but not constants use VMS::Stdio qw( !:CONSTANTS :FUNCTIONS ); # import both use VMS::Stdio qw( :CONSTANTS :FUNCTIONS ); # import neither use VMS::Stdio ();
Of course, you can also choose to import specific functions by name, as usual.
ISA IO::File, so that you can call IO::File methods on the handles returned by
vmssysopen. The IO::File package is not initialized, however, until you actually call a method that VMS::Stdio doesn't provide. This is doen to save startup time for users who don't wish to use the IO::File methods.
Note: In order to conform to naming conventions for Perl extensions and functions, the name of this package has been changed to VMS::Stdio as of Perl 5.002, and the names of some routines have been changed. Calls to the old VMS::stdio routines will generate a warning, and will be routed to the equivalent VMS::Stdio function. This compatibility interface will be removed in a future release of this extension, so please update your code to use the new routines.
This function causes the contents of stdio buffers for the specified file handle to be flushed. If
undef is used as the argument to
flush, all currently open file handles are flushed. Like the CRTL fflush() routine, it does not flush any underlying RMS buffers for the file, so the data may not be flushed all the way to the disk.
flush returns a true value if successful, and
undef if not.
getname function returns the file specification associated with a Perl I/O handle. If an error occurs, it returns
This function deletes the file named in its argument, returning a true value if successful and
undef if not. It differs from the CORE Perl function
unlink in that it does not try to reset file protection if the original protection does not give you delete access to the file (cf. perlvms). In other words,
remove is equivalent to
unlink($file) if VMS::Filespec::candelete($file);
rewind resets the current position of the specified file handle to the beginning of the file. It's really just a convenience method equivalent in effect to
seek($fh,0,0). It returns a true value if successful, and
undef if it fails.
This function sets the default device and directory for the process. It is identical to the built-in chdir() operator, except that the change persists after Perl exits. It returns a true value on success, and
undef if it encounters and error.
This function flushes buffered data for the specified file handle from stdio and RMS buffers all the way to disk. If successful, it returns a true value; otherwise, it returns
tmpnam function returns a unique string which can be used as a filename when creating temporary files. If, for some reason, it is unable to generate a name, it returns
vmsopen function enables you to specify optional RMS arguments to the VMS CRTL when opening a file. Its operation is similar to the built-in Perl
open function (see perlfunc for a complete description), but it will only open normal files; it cannot open pipes or duplicate existing I/O handles. Up to 8 optional arguments may follow the file name. These arguments should be strings which specify optional file characteristics as allowed by the CRTL. (See the CRTL reference manual description of creat() and fopen() for details.) If successful,
vmsopen returns a VMS::Stdio file handle; if an error occurs, it returns
You can use the file handle returned by
vmsopen just as you would any other Perl file handle. The class VMS::Stdio ISA IO::File, so you can call IO::File methods using the handle returned by
useing VMS::Stdio does not automatically
use IO::File; you must do so explicitly in your program if you want to call IO::File methods. This is done to avoid the overhead of initializing the IO::File package in programs which intend to use the handle returned by
vmsopen as a normal Perl file handle only. When the scalar containing a VMS::Stdio file handle is overwritten,
undefd, or goes out of scope, the associated file is closed automatically.
This function bears the same relationship to the CORE function
vmsopen does to
open. Its first three arguments are the name, access flags, and permissions for the file. Like
vmsopen, it takes up to 8 additional string arguments which specify file characteristics. Its return value is identical to that of
The symbolic constants for the mode argument are exported by VMS::Stdio by default, and are also exported by the Fcntl package.
This function causes Perl to wait for the completion of an I/O operation on the file handle specified as its argument. It is used with handles opened for asynchronous I/O, and performs its task by calling the CRTL routine fwait().
This function writes an EOF to a file handle, if the device driver supports this operation. Its primary use is to send an EOF to a subprocess through a pipe opened for writing without closing the pipe. It returns a true value if successful, and
undef if it encounters an error.
This document was last revised on 10-Dec-1996, for Perl 5.004.