Merge branch 'master' into system_is_dir

doc/specs/stdlib_system.md

@@ -410,14 +410,14 @@ None.
 
 Returns one of the `integer` `OS_*` parameters representing the OS type, from the `stdlib_system` module, or `OS_UNKNOWN` if undetermined.
 
----
-
 ### Example
 
 ```fortran
 {!example/system/example_os_type.f90!}
 ```
 
+---
+
 ## `is_directory` - Test if a path is a directory
 
 ### Status
@@ -434,6 +434,7 @@ It is designed to work across multiple platforms. On Windows, paths with both fo
 `result = [[stdlib_io(module):is_directory(function)]] (path)`
 
 ### Class
+
 Function
 
 ### Arguments
@@ -452,3 +453,42 @@ The function returns a `logical` value:
 ```fortran
 {!example/system/example_is_directory.f90!}
 ```
+
+---
+
+## `null_device` - Return the null device file path
+
+### Status
+
+Experimental
+
+### Description
+
+This function returns the file path of the null device, which is a special file used to discard any data written to it. 
+It reads as an empty file. The null device's path varies by operating system:
+- On Windows, the null device is represented as `NUL`.
+- On UNIX-like systems (Linux, macOS), the null device is represented as `/dev/null`.
+
+### Syntax
+
+`path = [[stdlib_system(module):null_device(function)]]()`
+
+### Class
+
+Function
+
+### Arguments
+
+None.
+
+### Return Value
+
+- **Type:** `character(:), allocatable`
+- Returns the null device file path as a character string, appropriate for the operating system.
+
+### Example
+
+```fortran
+{!example/system/example_null_device.f90!}
+```
+

example/system/CMakeLists.txt

@@ -1,5 +1,6 @@
 ADD_EXAMPLE(get_runtime_os)
 ADD_EXAMPLE(is_directory)
+ADD_EXAMPLE(null_device)
 ADD_EXAMPLE(os_type)
 ADD_EXAMPLE(process_1)
 ADD_EXAMPLE(process_2)

src/stdlib_system.F90

@@ -1,5 +1,6 @@
 module stdlib_system
-use, intrinsic :: iso_c_binding, only : c_int, c_long, c_null_ptr, c_int64_t
+use, intrinsic :: iso_c_binding, only : c_int, c_long, c_ptr, c_null_ptr, c_int64_t, c_size_t, &
+    c_f_pointer
 use stdlib_kinds, only: int64, dp, c_bool, c_char
 use stdlib_strings, only: to_c_char
 implicit none
@@ -97,6 +98,23 @@ module stdlib_system
 !! Windows, and various UNIX-like environments. On unsupported operating systems, the function will return `.false.`.
 !!
 public :: is_directory
+
+!! version: experimental
+!!
+!! Returns the file path of the null device, which discards all data written to it.
+!! ([Specification](../page/specs/stdlib_system.html#null_device-return-the-null-device-file-path))
+!!
+!! ### 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`.
+!!
+public :: null_device
 
 ! CPU clock ticks storage
 integer, parameter, private :: TICKS = int64
@@ -654,4 +672,39 @@ end function stdlib_is_directory
 
 end function is_directory
 
+!> Returns the file path of the null device for the current operating system.
+!>
+!> Version: Helper function.
+function null_device() result(path)
+    !> File path of the null device
+    character(:), allocatable :: path
+
+    interface
+
+        ! No-overhead return path to the null device
+        type(c_ptr) function process_null_device(len) bind(C,name='process_null_device')
+            import c_ptr, c_size_t    
+            implicit none
+            integer(c_size_t), intent(out) :: len
+        end function process_null_device    
+
+    end interface
+
+    integer(c_size_t) :: i, len
+    type(c_ptr) :: c_path_ptr
+    character(kind=c_char), pointer :: c_path(:)    
+
+    ! Call the C function to get the null device path and its length
+    c_path_ptr = process_null_device(len)
+    call c_f_pointer(c_path_ptr,c_path,[len])
+
+    ! Allocate the Fortran string with the length returned from C
+    allocate(character(len=len) :: path)
+
+    do concurrent (i=1:len)
+        path(i:i) = c_path(i)
+    end do
+
+end function null_device
+
 end module stdlib_system