Merge branch 'master' into system_is_dir

Author: perazz

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)

example/system/example_null_device.f90

@@ -0,0 +1,20 @@
+! Showcase usage of the null device
+program example_null_device
+    use stdlib_system, only: null_device
+    use iso_fortran_env, only: output_unit
+    implicit none
+    integer :: unit 
+    logical :: screen_output = .false.
+
+    if (screen_output) then 
+       unit = output_unit
+    else
+       ! Write to the null device if no screen output is wanted
+       open(newunit=unit,file=null_device())
+    endif     
+
+    write(unit,*) "Hello, world!" 
+
+    if (.not.screen_output) close(unit) 
+
+end program example_null_device

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

src/stdlib_system_subprocess.F90

@@ -51,13 +51,6 @@ subroutine process_wait(seconds) bind(C,name='process_wait')
             real(c_float), intent(in), value :: seconds
         end subroutine process_wait            
 
-        ! Return path to the null device
-        type(c_ptr) function process_null_device(len) bind(C,name='process_null_device')
-            import c_ptr, c_int    
-            implicit none
-            integer(c_int), intent(out) :: len
-        end function process_null_device
-        
         ! Utility: check if _WIN32 is defined in the C compiler
         logical(c_bool) function process_is_windows() bind(C,name='process_is_windows')
             import c_bool
@@ -604,29 +597,6 @@ function assemble_cmd(args, stdin, stdout, stderr) result(cmd)
 
     end function assemble_cmd            
 
-    !> Returns the file path of the null device for the current operating system.
-    !>
-    !> Version: Helper function.
-    function null_device() 
-        character(:), allocatable :: null_device
-        
-        integer(c_int) :: 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) :: null_device)
-        
-        do concurrent (i=1:len)
-            null_device(i:i) = c_path(i)
-        end do
-        
-    end function null_device
-    
     !> Returns the file path of the null device for the current operating system.
     !>
     !> Version: Helper function.

src/stdlib_system_subprocess.c

@@ -400,7 +400,7 @@ void process_wait(float seconds)
 }
 
 // Returns the cross-platform file path of the null device for the current operating system.
-const char* process_null_device(int* len) 
+const char* process_null_device(size_t* len) 
 {
 #ifdef _WIN32    
         (*len) = strlen("NUL");

test/system/test_os.f90

@@ -1,6 +1,6 @@
 module test_os
     use testdrive, only : new_unittest, unittest_type, error_type, check, skip_test
-    use stdlib_system, only: get_runtime_os, OS_WINDOWS, OS_UNKNOWN, OS_TYPE, is_windows
+    use stdlib_system, only: get_runtime_os, OS_WINDOWS, OS_UNKNOWN, OS_TYPE, is_windows, null_device
 
     implicit none
 
@@ -13,7 +13,8 @@ subroutine collect_suite(testsuite)
 
         testsuite = [ &
             new_unittest('test_get_runtime_os', test_get_runtime_os), &
-            new_unittest('test_is_windows', test_is_windows) &
+            new_unittest('test_is_windows', test_is_windows), &
+            new_unittest('test_null_device', test_null_device) &
         ]
     end subroutine collect_suite
 
@@ -38,6 +39,26 @@ subroutine test_is_windows(error)
 
     end subroutine test_is_windows
 
+    !> Test that the null_device is valid by writing something to it
+    subroutine test_null_device(error)
+        type(error_type), allocatable, intent(out) :: error
+        integer :: unit, ios
+        character(len=512) :: iomsg
+
+        ! Try opening the null device for writing
+        open(newunit=unit, file=null_device(), status='old', action='write', iostat=ios, iomsg=iomsg)        
+        call check(error, ios==0, 'Cannot open null_device unit: '//trim(iomsg))
+        if (allocated(error)) return
+        
+        write(unit, *, iostat=ios, iomsg=iomsg) 'Hello, World!' 
+        call check(error, ios==0, 'Cannot write to null_device unit: '//trim(iomsg))
+        if (allocated(error)) return        
+
+        close(unit, iostat=ios, iomsg=iomsg)
+        call check(error, ios==0, 'Cannot close null_device unit: '//trim(iomsg))
+        if (allocated(error)) return     
+        
+    end subroutine test_null_device
 
 end module test_os