add specs

Author: perazz

doc/specs/stdlib_io.md

@@ -260,3 +260,56 @@ Provides formats for all kinds as defined in the `stdlib_kinds` module.
 ```fortran
 {!example/io/example_fmt_constants.f90!}
 ```
+
+## `getfile` - Read a whole ASCII file into a string variable
+
+### Status
+
+Experimental
+
+### Description
+
+This function reads the entirety of a specified ASCII file and returns its content as a string. The function provides an optional error-handling mechanism via the `state_type` class. If the `err` argument is not provided, exceptions will trigger an `error stop`. The function also supports an optional flag to delete the file after reading.
+
+### Syntax
+
+`call [[stdlib_io(module):getfile(function)]] (fileName [, err] [, delete=.false.])`
+
+### Class
+Function
+
+### Arguments
+
+`fileName`: Shall be a character input containing the path to the ASCII file to read. It is an `intent(in)` argument.
+
+`err` (optional): Shall be a `type(state_type)` variable. It is an `intent(out)` argument used for error handling.
+
+`delete` (optional): Shall be a `logical` flag. If `.true.`, the file is deleted after reading. Default is `.false.`. It is an `intent(in)` argument.
+
+### Return values
+
+The function returns a `string_type` variable containing the full content of the specified file.
+
+Raises `STDLIB_IO_ERROR` if the file is not found, cannot be opened, read, or deleted. 
+Exceptions trigger an `error stop` unless the optional `err` argument is provided.
+
+### Example
+
+```fortran
+program example_getfile
+  use stdlib_io
+  implicit none
+
+  type(string_type) :: fileContent
+  type(state_type) :: err
+
+  ! Read a file into a string
+  fileContent = getfile("example.txt", err=err)
+
+  if (err%error()) then
+    print *, "Error reading file:", err%print()
+  else
+    print *, "File content:", fileContent
+  end if
+end program example_getfile
+```