This is the mail archive of the mailing list for the GCC project.

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

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

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)

+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.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]