docs: improve description and error handling of get_terminal_size

Author: zoziha

doc/specs/stdlib_system.md

@@ -533,17 +533,21 @@ The file is removed from the filesystem if the operation is successful. If the o
 {!example/system/example_delete_file.f90!}
 ```
 
-## `get_terminal_size` - Get the size of the terminal window
+## `get_terminal_size` - Get terminal window size in characters
 
 ### Status
 
 Experimental
 
 ### Description
 
-This subroutine returns the size of the terminal window in characters. 
+Queries the terminal window size in characters (columns × lines). 
 
-Note: This routine performs a detailed runtime inspection, so it has non-negligible overhead.
+This routine performs the following checks:
+1. Verifies stdout is connected to a terminal (not redirected);
+2. Queries terminal dimensions via platform-specific APIs.
+
+Typical execution time: <100μs on modern systems.
 
 ### Syntax
 
@@ -555,13 +559,24 @@ Subroutine
 
 ### Arguments
 
-`columns`: Shall be an `intent(out)` argument of type `integer` that will contain the number of columns in the terminal window.
+`columns`: `integer, intent(out)`.
+    Number of columns in the terminal window. Set to `-1` on error.
+
+`lines`: `integer, intent(out)`.
+    Number of lines in the terminal window. Set to `-1` on error.
 
-`lines`: Shall be an `intent(out)` argument of type `integer` that will contain the number of lines in the terminal window.
+`err`: `type(state_type), intent(out), optional`.
+    Error state object. If absent, errors terminate execution.
 
-`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.
+### Error Handling
 
-Note: If the query fails, the values of `columns` and `lines` will be set to `-1`.
+- **Success**: `columns` and `lines` contain valid dimensions.
+- **Failure**:
+  - Both arguments set to `-1`.
+  - If `err` present, `stat` contains error code:
+    - Unix: Contains `errno` (typically `ENOTTY` when redirected);
+    - Windows: Contains `GetLastError()` code.
+  - If `err` absent: Program stops with error message.
 
 ### Example
 

example/system/example_get_terminal_size.f90

@@ -11,6 +11,6 @@ program example_get_terminal_size
     call get_terminal_size(columns, lines, err)
 
     print "(2(a,i0))", "Terminal size is ", columns, 'x', lines
-    print "(a)", repeat("*", columns)
+    if (err%ok()) print "(a)", repeat("*", columns)
 
 end program example_get_terminal_size

src/stdlib_system.F90

@@ -554,7 +554,7 @@ end function process_get_ID
 
 contains
 
-!! Returns the size of the terminal window.
+!! Returns terminal window size in characters.
 !!
 !! ### Returns:
 !! - **columns**: The number of columns in the terminal window.
@@ -575,7 +575,7 @@ end subroutine c_get_terminal_size
 
     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')
+        err0 = state_type('get_terminal_size',STDLIB_FS_ERROR,'Failed to get terminal size,','stat =',stat)
         call err0%handle(err)
     end if