C Library Functions  - fileopen (3)

NAME
fileopen(3f) - [M_io] A simple open of a sequential file (LICENSE:PD)

CONTENTS

Synopsis
Description
Option
Returns
Examples
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 file


            If 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.

    READING PREFIX
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.

EXAMPLES
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

Nemo Release 3.1 fileopen (3) February 23, 2025
Generated by manServer 1.08 from 9374b368-ef2a-4fa5-8be4-00fb75b30e46 using man macros.