added doc and test

Author: wassup05

doc/specs/stdlib_system.md

@@ -284,6 +284,31 @@ This is an `intent(inout)` argument, and on return is updated with the terminate
 {!example/system/example_process_4.f90!}
 ```
 
+## `send_signal`- send (POSIX) signal to a process
+
+### Status
+
+Experimental
+
+### Description
+
+The `send_signal` interface is used to send POSIX signal to a running external process.
+It attempts to send the signal and returns a boolean flag indicating whether the operation was successful.
+It does not do anything on Windows (no-op).
+
+### Syntax
+
+`call ` [[stdlib_subprocess(module):send_signal(subroutine)]] `(process, signal, success)`
+
+### Arguments
+
+`process`: Shall be a `type(process_type)` object representing the external process to be terminated.
+This is an `intent(inout)` argument, and on return is updated with the terminated process state.
+
+`signal`: Shall be a `integer` variable representing the signal number to be sent.
+
+`success`: Shall be a `logical` variable. It is set to `.true.` if the signal was sent successfully, or `.false.` otherwise.
+
 ## `sleep` - Pause execution for a specified time in milliseconds
 
 ### Status

test/system/test_subprocess.f90

@@ -1,6 +1,7 @@
 module test_subprocess
     use testdrive, only : new_unittest, unittest_type, error_type, check, skip_test
-    use stdlib_system, only: process_type, run, runasync, is_running, wait, update, elapsed, is_windows, kill
+    use stdlib_system, only: process_type, run, runasync, is_running, wait, update, elapsed, is_windows, &
+        kill, send_signal
 
     implicit none
 
@@ -15,6 +16,7 @@ subroutine collect_suite(testsuite)
             new_unittest('test_run_synchronous', test_run_synchronous), &
             new_unittest('test_run_asynchronous', test_run_asynchronous), &
             new_unittest('test_process_kill', test_process_kill), &
+            new_unittest('test_process_send_signal', test_process_send_signal), &
             new_unittest('test_process_state', test_process_state) &
         ]
     end subroutine collect_suite
@@ -94,6 +96,44 @@ subroutine test_process_kill(error)
         call check(error, process%completed, "Process should be marked as completed after being killed")
     end subroutine test_process_kill
 
+    subroutine test_process_send_signal(error)
+        type(error_type), allocatable, intent(out) :: error
+        type(process_type) :: process
+        logical :: success
+
+        ! As the function does nothing on windows
+        if (is_windows()) return
+
+        ! Start a long-running process asynchronously
+        process = runasync("ping -c 10 127.0.0.1")
+
+        ! Ensure the process starts running
+        call check(error, .not. process%completed, "Process should not be completed immediately after starting")
+        if (allocated(error)) return
+
+        call check(error, is_running(process), "Process should be running immediately after starting")
+        if (allocated(error)) return
+
+        ! send SIGWINCH(28) to process, this should not cause the process to exit
+        call send_signal(process, 28, success)
+        call check(error, success, "Failed to send signal SIGWINCH to the process")
+        if (allocated(error)) return
+
+        ! Verify the process is still running
+        call check(error, .not. process%completed, "Process should not exit after SIGWINCH signal")
+        if (allocated(error)) return
+
+        ! send SIGKILL to process
+        call send_signal(process, 9, success)
+        call check(error, success, "Failed to send signal SIGKILL to the process")
+        if (allocated(error)) return
+
+        ! Verify the process is no longer running
+        call check(error, .not. process%completed, "Process should be completed after being killed")
+        if (allocated(error)) return
+
+    end subroutine test_process_send_signal
+
     !> Test updating and checking process state
     subroutine test_process_state(error)
         type(error_type), allocatable, intent(out) :: error