Manual Reference Pages - fileopen (3)
NAME
fileopen(3f) - [M_io] A simple open of a sequential file (LICENSE:PD)
CONTENTS
Synopsis
Description
Option
Returns
Example
Author
License
SYNOPSIS
function fileopen(filename,mode,ios) result(lun)
character(len=*),intent(in) :: filename character(len=*),intent(in),optional :: mode integer,intent(out),optional :: ios integer :: lun
DESCRIPTION
fileopen(3f) is a convenience routine that allows you to open a file for sequential reading and writing as a text file in a form commonly found in C and interpreted languages such as shells. See the OPEN(3f) statement for more demanding I/O specifications (asynchronous, direct, unformatted, ... ). The documentation for the flexible and powerful OPEN(3f) statement can be a bit overwhelming; this routine cuts it down to the just the simple basic functions typically available in a scripting language such as bash, tcsh, sh, ...Specify the file’s name as the string FILENAME with a shell-like prefix specifying the access mode, or alternatively specify a plain FILENAME and the kind of access you need to the file with the string MODE.
Three fundamental kinds of access are available: read, write, and append.
OPTION
FILENAME The filename to open. If the beginning of the filename is < open for read. File must exist > open for write. Will overwrite current file >> open for append. Will append to current fileIf no prefix exists to specify a file access mode, it will depend on the values of the MODE argument (meaning the default will be "readwrite").
A blank filename causes a unit number for a scratch file to be returned.
MODE [rwa][tb][+] An alternate way to specify the file access mode is to specify a MODE value. It should begin with one of the three characters "r", "w", or "a". It defaults to ’rw’. It is case-insensitive.
r,< Open the file for reading; the operation will fail if the file does not exist, or if the host system does not permit you to read it.
WRITING PREFIXES
w,> Open a file for writing from the beginning of the file. If the file whose name you specified already existed, the call fails.
o Open the file for writing from the beginning of the file: effectively, this always creates a new file. If the file whose name you specified already existed, its old contents are discarded. a,<< Initially open the file for appending data (ie. writing at the end of file).
SUFFIX
b Append a "b" to any of the three modes above to specify that you are opening the file as a "binary file" (the default is to open the file as a sequential formatted text file. This switch changes to to an unformatted stream). open( ... access=’stream’;form=’unformatted’)
t Append a "t" to any of the three modes (rwa) to specify a formatted stream open( ... access=’stream’;form=’formatted’)
o Finally, you might need to both read and write from the same file. You can specify "rw" or you can append a ‘+’ to any of the three primary modes ("rwa") to permit "readwrite" access v Additionally, "v" selects verbose mode, which prints the OPEN(3f) options explicitly selected
NOTES
If you want to append both ‘b’ and ‘+’, you can do it in either order: for example, "rb+" means the same thing as "r+b" when used as a mode string.)
| IOS | The error code returned by the OPEN(3f) statement ultimately executed by this function. If not present the program stops on an error. |
RETURNS
FILEOPEN(3f) returns a Fortran unit number which you can use for other file operations, unless the file you requested could not be opened; in that situation, the result is -1 (a reserved value that cannot be returned as a NEWUNIT value on an OPEN(3f)) and IOS will be non-zero.
EXAMPLE
Common usage
READ
R=fileopen(’<in.txt’) or R=fileopen(’in.txt’,’r’)
WRITE
W=fileopen(’>out.txt’) or W=fileopen(’out.txt’,’W’)
READWRITE
RW=fileopen(’inout.txt’)
APPEND
A=fileopen(’>>inout.txt’) or A=fileopen(’inout.txt’,’a’)
Sample program
program demo_fileopen
use M_io, only : fileopen, fileclose, print_inquire
implicit none
integer :: lun
lun=fileopen(’fred.txt’)
call print_inquire(lun)
end program demo_fileopen
AUTHOR
John S. Urban
LICENSE
Public Domain
| fileopen (3) | March 11, 2021 |
