From patchwork Sat Aug 12 12:16:19 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Thomas Koenig X-Patchwork-Id: 800909 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (mailfrom) smtp.mailfrom=gcc.gnu.org (client-ip=209.132.180.131; helo=sourceware.org; envelope-from=gcc-patches-return-460272-incoming=patchwork.ozlabs.org@gcc.gnu.org; receiver=) Authentication-Results: ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=gcc.gnu.org header.i=@gcc.gnu.org header.b="fYJ9+kgZ"; dkim-atps=neutral Received: from sourceware.org (server1.sourceware.org [209.132.180.131]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 3xV1873T0lz9t3F for ; Sat, 12 Aug 2017 22:16:54 +1000 (AEST) DomainKey-Signature: a=rsa-sha1; c=nofws; d=gcc.gnu.org; h=list-id :list-unsubscribe:list-archive:list-post:list-help:sender:to :from:subject:message-id:date:mime-version:content-type; q=dns; s=default; b=CE8NGCvOc8VWxxgkiHzwh8xhw/OB8o9FsnwVJy7/ffZtJvJFbE cAV08SFwwn0Tdu5od5T2CabUs9qkwKfrCS3DUOoF0J3vMUZMrC3yXZCtBI3yfFTk WePVwlbZEfAFMUiBjbt7+kmHaslkth+RESr+gqYhNncnU2/mYvAec571A= DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=gcc.gnu.org; h=list-id :list-unsubscribe:list-archive:list-post:list-help:sender:to :from:subject:message-id:date:mime-version:content-type; s= default; bh=MYEp4Kvi0k4Pvx7lGnBJDM+3Mos=; b=fYJ9+kgZG98ICUygXhJu jFr+Np1TkKQBm9biVTkgAEgP28BQt876MWRSSXwdhbcUp2afUvbr4UdnY6QyJvGa cd6WU1be9fn8tFRwFfOColHHTczwB4QjMGhmfztnNpHoeFfPLJDwltU+3Kr+thFW Y3XBln1Jhnq5JDAfEy7LBjc= Received: (qmail 75511 invoked by alias); 12 Aug 2017 12:16:37 -0000 Mailing-List: contact gcc-patches-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Archive: List-Post: List-Help: Sender: gcc-patches-owner@gcc.gnu.org Delivered-To: mailing list gcc-patches@gcc.gnu.org Received: (qmail 71477 invoked by uid 89); 12 Aug 2017 12:16:28 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-15.6 required=5.0 tests=AWL, BAYES_00, GIT_PATCH_1, GIT_PATCH_2, GIT_PATCH_3, KAM_ASCII_DIVIDERS, RCVD_IN_DNSWL_LOW, RP_MATCHES_RCVD, SPF_PASS autolearn=ham version=3.3.2 spammy=durability, H*MI:31a6, unformatted, altough X-Spam-User: qpsmtpd, 2 recipients X-HELO: cc-smtpout2.netcologne.de Received: from cc-smtpout2.netcologne.de (HELO cc-smtpout2.netcologne.de) (89.1.8.212) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Sat, 12 Aug 2017 12:16:26 +0000 Received: from cc-smtpin1.netcologne.de (cc-smtpin1.netcologne.de [89.1.8.201]) by cc-smtpout2.netcologne.de (Postfix) with ESMTP id B109C1265D; Sat, 12 Aug 2017 14:16:20 +0200 (CEST) Received: from localhost (localhost [127.0.0.1]) by cc-smtpin1.netcologne.de (Postfix) with ESMTP id A2AC711DCC; Sat, 12 Aug 2017 14:16:20 +0200 (CEST) Received: from [78.35.129.89] (helo=cc-smtpin1.netcologne.de) by localhost with ESMTP (eXpurgate 4.1.9) (envelope-from ) id 598ef194-029d-7f0000012729-7f00000189be-1 for ; Sat, 12 Aug 2017 14:16:20 +0200 Received: from [192.168.178.20] (xdsl-78-35-129-89.netcologne.de [78.35.129.89]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by cc-smtpin1.netcologne.de (Postfix) with ESMTPSA; Sat, 12 Aug 2017 14:16:19 +0200 (CEST) To: "fortran@gcc.gnu.org" , gcc-patches From: Thomas Koenig Subject: [patch, fortran, docs] Document sequential unformatted file structure Message-ID: Date: Sat, 12 Aug 2017 14:16:19 +0200 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.2.1 MIME-Version: 1.0 Hello world, seems like we never got around to documenting the structure of our unformatted sequential files. Well, here is a patch for that. Regards Thomas 2017-08-12 Thomas Koenig * 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 +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 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 +variable. + +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 +record, + +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: + +@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 + @c --------------------------------------------------------------------- @c Extensions @c ---------------------------------------------------------------------