# flibs/m_platform(n) 1.0 "flibs"

## NAME

flibs/m_platform - Platform-dependent routines and features

## TABLE OF CONTENTS

TABLE OF CONTENTS
SYNOPSIS
DESCRIPTION
OVERVIEW
Pre-processing macros
Compile
Operating System dependency
System fortran extension
Environment variables extension
Change directory fortran extension
File stat fortran extension
Example of compiler settings
ROUTINES
COPYRIGHT

## SYNOPSIS

use m_platform
platform_system (command ?, status?)
platform_get_os() result ( currentos )
platform_osstring (currentos)
platform_get_platform() result ( currentplatform )
platform_platformstring (currentplatform)
platform_get_environment_variable ( envvar , value)
platform_cd ( dirname ?, status?)
platform_stat ( filename , statarray ?, status?)

## DESCRIPTION

The m_platform module contains parameters to identify the platform the program is running on and provides several routines to interact with the operating system.

## OVERVIEW

The goal is to make the client source code as independent as possible from the particular environment, that is

- independent from the operating system, so that the binaries can be used under Windows, Linux or any other specific OS without modifying the source code,
- independent from the fortran compiler, so that the binaries can be generated with gfortran Intel Fortran, Absoft, or any other specific compiler without modifying the source code.

For instance, the m_platform module provides the following features :

- The parameter PLATFORM_OS identifies the operating system and the parameter PLATFORM_PLATFORM identifies the general category.
- The subroutine platform_system() hides the platform-specific details of running an external command or program.

The function platform_get_os() returns an integer which identifies the operating system and the function platform_get_platform() identifies the general category. For example, the file separator is different on windows ("\"), unix ("/") and Mac (":"). In the following example, extracted from the m_vfile module included with flibs, the platform_get_platform() function is used to configure the separator for the current platform.

         use m_platform, only : &
           platform_get_platform , &
           PLATFORM_PLATFORM_WINDOWS ,&
           PLATFORM_PLATFORM_UNIX , &
           PLATFORM_PLATFORM_MAC
         integer :: platform
         character (len=1) :: VFILE_PLATFORM_SEPARATOR
         platform = platform_get_platform ()
         select case ( platform )
         case ( PLATFORM_PLATFORM_WINDOWS )
           VFILE_PLATFORM_SEPARATOR = VFILE_PLATFORM_SEPARATOR_WINDOWS
         case ( PLATFORM_PLATFORM_UNIX )
           VFILE_PLATFORM_SEPARATOR = VFILE_PLATFORM_SEPARATOR_UNIX
         case ( PLATFORM_PLATFORM_MAC )
           VFILE_PLATFORM_SEPARATOR = VFILE_PLATFORM_SEPARATOR_MAC
         case default
           print *, "I come from Vega."
           return
         end select

The subroutine platform_system() allows to execute an external program at the system level. This routine is generally provided by the fortran compiler as an extension to standard fortran. But some compilers provide the feature as a subroutine (for example gfortran), while other compilers provide the feature as a function (for example Intel Fortran). In the following example, one execute a Monte-Carlo simulation with no dependency on the specific compiler.

          use m_platform, only platform_system
          call platform_system ( "montecarlo.exe" , status )

This is a sketch of available routines :

- platform_system Executes an external command on the system
- platform_get_os Returns the current operating system
- platform_get_platform Returns the current platform
- platform_get_environment_variable Get to one environment variable
- platform_cd Change the system current directory
- platform_stat Get status of a file

### Pre-processing macros

The source code of m_platform is based on pre-processing macro, which must be configured for the specific couple (OS,compiler) at use. With most compilers, defining a pre-processing macro simply consists in enabling the pre-processing with a specific option and adding "-D<macro>" options on the command-line.

The only mandatory pre-processing macro which must be defined is the _PLATFORM_OS_<your OS> macro. Optionnaly, other pre-processing macros may be defined so that the client code may access to additionnal features. If a feature is used and the associated macros have not been defined, the "status" integer of the associated routine will have the value PLATFORM_ERROR_UNDEFINED_SERVICE.

### Compile

The "make" directory provided with flibs should help the use to compile m_platform. The "make/makefile" contains all the makefiles necessary for the project, include specific settings for several compilers. the "make/visualstudio" directory include all projects .nfproj and solutions .sln files necessary to compile the project with Intel Fortran 8 and Visual Studio 2003.

### Operating System dependency

The m_platform module must be informed of the specific OS for which it is compiled. One of the following pre-processing macros must be defined to set the spefic OS at use :

- _PLATFORM_OS_WINDOWS_95
- _PLATFORM_OS_WINDOWS_NT
- _PLATFORM_OS_MAC
- _PLATFORM_OS_SUN
- _PLATFORM_OS_LINUX
- _PLATFORM_OS_UNIX

### System fortran extension

The SYSTEM fortran extension allows to execute an external program. Depending on the compiler, the SYSTEM fortran extension is provided as a subroutine or a function. The m_platform module may be informed of the particular version of the SYSTEM extension at use and one of the following pre-processing macro must be defined :

- _PLATFORM_SYSTEM_SUBROUTINE
- _PLATFORM_SYSTEM_FUNCTION

See in your compiler manual for the specific settings. For example, this is a short list of compilers and the SYSTEM provided :

- function : Intel Fortran, g95.
- subroutine : gfortran,

### Environment variables extension

The fortran 2003 standard introduces a standard way of accessing to the environment variables. Older compilers does not match that standard but provide extensions to access to environment variables. To inform the m_platform module of the particular environment variable extension, one of the following pre-processing macro may be defined :

- _PLATFORM_INTEL_FORTRAN_PORTABILITY_ROUTINES
- _PLATFORM_FORTRAN_2003

### Change directory fortran extension

Depending on the compiler, the "CHDIR" fortran extension is provided as a subroutine or a function. To inform the m_platform module of the particular CHDIR extension, one of the following pre-processing macro may be defined :

- _PLATFORM_CHDIR_SUBROUTINE
- _PLATFORM_CHDIR_FUNCTION

See in your manual for the specific settings. For example, this is a short list of compilers and their particular CHDIR provided :

- function : Intel Fortran, g95, gfortran
- subroutine : gfortran

### File stat fortran extension

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

- function : Intel Fortran, g95
- subroutine : gfortran

To inform the m_platform module of the particular STAT extension, one of the following pre-processing macro may be defined :

- _PLATFORM_STAT_SUBROUTINE
- _PLATFORM_STAT_FUNCTION

### Example of compiler settings

This is an abstract of all pre-processing macros for several compilers.

Compiler : gfortran

- _PLATFORM_FORTRAN_2003
- _PLATFORM_CHDIR_SUBROUTINE
- _PLATFORM_STAT_SUBROUTINE
- _PLATFORM_SYSTEM_SUBROUTINE

Compiler : Intel Fortran

- _PLATFORM_INTEL_FORTRAN_PORTABILITY_ROUTINES
- _PLATFORM_CHDIR_FUNCTION
- _PLATFORM_STAT_FUNCTION
- _PLATFORM_SYSTEM_FUNCTION

Compiler : g95

- _PLATFORM_FORTRAN_2003
- _PLATFORM_CHDIR_FUNCTION
- _PLATFORM_STAT_FUNCTION
- _PLATFORM_SYSTEM_FUNCTION

## ROUTINES

The module contains the following routines.

use m_platform
  To import the subroutines, use this module.
platform_system (command ?, status?)
  character(len=*) :: command
  integer, intent ( out ), optional :: status
  Run an external command or program, optionally retrieving the status of that command. Under Windows the "call system" may generate the display of a console. Optional argument status contains the execution status. Notice that the information contained in it is not very reliable - some systems do not give any information. The command to run is quite likely platform-dependent.
platform_get_os() result ( currentos )
  integer :: currentos
  Return the type of operating system, one of: PLATFORM_OS_WINDOWS_95, PLATFORM_OS_WINDOWS_NT, PLATFORM_OS_MACOS, PLATFORM_OS_SUNOS, PLATFORM_OS_LINUX, PLATFORM_OS_UNIX. The actual integer value should not be used directly ; instead, it should be compared against the PLATFORM_OS_* public variables.
platform_osstring (currentos)
  character(len=*), intent(out) :: currentos
  Returns a string containing the current operating system running on the current machine, one of "Windows 95", "Windows NT", "MacOS", "SunOS", "Linux" or "Unix".
platform_get_platform() result ( currentplatform )
  integer :: currentplatform
  Return the category of platform, one of: PLATFORM_PLATFORM_WINDOWS, PLATFORM_PLATFORM_MAC, PLATFORM_PLATFORM_UNIX The actual integer value should not be used directly ; instead, it should be compared against the PLATFORM_PLATFORM_* public variables.
platform_platformstring (currentplatform)
  character(len=*), intent(out) :: currentplatform
  Returns a string containing the current platform running on the current machine, one of "Windows", "Mac", "Unix".
platform_get_environment_variable ( envvar , value)
  character(len=*) :: envvar
  character(len=*) :: value
  Retrieve the value of the environment variable envvar. There is no indication of whether the variable indeed exists and it is up to the calling program to provide a string argument sufficiently long to hold the value. The environment variable envvar is case-sensitive on some platforms, case-insensitive on others. This is entirely up to the platform. As the underlying routines give no indication of the existence of the environment variable, it is probably best to fill the value with a known value first (like: "????") to check it.
platform_cd ( dirname ?, status?)
  character(len=*), intent(in) :: dirname
  integer, intent(out) , optional :: status
  Change working directory to dirname. If status is supplied, it contains 0 on success or nonzero error code upon return
platform_stat ( filename , statarray ?, status?)
  character(len=*), intent(in) :: filename
  integer, dimension (1:13) , intent(out) :: filename
  integer, intent(out) , optional :: status
  Get status of the file filename and fills the array statarray with the following content.
  - statarray(1) Device ID
  - statarray(2) Inode number
  - statarray(3) File mode
  - statarray(4) Number of links
  - statarray(5) Owner's uid
  - statarray(6) Owner's gid
  - statarray(7) ID of device containing directory entry for file (0 if not available)
  - statarray(8) File size (bytes)
  - statarray(9) Last access time
  - statarray(10) Last modification time
  - statarray(11) Last file status change time
  - statarray(12) Preferred I/O block size (-1 if not available)
  - statarray(13) Number of blocks allocated (-1 if not available)
  If status is supplied, it contains 0 on success or nonzero error code upon return

## COPYRIGHT

Copyright © 2008 Arjen Markus <arjenmarkus@sourceforge.net>
Copyright © 2008 Michael Baudin <michael.baudin@gmail.com>