System modules#

stdlib_system (module)#

version: experimental

Cached OS type retrieval with negligible runtime overhead. (Specification: stdlib_system)

Summary

Provides a cached value for the runtime OS type.

Description

This function caches the result of get_runtime_os after the first invocation. Subsequent calls return the cached value, ensuring minimal overhead.

version: experimental

Determine the current operating system (OS) type at runtime. (Specification: stdlib_system)

Summary

This function inspects the runtime environment to identify the OS type.

Description

The function evaluates environment variables (OSTYPE or OS) and filesystem attributes to identify the OS. It distinguishes between several common operating systems: - Linux - macOS - Windows - Cygwin - Solaris - FreeBSD - OpenBSD

Returns a constant representing the OS type or OS_UNKNOWN if the OS cannot be determined.

Public sub-processing interface Public path related functions and interfaces version: experimental

Tests if a given path matches an existing directory. (Specification: stdlib_system)

Summary

Function to evaluate whether a specified path corresponds to an existing directory.

Description

This function checks if a given file system path is a directory. It follows symbolic links to return the status of the target.

It is cross-platform and utilizes native system calls. It supports common operating systems such as Linux, macOS, Windows, and various UNIX-like environments. On unsupported operating systems, the function will return .false..

version: experimental

Makes an empty directory. (Specification: stdlib_system)

Summary

Creates an empty directory with default permissions.

Description

This function makes an empty directory according to the path provided. Relative paths are supported. On Windows, paths involving either / or \ are accepted. An appropriate error message is returned whenever any error occurs.

version: experimental

Makes an empty directory, also creating all the parent directories required. (Specification: stdlib_system)

Summary

Creates an empty directory with all the parent directories required to do so.

Description

This function makes an empty directory according to the path provided. It also creates all the necessary parent directories in the path if they do not exist already. Relative paths are supported. An appropriate error message is returned whenever any error occurs.

version: experimental

Removes an empty directory. (Specification: stdlib_system)

Summary

Removes an empty directory.

Description

This function Removes an empty directory according to the path provided. Relative paths are supported. On Windows paths involving either / or \ are accepted. An appropriate error message is returned whenever any error occurs.

version: experimental

Gets the current working directory of the process (Specification: stdlib_system)

Summary

Gets the current working directory.

Description

This subroutine gets the current working directory the process is executing from.

version: experimental

Sets the current working directory of the process (Specification: stdlib_system)

Summary

Changes the current working directory to the one specified.

Description

This subroutine sets the current working directory the process is executing from.

version: experimental

Sets an environment variable for the calling process (Specification: stdlib_system)

### Summary Creates an environment variable, or changes the value of an existing one.

### Description The variable is visible to this process and to any process it starts afterwards. It is not written back to the parent shell, which is a property of the operating system rather than of this implementation.

overwrite selects whether an existing variable is replaced, and defaults to .true.. It has no effect on Windows, whose _putenv_s always replaces.

version: experimental

Removes an environment variable from the calling process (Specification: stdlib_system)

### Summary Deletes an environment variable, if it is set.

### Description Removing a variable that is not set is not an error, which matches unsetenv.

version: experimental

Deletes a specified file from the filesystem. (Specification: stdlib_system)

Summary

Subroutine to safely delete a file from the filesystem. It handles errors gracefully using the library’s state_type.

Description

This subroutine deletes a specified file. If the file is a directory or inaccessible, an error is raised. If the file does not exist, a warning is returned, but no error state. Errors are handled using the library’s state_type mechanism. If the optional err argument is not provided, exceptions trigger an error stop.

version: experimental

Returns the file path of the null device, which discards all data written to it. (Specification: stdlib_system)

Summary

Function that provides the file path of the null device appropriate for the current operating system.

Description

The null device is a special file that discards all data written to it and always reads as an empty file. This function returns the null device path, adapted for the operating system in use.

On Windows, this is NUL. On UNIX-like systems, this is /dev/null.

version: experimental

A helper function for returning the type(state_type) with the flag STDLIB_FS_ERROR set. (Specification: stdlib_system)

version: experimental

A helper function for returning the type(state_type) with the flag STDLIB_FS_ERROR set. It also formats and prefixes the code passed to it as the first argument (Specification: stdlib_system)

version: experimental

Tests if a given path is a symbolic link. (Specification: stdlib_system)

Summary

Function to evaluate whether a specified path corresponds to a symbolic link.

Description

This function checks if a given file system path is a symbolic link either to a file or a directory. It is cross-platform and utilizes native system calls. It supports common operating systems such as Linux, macOS, Windows, and various UNIX-like environments.

version: experimental

Tests if a given path is a regular file. (Specification: stdlib_system)

Summary

Function to evaluate whether a specified path corresponds to a regular file.

Description

This function checks if a given file system path is a regular file. It follows symbolic links to return the status of the target. It is cross-platform and utilizes native system calls. It supports common operating systems such as Linux, macOS, Windows, and various UNIX-like environments.

Static storage for the current OS Tests if a given path matches an existing directory. Cross-platform implementation without using external C libraries. makes an empty directory removes an empty directory

Variables

OS_UNKNOWNinteger, parameter, Default = 0

Integer constants representing known operating system (OS) types (Specification: stdlib_system) Represents an unknown operating system Represents a Linux operating system Represents a macOS operating system Represents a Windows operating system Represents a Cygwin environment Represents a Solaris operating system Represents a FreeBSD operating system Represents an OpenBSD operating system

Helper function returning the name of an OS parameter

OS_LINUXinteger, parameter, Default = 1

Integer constants representing known operating system (OS) types (Specification: stdlib_system) Represents an unknown operating system Represents a Linux operating system Represents a macOS operating system Represents a Windows operating system Represents a Cygwin environment Represents a Solaris operating system Represents a FreeBSD operating system Represents an OpenBSD operating system

Helper function returning the name of an OS parameter

OS_MACOSinteger, parameter, Default = 2

Integer constants representing known operating system (OS) types (Specification: stdlib_system) Represents an unknown operating system Represents a Linux operating system Represents a macOS operating system Represents a Windows operating system Represents a Cygwin environment Represents a Solaris operating system Represents a FreeBSD operating system Represents an OpenBSD operating system

Helper function returning the name of an OS parameter

OS_WINDOWSinteger, parameter, Default = 3

Integer constants representing known operating system (OS) types (Specification: stdlib_system) Represents an unknown operating system Represents a Linux operating system Represents a macOS operating system Represents a Windows operating system Represents a Cygwin environment Represents a Solaris operating system Represents a FreeBSD operating system Represents an OpenBSD operating system

Helper function returning the name of an OS parameter

OS_CYGWINinteger, parameter, Default = 4

Integer constants representing known operating system (OS) types (Specification: stdlib_system) Represents an unknown operating system Represents a Linux operating system Represents a macOS operating system Represents a Windows operating system Represents a Cygwin environment Represents a Solaris operating system Represents a FreeBSD operating system Represents an OpenBSD operating system

Helper function returning the name of an OS parameter

OS_SOLARISinteger, parameter, Default = 5

Integer constants representing known operating system (OS) types (Specification: stdlib_system) Represents an unknown operating system Represents a Linux operating system Represents a macOS operating system Represents a Windows operating system Represents a Cygwin environment Represents a Solaris operating system Represents a FreeBSD operating system Represents an OpenBSD operating system

Helper function returning the name of an OS parameter

OS_FREEBSDinteger, parameter, Default = 6

Integer constants representing known operating system (OS) types (Specification: stdlib_system) Represents an unknown operating system Represents a Linux operating system Represents a macOS operating system Represents a Windows operating system Represents a Cygwin environment Represents a Solaris operating system Represents a FreeBSD operating system Represents an OpenBSD operating system

Helper function returning the name of an OS parameter

OS_OPENBSDinteger, parameter, Default = 7

Integer constants representing known operating system (OS) types (Specification: stdlib_system) Represents an unknown operating system Represents a Linux operating system Represents a macOS operating system Represents a Windows operating system Represents a Cygwin environment Represents a Solaris operating system Represents a FreeBSD operating system Represents an OpenBSD operating system

Helper function returning the name of an OS parameter

fs_type_unknowninteger, parameter, Default = 0

Integer constants representing the most common path types. (Specification: stdlib_system) Represents an unknown path type Represents a regular file Represents a directory Represents a symbolic link

version: experimental

Checks if a path exists in the filesystem. (Specification: stdlib_system)

Summary

Function to check whether the path exists in the fileystem at all. If the path does exist, returns the type of the path.

Description

This function makes a system call (syscall) to retrieve metadata for the specified path and determines its type. It can distinguish between the following path types:

  • Regular File

  • Directory

  • Symbolic Link

It does not follow symbolic links.

It returns a constant representing the detected path type, or type_unknown if the type cannot be determined. Any encountered errors are handled using state_type.

fs_type_regular_fileinteger, parameter, Default = 1

Integer constants representing the most common path types. (Specification: stdlib_system) Represents an unknown path type Represents a regular file Represents a directory Represents a symbolic link

version: experimental

Checks if a path exists in the filesystem. (Specification: stdlib_system)

Summary

Function to check whether the path exists in the fileystem at all. If the path does exist, returns the type of the path.

Description

This function makes a system call (syscall) to retrieve metadata for the specified path and determines its type. It can distinguish between the following path types:

  • Regular File

  • Directory

  • Symbolic Link

It does not follow symbolic links.

It returns a constant representing the detected path type, or type_unknown if the type cannot be determined. Any encountered errors are handled using state_type.

fs_type_directoryinteger, parameter, Default = 2

Integer constants representing the most common path types. (Specification: stdlib_system) Represents an unknown path type Represents a regular file Represents a directory Represents a symbolic link

version: experimental

Checks if a path exists in the filesystem. (Specification: stdlib_system)

Summary

Function to check whether the path exists in the fileystem at all. If the path does exist, returns the type of the path.

Description

This function makes a system call (syscall) to retrieve metadata for the specified path and determines its type. It can distinguish between the following path types:

  • Regular File

  • Directory

  • Symbolic Link

It does not follow symbolic links.

It returns a constant representing the detected path type, or type_unknown if the type cannot be determined. Any encountered errors are handled using state_type.

fs_type_symlinkinteger, parameter, Default = 3

Integer constants representing the most common path types. (Specification: stdlib_system) Represents an unknown path type Represents a regular file Represents a directory Represents a symbolic link

version: experimental

Checks if a path exists in the filesystem. (Specification: stdlib_system)

Summary

Function to check whether the path exists in the fileystem at all. If the path does exist, returns the type of the path.

Description

This function makes a system call (syscall) to retrieve metadata for the specified path and determines its type. It can distinguish between the following path types:

  • Regular File

  • Directory

  • Symbolic Link

It does not follow symbolic links.

It returns a constant representing the detected path type, or type_unknown if the type cannot be determined. Any encountered errors are handled using state_type.

process_IDinteger, parameter, Default = c_int64_t

Types

process_type (type)#

process_type (type)

Process type holding process information and the connected stdout, stderr, stdin units

Check if process is still running

Attributes:
idinteger(kind=process_ID), Default = FORKED_PROCESS

Process ID (if external); 0 if run by the program process

completedlogical, Default = .false.

Process is completed

start_timeinteger(kind=TICKS), Default = 0
stdin_filecharacter(len=:), allocatable

Standard input

stdincharacter(len=:), allocatable
stdout_filecharacter(len=:), allocatable

Standard output

stdoutcharacter(len=:), allocatable
exit_codeinteger, Default = 0

Error output

stderr_filecharacter(len=:), allocatable
stderrcharacter(len=:), allocatable
oncompleteprocedure(process_callback), nopass, pointer, Default = null()

Callback function

payloadclass(*), pointer, Default = null()

Optional payload for the callback function

last_updateinteger(kind=TICKS), Default = 0

Store time at the last update

Procedures:

  • is_running => process_is_running

  • is_completed => process_is_completed

  • elapsed => process_lifetime

  • update => update_process_state

  • kill => process_kill

  • pid => process_get_ID

Interfaces

runasync (interface)#

runasync (interface)

Executes an external process asynchronously. (Specification: stdlib_system)

Procedures:
module function run_async_cmd(cmd, stdin, want_stdout, want_stderr, callback, payload) -> process#
Arguments:
cmdcharacter(len=*), intent(in)

The command line string to execute.

stdincharacter(len=*), intent(in), optional

Optional input sent to the process via standard input (stdin).

want_stdoutlogical, intent(in), optional

Whether to collect standard output.

want_stderrlogical, intent(in), optional

Whether to collect standard error output.

callbackprocedure(process_callback), optional

Optional callback function to be called on process completion

payloadclass(*), target, intent(inout), optional

Optional payload to pass to the callback on completion

Returns:
processtype(process_type)

The output process handler.

module function run_async_args(args, stdin, want_stdout, want_stderr, callback, payload) -> process#
Arguments:
argscharacter(len=*), intent(in), dimension(:)

List of arguments for the process to execute.

stdincharacter(len=*), intent(in), optional

Optional input sent to the process via standard input (stdin).

want_stdoutlogical, intent(in), optional

Whether to collect standard output.

want_stderrlogical, intent(in), optional

Whether to collect standard error output.

callbackprocedure(process_callback), optional

Optional callback function to be called on process completion

payloadclass(*), target, intent(inout), optional

Optional payload to pass to the callback on completion

Returns:
processtype(process_type)

The output process handler.

Summary

Provides methods for executing external processes asynchronously, using either a single command string or an argument list, with options for output collection and standard input.

Description

This interface allows the user to spawn external processes asynchronously (non-blocking). Processes can be executed via a single command string or a list of arguments, with options to collect standard output and error streams, or to provide a standard input stream via a character string. Additionally, a callback function can be provided, which will be called upon process completion. A user-defined payload can be attached and passed to the callback for handling process-specific data.

Notes

The implementation depends on system-level process management capabilities.

run (interface)#

run (interface)

Executes an external process synchronously. (Specification: stdlib_system)

Procedures:
module function run_sync_cmd(cmd, stdin, want_stdout, want_stderr, callback, payload) -> process#
Arguments:
cmdcharacter(len=*), intent(in)

The command line string to execute.

stdincharacter(len=*), intent(in), optional

Optional input sent to the process via standard input (stdin).

want_stdoutlogical, intent(in), optional

Whether to collect standard output.

want_stderrlogical, intent(in), optional

Whether to collect standard error output.

callbackprocedure(process_callback), optional

Optional callback function to be called on process completion

payloadclass(*), target, intent(inout), optional

Optional payload to pass to the callback on completion

Returns:
processtype(process_type)

The output process handler.

module function run_sync_args(args, stdin, want_stdout, want_stderr, callback, payload) -> process#
Arguments:
argscharacter(len=*), intent(in), dimension(:)

List of arguments for the process to execute.

stdincharacter(len=*), intent(in), optional

Optional input sent to the process via standard input (stdin).

want_stdoutlogical, intent(in), optional

Whether to collect standard output.

want_stderrlogical, intent(in), optional

Whether to collect standard error output.

callbackprocedure(process_callback), optional

Optional callback function to be called on process completion

payloadclass(*), target, intent(inout), optional

Optional payload to pass to the callback on completion

Returns:
processtype(process_type)

The output process handler.

Summary

Provides methods for executing external processes synchronously, using either a single command string or an argument list, with options for output collection and standard input.

Description

This interface allows the user to spawn external processes synchronously (blocking), via either a single command string or a list of arguments. It also includes options to collect standard output and error streams, or to provide a standard input stream via a character string. Additionally, it supports an optional callback function that is invoked upon process completion, allowing users to process results dynamically. A user-defined payload can also be provided, which is passed to the callback function to facilitate contextual processing.

Notes

The implementation depends on system-level process management capabilities.

is_running (interface)#

is_running (interface)

Checks if an external process is still running. (Specification: stdlib_system)

Procedures:
module function process_is_running(process) -> is_running#
Arguments:
processclass(process_type), intent(inout)

The process object to check.

Returns:
is_runninglogical

Summary

Provides a method to determine if an external process is still actively running.

Description

This interface checks the status of an external process to determine whether it is still actively running. It is particularly useful for monitoring asynchronous processes created using the run interface. The internal state of the process_type object is updated after the call to reflect the current process status.

Notes

The implementation relies on system-level process management capabilities.

Logical result: .true. if the process is still running, .false. otherwise.

is_completed (interface)#

is_completed (interface)

Checks if an external process has completed execution. (Specification: stdlib_system)

Procedures:
module function process_is_completed(process) -> is_completed#
Arguments:
processclass(process_type), intent(inout)

The process object to check.

Returns:
is_completedlogical

Summary

Provides a method to determine if an external process has finished execution.

Description

This interface checks the status of an external process to determine whether it has finished execution. It is particularly useful for monitoring asynchronous processes created using the run interface. The internal state of the process_type object is updated after the call to reflect the current process status.

Notes

The implementation relies on system-level process management capabilities.

Logical result: .true. if the process has completed, .false. otherwise.

elapsed (interface)#

elapsed (interface)

Returns the lifetime of a process, in seconds. (Specification: stdlib_system)

Procedures:
module function process_lifetime(process) -> delta_t#
Arguments:
processclass(process_type), intent(in)

The process object for which to calculate elapsed time.

Returns:
delta_treal(kind=RTICKS)

The elapsed time in seconds since the process started.

Summary

Provides the total elapsed time (in seconds) since the creation of the specified process.

Description

This interface returns the total elapsed time (in seconds) for a given process since it was started. If the process is still running, the value returned reflects the time from the creation of the process until the call to this function. Otherwise, the total process duration until completion is returned.

wait (interface)#

wait (interface)

Waits for a running process to complete. (Specification: stdlib_system)

Procedures:
module subroutine wait_for_completion(process, max_wait_time)#
Arguments:
processclass(process_type), intent(inout)

The process object to monitor.

max_wait_timereal, intent(in), optional

Optional maximum wait time in seconds. If not provided, waits indefinitely.

Summary

Provides a method to block the execution and wait until the specified process finishes. Supports an optional maximum wait time, after which the function returns regardless of process completion.

Description

This interface allows waiting for a process to complete. If the process is running asynchronously, this subroutine will block further execution until the process finishes. Optionally, a maximum wait time can be specified; if the process doesn’t complete within this time, the subroutine returns without further waiting.

Notes

The process state is accordingly updated on return from this call.

update (interface)#

update (interface)

Updates the internal state of a process variable. (Specification: stdlib_system)

Procedures:
module subroutine update_process_state(process)#
Arguments:
processclass(process_type), intent(inout)

The process object whose state needs to be updated.

Summary

Provides a method to query the system and update the internal state of the specified process variable.

Description

This subroutine queries the system to retrieve and update information about the state of the process. Once the process is completed, and if standard output or standard error were requested, their respective data is loaded into the process%stdout and process%stderr variables. This routine is useful for keeping track of the latest state and output of a process, particularly for asynchronous processes.

Notes

This subroutine should be called periodically for asynchronous processes to check their completion and retrieve the output.

kill (interface)#

kill (interface)

Terminates a running process. (Specification: stdlib_system)

Procedures:
module subroutine process_kill(process, success)#
Arguments:
processclass(process_type), intent(inout)

The process object to be terminated.

successlogical, intent(out)

Boolean flag indicating whether the termination was successful.

Summary

Provides a method to kill or terminate a running process. Returns a boolean flag indicating whether the termination was successful.

Description

This interface allows for the termination of an external process that is still running. If the process is successfully killed, the success output flag is set to .true., otherwise .false.. This function is useful for controlling and managing processes that are no longer needed or for forcefully stopping an unresponsive process.

Notes

This operation may be system-dependent and could fail if the underlying user does not have the necessary rights to kill a process.

sleep (interface)#

module subroutine sleep(millisec)

Pauses execution for a specified time in milliseconds. (Specification: stdlib_system)

Arguments:
millisecinteger, intent(in)

The number of milliseconds to pause execution for.

Summary

Pauses code execution for a specified number of milliseconds. This routine is a cross-platform wrapper around platform-specific sleep functions, providing consistent behavior on different operating systems.

Description

This interface allows the user to pause the execution of a program for a specified duration, expressed in milliseconds. It provides a cross-platform wrapper around native sleep functions, ensuring that the program will sleep for the requested amount of time on different systems (e.g., using Sleep on Windows or nanosleep on Unix-like systems).

Notes

The precision of the sleep may vary depending on the system and platform.

is_windows (interface)#

module function is_windows -> is_windows

Returns a logical flag indicating if the system is Windows. (Specification: stdlib_system)

Returns:
is_windowslogical

Summary

A fast, compile-time check to determine if the system is running Windows, based on the _WIN32 macro.

Description

This interface provides a function to check if the current system is Windows. The check is performed by wrapping a C function that tests if the _WIN32 macro is defined. This check is fast and occurs at compile-time, making it a more efficient alternative to platform-specific runtime checks.

The is_windows function is particularly useful for conditional compilation or system-specific code paths that are dependent on whether the code is running on Windows.

Notes

This function relies on the _WIN32 macro, which is defined in C compilers when targeting Windows.

join_path (interface)#

join_path (interface)
Procedures:
module function join2_char_char(p1, p2) -> path#
Arguments:
p1character(len=*), intent(in)
p2character(len=*), intent(in)
Returns:
pathcharacter(len=:), allocatable
module function join2_char_string(p1, p2) -> path#
Arguments:
p1character(len=*), intent(in)
p2type(string_type), intent(in)
Returns:
pathcharacter(len=:), allocatable
module function join2_string_char(p1, p2) -> path#
Arguments:
p1type(string_type), intent(in)
p2character(len=*), intent(in)
Returns:
pathtype(string_type)
module function join2_string_string(p1, p2) -> path#
Arguments:
p1type(string_type), intent(in)
p2type(string_type), intent(in)
Returns:
pathtype(string_type)
module function joinarr_char(p) -> path#
Arguments:
pcharacter(len=*), intent(in), dimension(:)
Returns:
pathcharacter(len=:), allocatable
module function joinarr_string(p) -> path#
Arguments:
ptype(string_type), intent(in), dimension(:)
Returns:
pathtype(string_type)

Summary

join the paths provided according to the OS-specific path-separator (Specification: stdlib_system)

operator(/) (interface)#

operator(/) (interface)
Procedures:
module function join_op_char_char(p1, p2) -> path#
Arguments:
p1character(len=*), intent(in)
p2character(len=*), intent(in)
Returns:
pathcharacter(len=:), allocatable
module function join_op_char_string(p1, p2) -> path#
Arguments:
p1character(len=*), intent(in)
p2type(string_type), intent(in)
Returns:
pathcharacter(len=:), allocatable
module function join_op_string_char(p1, p2) -> path#
Arguments:
p1type(string_type), intent(in)
p2character(len=*), intent(in)
Returns:
pathtype(string_type)
module function join_op_string_string(p1, p2) -> path#
Arguments:
p1type(string_type), intent(in)
p2type(string_type), intent(in)
Returns:
pathtype(string_type)

Summary

A binary operator to join the paths provided according to the OS-specific path-separator (Specification: stdlib_system)

split_path (interface)#

split_path (interface)
Procedures:
module subroutine split_path_char(p, head, tail)#
Arguments:
pcharacter(len=*), intent(in)
headcharacter(len=:), allocatable, intent(out)
tailcharacter(len=:), allocatable, intent(out)
module subroutine split_path_string(p, head, tail)#
Arguments:
ptype(string_type), intent(in)
headtype(string_type), intent(out)
tailtype(string_type), intent(out)

Summary

splits the path immediately following the final path-separator separating into typically a directory and a file name. (Specification: stdlib_system)

Description

If the path is empty head`=’.’ and tail=’’ If the path only consists of separators, `head is set to the separator and tail is empty If the path is a root directory, head is set to that directory and tail is empty head ends with a path-separator iff the path appears to be a root directory or a child of the root directory

base_name (interface)#

base_name (interface)
Procedures:
module function base_name_char(p) -> base#
Arguments:
pcharacter(len=*), intent(in)
Returns:
basecharacter(len=:), allocatable
module function base_name_string(p) -> base#
Arguments:
ptype(string_type), intent(in)
Returns:
basetype(string_type)

Summary

returns the base name (last component) of the provided path (Specification: stdlib_system)

Description

The value returned is the tail of the interface split_path

dir_name (interface)#

dir_name (interface)
Procedures:
module function dir_name_char(p) -> dir#
Arguments:
pcharacter(len=*), intent(in)
Returns:
dircharacter(len=:), allocatable
module function dir_name_string(p) -> dir#
Arguments:
ptype(string_type), intent(in)
Returns:
dirtype(string_type)

Summary

returns everything but the last component of the provided path (Specification: stdlib_system)

Description

The value returned is the head of the interface split_path

Procedures

get_runtime_os (function)#

function get_runtime_os -> os

The function identifies the OS by inspecting environment variables and filesystem attributes.

Returns:
osinteger

Returns:

  • OS_UNKNOWN: If the OS cannot be determined.

  • OS_LINUX, OS_MACOS, OS_WINDOWS, OS_CYGWIN, OS_SOLARIS, OS_FREEBSD, or OS_OPENBSD.

Note: This function performs a detailed runtime inspection, so it has non-negligible overhead.

OS_TYPE (function)#

function OS_TYPE -> os

Retrieves the cached OS type for minimal runtime overhead. This function uses a static cache to avoid recalculating the OS type after the first call. It is recommended for performance-sensitive use cases where the OS type is checked multiple times.

Returns:
osinteger

OS_NAME (function)#

pure function OS_NAME(os) -> OS_NAME

Return string describing the OS type flag

Arguments:
osinteger, intent(in)
Returns:
OS_NAMEcharacter(len=:), allocatable

is_directory (function)#

function is_directory(path) -> is_directory
Arguments:
pathcharacter(len=*), intent(in)

Input path to evaluate

Returns:
is_directorylogical

null_device (function)#

function null_device -> path

Returns the file path of the null device for the current operating system.

Version: Helper function.

Returns:
pathcharacter(len=:), allocatable

File path of the null device

FS_ERROR_CODE (function)#

pure function FS_ERROR_CODE(code, a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, a11, a12, a13, a14, a15, a16, a17, a18, a19) -> state
Arguments:
codeinteger, intent(in)

Platform specific error code

a1class(*), dimension(..), intent(in), optional

Optional rank-agnostic arguments

a2class(*), dimension(..), intent(in), optional

Optional rank-agnostic arguments

a3class(*), dimension(..), intent(in), optional

Optional rank-agnostic arguments

a4class(*), dimension(..), intent(in), optional

Optional rank-agnostic arguments

a5class(*), dimension(..), intent(in), optional

Optional rank-agnostic arguments

a6class(*), dimension(..), intent(in), optional

Optional rank-agnostic arguments

a7class(*), dimension(..), intent(in), optional

Optional rank-agnostic arguments

a8class(*), dimension(..), intent(in), optional

Optional rank-agnostic arguments

a9class(*), dimension(..), intent(in), optional

Optional rank-agnostic arguments

a10class(*), dimension(..), intent(in), optional

Optional rank-agnostic arguments

a11class(*), dimension(..), intent(in), optional

Optional rank-agnostic arguments

a12class(*), dimension(..), intent(in), optional

Optional rank-agnostic arguments

a13class(*), dimension(..), intent(in), optional

Optional rank-agnostic arguments

a14class(*), dimension(..), intent(in), optional

Optional rank-agnostic arguments

a15class(*), dimension(..), intent(in), optional

Optional rank-agnostic arguments

a16class(*), dimension(..), intent(in), optional

Optional rank-agnostic arguments

a17class(*), dimension(..), intent(in), optional

Optional rank-agnostic arguments

a18class(*), dimension(..), intent(in), optional

Optional rank-agnostic arguments

a19class(*), dimension(..), intent(in), optional

Optional rank-agnostic arguments

Returns:
statetype(state_type)

FS_ERROR (function)#

pure function FS_ERROR(a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, a11, a12, a13, a14, a15, a16, a17, a18, a19, a20) -> state
Arguments:
a1class(*), dimension(..), intent(in), optional

Optional rank-agnostic arguments

a2class(*), dimension(..), intent(in), optional

Optional rank-agnostic arguments

a3class(*), dimension(..), intent(in), optional

Optional rank-agnostic arguments

a4class(*), dimension(..), intent(in), optional

Optional rank-agnostic arguments

a5class(*), dimension(..), intent(in), optional

Optional rank-agnostic arguments

a6class(*), dimension(..), intent(in), optional

Optional rank-agnostic arguments

a7class(*), dimension(..), intent(in), optional

Optional rank-agnostic arguments

a8class(*), dimension(..), intent(in), optional

Optional rank-agnostic arguments

a9class(*), dimension(..), intent(in), optional

Optional rank-agnostic arguments

a10class(*), dimension(..), intent(in), optional

Optional rank-agnostic arguments

a11class(*), dimension(..), intent(in), optional

Optional rank-agnostic arguments

a12class(*), dimension(..), intent(in), optional

Optional rank-agnostic arguments

a13class(*), dimension(..), intent(in), optional

Optional rank-agnostic arguments

a14class(*), dimension(..), intent(in), optional

Optional rank-agnostic arguments

a15class(*), dimension(..), intent(in), optional

Optional rank-agnostic arguments

a16class(*), dimension(..), intent(in), optional

Optional rank-agnostic arguments

a17class(*), dimension(..), intent(in), optional

Optional rank-agnostic arguments

a18class(*), dimension(..), intent(in), optional

Optional rank-agnostic arguments

a19class(*), dimension(..), intent(in), optional

Optional rank-agnostic arguments

a20class(*), dimension(..), intent(in), optional

Optional rank-agnostic arguments

Returns:
statetype(state_type)

exists (function)#

function exists(path, err) -> fs_type
Arguments:
pathcharacter(len=*), intent(in)
errtype(state_type), intent(out), optional
Returns:
fs_typeinteger

is_file (function)#

function is_file(path) -> is_file
Arguments:
pathcharacter(len=*), intent(in)
Returns:
is_filelogical

path_sep (function)#

function path_sep -> path_sep
Returns:
path_sepcharacter(len=1)

make_directory (subroutine)#

subroutine make_directory(path, err)
Arguments:
pathcharacter(len=*), intent(in)
errtype(state_type), intent(out), optional

make_directory_all (subroutine)#

subroutine make_directory_all(path, err)
Arguments:
pathcharacter(len=*), intent(in)
errtype(state_type), intent(out), optional

remove_directory (subroutine)#

subroutine remove_directory(path, err)
Arguments:
pathcharacter(len=*), intent(in)
errtype(state_type), intent(out), optional

get_cwd (subroutine)#

subroutine get_cwd(cwd, err)
Arguments:
cwdcharacter(len=:), allocatable, intent(out)
errtype(state_type), intent(out), optional

set_cwd (subroutine)#

subroutine set_cwd(path, err)
Arguments:
pathcharacter(len=*), intent(in)
errtype(state_type), intent(out), optional

set_environment_variable (subroutine)#

subroutine set_environment_variable(name, value, overwrite, err)

Sets an environment variable for the calling process.

Arguments:
namecharacter(len=*), intent(in)

Name of the variable. Must not be empty or contain ‘=’.

valuecharacter(len=*), intent(in)

Value to give it.

overwritelogical, intent(in), optional

Replace the variable if it already exists. Default .true.. Ignored on Windows, where the underlying call always replaces.

errtype(state_type), intent(out), optional

Error handler

delete_environment_variable (subroutine)#

subroutine delete_environment_variable(name, err)

Removes an environment variable from the calling process.

Arguments:
namecharacter(len=*), intent(in)

Name of the variable. Must not be empty or contain ‘=’.

errtype(state_type), intent(out), optional

Error handler

delete_file (subroutine)#

subroutine delete_file(path, err)

Delete a file at the given path.

Arguments:
pathcharacter(len=*), intent(in)
errtype(state_type), intent(out), optional

See also the specification page: stdlib_system.

stdlib_load_library (module)#

Cross-platform run-time loading of shared libraries (.so / .dll / .dylib), in the spirit of numpy.ctypeslib.load_library. (Specification: stdlib_load_library)

This file is standard Fortran 2008 and needs no preprocessing: the OS-specific calls (dlopen / LoadLibraryExW, …) live in stdlib_load_library_c.c, which must be compiled and linked with it. Platform naming conventions, on the other hand, are resolved in Fortran through stdlib_system.

Example

type(shared_library_type) :: lib
procedure(my_iface), pointer :: f

lib = load_library("kernels", path="./plugins")   ! libkernels.so / kernels.dll / ...
call c_f_procpointer(lib%symbol("my_func"), f)
call f(...)
call lib%close()

Error handling follows the stdlib convention: when err is present the error is returned through it, otherwise the program stops with an error message.

Caveats:

  • Copying a shared_library_type (intrinsic assignment) copies the OS handle. Closing one copy invalidates procedure pointers obtained from any copy. There is deliberately no finalizer: unloading must be explicit.

  • Exported symbols should use bind(C, name=”…”) so their names do not depend on the compiler that built the library.

  • global (RTLD_GLOBAL) has no meaning on Windows and is ignored there.

Types

shared_library_type (type)#

shared_library_type (type)

Handle on a loaded shared library. (Specification: stdlib_load_library)

Procedures:

Procedures

load_library (function)#

function load_library(name, path, global, err) -> lib

Load a shared library and return a handle on it.

name may be a bare name (“kernels”), a file name (“libkernels.so.2”) or a path (“./plugins/kernels.dll”). A name without extension is decorated with the platform prefix/suffix. If path is given, the library is searched only in that directory; otherwise the OS search rules apply (LD_LIBRARY_PATH, rpath, PATH, …).

Arguments:
namecharacter(len=*), intent(in)

Library name, file name or path

pathcharacter(len=*), intent(in), optional

Optional directory to search in, instead of the OS search rules

globallogical, intent(in), optional

Optional flag to make the library symbols available to libraries loaded afterwards (RTLD_GLOBAL). Ignored on Windows

errtype(state_type), intent(out), optional

Optional state return flag. On error, if not requested, the code stops

Returns:
libtype(shared_library_type)

Handle on the loaded library

library_filename (function)#

function library_filename(name) -> fname

Platform-decorated file name of a library, e.g. “fft” -> “libfft.so” / “fft.dll”. (Specification: stdlib_load_library)

Arguments:
namecharacter(len=*), intent(in)

Undecorated library name

Returns:
fnamecharacter(len=:), allocatable

Platform-specific file name

shared_library_suffix (function)#

function shared_library_suffix -> suffix

Shared library file extension on this platform (“.so”, “.dll”, “.dylib”). (Specification: stdlib_load_library)

Returns:
suffixcharacter(len=:), allocatable

Platform-specific extension, dot included

lib_symbol (function)#

function lib_symbol(self, name, err) -> fptr

Address of an exported procedure, to be used with c_f_procpointer.

Arguments:
selfclass(shared_library_type), intent(in)

Handle on a loaded library

namecharacter(len=*), intent(in)

Name of the exported procedure

errtype(state_type), intent(out), optional

Optional state return flag. On error, if not requested, the code stops

Returns:
fptrtype(c_funptr)

Address of the procedure, c_null_funptr on error

lib_data (function)#

function lib_data(self, name, err) -> ptr

Address of an exported variable, to be used with c_f_pointer.

Arguments:
selfclass(shared_library_type), intent(in)

Handle on a loaded library

namecharacter(len=*), intent(in)

Name of the exported variable

errtype(state_type), intent(out), optional

Optional state return flag. On error, if not requested, the code stops

Returns:
ptrtype(c_ptr)

Address of the variable, c_null_ptr on error

lib_has_symbol (function)#

function lib_has_symbol(self, name) -> found

.true. if the library is loaded and exports name.

Arguments:
selfclass(shared_library_type), intent(in)

Handle on a library

namecharacter(len=*), intent(in)

Name of the symbol to look for

Returns:
foundlogical

Whether the symbol is exported

lib_is_loaded (function)#

pure function lib_is_loaded(self) -> loaded

Whether a library is currently loaded into this handle.

Arguments:
selfclass(shared_library_type), intent(in)

Handle on a library

Returns:
loadedlogical

Whether a library is loaded

lib_filename (function)#

pure function lib_filename(self) -> fname

Path of the file that was actually loaded (“” if none).

Arguments:
selfclass(shared_library_type), intent(in)

Handle on a library

Returns:
fnamecharacter(len=:), allocatable

Path of the loaded file

lib_open (subroutine)#

subroutine lib_open(self, name, path, global, err)

Load a shared library into an existing handle.

Arguments:
selfclass(shared_library_type), intent(inout)

Handle on the library. Must not be loaded already

namecharacter(len=*), intent(in)

Library name, file name or path

pathcharacter(len=*), intent(in), optional

Optional directory to search in, instead of the OS search rules

globallogical, intent(in), optional

Optional RTLD_GLOBAL flag. Ignored on Windows

errtype(state_type), intent(out), optional

Optional state return flag. On error, if not requested, the code stops

lib_close (subroutine)#

subroutine lib_close(self, err)

Unload the library. Procedure pointers obtained from it become invalid. Closing an unloaded handle is a no-op.

Arguments:
selfclass(shared_library_type), intent(inout)

Handle on the library

errtype(state_type), intent(out), optional

Optional state return flag. On error, if not requested, the code stops

See also the specification page: stdlib_load_library.