[fortran,docs] Document sequential unformatted file structure

Message ID adf6b27a-31a6-3d99-d05d-190770a06184@netcologne.de
State New
Headers show

Commit Message

Thomas Koenig Aug. 12, 2017, 12:16 p.m.
Hello world,

seems like we never got around to documenting the structure of
our unformatted sequential files.  Well, here is a patch for that.



2017-08-12  Thomas Koenig  <tkoenig@gcc.gnu.org>

         * gfortran.texi: Document format of unformatted sequential files.


Index: gfortran.texi
--- gfortran.texi	(Revision 250720)
+++ gfortran.texi	(Arbeitskopie)
@@ -1172,6 +1172,7 @@ 
 * Data consistency and durability::
 * Files opened without an explicit ACTION= specifier::
 * File operations on symbolic links::
+* File format of unformatted sequential files::
 @end menu
@@ -1402,8 +1403,66 @@ 
 @end itemize
+@node File format of unformatted sequential files
+@section File format of unformatted sequential files
+@cindex file, unformatted sequential
+@cindex unformatted sequential
+@cindex sequential, unformatted
+@cindex record marker
+@cindex subrecord
+Unformatted sequential files are stored as logical records using
+record markers.  Each logical record consists of one of more
+Each subrecord 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 (which exists for backwards
+compability only) is in effect.
+The representation of the record markers is that of unformatted files
+given with the @option{-fconvert} option, the @xref{CONVERT specifier}
+on the open statement or the @xref{GFORTRAN_CONVERT_UNIT} environment
+The maximum number of bytes of user data in a subrecord is 2147483639
+(2 GiB - 9) for a four-byte record marker.  This limit can be lowered
+with the @option{-fmax-subrecord-length} option, altough this is
+rarely useful. If the lenght of a logical record exceeds this limit,
+the data is distributed among several subrecords.
+The absolute of the number stored in the record markers is the number
+of bytes of user data in the corresponding subrecord.  If the leading
+record marker of a subrecord contains a negative number, another
+subrecord follows the current one.  If the trailing record marker
+contains a negative number, then there is a preceding subrecord.
+In the most simple case, with only one subrecord per logical record,
+both record markers contain the number of bytes of user data in the
+The format for unformatted sequential data can be duplicated using
+unformatted stream, as shown in the example program for an unformatted
+record containing a single subrecord:
+program main
+  use iso_fortran_env, only: int32
+  implicit none
+  integer(int32) :: i 
+  real, dimension(10) :: a, b
+  call random_number(a)
+  open (10,file='test.dat',form='unformatted',access='stream')
+  inquire (iolength=i) a
+  write (10) i, a, i
+  close (10)
+  open (10,file='test.dat',form='unformatted')
+  read (10) b
+  if (all (a == b)) print *,'success!'
+end program main
+@end smallexample
 @c ---------------------------------------------------------------------
 @c Extensions
 @c ---------------------------------------------------------------------