[p5sagit/p5-mst-13.2.git] / vms / ext / Stdio / Stdio.pm

#   VMS::stdio - VMS extensions to Perl's stdio calls
#
#   Author:  Charles Bailey  bailey@genetics.upenn.edu
#   Version: 1.0
#   Revised: 29-Nov-1994
#
#   Revision History:
#   1.0  29-Nov-1994  Charles Bailey  bailey@genetics.upenn.edu
#     original version
#   1.1  09-Mar-1995  Charles Bailey  bailey@genetics.upenn.edu
#     changed calling sequence to return FH/undef - like POSIX::open
#     added fgetname and tmpnam

=head1 NAME

VMS::stdio

=head1 SYNOPSIS

use VMS::stdio;
$name = fgetname(FH);
$uniquename = &tmpnam;
$fh = vmsfopen("my.file","rfm=var","alq=100",...) or die $!;

=head1 DESCRIPTION

This package gives Perl scripts access to VMS extensions to the
C stdio routines, such as optional arguments to C<fopen()>.
The specific routines are described below.

=head2 fgetname

The C<fgetname> function returns the file specification associated
with a Perl FileHandle.  If an error occurs, it returns C<undef>.

=head2 tmpnam

The C<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 C<undef>.

=head2 vmsfopen

The C<vmsfopen> function provides access to the VMS CRTL
C<fopen()> function.  It is similar to the built-in Perl C<open>
function (see L<perlfunc> for a complete description), but will
only open normal files; it cannot open pipes or duplicate
existing FileHandles.  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 C<fopen()>
routine. (See the CRTL reference manual for details.)

You can use the FileHandle returned by C<vmsfopen> just as you
would any other Perl FileHandle.

C<vmsfopen> is a temporary solution to problems which arise in
handling VMS-specific file formats; in the long term, we hope to
provide more transparent access to VMS file I/O through routines
which replace standard Perl C<open> function, or through tied
FileHandles.  When this becomes possible, C<vmsfopen> may be
replaced.

=head1 REVISION

This document was last revised on 09-Mar-1995, for Perl 5.001.

=cut

package VMS::stdio;

require DynaLoader;
require Exporter;
 
@ISA = qw( Exporter DynaLoader);
@EXPORT = qw( &fgetname &tmpfile &tmpnam &vmsfopen );

bootstrap VMS::stdio;
1;
Commit	Line	Data
748a9306	1	# VMS::stdio - VMS extensions to Perl's stdio calls
	2	#
	3	# Author: Charles Bailey bailey@genetics.upenn.edu
	4	# Version: 1.0
	5	# Revised: 29-Nov-1994
	6	#
	7	# Revision History:
	8	# 1.0 29-Nov-1994 Charles Bailey bailey@genetics.upenn.edu
	9	# original version
	10	# 1.1 09-Mar-1995 Charles Bailey bailey@genetics.upenn.edu
	11	# changed calling sequence to return FH/undef - like POSIX::open
	12	# added fgetname and tmpnam
	13
	14	=head1 NAME
	15
	16	VMS::stdio
	17
	18	=head1 SYNOPSIS
	19
	20	use VMS::stdio;
	21	$name = fgetname(FH);
	22	$uniquename = &tmpnam;
	23	$fh = vmsfopen("my.file","rfm=var","alq=100",...) or die $!;
	24
	25	=head1 DESCRIPTION
	26
	27	This package gives Perl scripts access to VMS extensions to the
	28	C stdio routines, such as optional arguments to C<fopen()>.
	29	The specific routines are described below.
	30
	31	=head2 fgetname
	32
	33	The C<fgetname> function returns the file specification associated
	34	with a Perl FileHandle. If an error occurs, it returns C<undef>.
	35
	36	=head2 tmpnam
	37
	38	The C<tmpnam> function returns a unique string which can be used
	39	as a filename when creating temporary files. If, for some
	40	reason, it is unable to generate a name, it returns C<undef>.
	41
	42	=head2 vmsfopen
	43
	44	The C<vmsfopen> function provides access to the VMS CRTL
	45	C<fopen()> function. It is similar to the built-in Perl C<open>
	46	function (see L<perlfunc> for a complete description), but will
	47	only open normal files; it cannot open pipes or duplicate
	48	existing FileHandles. Up to 8 optional arguments may follow the
	49	file name. These arguments should be strings which specify
	50	optional file characteristics as allowed by the CRTL C<fopen()>
	51	routine. (See the CRTL reference manual for details.)
	52
	53	You can use the FileHandle returned by C<vmsfopen> just as you
	54	would any other Perl FileHandle.
	55
	56	C<vmsfopen> is a temporary solution to problems which arise in
	57	handling VMS-specific file formats; in the long term, we hope to
	58	provide more transparent access to VMS file I/O through routines
	59	which replace standard Perl C<open> function, or through tied
	60	FileHandles. When this becomes possible, C<vmsfopen> may be
	61	replaced.
	62
	63	=head1 REVISION
	64
65	This document was last revised on 09-Mar-1995, for Perl 5.001.
66
67	=cut
68
69	package VMS::stdio;
70
71	require DynaLoader;
72	require Exporter;
73
74	@ISA = qw( Exporter DynaLoader);
75	@EXPORT = qw( &fgetname &tmpfile &tmpnam &vmsfopen );
76
77	bootstrap VMS::stdio;
78	1;