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

[Thomas Koenig <tkoenig at netcologne dot de>]

Hello world,

here is a rewrite, which I hope make things more clear.
Unformatted sequential files are now made up of subrecords, where
a logical record may only have one.

Regarding block devices: I don't know anybody who ever used them
from gfortran, so I tried to be as vague as possible.

Any more suggestions?  OK for trunk otherwise?

	Thomas

Index: gfortran.texi
===================================================================
--- gfortran.texi	(Revision 201996)
+++ gfortran.texi	(Arbeitskopie)
@@ -1121,6 +1121,8 @@
 * Internal representation of LOGICAL variables::
 * Thread-safety of the runtime library::
 * Data consistency and durability::
+* Unformatted sequential file format::
+* I/O with special files::
 @end menu
 
 
@@ -1291,7 +1293,109 @@
 releasing @code{fcntl} file locks, if the server supports them, will
 also force cache validation and flushing dirty data and metadata.
 
+@node Unformatted sequential file format
+@section Unformatted sequential file format
+@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 subrecords.
+
+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 reasons only) is in effect.
+
+The maximum number of bytes of user data in a subrecord is 2147483639
+(2 GiB - 9) for a four-byte record marker.  If a logical record
+contains more data, 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
+record,
+
+The format for unformatted sequential data can be duplicated using
+unformatted stream, as shown in the example program for a single
+subrecord only:
+
+@smallexample
+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
+
+@node I/O with special files
+@section I/O with special files
+@cindex special files
+@cindex character devices
+@cindex devices, character
+@cindex block devices
+@cindex devices, block
+@cindex sockets
+@cindex special files, character
+@cindex BACKSPACE
+@cindex REWIND
+@cindex ENDFILE
+@cindex pipes
+@cindex FIFO
+@cindex terminal devices
+@cindex unformatted sequential
+@cindex sequential, unformatted
+@cindex unformatted stream
+@cindex stream, unformatted
+@cindex formatted stream
+@cindex stream, formatted
+@cindex direct access
+
+Special character files such as pipes, FIFOs, sockets or terminal
+devices are supported only for the following types of file access:
+
+@itemize
+
+@item Formatted sequential
+
+@item Formatted stream
+
+@item Unformatted stream
+
+@end itemize
+
+For special character files, the @code{POS=} specifier for stream I/O
+can only be used in @code{INQUIRE} statements.
+
+@code{BACKSPACE}, @code{REWIND} and @code{ENDFILE} are not supported
+for character special files.
+
+Unformatted sequential and direct file access are @emph{not} supported
+for character special files.  If necessary, unformatted sequential
+access can be simulated using unformatted stream, see @ref{Unformatted
+sequential file format}.
+
+Block devices have not been tested.  It is likely that only
+unformatted stream and direct access will work for those.  Some
+restrictions specific to the operating system regarding sizes and
+alignment of data may apply.
+
 @c ---------------------------------------------------------------------
 @c Extensions
 @c ---------------------------------------------------------------------