gcc/ada/libgnat/a-textio.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT RUN-TIME COMPONENTS                         --
   4 --                                                                          --
   5 --                          A D A . T E X T _ I O                           --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --          Copyright (C) 1992-2023, Free Software Foundation, Inc.         --
  10 --                                                                          --
  11 -- This specification is derived from the Ada Reference Manual for use with --
  12 -- GNAT. The copyright notice above, and the license provisions that follow --
  13 -- apply solely to the  contents of the part following the private keyword. --
  14 --                                                                          --
  15 -- GNAT is free software;  you can  redistribute it  and/or modify it under --
  16 -- terms of the  GNU General Public License as published  by the Free Soft- --
  17 -- ware  Foundation;  either version 3,  or (at your option) any later ver- --
  18 -- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
  19 -- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
  20 -- or FITNESS FOR A PARTICULAR PURPOSE.                                     --
  21 --                                                                          --
  22 -- As a special exception under Section 7 of GPL version 3, you are granted --
  23 -- additional permissions described in the GCC Runtime Library Exception,   --
  24 -- version 3.1, as published by the Free Software Foundation.               --
  25 --                                                                          --
  26 -- You should have received a copy of the GNU General Public License and    --
  27 -- a copy of the GCC Runtime Library Exception along with this program;     --
  28 -- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    --
  29 -- <http://www.gnu.org/licenses/>.                                          --
  30 --                                                                          --
  31 -- GNAT was originally developed  by the GNAT team at  New York University. --
  32 -- Extensive contributions were provided by Ada Core Technologies Inc.      --
  33 --                                                                          --
  34 ------------------------------------------------------------------------------
  35
  36 --  Preconditions in this unit are meant for analysis only, not for run-time
  37 --  checking, so that the expected exceptions are raised. This is enforced by
  38 --  setting the corresponding assertion policy to Ignore. These preconditions
  39 --  are partial. They protect fully against Status_Error and Mode_Error,
  40 --  partially against Layout_Error (see SPARK User's Guide for details), and
  41 --  not against other types of errors.
  42
  43 pragma Assertion_Policy (Pre => Ignore);
  44
  45 --  Note: the generic subpackages of Text_IO (Integer_IO, Float_IO, Fixed_IO,
  46 --  Modular_IO, Decimal_IO and Enumeration_IO) appear as private children in
  47 --  GNAT. These children are with'ed automatically if they are referenced, so
  48 --  this rearrangement is invisible to user programs, but has the advantage
  49 --  that only the needed parts of Text_IO are processed and loaded.
  50
  51 with Ada.IO_Exceptions;
  52 with Ada.Streams;
  53
  54 with System;
  55 with System.File_Control_Block;
  56 with System.WCh_Con;
  57
  58 package Ada.Text_IO with
  59   SPARK_Mode,
  60   Abstract_State    => File_System,
  61   Initializes       => File_System,
  62   Initial_Condition => Line_Length = 0 and Page_Length = 0,
  63   Always_Terminates
  64 is
  65    pragma Elaborate_Body;
  66
  67    type File_Type is limited private with
  68      Default_Initial_Condition => (not Is_Open (File_Type));
  69    type File_Mode is (In_File, Out_File, Append_File);
  70
  71    --  The following representation clause allows the use of unchecked
  72    --  conversion for rapid translation between the File_Mode type
  73    --  used in this package and System.File_IO.
  74
  75    for File_Mode use
  76      (In_File     => 0,  -- System.File_IO.File_Mode'Pos (In_File)
  77       Out_File    => 2,  -- System.File_IO.File_Mode'Pos (Out_File)
  78       Append_File => 3); -- System.File_IO.File_Mode'Pos (Append_File)
  79
  80    type Count is range 0 .. Natural'Last;
  81    --  The value of Count'Last must be large enough so that the assumption that
  82    --  the Line, Column and Page counts can never exceed this value is valid.
  83
  84    subtype Positive_Count is Count range 1 .. Count'Last;
  85
  86    Unbounded : constant Count := 0;
  87    --  Line and page length
  88
  89    subtype Field is Integer range 0 .. 255;
  90
  91    subtype Number_Base is Integer range 2 .. 16;
  92
  93    type Type_Set is (Lower_Case, Upper_Case);
  94
  95    ---------------------
  96    -- File Management --
  97    ---------------------
  98
  99    procedure Create
 100      (File : in out File_Type;
 101       Mode : File_Mode := Out_File;
 102       Name : String := "";
 103       Form : String := "")
 104    with
 105      Pre               => not Is_Open (File),
 106      Post              =>
 107        Is_Open (File)
 108        and then Ada.Text_IO.Mode (File) = Mode
 109        and then (if Mode /= In_File
 110                    then (Line_Length (File) = 0
 111                          and then Page_Length (File) = 0)),
 112      Global            => (In_Out => File_System),
 113      Exceptional_Cases => (Name_Error | Use_Error => Standard.True);
 114
 115    procedure Open
 116      (File : in out File_Type;
 117       Mode : File_Mode;
 118       Name : String;
 119       Form : String := "")
 120    with
 121      Pre               => not Is_Open (File),
 122      Post              =>
 123       Is_Open (File)
 124       and then Ada.Text_IO.Mode (File) = Mode
 125       and then (if Mode /= In_File
 126                   then (Line_Length (File) = 0
 127                         and then Page_Length (File) = 0)),
 128      Global            => (In_Out => File_System),
 129      Exceptional_Cases => (Name_Error | Use_Error => Standard.True);
 130
 131    procedure Close  (File : in out File_Type) with
 132      Pre    => Is_Open (File),
 133      Post   => not Is_Open (File),
 134      Global => (In_Out => File_System);
 135
 136    procedure Delete (File : in out File_Type) with
 137      Pre               => Is_Open (File),
 138      Post              => not Is_Open (File),
 139      Global            => (In_Out => File_System),
 140      Exceptional_Cases => (Use_Error => Standard.True);
 141
 142    procedure Reset  (File : in out File_Type; Mode : File_Mode) with
 143      Pre               => Is_Open (File),
 144      Post              =>
 145        Is_Open (File)
 146        and then Ada.Text_IO.Mode (File) = Mode
 147        and then (if Mode /= In_File
 148                    then (Line_Length (File) = 0
 149                          and then Page_Length (File) = 0)),
 150      Global            => (In_Out => File_System),
 151      Exceptional_Cases => (Use_Error => Standard.True);
 152
 153    procedure Reset  (File : in out File_Type) with
 154      Pre               => Is_Open (File),
 155      Post              =>
 156        Is_Open (File)
 157        and Mode (File)'Old = Mode (File)
 158        and (if Mode (File) /= In_File
 159                 then (Line_Length (File) = 0
 160                       and then Page_Length (File) = 0)),
 161      Global            => (In_Out => File_System),
 162      Exceptional_Cases => (Use_Error => Standard.True);
 163
 164    function Mode (File : File_Type) return File_Mode with
 165      Pre    => Is_Open (File),
 166      Global => null;
 167
 168    function Name (File : File_Type) return String with
 169      Pre        => Is_Open (File),
 170      SPARK_Mode => Off;
 171
 172    function Form (File : File_Type) return String with
 173      Pre    => Is_Open (File),
 174      Global => null;
 175
 176    function Is_Open (File : File_Type) return Boolean with
 177      Global => null;
 178
 179    ------------------------------------------------------
 180    -- Control of default input, output and error files --
 181    ------------------------------------------------------
 182
 183    procedure Set_Input  (File : File_Type) with SPARK_Mode => Off;
 184    procedure Set_Output (File : File_Type) with SPARK_Mode => Off;
 185    procedure Set_Error  (File : File_Type) with SPARK_Mode => Off;
 186
 187    function Standard_Input  return File_Type with SPARK_Mode => Off;
 188    function Standard_Output return File_Type with SPARK_Mode => Off;
 189    function Standard_Error  return File_Type with SPARK_Mode => Off;
 190
 191    function Current_Input  return File_Type with SPARK_Mode => Off;
 192    function Current_Output return File_Type with SPARK_Mode => Off;
 193    function Current_Error  return File_Type with SPARK_Mode => Off;
 194
 195    type File_Access is access constant File_Type;
 196
 197    function Standard_Input  return File_Access with SPARK_Mode => Off;
 198    function Standard_Output return File_Access with SPARK_Mode => Off;
 199    function Standard_Error  return File_Access with SPARK_Mode => Off;
 200
 201    function Current_Input  return File_Access with SPARK_Mode => Off;
 202    function Current_Output return File_Access with SPARK_Mode => Off;
 203    function Current_Error  return File_Access with SPARK_Mode => Off;
 204
 205    --------------------
 206    -- Buffer control --
 207    --------------------
 208
 209    --  Note: The parameter file is IN OUT in the RM, but this is clearly
 210    --  an oversight, and was intended to be IN, see AI95-00057.
 211
 212    procedure Flush (File : File_Type) with
 213      Pre    => Is_Open (File) and then Mode (File) /= In_File,
 214      Post   =>
 215        Line_Length (File)'Old = Line_Length (File)
 216        and Page_Length (File)'Old = Page_Length (File),
 217      Global => (In_Out => File_System);
 218
 219    procedure Flush with
 220      Post   =>
 221        Line_Length'Old = Line_Length
 222        and Page_Length'Old = Page_Length,
 223      Global => (In_Out => File_System);
 224
 225    --------------------------------------------
 226    -- Specification of line and page lengths --
 227    --------------------------------------------
 228
 229    procedure Set_Line_Length (File : File_Type; To : Count) with
 230      Pre               => Is_Open (File)  and then Mode (File) /= In_File,
 231      Post              =>
 232        Line_Length (File) = To
 233        and Page_Length (File)'Old = Page_Length (File),
 234      Global            => (In_Out => File_System),
 235      Exceptional_Cases => (Use_Error => Standard.True);
 236
 237    procedure Set_Line_Length (To : Count) with
 238      Post              =>
 239        Line_Length = To
 240        and Page_Length'Old = Page_Length,
 241      Global            => (In_Out => File_System),
 242      Exceptional_Cases => (Use_Error => Standard.True);
 243
 244    procedure Set_Page_Length (File : File_Type; To : Count) with
 245      Pre               => Is_Open (File) and then Mode (File) /= In_File,
 246      Post              =>
 247        Page_Length (File) = To
 248        and Line_Length (File)'Old = Line_Length (File),
 249      Global            => (In_Out => File_System),
 250      Exceptional_Cases => (Use_Error => Standard.True);
 251
 252    procedure Set_Page_Length (To : Count) with
 253      Post              =>
 254        Page_Length = To
 255        and Line_Length'Old = Line_Length,
 256      Global            => (In_Out => File_System),
 257      Exceptional_Cases => (Use_Error => Standard.True);
 258
 259    function Line_Length (File : File_Type) return Count with
 260      Pre    => Is_Open (File) and then Mode (File) /= In_File,
 261      Global => (Input => File_System);
 262
 263    function Line_Length return Count with
 264      Global => (Input => File_System);
 265
 266    function Page_Length (File : File_Type) return Count with
 267      Pre    => Is_Open (File) and then Mode (File) /= In_File,
 268      Global => (Input => File_System);
 269
 270    function Page_Length return Count with
 271      Global => (Input => File_System);
 272
 273    ------------------------------------
 274    -- Column, Line, and Page Control --
 275    ------------------------------------
 276
 277    procedure New_Line (File : File_Type; Spacing : Positive_Count := 1) with
 278      Pre    => Is_Open (File) and then Mode (File) /= In_File,
 279      Post   =>
 280        Line_Length (File)'Old = Line_Length (File)
 281        and Page_Length (File)'Old = Page_Length (File),
 282      Global => (In_Out => File_System);
 283
 284    procedure New_Line (Spacing : Positive_Count := 1) with
 285      Post   =>
 286        Line_Length'Old = Line_Length
 287        and Page_Length'Old = Page_Length,
 288      Global => (In_Out => File_System);
 289
 290    procedure Skip_Line (File : File_Type; Spacing : Positive_Count := 1) with
 291      Pre               => Is_Open (File) and then Mode (File) = In_File,
 292      Global            => (In_Out => File_System),
 293      Exceptional_Cases => (End_Error => Standard.True);
 294
 295    procedure Skip_Line (Spacing : Positive_Count := 1) with
 296      Post              =>
 297        Line_Length'Old = Line_Length
 298        and Page_Length'Old = Page_Length,
 299      Global            => (In_Out => File_System),
 300      Exceptional_Cases => (End_Error => Standard.True);
 301
 302    function End_Of_Line (File : File_Type) return Boolean with
 303      Pre    => Is_Open (File) and then Mode (File) = In_File,
 304      Global => (Input => File_System);
 305
 306    function End_Of_Line return Boolean with
 307      Global => (Input => File_System);
 308
 309    procedure New_Page (File : File_Type) with
 310      Pre    => Is_Open (File) and then Mode (File) /= In_File,
 311      Post   =>
 312        Line_Length (File)'Old = Line_Length (File)
 313        and Page_Length (File)'Old = Page_Length (File),
 314      Global => (In_Out => File_System);
 315
 316    procedure New_Page with
 317      Post   =>
 318        Line_Length'Old = Line_Length
 319        and Page_Length'Old = Page_Length,
 320      Global => (In_Out => File_System);
 321
 322    procedure Skip_Page (File : File_Type) with
 323      Pre               => Is_Open (File) and then Mode (File) = In_File,
 324      Global            => (In_Out => File_System),
 325      Exceptional_Cases => (End_Error => Standard.True);
 326
 327    procedure Skip_Page with
 328      Post              =>
 329        Line_Length'Old = Line_Length
 330        and Page_Length'Old = Page_Length,
 331      Global            => (In_Out => File_System),
 332      Exceptional_Cases => (End_Error => Standard.True);
 333
 334    function End_Of_Page (File : File_Type) return Boolean with
 335      Pre    => Is_Open (File) and then Mode (File) = In_File,
 336      Global => (Input => File_System);
 337
 338    function End_Of_Page return Boolean with
 339      Global => (Input => File_System);
 340
 341    function End_Of_File (File : File_Type) return Boolean with
 342      Pre    => Is_Open (File) and then Mode (File) = In_File,
 343      Global => (Input => File_System);
 344
 345    function End_Of_File return Boolean with
 346      Global => (Input => File_System);
 347
 348    procedure Set_Col (File : File_Type;  To : Positive_Count) with
 349      Pre               =>
 350        Is_Open (File)
 351        and then (if Mode (File) /= In_File
 352                      then (Line_Length (File) = 0
 353                            or else To <= Line_Length (File))),
 354      Contract_Cases    =>
 355        (Mode (File) /= In_File =>
 356               Line_Length (File)'Old = Line_Length (File)
 357               and Page_Length (File)'Old = Page_Length (File),
 358         others                 => True),
 359      Global            => (In_Out => File_System),
 360      Exceptional_Cases => (End_Error => Standard.True);
 361
 362    procedure Set_Col (To : Positive_Count) with
 363      Pre               => Line_Length = 0 or To <= Line_Length,
 364      Post              =>
 365        Line_Length'Old = Line_Length
 366        and Page_Length'Old = Page_Length,
 367      Global            => (In_Out => File_System),
 368      Exceptional_Cases => (End_Error => Standard.True);
 369
 370    procedure Set_Line (File : File_Type; To : Positive_Count) with
 371      Pre               =>
 372        Is_Open (File)
 373        and then (if Mode (File) /= In_File
 374                      then (Page_Length (File) = 0
 375                            or else To <= Page_Length (File))),
 376      Contract_Cases    =>
 377        (Mode (File) /= In_File =>
 378               Line_Length (File)'Old = Line_Length (File)
 379               and Page_Length (File)'Old = Page_Length (File),
 380         others                 => True),
 381      Global            => (In_Out => File_System),
 382      Exceptional_Cases => (End_Error => Standard.True);
 383
 384    procedure Set_Line (To : Positive_Count) with
 385      Pre               => Page_Length = 0 or To <= Page_Length,
 386      Post              =>
 387        Line_Length'Old = Line_Length
 388        and Page_Length'Old = Page_Length,
 389      Global            => (In_Out => File_System),
 390      Exceptional_Cases => (End_Error => Standard.True);
 391
 392    function Col (File : File_Type) return Positive_Count with
 393      SPARK_Mode => Off;
 394
 395    function Col return Positive_Count with
 396      SPARK_Mode => Off;
 397
 398    function Line (File : File_Type) return Positive_Count with
 399      SPARK_Mode => Off;
 400
 401    function Line return Positive_Count with
 402      SPARK_Mode => Off;
 403
 404    function Page (File : File_Type) return Positive_Count with
 405      SPARK_Mode => Off;
 406
 407    function Page return Positive_Count with
 408      SPARK_Mode => Off;
 409
 410    ----------------------------
 411    -- Character Input-Output --
 412    ----------------------------
 413
 414    procedure Get (File : File_Type; Item : out Character) with
 415      Pre               => Is_Open (File) and then Mode (File) = In_File,
 416      Global            => (In_Out => File_System),
 417      Exceptional_Cases => (End_Error => Standard.True);
 418
 419    procedure Get (Item : out Character) with
 420      Post              =>
 421        Line_Length'Old = Line_Length
 422        and Page_Length'Old = Page_Length,
 423      Global            => (In_Out => File_System),
 424      Exceptional_Cases => (End_Error => Standard.True);
 425
 426    procedure Put (File : File_Type; Item : Character) with
 427      Pre    => Is_Open (File) and then Mode (File) /= In_File,
 428      Post   =>
 429        Line_Length (File)'Old = Line_Length (File)
 430        and Page_Length (File)'Old = Page_Length (File),
 431      Global => (In_Out => File_System);
 432
 433    procedure Put (Item : Character) with
 434      Post   =>
 435        Line_Length'Old = Line_Length
 436        and Page_Length'Old = Page_Length,
 437      Global => (In_Out => File_System);
 438
 439    procedure Look_Ahead
 440      (File        : File_Type;
 441       Item        : out Character;
 442       End_Of_Line : out Boolean)
 443    with
 444      Pre    => Is_Open (File) and then Mode (File) = In_File,
 445      Global => (Input => File_System);
 446
 447    procedure Look_Ahead
 448      (Item        : out Character;
 449       End_Of_Line : out Boolean)
 450    with
 451      Post   =>
 452        Line_Length'Old = Line_Length
 453        and Page_Length'Old = Page_Length,
 454      Global => (Input => File_System);
 455
 456    procedure Get_Immediate
 457      (File : File_Type;
 458       Item : out Character)
 459    with
 460      Pre               => Is_Open (File) and then Mode (File) = In_File,
 461      Global            => (In_Out => File_System),
 462      Exceptional_Cases => (End_Error => Standard.True);
 463
 464    procedure Get_Immediate
 465      (Item : out Character)
 466    with
 467      Post              =>
 468        Line_Length'Old = Line_Length
 469        and Page_Length'Old = Page_Length,
 470      Global            => (In_Out => File_System),
 471      Exceptional_Cases => (End_Error => Standard.True);
 472
 473    procedure Get_Immediate
 474      (File      : File_Type;
 475       Item      : out Character;
 476       Available : out Boolean)
 477    with
 478      Pre               => Is_Open (File) and then Mode (File) = In_File,
 479      Global            => (In_Out => File_System),
 480      Exceptional_Cases => (End_Error => Standard.True);
 481
 482    procedure Get_Immediate
 483      (Item      : out Character;
 484       Available : out Boolean)
 485    with
 486      Post              =>
 487        Line_Length'Old = Line_Length
 488        and Page_Length'Old = Page_Length,
 489      Global            => (In_Out => File_System),
 490      Exceptional_Cases => (End_Error => Standard.True);
 491
 492    -------------------------
 493    -- String Input-Output --
 494    -------------------------
 495
 496    procedure Get (File : File_Type; Item : out String) with
 497      Pre               => Is_Open (File) and then Mode (File) = In_File,
 498      Global            => (In_Out => File_System),
 499      Exceptional_Cases => (End_Error => Item'Length'Old > 0);
 500
 501    procedure Get (Item : out String) with
 502      Post              =>
 503        Line_Length'Old = Line_Length
 504        and Page_Length'Old = Page_Length,
 505      Global            => (In_Out => File_System),
 506      Exceptional_Cases => (End_Error => Item'Length'Old > 0);
 507
 508    procedure Put (File : File_Type; Item : String) with
 509      Pre    => Is_Open (File) and then Mode (File) /= In_File,
 510      Post   =>
 511        Line_Length (File)'Old = Line_Length (File)
 512        and Page_Length (File)'Old = Page_Length (File),
 513      Global => (In_Out => File_System);
 514
 515    procedure Put (Item : String) with
 516      Post   =>
 517        Line_Length'Old = Line_Length
 518        and Page_Length'Old = Page_Length,
 519      Global => (In_Out => File_System);
 520
 521    procedure Get_Line
 522      (File : File_Type;
 523       Item : out String;
 524       Last : out Natural)
 525    with
 526      Relaxed_Initialization => Item,
 527      Pre                    => Is_Open (File) and then Mode (File) = In_File,
 528      Post                   =>
 529        (if Item'Length > 0 then Last in Item'First - 1 .. Item'Last
 530         else Last = Item'First - 1)
 531        and (for all I in Item'First .. Last => Item (I)'Initialized),
 532      Global                 => (In_Out => File_System),
 533      Exceptional_Cases      => (End_Error => Item'Length'Old > 0);
 534
 535    procedure Get_Line
 536      (Item : out String;
 537       Last : out Natural)
 538    with
 539      Relaxed_Initialization => Item,
 540      Post                   =>
 541        Line_Length'Old = Line_Length
 542        and Page_Length'Old = Page_Length
 543        and (if Item'Length > 0 then Last in Item'First - 1 .. Item'Last
 544             else Last = Item'First - 1)
 545        and (for all I in Item'First .. Last => Item (I)'Initialized),
 546      Global                => (In_Out => File_System),
 547      Exceptional_Cases     => (End_Error => Item'Length'Old > 0);
 548
 549    function Get_Line (File : File_Type) return String with SPARK_Mode => Off;
 550    pragma Ada_05 (Get_Line);
 551
 552    function Get_Line return String with SPARK_Mode => Off;
 553    pragma Ada_05 (Get_Line);
 554
 555    procedure Put_Line
 556      (File : File_Type;
 557       Item : String)
 558    with
 559      Pre    => Is_Open (File) and then Mode (File) /= In_File,
 560      Post   =>
 561        Line_Length (File)'Old = Line_Length (File)
 562        and Page_Length (File)'Old = Page_Length (File),
 563      Global => (In_Out => File_System);
 564
 565    procedure Put_Line
 566      (Item : String)
 567    with
 568      Post   =>
 569        Line_Length'Old = Line_Length
 570        and Page_Length'Old = Page_Length,
 571      Global => (In_Out => File_System);
 572
 573    ---------------------------------------
 574    -- Generic packages for Input-Output --
 575    ---------------------------------------
 576
 577    --  The generic packages:
 578
 579    --    Ada.Text_IO.Integer_IO
 580    --    Ada.Text_IO.Modular_IO
 581    --    Ada.Text_IO.Float_IO
 582    --    Ada.Text_IO.Fixed_IO
 583    --    Ada.Text_IO.Decimal_IO
 584    --    Ada.Text_IO.Enumeration_IO
 585
 586    --  are implemented as separate child packages in GNAT, so the
 587    --  spec and body of these packages are to be found in separate
 588    --  child units. This implementation detail is hidden from the
 589    --  Ada programmer by special circuitry in the compiler that
 590    --  treats these child packages as though they were nested in
 591    --  Text_IO. The advantage of this special processing is that
 592    --  the subsidiary routines needed if these generics are used
 593    --  are not loaded when they are not used.
 594
 595    ----------------
 596    -- Exceptions --
 597    ----------------
 598
 599    Status_Error : exception renames IO_Exceptions.Status_Error;
 600    Mode_Error   : exception renames IO_Exceptions.Mode_Error;
 601    Name_Error   : exception renames IO_Exceptions.Name_Error;
 602    Use_Error    : exception renames IO_Exceptions.Use_Error;
 603    Device_Error : exception renames IO_Exceptions.Device_Error;
 604    End_Error    : exception renames IO_Exceptions.End_Error;
 605    Data_Error   : exception renames IO_Exceptions.Data_Error;
 606    Layout_Error : exception renames IO_Exceptions.Layout_Error;
 607
 608 private
 609    pragma SPARK_Mode (Off);
 610
 611    --  The following procedures have a File_Type formal of mode IN OUT because
 612    --  they may close the original file. The Close operation may raise an
 613    --  exception, but in that case we want any assignment to the formal to
 614    --  be effective anyway, so it must be passed by reference (or the caller
 615    --  will be left with a dangling pointer).
 616
 617    pragma Export_Procedure
 618      (Internal  => Close,
 619       External  => "",
 620       Mechanism => Reference);
 621    pragma Export_Procedure
 622      (Internal  => Delete,
 623       External  => "",
 624       Mechanism => Reference);
 625    pragma Export_Procedure
 626      (Internal        => Reset,
 627       External        => "",
 628       Parameter_Types => (File_Type),
 629       Mechanism       => Reference);
 630    pragma Export_Procedure
 631      (Internal        => Reset,
 632       External        => "",
 633       Parameter_Types => (File_Type, File_Mode),
 634       Mechanism       => (File => Reference));
 635
 636    -----------------------------------
 637    -- Handling of Format Characters --
 638    -----------------------------------
 639
 640    --  Line marks are represented by the single character ASCII.LF (16#0A#).
 641    --  In DOS and similar systems, underlying file translation takes care
 642    --  of translating this to and from the standard CR/LF sequences used in
 643    --  these operating systems to mark the end of a line. On output there is
 644    --  always a line mark at the end of the last line, but on input, this
 645    --  line mark can be omitted, and is implied by the end of file.
 646
 647    --  Page marks are represented by the single character ASCII.FF (16#0C#),
 648    --  The page mark at the end of the file may be omitted, and is normally
 649    --  omitted on output unless an explicit New_Page call is made before
 650    --  closing the file. No page mark is added when a file is appended to,
 651    --  so, in accordance with the permission in (RM A.10.2(4)), there may
 652    --  or may not be a page mark separating preexisting text in the file
 653    --  from the new text to be written.
 654
 655    --  A file mark is marked by the physical end of file. In DOS translation
 656    --  mode on input, an EOF character (SUB = 16#1A#) gets translated to the
 657    --  physical end of file, so in effect this character is recognized as
 658    --  marking the end of file in DOS and similar systems.
 659
 660    LM : constant := Character'Pos (ASCII.LF);
 661    --  Used as line mark
 662
 663    PM : constant := Character'Pos (ASCII.FF);
 664    --  Used as page mark, except at end of file where it is implied
 665
 666    --------------------------------
 667    -- Text_IO File Control Block --
 668    --------------------------------
 669
 670    Default_WCEM : System.WCh_Con.WC_Encoding_Method :=
 671                     System.WCh_Con.WCEM_UTF8;
 672    --  This gets modified during initialization (see body) using
 673    --  the default value established in the call to Set_Globals.
 674
 675    package FCB renames System.File_Control_Block;
 676
 677    type Text_AFCB;
 678    type File_Type is access all Text_AFCB;
 679
 680    type Text_AFCB is new FCB.AFCB with record
 681       Page        : Count := 1;
 682       Line        : Count := 1;
 683       Col         : Count := 1;
 684       Line_Length : Count := 0;
 685       Page_Length : Count := 0;
 686
 687       Self : aliased File_Type;
 688       --  Set to point to the containing Text_AFCB block. This is used to
 689       --  implement the Current_{Error,Input,Output} functions which return
 690       --  a File_Access, the file access value returned is a pointer to
 691       --  the Self field of the corresponding file.
 692
 693       Before_LM : Boolean := False;
 694       --  This flag is used to deal with the anomalies introduced by the
 695       --  peculiar definition of End_Of_File and End_Of_Page in Ada. These
 696       --  functions require looking ahead more than one character. Since
 697       --  there is no convenient way of backing up more than one character,
 698       --  what we do is to leave ourselves positioned past the LM, but set
 699       --  this flag, so that we know that from an Ada point of view we are
 700       --  in front of the LM, not after it. A little odd, but it works.
 701
 702       Before_LM_PM : Boolean := False;
 703       --  This flag similarly handles the case of being physically positioned
 704       --  after a LM-PM sequence when logically we are before the LM-PM. This
 705       --  flag can only be set if Before_LM is also set.
 706
 707       WC_Method : System.WCh_Con.WC_Encoding_Method := Default_WCEM;
 708       --  Encoding method to be used for this file. Text_IO does not deal with
 709       --  wide characters, but it does deal with upper half characters in the
 710       --  range 16#80#-16#FF# which may need encoding, e.g. in UTF-8 mode.
 711
 712       Before_Upper_Half_Character : Boolean := False;
 713       --  This flag is set to indicate that an encoded upper half character has
 714       --  been read by Text_IO.Look_Ahead. If it is set to True, then it means
 715       --  that the stream is logically positioned before the character but is
 716       --  physically positioned after it. The character involved must be in
 717       --  the range 16#80#-16#FF#, i.e. if the flag is set, then we know the
 718       --  next character has a code greater than 16#7F#, and the value of this
 719       --  character is saved in Saved_Upper_Half_Character.
 720
 721       Saved_Upper_Half_Character : Character;
 722       --  This field is valid only if Before_Upper_Half_Character is set. It
 723       --  contains an upper-half character read by Look_Ahead. If Look_Ahead
 724       --  reads a character in the range 16#00# to 16#7F#, then it can use
 725       --  ungetc to put it back, but ungetc cannot be called more than once,
 726       --  so for characters above this range, we don't try to back up the
 727       --  file. Instead we save the character in this field and set the flag
 728       --  Before_Upper_Half_Character to True to indicate that we are logically
 729       --  positioned before this character even though the stream is physically
 730       --  positioned after it.
 731
 732    end record;
 733
 734    function AFCB_Allocate (Control_Block : Text_AFCB) return FCB.AFCB_Ptr;
 735
 736    procedure AFCB_Close (File : not null access Text_AFCB);
 737    procedure AFCB_Free  (File : not null access Text_AFCB);
 738
 739    procedure Read
 740      (File : in out Text_AFCB;
 741       Item : out Ada.Streams.Stream_Element_Array;
 742       Last : out Ada.Streams.Stream_Element_Offset);
 743    --  Read operation used when Text_IO file is treated directly as Stream
 744
 745    procedure Write
 746      (File : in out Text_AFCB;
 747       Item : Ada.Streams.Stream_Element_Array);
 748    --  Write operation used when Text_IO file is treated directly as Stream
 749
 750    ------------------------
 751    -- The Standard Files --
 752    ------------------------
 753
 754    Standard_In_AFCB  : aliased Text_AFCB;
 755    Standard_Out_AFCB : aliased Text_AFCB;
 756    Standard_Err_AFCB : aliased Text_AFCB;
 757
 758    Standard_In  : aliased File_Type := Standard_In_AFCB'Access with
 759      Part_Of => File_System;
 760    Standard_Out : aliased File_Type := Standard_Out_AFCB'Access with
 761      Part_Of => File_System;
 762    Standard_Err : aliased File_Type := Standard_Err_AFCB'Access with
 763      Part_Of => File_System;
 764    --  Standard files
 765
 766    Current_In   : aliased File_Type := Standard_In with
 767      Part_Of => File_System;
 768    Current_Out  : aliased File_Type := Standard_Out with
 769      Part_Of => File_System;
 770    Current_Err  : aliased File_Type := Standard_Err with
 771      Part_Of => File_System;
 772    --  Current files
 773
 774    function EOF_Char return Integer;
 775    --  Returns the system-specific character indicating the end of a text file.
 776    --  This is exported for use by child packages such as Enumeration_Aux to
 777    --  eliminate their needing to depend directly on Interfaces.C_Streams,
 778    --  which might not be available in certain target environments.
 779
 780    procedure Initialize_Standard_Files;
 781    --  Initializes the file control blocks for the standard files. Called from
 782    --  the elaboration routine for this package, and from Reset_Standard_Files
 783    --  in package Ada.Text_IO.Reset_Standard_Files.
 784
 785 end Ada.Text_IO;