feat(stdlib_system): add optional error argument to get_terminal_size

Author: zoziha

doc/specs/stdlib_system.md

@@ -547,7 +547,7 @@ Note: This routine performs a detailed runtime inspection, so it has non-negligi
 
 ### Syntax
 
-`call [[stdlib_system(module):get_terminal_size(subroutine)]](columns, lines)`
+`call [[stdlib_system(module):get_terminal_size(subroutine)]](columns, lines[, err])`
 
 ### Class
 
@@ -559,6 +559,8 @@ Subroutine
 
 `lines`: Shall be an `intent(out)` argument of type `integer` that will contain the number of lines in the terminal window.
 
+`err`: Shall be an `intent(out)` and `optional` argument of type `type(state_type)` that will contain the error state. If not provided, the program stops execution on error.
+
 Note: If the query fails, the values of `columns` and `lines` will be set to `-1`.
 
 ### Example

example/system/example_get_terminal_size.f90

@@ -1,12 +1,14 @@
 program example_get_terminal_size
 
     use stdlib_system, only: get_terminal_size
+    use stdlib_error, only: state_type
     implicit none
 
     integer :: columns, lines
+    type(state_type) :: err
 
     !> Get terminal size
-    call get_terminal_size(columns, lines)
+    call get_terminal_size(columns, lines, err)
 
     print "(2(a,i0))", "Terminal size is ", columns, 'x', lines
     print "(a)", repeat("*", columns)

src/stdlib_system.F90

@@ -550,21 +550,38 @@ module function process_get_ID(process) result(ID)
         integer(process_ID) :: ID
     end function process_get_ID
 
-    !! Returns the size of the terminal window.
-    !!
-    !! ### Returns:
-    !! - **columns**: The number of columns in the terminal window.
-    !! - **lines**: The number of lines in the terminal window.
-    !!
-    !! Note: This function performs a detailed runtime inspection, so it has non-negligible overhead.
-    subroutine get_terminal_size(columns, lines) bind(C)
-        integer, intent(out) :: columns, lines
-    end subroutine get_terminal_size
-
 end interface
 
 contains
 
+!! Returns the size of the terminal window.
+!!
+!! ### Returns:
+!! - **columns**: The number of columns in the terminal window.
+!! - **lines**: The number of lines in the terminal window.
+!! - **err**: An optional error object.
+!!
+!! Note: This function performs a detailed runtime inspection, so it has non-negligible overhead.
+subroutine get_terminal_size(columns, lines, err)
+    integer, intent(out) :: columns, lines
+    type(state_type), intent(out), optional :: err
+    type(state_type) :: err0
+    integer :: stat
+    interface
+        subroutine c_get_terminal_size(columns, lines, stat) bind(C, name="get_terminal_size")
+            integer, intent(out) :: columns, lines, stat
+        end subroutine c_get_terminal_size
+    end interface
+
+    call c_get_terminal_size(columns, lines, stat)
+    if (stat /= 0) then
+        err0 = state_type('get_terminal_size',STDLIB_FS_ERROR,'Failed to get terminal size')
+        call err0%handle(err)
+    end if
+
+end subroutine get_terminal_size
+
+
 integer function get_runtime_os() result(os)
     !! The function identifies the OS by inspecting environment variables and filesystem attributes.
     !!

src/stdlib_system_get_terminal_size.c

@@ -5,27 +5,47 @@
 #else
 #include <sys/ioctl.h>
 #include <unistd.h>
+#include <errno.h>
 #endif
 
-void get_terminal_size(int *columns, int *lines)
+void get_terminal_size(int *columns, int *lines, int *stat)
 {
+    /* Initialize outputs to error state */
     *columns = -1;
     *lines = -1;
+    *stat = 0;
 
 #ifdef _WIN32
+    /* Windows implementation using Console API */
     HANDLE hConsole = GetStdHandle(STD_OUTPUT_HANDLE);
+    if (hConsole == INVALID_HANDLE_VALUE)
+    {
+        *stat = (int)GetLastError(); // Return Windows system error code
+        return;
+    }
+
     CONSOLE_SCREEN_BUFFER_INFO csbi;
-    if (GetConsoleScreenBufferInfo(hConsole, &csbi))
+    if (!GetConsoleScreenBufferInfo(hConsole, &csbi))
     {
-        *columns = csbi.srWindow.Right - csbi.srWindow.Left + 1;
-        *lines = csbi.srWindow.Bottom - csbi.srWindow.Top + 1;
+        *stat = (int)GetLastError(); // Failed to get console info
+        return;
     }
+
+    /* Calculate visible window dimensions */
+    *columns = csbi.srWindow.Right - csbi.srWindow.Left + 1;
+    *lines = csbi.srWindow.Bottom - csbi.srWindow.Top + 1;
+
 #else
+    /* Unix implementation using termios ioctl */
     struct winsize w;
-    if (ioctl(STDOUT_FILENO, TIOCGWINSZ, &w) == 0)
+    if (ioctl(STDOUT_FILENO, TIOCGWINSZ, &w) == -1)
     {
-        *columns = w.ws_col;
-        *lines = w.ws_row;
+        *stat = errno; // Return POSIX system error code
+        return;
     }
+
+    /* Directly use reported terminal dimensions */
+    *columns = w.ws_col;
+    *lines = w.ws_row;
 #endif
 }