flibs/m_vfile(n) 1.0 "flibs"

NAME

flibs/m_vfile - Processing files

    TABLE OF CONTENTS
    SYNOPSIS
    DESCRIPTION
    OVERVIEW
        Portability
        How to use it
        Error management
        Intel Fortran portability
        RENAME and GETCWD fortran extension
        Dynamic or static buffer
        Preprocessing
        Example of compiler settings
    METHODS
    STATIC METHODS
    COPYRIGHT

SYNOPSIS

The module m_vfile provides OO services to process files and directories. This component is based on a dynamic strings so that the file or directory name may be defined with no limit in the number of characters.

OVERVIEW

This component allows to manage the file system, by providing services to create, move and destroy files and directories, and to get informations about files and directories. The services provided are based either on standard fortran, or on fortran extensions.

Portability

One of the main interest of this component is to separate the client-side application from platform-specific file management or from compiler-specific fortran extensions.

This separation is possible because m_vfile deals for the platform directly, by using the m_platform module. This allows to design a client source code which portable on several operating systems (for example windows, linux) without any change. For example, the several file separators used on the various operating systems are taken into account internally : "/" on linux systems, "\" on windows systems and ":" on Mac OS.

The portability is also ensured with respect to the fortran compiler used to create the executable. All fortran compilers provide commands to rename the files or get the working directory. But not all fortran compilers define these commands the same way : some provide subroutines, some provide functions, etc... The current component can be configured at compile-time with pre-processing commands. This allows to configure the component with compiler specific settings, to make so that the component know what features your particular compiler knows about.

<your application> > m_vfile (operating system , fortran compiler) > m_platform (operating system , fortran compiler)

How to use it

Before using the services provided by m_vfile, the client code must call vfile_startup which initializes platform-specific commands. After using these services, the client code should call vfile_shutdown.

The commands vfile_delete, vfile_copy, vfile_rename allow to delete, copy and rename files or directories. To inquire about a file or directory, one can use vfile_exists or vfile_isdirectory.

In the following example, one creates a new file with vfile_touch, rename that file and finally delete it.

call vfile_startup () call vstring_new ( file , "foo.txt" ) call vfile_touch ( file ) call vfile_rename ( file , "toto.txt" ) call vfile_delete ( file ) call vstring_free ( file ) call vfile_shutdown ()

The component makes no differences between file names and directory names, except for methods which are specific for file or for directory.

The vfile_separator method returns the platform-specific character used on the current operating system.

The commands vfile_nativename , vfile_normalize , vfile_pathtype provide ways to manage file names and paths. The vfile_nativename function returns the platform-specific name of the file. The vfile_pathtype command returns one of VFILE_PATHTYPE_ABSOLUTE, VFILE_PATHTYPE_RELATIVE, VFILE_PATHTYPE_VOLUMERELATIVE which correspond to the current file. The VFILE_PATHTYPE_VOLUMERELATIVE only exist on windows. The vfile_normalize command returns a unique normalized path representation for the file-system object (file, directory, link, etc), whose string value can be used as a unique identifier for it.

The vfile_split and vfile_join services allows to separate or concatenate the components of a file. This can be useful when dealing with relative file or directories. The vfile_split command splits a file into pieces each time the platform-specific separator is found. The vfile_join command concatenate a list of strings with the platform-specific separator and returns the concatenated file name.

In the following example, extracted from the unit tests included in flibs, the file "declaration.txt" is first normalized, so that the normalized dynamic string may have the value "/home/bill/flibs/tests/filedir/declaration.txt" under Windows or "C:/workbench/flibs/tests/filedir/declaration.txt" under Linux. Then the file name is split into a list of strings, for example "home", "bill", "flibs", "tests", "filedir", "declaration.txt". The number of strings in the list is then computed with the method vstrlist_length.

use m_vstring use m_vstringlist use m_vfile type ( t_vstring ) :: normalized type ( t_vstringlist ) :: listOfFiles integer :: numberOfStrings normalized = vfile_normalize ( "declaration.txt" ) listOfFiles = vfile_split ( normalized ) numberOfStrings = vstrlist_length ( listOfFiles )

One particularly useful command when dealing with files is vfile_findbypattern. The command takes a string as an input file pattern. It then computes the list of all files which match that pattern. The string matching system is based on the vstring_match method of the m_vstring module.

In the following example, extracted again from the unit tests of flibs, one computes the list of files in the directory "testfindbypattern" matching the pattern "*dec*.txt".

type ( t_vstringlist ) :: listOfFiles listOfFiles = vfile_findbypattern ( "testfindbypattern" , pattern = "*dec*.txt" )

Error management

The file management may raise errors, for example when the user want to rename a file which does not exist. Many of the provided commands have an optional integer output argument "status" which is zero when no error occurred and non-zero in case of error. If the status argument is not provided and an error is generated, then the program stops and a message is displayed on standard output. These are the public error flags that the current component may generate :

VFILE_ERROR_OK VFILE_ERROR_UNABLE_TO_OPEN_SOURCE VFILE_ERROR_UNABLE_TO_OPEN_TARGET VFILE_ERROR_UNABLE_TO_WRITE_TARGET VFILE_ERROR_SOURCE_FILE_DOES_NOT_EXIST

Intel Fortran portability

Several methods of this component are based on Fortran extensions, which requires compiler-specific settings. For Intel Fortran compiler, the current implementation was based on IFPORT.F90 file in the Intel release for details on the interfaces provided. If the client code use these routines, it must define the pre-processing macro _VFILE_INTEL_FORTRAN_PORTABILITY_ROUTINES

RENAME and GETCWD fortran extension

Depending on the compiler, the "RENAME" fortran extension is provided as a subroutine or a function. For example, this is a short list of compilers and their particular RENAME provided :

function : Intel Fortran, g95
subroutine : gfortran

To inform the m_vfile module of the particular RENAME extension, one of the following pre-processing macro must be defined :

_VFILE_RENAME_FUNCTION
_VFILE_RENAME_SUBROUTINE

The same situation happens with the GETCWD fortran extension. To inform the m_vfile module of the particular GETCWD extension, one of the following pre-processing macro must be defined :

_VFILE_GETCWD_FUNCTION
_VFILE_GETCWD_SUBROUTINE

Dynamic or static buffer

The internal algorithms provided by m_vstrings are based on basic fortran character strings. In several situations, the dynamic vstring has to be converted into a basic fortran character buffer string, which size has to be given explicitly in the source code, with "character ( len = <something>)" statement. Two solutions are provided, and the user can define the pre-processing macro _VFILE_STATIC_BUFFER to configure that :

the first solution is to set the size of the buffer statically, to a constant integer value VSTRING_BUFFER_SIZE.
the second solution is to compute the size of the buffer dynamically, with the fortran 90 len = vstring_length(this) statement.

If the _VFILE_STATIC_BUFFER is defined, then character strings of constant size are used as buffers. If the _VFILE_STATIC_BUFFER is not defined (which is the default), then character strings of dynamic size are used as buffers. The second solution is more efficient, because the strings are not oversized or undersized, depending on the real number of characters in the dynamic string. But the feature may not be provided by the compiler at hand. For example, problems with the dynamic length character string have been experienced with Intel Fortran 8.

Preprocessing

The following preprocessing macro must be considered :

_VFILE_STATIC_BUFFER : see the section "Dynamic or static buffer"
_VFILE_RENAME_FUNCTION or _VFILE_RENAME_SUBROUTINE : see the section "RENAME and GETCWD fortran extension"
_VFILE_GETCWD_FUNCTION or _VFILE_GETCWD_SUBROUTINE : see the section "RENAME and GETCWD fortran extension"

Example of compiler settings

This is an abstract of all macros for several compilers.

Compiler : Intel Fortran V8.0

_VFILE_INTEL_FORTRAN_PORTABILITY_ROUTINES
_VFILE_RENAME_FUNCTION
_VFILE_STATIC_BUFFER
_VFILE_GETCWD_FUNCTION

Compiler : g95

_VFILE_RENAME_FUNCTION
_VFILE_GETCWD_FUNCTION

Compiler : gfortran

_VFILE_RENAME_SUBROUTINE
_VFILE_GETCWD_SUBROUTINE

METHODS

vfile_rootname ( filename) result ( rootname )

type ( t_vstring ) , intent(in) :: filename
type ( t_vstring ) :: rootname

Returns the name without the extension (if any), that is, The part of the name _before_ the last "." in filename or the whole name if no "." is present in filename. Example : if filename is "declaration.txt", the file root name is "declaration".

vfile_rootname ( filename) result ( rootname )

character(len=*), intent(in) :: filename
type ( t_vstring ) :: rootname

Same as previous but with filename as a character string.

vfile_extension ( filename) result ( extension )

type ( t_vstring ), intent(in) :: filename
type ( t_vstring ) :: extension

Returns the extension (if any), that is the part of the name after and including the last "." or empty if none present. Example : if filename is "declaration.txt", the file extension is ".txt".

vfile_extension ( filename) result ( extension )

character(len=*), intent(in) :: filename
type ( t_vstring ) :: extension

Same as previous but with filename as a character string.

vfile_tail ( filename) result ( filetail )

type ( t_vstring ), intent(in) :: filename
type ( t_vstring ) :: filetail

Returns all of the characters in name after the last directory separator. If filename contains no separators then returns filename. Example : if filename is "dir1/declaration.txt", the file tail is "declaration.txt".

vfile_tail ( filename) result ( filetail )

character(len=*), intent(in) :: filename
type ( t_vstring ) :: filetail

Same as previous but with filename as a character string.

vfile_dirname ( filename) result ( dirname )

type ( t_vstring ), intent(in) :: filename
type ( t_vstring ) :: dirname

Return the directory, that is, the part of the name before the last directory separator. Example : if filename is "dir1/declaration.txt", the directory name is "dir1".

vfile_dirname ( filename) result ( dirname )

character(len=*), intent(in) :: filename
type ( t_vstring ) :: dirname

Same as previous but with filename as a character string.

vfile_first_separator_index ( filename) result ( sepindex )

type ( t_vstring ), intent(in) :: filename
integer :: sepindex

Returns the index of the first separator in the given filename or 0 if there is no separator in the given file name.

vfile_first_separator_index ( filename) result ( sepindex )

character(len=*), intent(in) :: filename
integer :: sepindex

Same as previous but with filename as a character string.

vfile_last_separator_index ( filename) result ( sepindex )

type ( t_vstring ), intent(in) :: filename
integer :: sepindex

Returns the index of the last separator in the given filename or 0 if there is no separator in the given file name.

vfile_last_separator_index ( filename) result ( sepindex )

character(len=*), intent(in) :: filename
integer :: sepindex

Same as previous but with filename as a character string.

vfile_join ( dirname filename) result ( fullname )

type ( t_vstring ), intent(in) :: dirname
type ( t_vstring ), intent(in) :: filename
type ( t_vstring ) :: fullname

Join the current file with the given file name, using the platform-specific separator as the joining character. The result is always canonical for the current platform: / for Unix and Windows, and : for Macintosh. If a particular name is relative, then it will be joined to the previous file name argument. Otherwise, any earlier arguments will be discarded, and joining will proceed from the current argument.

vfile_join ( dirname , filename) result ( fullname )

type ( t_vstring ), intent(in) :: dirname
character(len=*), intent(in) :: filename
type ( t_vstring ) :: fullname

Same as previous but with filename as a character string.

vfile_add_extension ( filename , extension ) result ( newname )

type ( t_vstring ), intent(in) :: filename
type ( t_vstring ), intent(in) :: extension
type ( t_vstring ) :: newname

Return a new file name with the given extension concatenated. If the given file name ends with a dot and the given extension begins with a dot, only one dot is kept. Note that the extension of one file begins with a dot : ".txt" is a file extension while "txt" is not.

vfile_separator ( ) result ( separator )

type ( t_vstring ) :: separator

Return the native separator for the current platform The separator depends on the platform :

"/" on Unix, Linux systems,
"\" on Windows systems,
":" on Macintosh.

vfile_pwd ( pwd ?, status? )

type ( t_vstring ) :: pwd
integer , intent(out) , optional :: status

Returns the name of the current directory by using the fortran extension GETCWD. The separator used here is the platform-independent "/".

vfile_exists ( filename ) result ( exists )

type ( t_vstring ), intent(in) :: filename
logical :: exists

Returns .true. if file name exists, .false. otherwise.

vfile_exists ( filename ) result ( exists )

character(len=*), intent(in) :: filename
logical :: exists

Same as previous but with filename as a character string.

vfile_rename ( filename , newfn ?, status? )

type ( t_vstring ), intent(in) :: filename
type ( t_vstring ), intent(in) :: newfn
integer, intent(out) , optional :: status

Renames the file ofdln to newfn by using the RENAME fortran extension. If status is supplied, it contains 0 on success or nonzero error code upon return.

vfile_rename ( filename , newfn ?, status? )

type ( t_vstring ), intent(in) :: filename
character(len=*), intent(in) :: newfn
integer, intent(out) , optional :: status

Same as previous but with newfn as a character string.

vfile_copy ( filename , targetfn ?, status? ?, mode? ?, force? ?, trimline? )

type ( t_vstring ), intent(in) :: filename
type ( t_vstring ), intent(in) :: targetfn
integer, intent(out) , optional :: status
character(len=*), intent(in), optional :: mode
logical, intent(in) , optional :: force
logical, intent(in) , optional :: trimline

Copy the ascii file ofdln to targetfn. If the source file does not exists, generates an error. If the target file allready exists and force option is undefined or defined to false, generates an error. If status is supplied, it contains 0 on success or nonzero error code upon return

status = 1 when one was unable to open the source file
status = 2 when one was unable to open the target file
status = 3 when there was a problem while writing the target file
status = 4 when the source file does not exist

If mode is not supplied or supplied and equals to "system", then the copy is made using an operating system command. If mode is supplied and equals to "ascii", then the copy is made using standard fortran. The force option is available only in "ascii" mode. If force is supplied and true, if the target file allready exists, delete it before making the copy. The trimline option is available only in "ascii" mode. If trimline is supplied and true, or not supplied, the lines of the file copy are trimmed. If trimline is supplied and false, the number of columns in the file copy are all of maximum possible length.

The "ascii" mode may not behave as expected :

The maximum number of columns in the source filename is 1000.
After execution, the target file is not an exact copy of the source file. Because of the fortran format used, all the lines of the target file are of length 1000 : blank spaces are appended at the end of the string.

vfile_copy ( filename , targetfn ?, status? ?, mode? ?, force? ?, trimline? )

type ( t_vstring ), intent(in) :: filename
character(len=*), intent(in) :: targetfn
integer, intent(out) , optional :: status
character(len=*), intent(in), optional :: mode
logical, intent(in) , optional :: force
logical, intent(in) , optional :: trimline

Same as previous but with targetfn as a character string.

vfile_delete ( filename ?, force? ?, status? )

type ( t_vstring ), intent(in) :: filename
logical, intent(in) , optional :: force
integer, intent(out) , optional :: status

Removes the file or directory filename. Non-empty directories will be removed only if the force option is specified. If force is supplied and true, forces to delete the directory, even if it is empty. If force is not supplied or supplied and false, the directory is not deleted if it is empty. If status is supplied, it contains 0 on success or nonzero error code upon return.

vfile_delete ( filename ?, force? ?, status? )

character(len=*), intent(in) :: filename
logical, intent(in) , optional :: force
integer, intent(out) , optional :: status

Same as previous but with filename as a character string.

vfile_isdirectory ( filename) result ( isdirectory )

type ( t_vstring ), intent(in) :: filename
logical :: isdirectory

Returns .true. if file name is a directory, .false. otherwise.

vfile_isdirectory ( filename) result ( isdirectory )

character(len=*), intent(in) :: filename
logical :: isdirectory

Same as previous but with filename as a character string.

vfile_isfile ( filename) result ( isfile )

type ( t_vstring ), intent(in) :: filename
logical :: isfile

Returns .true. if file name is a file, .false. otherwise.

vfile_isfile ( filename) result ( isfile )

character(len=*), intent(in) :: filename
logical :: isfile

Same as previous but with filename as a character string.

vfile_size ( filename ?, status?) result ( vfile_size )

type ( t_vstring ), intent(in) :: filename
integer, intent(out) , optional :: status
integer :: vfile_size

Returns .true. if file name is a file, .false. otherwise. Returns an integer giving the size of file name in bytes. If the file doesn't exist or its size cannot be queried then an error is generated. If status is supplied, it contains 0 on success or nonzero error code upon return.

vfile_size ( filename ?, status?) result ( vfile_size )

character(len=*), intent(in) :: filename
integer, intent(out) , optional :: status
integer :: vfile_size

Same as previous but with filename as a character string.

vfile_atime ( filename ?, status?) result ( vfile_atime )

type ( t_vstring ), intent(in) :: filename
integer, intent(out) , optional :: status
integer :: vfile_atime

Returns an integer representing the time at which file name was last accessed. If status is supplied, it contains 0 on success or nonzero error code upon return.

vfile_atime ( filename ?, status?) result ( vfile_atime )

character(len=*), intent(in) :: filename
integer, intent(out) , optional :: status
integer :: vfile_atime

Same as previous but with filename as a character string.

vfile_mtime ( filename ?, status?) result ( vfile_mtime )

type ( t_vstring ), intent(in) :: filename
integer, intent(out) , optional :: status
integer :: vfile_mtime

Returns an integer representing the time at which file name was last modified. If status is supplied, it contains 0 on success or nonzero error code upon return.

vfile_mtime ( filename ?, status?) result ( vfile_mtime )

character(len=*), intent(in) :: filename
integer, intent(out) , optional :: status
integer :: vfile_mtime

Same as previous but with filename as a character string.

vfile_normalize ( filename ) result ( vfile_normalize )

type ( t_vstring ), intent(in) :: filename
type ( t_vstring ) :: vfile_normalize

Returns a unique normalized path representation for the file-system object (file, directory, link, etc), whose string value can be used as a unique identifier for it. A normalized path is an absolute path which has all '../', './' removed. Also it is one which is in the ``standard'' format for the native platform. On Windows or Mac, any platform-specific separator in the path is replaced by the platform-independent separator "/". On Windows it also means we want the long form with that form's case-dependence (which gives us a unique, case-dependent path).

vfile_normalize ( filename ) result ( vfile_normalize )

character(len=*), intent(in) :: filename
type ( t_vstring ) :: vfile_normalize

Same as previous but with filename as a character string.

vfile_find ( ?basedir? ) result ( listOfFiles )

type ( t_vstring ), intent(in), optional :: basedir
type ( t_vstringlist ) :: listOfFiles

vfile_find ( basedir ) result ( listOfFiles )

character(len=*), intent(in) :: basedir
type ( t_vstringlist ) :: listOfFiles

Same as previous but with basedir as a character string.

vfile_find ( ?basedir? , filtercmd ) result ( listOfFiles )

type ( t_vstring ), intent(in), optional :: basedir
type ( t_vstringlist ) :: listOfFiles

interface function filtercmd ( filename ) result ( keepfile ) use m_vstring, only : t_vstring type ( t_vstring ), intent(in) :: filename logical :: keepfile end function filtercmd end interface

An implementation of the unix command find. Returns a list of files or directories which are located in the given basedir directory, and, recursively, in all sub-directories. Each file in the resulting list has a path relative to the given basedir directory. If basedir is provided, this is the name of the base directory into which the search is done. If basedir is not provided, the current directory is used by default. The filtercmd command, if provided, is interpreted as a command prefix and one argument is passed to it, the name of the file or directory find is currently looking at. Note that this name is not fully qualified. It has to be joined it with the result of pwd to get an absolute filename. The result of filtercmd is a boolean value that indicates if the current file should be included in the list of interesting files.

vfile_find ( basedir , filtercmd ) result ( listOfFiles )

character(len=*), intent(in) :: basedir
type ( t_vstringlist ) :: listOfFiles

interface function filtercmd ( filename ) result ( keepfile ) use m_vstring, only : t_vstring type ( t_vstring ), intent(in) :: filename logical :: keepfile end function filtercmd end interface

Same as previous but with basedir as a character string.

vfile_findbypattern ( ?basedir? , pattern ) result ( listOfFiles )

type ( t_vstring ), intent(in), optional :: basedir
type ( t_vstring ), intent(in) :: pattern
type ( t_vstringlist ) :: listOfFiles

Returns a list of files which match the given pattern. Internally, this command is based on vfile_find, with a particular filter command applied. If basedir is provided, this is the name of the base directory into which the search is done. If basedir is not provided, the current directory is used by default. The pattern is the pattern for the file names (like: *.f90) against which each file name is compared. The method used for string matching is vstring_match, so that all features available is vstring_match are available in vfile_findbypattern.

vfile_findbypattern ( ?basedir? , pattern ) result ( listOfFiles )

character(len=*), intent(in), optional :: basedir
character(len=*), intent(in) :: pattern
type ( t_vstringlist ) :: listOfFiles

Same as previous but with basedir and pattern as a character string.

vfile_listfiles ( ?directory? ?, filetypes? ?, pattern? ?, tails?) result ( listOfFiles )

type ( t_vstring ), intent(in), optional :: basedir
type ( t_vstringlist ), intent(in), optional :: pattern
type ( t_vstring ), intent(in), optional :: pattern
logical, intent(in), optional :: tails
type ( t_vstringlist ) :: listOfFiles

Returns a list of files in one directory. Only the file tails are in the list. If directory is provided, the directory into which the list is to be computed. If directory is not provided, the current directory is used and only the file names are file tails. If directory is provided, the computed files names are relative and begin with the given directory (following the template directory/filetail). If filetypes is provided, only list files or directories which match filetypes, with d (directory), f (plain file). If filetypes is not provided, the filetypes "d" , "f" list is used. If pattern is provided, only list files which match the given pattern. If pattern is not provided, the "*" pattern is used. The vstring_match command is used to compare the file against the pattern so that all the pattern types available in vstring_match are available in vfile_listfiles. If tails is provided and true, only return the part of each file found which follows the last directory named in directory. Thus the statement

listoffiles = vfile_listfile ( tails = .true. , directory = directory , pattern = "*" )

is equivalent to

call vfile_pwd ( cwd ) call vstrplatform_cd ( directory ) listoffiles = vfile_listfile ( tails = .true. , pattern = "*" ) call vstrplatform_cd ( cwd )

If tails is provided and false, or not provided, the files are left as specified by the directory argument.

vfile_listfiles ( directory ?, filetypes? ?, pattern? ?, tails?) result ( listOfFiles )

character(len=*), intent(in) :: basedir
type ( t_vstringlist ), intent(in), optional :: pattern
character(len=*), intent(in), optional :: pattern
logical, intent(in), optional :: tails
type ( t_vstringlist ) :: listOfFiles

Same as previous but with directory and pattern as a character string.

vfile_type ( filename ?, status?) result ( filetype )

type ( t_vstring ), intent(in) :: filename
integer , intent(out), optional :: status
type ( t_vstring ) :: filetype

Returns a string giving the type of file name, which will be one of "file" or "directory". If status is provided and the file type could be computed, the status is set to 0. If status is provided and the file type could not be computed, the status is set to VFILE_ERROR_UNKNOWN_FILE_TYPE. If status is not provided and the file type could not be computed, an error is generated.

vfile_type ( filename ?, status?) result ( filetype )

character(len=*), intent(in) :: filename
integer , intent(out), optional :: status
type ( t_vstring ) :: filetype

Same as previous but with filename as a character string.

vfile_split ( filename) result ( listOfComponents )

type ( t_vstring ), intent(in) :: filename
type ( t_vstringlist ) :: listOfComponents

Returns a list of strings where elements are the path components in name.

vfile_split ( filename) result ( listOfComponents )

character(len=*), intent(in) :: filename
type ( t_vstringlist ) :: listOfComponents

Same as previous but with filename as a character string.

vfile_touch ( filename ?, status?)

type ( t_vstring ), intent(in) :: filename
integer, intent(out) , optional :: status

Implementation of touch. Alter the atime and mtime of the specified files. If status is supplied, it contains 0 on success or nonzero error code upon return. If status is not provided and the process could not be done, an error is generated.

vfile_touch ( filename ?, status?)

character(len=*), intent(in) :: filename
integer, intent(out) , optional :: status

Same as previous but with filename as a character string.

vfile_pathtype ( filename) result ( pathtype )

type ( t_vstring ), intent(in) :: filename
integer :: pathtype

Returns one of VFILE_PATHTYPE_ABSOLUTE, VFILE_PATHTYPE_RELATIVE, VFILE_PATHTYPE_VOLUMERELATIVE. If filename refers to a specific file on a specific volume, the path type will be absolute. If filename refers to a file relative to the current working directory, then the path type will be relative. If name refers to a file relative to the current working directory on a specified volume, or to a specific file on the current working volume, then the path type is volumerelative.

Examples :

"." is relative on all platforms
".." is relative on all platforms
"/" is absolute on Linux/Unix
"C:/" is absolute on Windows (if the C:/ exists)
"/" is volumerelative on windows and refers to the current volume (for example C:/)
"toto.txt" is relative on all platforms
"./toto.txt" is relative on all platforms

vfile_pathtype ( filename) result ( pathtype )

character(len=*), intent(in) :: filename
integer :: pathtype

Same as previous but with filename as a character string.

vfile_nativename ( filename) result ( nativename )

type ( t_vstring ), intent(in) :: filename
( t_vstring ) :: nativename

Returns the platform-specific name of the file. filename is useful if the filename is needed to pass to a platform-specific call, such as the execution of a system command under Windows or AppleScript on the Macintosh.

vfile_nativename ( filename) result ( nativename )

character(len=*), intent(in) :: filename
( t_vstring ) :: nativename

Same as previous but with filename as a character string.

vfile_mkdir ( filename ?, status?)

type ( t_vstring ), intent(in) :: filename
integer, intent(out) , optional :: status

Create a directory. If status is supplied, it contains 0 on success or nonzero error code upon return. If status is not provided and the process could not be done, an error is generated.

vfile_mkdir ( filename ?, status?)

character(len=*), intent(in) :: filename
integer, intent(out) , optional :: status

Same as previous but with filename as a character string.

vfile_open ( filename ?, fileunit? ?, iostat? ?, status? ?, access? ?, form? ?, recl? ?, blank? ?, position? ?, action? ?, delim? ?, pad?) result ( fileunit_real )

type ( t_vstring ), intent(in) :: filename
integer, intent(out) , optional :: fileunit
character(len=*) , intent(in) , optional :: action
character(len=*) , intent(in) , optional :: status
character(len=*) , intent(in) , optional :: access
character(len=*) , intent(in) , optional :: form
character(len=*) , intent(in) , optional :: blank
character(len=*) , intent(in) , optional :: position
character(len=*) , intent(in) , optional :: delim
character(len=*) , intent(in) , optional :: pad
integer , intent(in) , optional :: recl
integer , intent(out) , optional :: iostat
integer :: fileunit_real

Open a file and returns the unit associated with the opened file. The command is based on fortran intrinsic "open". If the optional argument fileunit is provided, it is used to open the file. If not provided, a file unit is automatically computed on the base of currently free logical units.

Note:

All the options of the intrinsic "open" are provided with the same behaviour and default values, with some exceptions.

The file name is mandatory in vfile_open, even if the "file=" specifier is not mandatory in fortran "open". This behaviour allows the fortran to manage a status="scratch" specifier, which provides a way to manage for temporary files internally. Instead, the m_vfile component provides the vfile_tempfile service.
The "err=" option with an error label as argument is not provided. The client code may use the iostat option instead.

vfile_open ( filename ?, fileunit? ?, iostat? ?, status? ?, access? ?, form? ?, recl? ?, blank? ?, position? ?, action? ?, delim? ?, pad?) result ( fileunit_real )

character(len=*), intent(in) :: filename
integer, intent(out) , optional :: fileunit
character(len=*) , intent(in) , optional :: action
character(len=*) , intent(in) , optional :: status
character(len=*) , intent(in) , optional :: access
character(len=*) , intent(in) , optional :: form
character(len=*) , intent(in) , optional :: blank
character(len=*) , intent(in) , optional :: position
character(len=*) , intent(in) , optional :: delim
character(len=*) , intent(in) , optional :: pad
integer , intent(in) , optional :: recl
integer , intent(out) , optional :: iostat
integer :: fileunit_real

Same as previous but with filename as a character string.

STATIC METHODS

vfile_startup ()

Initialize module internal state. This routine must be called once before calling any method of the module.

vfile_shutdown ()

Shutdown module internal state.

vfile_set_stoponerror ( stoponerror )

logical , intent(in) :: stoponerror

Configure the behaviour of the component whenever an error is met. If stoponerror is true, then the execution stops if an error is encountered. If stoponerror is false, then the execution continues if an error is encountered. In both cases, a message is displayed on standard output.

vfile_tempdir () result ( tempdir )

type ( t_vstring ) :: tempdir

Returns the temporary directory for the current platform. The command returns the path of a directory where the caller can place temporary files, such as "/tmp" on Unix systems. The algorithm we use to find the correct directory is as follows:

The directory named in the TMPDIR environment variable.
The directory named in the TEMP environment variable.
The directory named in the TMP environment variable.
A platform specific location:
- Windows "C:\TEMP", "C:\TMP", "\TEMP", and "\TMP" are tried in that order. (classic) Macintosh The TRASH_FOLDER environment variable is used. filename is most likely not correct.
- Unix The directories "/tmp", "/var/tmp", and "/usr/tmp" are tried in that order.

vfile_tempfile result ( tempfile )

type ( t_vstring ) :: tempfile

Returns the name of a temporary file name suitable for writing to. The tempfile name is unique, and the file will be writable and contained in the appropriate system specific temp directory.

vfile_volumes result ( listofvolumes )

type ( t_vstringlist ) :: listofvolumes

Returns the absolute paths to the volumes mounted on the system, as a proper string list. On UNIX, the command will always return "/", since all filesystems are locally mounted. On Windows, it will return a list of the available local drives (e.g. {a:/ c:/}).

Note:

With Intel Fortran, the portability routines provide the "GETDRIVESQQ" function, which returns the list of current drive as a 26 letters string.