Re: [patch, fortran, docs] Unformatted sequential and special files

[Tobias Burnus <burnus@net-b.de>]

Thomas Koenig wrote:
> +Unformatted sequential files are stored using record markers. Each
> +full record consists of a leading record marker, the data written
> +by the user program, and a trailing record marker.  The record markers
> +are four-byte integers by default, and eight-byte integers if the
> +@option{-fmax-subrecord-length=8} option is in effect. Each record
> +marker contains the number of bytes of data in the record.

I wonder whether one should discourage the use of 
-fmax-subrecord-length=8 more explicitly here - when reading until here 
one might think that there is a 2GB limit for =4.

> +The maximum number of bytes of user data in a record is 2147483639 for
> +a four-byte record marker.

Why this number? I had expected it to be exactly  2 GiB (minus 1 Byte) = 
2**31-1 = 2147483647. Your number is one byte shorter. Why?

Actually, I had also mentioned GiB as those are simpler to remember, e.g.
"The maximal user data per record is 2 gigabytes (2147483647/2147483639 
bytes) for the four-byte record marker.

> If this is exceeded, a record is split into
> +subrecords. Each subrecord also has a leading and a trailing record
> +marker. If the leading record marker contains a negative number, the
> +number of user data bytes in the subrecord equals the absolute value
> +of this number, and another subrecord follows the current one.  If the
> +trailing record marker contains a negative number, then the number of
> +bytes of user data equals the absolute value of that number, and there
> +is a preceding subrecord.
> +
> +The format for unformatted sequential data can be duplicated using
> +unformatted stream, as shown in this example program:

(which assumes records shorter than 2 GiB)

> +
> +@smallexample
> +program main
> +  implicit none
> +  integer :: i

I wonder whether one should make this more explicit by using

use iso_fortran_env, only: int32
integer(int32) :: i

> +Unformatted sequential file access is @emph{not} supported for special
> +files.  If necessary, it can be simulated using unformatted stream,
> +see @ref{Unformatted sequential file format}.
> +
> +I/O to and from block devices are also not supported.
> +
> +@code{BACKSPACE}, @code{REWIND} and @code{ENDFILE} are not supported
> +for special files.

I think I understand what you mean but  "I/O to and from block devices 
are also not supported." sounds as if it also could apply to all I/O, 
including stream I/O.

How about adding "block devices" to the list of special files in the 
intro? You could also mention sockets, which behave similarly. The 
BACKSPACE/REWIND/ENDFILE could be moved directly after the itemize in 
the same paragraph as the POS=.

And instead of "unformatted sequential", you could write "unformatted 
sequential and directed access", which reminds me that we should also 
document that file format for the sake of completeness.

Tobias