| VMS::Stdio - standard I/O functions via VMS extensions |
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);
binmode($fh);
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 vmsopen
and vmssysopen, which can take any number of arguments, and
tmpnam, 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.
This package ISA IO::File, so that you can call IO::File
methods on the handles returned by vmsopen and vmssysopen.
The IO::File package is not initialized, however, until you
actually call a method that VMS::Stdio doesn't provide. This
is done 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.
b access mode in vmsopen. After the file is reopened,
the file pointer is positioned as close to its position before the
call as possible (i.e. as close as fsetpos() can get it -- for
some record-structured files, it's not possible to return to the
exact byte offset in the file). Because the file must be reopened,
this function cannot be used on temporary-delete files. binmode
returns true if successful, and undef if not.
Note that the effect of binmode differs from that of the binmode()
function on operating systems such as Windows and MSDOS, and is not
needed to process most types of file.
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 undef.
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. the perlvms manpage). 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.
chdir() operator, except that the change
persists after Perl exits. It returns a true value on success, and
undef if it encounters an error.
undef.
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 undef.
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 the perlfunc manpage 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 undef.
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 vmsopen. However, 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.
File characteristic options:
ctx=noctx
sysopen as 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 vmsopen.
The symbolic constants for the mode argument are exported by VMS::Stdio by default, and are also exported by the Fcntl package.
undef if
it encounters an error.
This document was last revised on 13-Oct-1998, for Perl 5.004, 5.005, and 5.6.0.
| VMS::Stdio - standard I/O functions via VMS extensions |