diff mbox

[fortran,docs] Unformatted sequential and special files

Message ID 5225D048.8030902@netcologne.de
State New
Headers show

Commit Message

Thomas Koenig Sept. 3, 2013, 12:04 p.m. UTC 
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

Comments

Janne Blomqvist Sept. 4, 2013, 10:40 a.m. UTC | #1 
On Tue, Sep 3, 2013 at 3:04 PM, Thomas Koenig <tkoenig@netcologne.de> wrote:
> 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.

Looks ok.

> 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?

I'm still not comfortable with the wording. As I've argued before,
special files are special in different ways, and can behave
differently on different systems, so it's difficult to say anything
definitive about their behavior in general. Maybe being more explicit
about what is supported for a limited subset would help. E.g. starting
the section with something like

"For terminal devices, pipes, FIFO's and sockets the following file
modes are supported:
- ...

For other special files and other file modes, the result is undefined."

("undefined" rather than "not supported", as we're not going out of
our way to prevent it if somebody wants to do it either)

- Wrt the POS= specifier with INQUIRE, even it it "works" (as in, does
not generate an error), there is no sensible concept of file position
for a stream file anyway, so perhaps we shouldn't explicitly say it's
supported either.

- Wrt. block devices, perhaps remove that section and cover it just
with the "...implementation defined" sentence above.
Tobias Burnus Nov. 24, 2013, 7:59 p.m. UTC | #2 
Thomas, what's actually the status of this patch? I think it was 
half-complete in September.

Tobias

On September 4, 2013 12:40, Janne Blomqvist wrote:
> On Tue, Sep 3, 2013 at 3:04 PM, Thomas Koenig <tkoenig@netcologne.de> wrote:
>> 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.
> Looks ok.
>
>> 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?
> I'm still not comfortable with the wording. As I've argued before,
> special files are special in different ways, and can behave
> differently on different systems, so it's difficult to say anything
> definitive about their behavior in general. Maybe being more explicit
> about what is supported for a limited subset would help. E.g. starting
> the section with something like
>
> "For terminal devices, pipes, FIFO's and sockets the following file
> modes are supported:
> - ...
>
> For other special files and other file modes, the result is undefined."
>
> ("undefined" rather than "not supported", as we're not going out of
> our way to prevent it if somebody wants to do it either)
>
> - Wrt the POS= specifier with INQUIRE, even it it "works" (as in, does
> not generate an error), there is no sensible concept of file position
> for a stream file anyway, so perhaps we shouldn't explicitly say it's
> supported either.
>
> - Wrt. block devices, perhaps remove that section and cover it just
> with the "...implementation defined" sentence above.
>
>
>
diff mbox

Patch

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