1 //===-- runtime/unit.cpp --------------------------------------------------===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 
9 #include "unit.h"
10 #include "environment.h"
11 #include "io-error.h"
12 #include "lock.h"
13 #include "unit-map.h"
14 #include <cstdio>
15 #include <limits>
16 #include <utility>
17 
18 namespace Fortran::runtime::io {
19 
20 // The per-unit data structures are created on demand so that Fortran I/O
21 // should work without a Fortran main program.
22 static Lock unitMapLock;
23 static UnitMap *unitMap{nullptr};
24 static ExternalFileUnit *defaultInput{nullptr}; // unit 5
25 static ExternalFileUnit *defaultOutput{nullptr}; // unit 6
26 static ExternalFileUnit *errorOutput{nullptr}; // unit 0 extension
27 
28 void FlushOutputOnCrash(const Terminator &terminator) {
29   if (!defaultOutput && !errorOutput) {
30     return;
31   }
32   IoErrorHandler handler{terminator};
33   handler.HasIoStat(); // prevent nested crash if flush has error
34   CriticalSection critical{unitMapLock};
35   if (defaultOutput) {
36     defaultOutput->FlushOutput(handler);
37   }
38   if (errorOutput) {
39     errorOutput->FlushOutput(handler);
40   }
41 }
42 
43 ExternalFileUnit *ExternalFileUnit::LookUp(int unit) {
44   return GetUnitMap().LookUp(unit);
45 }
46 
47 ExternalFileUnit &ExternalFileUnit::LookUpOrCrash(
48     int unit, const Terminator &terminator) {
49   ExternalFileUnit *file{LookUp(unit)};
50   if (!file) {
51     terminator.Crash("Not an open I/O unit number: %d", unit);
52   }
53   return *file;
54 }
55 
56 ExternalFileUnit &ExternalFileUnit::LookUpOrCreate(
57     int unit, const Terminator &terminator, bool &wasExtant) {
58   return GetUnitMap().LookUpOrCreate(unit, terminator, wasExtant);
59 }
60 
61 ExternalFileUnit &ExternalFileUnit::LookUpOrCreateAnonymous(int unit,
62     Direction dir, std::optional<bool> isUnformatted,
63     const Terminator &terminator) {
64   bool exists{false};
65   ExternalFileUnit &result{
66       GetUnitMap().LookUpOrCreate(unit, terminator, exists)};
67   if (!exists) {
68     IoErrorHandler handler{terminator};
69     result.OpenAnonymousUnit(
70         dir == Direction::Input ? OpenStatus::Unknown : OpenStatus::Replace,
71         Action::ReadWrite, Position::Rewind, Convert::Native, handler);
72     result.isUnformatted = isUnformatted;
73   }
74   return result;
75 }
76 
77 ExternalFileUnit *ExternalFileUnit::LookUp(const char *path) {
78   return GetUnitMap().LookUp(path);
79 }
80 
81 ExternalFileUnit &ExternalFileUnit::CreateNew(
82     int unit, const Terminator &terminator) {
83   bool wasExtant{false};
84   ExternalFileUnit &result{
85       GetUnitMap().LookUpOrCreate(unit, terminator, wasExtant)};
86   RUNTIME_CHECK(terminator, !wasExtant);
87   return result;
88 }
89 
90 ExternalFileUnit *ExternalFileUnit::LookUpForClose(int unit) {
91   return GetUnitMap().LookUpForClose(unit);
92 }
93 
94 ExternalFileUnit &ExternalFileUnit::NewUnit(
95     const Terminator &terminator, bool forChildIo) {
96   ExternalFileUnit &unit{GetUnitMap().NewUnit(terminator)};
97   unit.createdForInternalChildIo_ = forChildIo;
98   return unit;
99 }
100 
101 void ExternalFileUnit::OpenUnit(std::optional<OpenStatus> status,
102     std::optional<Action> action, Position position, OwningPtr<char> &&newPath,
103     std::size_t newPathLength, Convert convert, IoErrorHandler &handler) {
104   if (executionEnvironment.conversion != Convert::Unknown) {
105     convert = executionEnvironment.conversion;
106   }
107   swapEndianness_ = convert == Convert::Swap ||
108       (convert == Convert::LittleEndian && !isHostLittleEndian) ||
109       (convert == Convert::BigEndian && isHostLittleEndian);
110   if (IsConnected()) {
111     bool isSamePath{newPath.get() && path() && pathLength() == newPathLength &&
112         std::memcmp(path(), newPath.get(), newPathLength) == 0};
113     if (status && *status != OpenStatus::Old && isSamePath) {
114       handler.SignalError("OPEN statement for connected unit may not have "
115                           "explicit STATUS= other than 'OLD'");
116       return;
117     }
118     if (!newPath.get() || isSamePath) {
119       // OPEN of existing unit, STATUS='OLD' or unspecified, not new FILE=
120       newPath.reset();
121       return;
122     }
123     // Otherwise, OPEN on open unit with new FILE= implies CLOSE
124     DoImpliedEndfile(handler);
125     FlushOutput(handler);
126     Close(CloseStatus::Keep, handler);
127   }
128   set_path(std::move(newPath), newPathLength);
129   Open(status.value_or(OpenStatus::Unknown), action, position, handler);
130   auto totalBytes{knownSize()};
131   if (access == Access::Direct) {
132     if (!openRecl) {
133       handler.SignalError(IostatOpenBadRecl,
134           "OPEN(UNIT=%d,ACCESS='DIRECT'): record length is not known",
135           unitNumber());
136     } else if (*openRecl <= 0) {
137       handler.SignalError(IostatOpenBadRecl,
138           "OPEN(UNIT=%d,ACCESS='DIRECT',RECL=%jd): record length is invalid",
139           unitNumber(), static_cast<std::intmax_t>(*openRecl));
140     } else if (totalBytes && (*totalBytes % *openRecl != 0)) {
141       handler.SignalError(IostatOpenBadAppend,
142           "OPEN(UNIT=%d,ACCESS='DIRECT',RECL=%jd): record length is not an "
143           "even divisor of the file size %jd",
144           unitNumber(), static_cast<std::intmax_t>(*openRecl),
145           static_cast<std::intmax_t>(*totalBytes));
146     }
147     recordLength = openRecl;
148   }
149   endfileRecordNumber.reset();
150   currentRecordNumber = 1;
151   if (totalBytes && access == Access::Direct && openRecl.value_or(0) > 0) {
152     endfileRecordNumber = 1 + (*totalBytes / *openRecl);
153   }
154   if (position == Position::Append && access != Access::Stream) {
155     if (!endfileRecordNumber) {
156       // Fake it so that we can backspace relative from the end
157       endfileRecordNumber = std::numeric_limits<std::int64_t>::max() - 2;
158     }
159     currentRecordNumber = *endfileRecordNumber;
160   }
161 }
162 
163 void ExternalFileUnit::OpenAnonymousUnit(std::optional<OpenStatus> status,
164     std::optional<Action> action, Position position, Convert convert,
165     IoErrorHandler &handler) {
166   // I/O to an unconnected unit reads/creates a local file, e.g. fort.7
167   std::size_t pathMaxLen{32};
168   auto path{SizedNew<char>{handler}(pathMaxLen)};
169   std::snprintf(path.get(), pathMaxLen, "fort.%d", unitNumber_);
170   OpenUnit(status, action, position, std::move(path), std::strlen(path.get()),
171       convert, handler);
172 }
173 
174 void ExternalFileUnit::CloseUnit(CloseStatus status, IoErrorHandler &handler) {
175   DoImpliedEndfile(handler);
176   FlushOutput(handler);
177   Close(status, handler);
178 }
179 
180 void ExternalFileUnit::DestroyClosed() {
181   GetUnitMap().DestroyClosed(*this); // destroys *this
182 }
183 
184 bool ExternalFileUnit::SetDirection(
185     Direction direction, IoErrorHandler &handler) {
186   if (direction == Direction::Input) {
187     if (mayRead()) {
188       direction_ = Direction::Input;
189       return true;
190     } else {
191       handler.SignalError(IostatReadFromWriteOnly,
192           "READ(UNIT=%d) with ACTION='WRITE'", unitNumber());
193       return false;
194     }
195   } else {
196     if (mayWrite()) {
197       direction_ = Direction::Output;
198       return true;
199     } else {
200       handler.SignalError(IostatWriteToReadOnly,
201           "WRITE(UNIT=%d) with ACTION='READ'", unitNumber());
202       return false;
203     }
204   }
205 }
206 
207 UnitMap &ExternalFileUnit::GetUnitMap() {
208   if (unitMap) {
209     return *unitMap;
210   }
211   CriticalSection critical{unitMapLock};
212   if (unitMap) {
213     return *unitMap;
214   }
215   Terminator terminator{__FILE__, __LINE__};
216   IoErrorHandler handler{terminator};
217   UnitMap *newUnitMap{New<UnitMap>{terminator}().release()};
218 
219   bool wasExtant{false};
220   ExternalFileUnit &out{newUnitMap->LookUpOrCreate(6, terminator, wasExtant)};
221   RUNTIME_CHECK(terminator, !wasExtant);
222   out.Predefine(1);
223   out.SetDirection(Direction::Output, handler);
224   out.isUnformatted = false;
225   defaultOutput = &out;
226 
227   ExternalFileUnit &in{newUnitMap->LookUpOrCreate(5, terminator, wasExtant)};
228   RUNTIME_CHECK(terminator, !wasExtant);
229   in.Predefine(0);
230   in.SetDirection(Direction::Input, handler);
231   in.isUnformatted = false;
232   defaultInput = &in;
233 
234   ExternalFileUnit &error{newUnitMap->LookUpOrCreate(0, terminator, wasExtant)};
235   RUNTIME_CHECK(terminator, !wasExtant);
236   error.Predefine(2);
237   error.SetDirection(Direction::Output, handler);
238   error.isUnformatted = false;
239   errorOutput = &error;
240 
241   // TODO: Set UTF-8 mode from the environment
242   unitMap = newUnitMap;
243   return *unitMap;
244 }
245 
246 void ExternalFileUnit::CloseAll(IoErrorHandler &handler) {
247   CriticalSection critical{unitMapLock};
248   if (unitMap) {
249     unitMap->CloseAll(handler);
250     FreeMemoryAndNullify(unitMap);
251   }
252   defaultOutput = nullptr;
253   defaultInput = nullptr;
254   errorOutput = nullptr;
255 }
256 
257 void ExternalFileUnit::FlushAll(IoErrorHandler &handler) {
258   CriticalSection critical{unitMapLock};
259   if (unitMap) {
260     unitMap->FlushAll(handler);
261   }
262 }
263 
264 static void SwapEndianness(
265     char *data, std::size_t bytes, std::size_t elementBytes) {
266   if (elementBytes > 1) {
267     auto half{elementBytes >> 1};
268     for (std::size_t j{0}; j + elementBytes <= bytes; j += elementBytes) {
269       for (std::size_t k{0}; k < half; ++k) {
270         std::swap(data[j + k], data[j + elementBytes - 1 - k]);
271       }
272     }
273   }
274 }
275 
276 bool ExternalFileUnit::Emit(const char *data, std::size_t bytes,
277     std::size_t elementBytes, IoErrorHandler &handler) {
278   auto furthestAfter{std::max(furthestPositionInRecord,
279       positionInRecord + static_cast<std::int64_t>(bytes))};
280   if (openRecl) {
281     // Check for fixed-length record overrun, but allow for
282     // sequential record termination.
283     int extra{0};
284     int header{0};
285     if (access == Access::Sequential) {
286       if (isUnformatted.value_or(false)) {
287         // record header + footer
288         header = static_cast<int>(sizeof(std::uint32_t));
289         extra = 2 * header;
290       } else {
291 #ifdef _WIN32
292         if (!isWindowsTextFile()) {
293           ++extra; // carriage return (CR)
294         }
295 #endif
296         ++extra; // newline (LF)
297       }
298     }
299     if (furthestAfter > extra + *openRecl) {
300       handler.SignalError(IostatRecordWriteOverrun,
301           "Attempt to write %zd bytes to position %jd in a fixed-size record "
302           "of %jd bytes",
303           bytes, static_cast<std::intmax_t>(positionInRecord - header),
304           static_cast<std::intmax_t>(*openRecl));
305       return false;
306     }
307   } else if (recordLength) {
308     // It is possible for recordLength to have a value now for a
309     // variable-length output record if the previous operation
310     // was a BACKSPACE or non advancing input statement.
311     recordLength.reset();
312     beganReadingRecord_ = false;
313   }
314   if (IsAfterEndfile()) {
315     handler.SignalError(IostatWriteAfterEndfile);
316     return false;
317   }
318   WriteFrame(frameOffsetInFile_, recordOffsetInFrame_ + furthestAfter, handler);
319   if (positionInRecord > furthestPositionInRecord) {
320     std::memset(Frame() + recordOffsetInFrame_ + furthestPositionInRecord, ' ',
321         positionInRecord - furthestPositionInRecord);
322   }
323   char *to{Frame() + recordOffsetInFrame_ + positionInRecord};
324   std::memcpy(to, data, bytes);
325   if (swapEndianness_) {
326     SwapEndianness(to, bytes, elementBytes);
327   }
328   positionInRecord += bytes;
329   furthestPositionInRecord = furthestAfter;
330   return true;
331 }
332 
333 bool ExternalFileUnit::Receive(char *data, std::size_t bytes,
334     std::size_t elementBytes, IoErrorHandler &handler) {
335   RUNTIME_CHECK(handler, direction_ == Direction::Input);
336   auto furthestAfter{std::max(furthestPositionInRecord,
337       positionInRecord + static_cast<std::int64_t>(bytes))};
338   if (furthestAfter > recordLength.value_or(furthestAfter)) {
339     handler.SignalError(IostatRecordReadOverrun,
340         "Attempt to read %zd bytes at position %jd in a record of %jd bytes",
341         bytes, static_cast<std::intmax_t>(positionInRecord),
342         static_cast<std::intmax_t>(*recordLength));
343     return false;
344   }
345   auto need{recordOffsetInFrame_ + furthestAfter};
346   auto got{ReadFrame(frameOffsetInFile_, need, handler)};
347   if (got >= need) {
348     std::memcpy(data, Frame() + recordOffsetInFrame_ + positionInRecord, bytes);
349     if (swapEndianness_) {
350       SwapEndianness(data, bytes, elementBytes);
351     }
352     positionInRecord += bytes;
353     furthestPositionInRecord = furthestAfter;
354     return true;
355   } else {
356     handler.SignalEnd();
357     if (access == Access::Sequential) {
358       endfileRecordNumber = currentRecordNumber;
359     }
360     return false;
361   }
362 }
363 
364 std::size_t ExternalFileUnit::GetNextInputBytes(
365     const char *&p, IoErrorHandler &handler) {
366   RUNTIME_CHECK(handler, direction_ == Direction::Input);
367   std::size_t length{1};
368   if (auto recl{EffectiveRecordLength()}) {
369     if (positionInRecord < *recl) {
370       length = *recl - positionInRecord;
371     } else {
372       p = nullptr;
373       return 0;
374     }
375   }
376   p = FrameNextInput(handler, length);
377   return p ? length : 0;
378 }
379 
380 std::optional<char32_t> ExternalFileUnit::GetCurrentChar(
381     IoErrorHandler &handler) {
382   const char *p{nullptr};
383   std::size_t bytes{GetNextInputBytes(p, handler)};
384   if (bytes == 0) {
385     return std::nullopt;
386   } else {
387     // TODO: UTF-8 decoding; may have to get more bytes in a loop
388     return *p;
389   }
390 }
391 
392 const char *ExternalFileUnit::FrameNextInput(
393     IoErrorHandler &handler, std::size_t bytes) {
394   RUNTIME_CHECK(handler, isUnformatted.has_value() && !*isUnformatted);
395   if (static_cast<std::int64_t>(positionInRecord + bytes) <=
396       recordLength.value_or(positionInRecord + bytes)) {
397     auto at{recordOffsetInFrame_ + positionInRecord};
398     auto need{static_cast<std::size_t>(at + bytes)};
399     auto got{ReadFrame(frameOffsetInFile_, need, handler)};
400     SetVariableFormattedRecordLength();
401     if (got >= need) {
402       return Frame() + at;
403     }
404     handler.SignalEnd();
405     if (access == Access::Sequential) {
406       endfileRecordNumber = currentRecordNumber;
407     }
408   }
409   return nullptr;
410 }
411 
412 bool ExternalFileUnit::SetVariableFormattedRecordLength() {
413   if (recordLength || access == Access::Direct) {
414     return true;
415   } else if (FrameLength() > recordOffsetInFrame_) {
416     const char *record{Frame() + recordOffsetInFrame_};
417     std::size_t bytes{FrameLength() - recordOffsetInFrame_};
418     if (const char *nl{
419             reinterpret_cast<const char *>(std::memchr(record, '\n', bytes))}) {
420       recordLength = nl - record;
421       if (*recordLength > 0 && record[*recordLength - 1] == '\r') {
422         --*recordLength;
423       }
424       return true;
425     }
426   }
427   return false;
428 }
429 
430 void ExternalFileUnit::SetLeftTabLimit() {
431   leftTabLimit = furthestPositionInRecord;
432   positionInRecord = furthestPositionInRecord;
433 }
434 
435 bool ExternalFileUnit::BeginReadingRecord(IoErrorHandler &handler) {
436   RUNTIME_CHECK(handler, direction_ == Direction::Input);
437   if (!beganReadingRecord_) {
438     beganReadingRecord_ = true;
439     if (access == Access::Direct) {
440       RUNTIME_CHECK(handler, openRecl);
441       auto need{static_cast<std::size_t>(recordOffsetInFrame_ + *openRecl)};
442       auto got{ReadFrame(frameOffsetInFile_, need, handler)};
443       if (got >= need) {
444         recordLength = openRecl;
445       } else {
446         recordLength.reset();
447         handler.SignalEnd();
448       }
449     } else {
450       recordLength.reset();
451       if (IsAtEOF()) {
452         handler.SignalEnd();
453       } else {
454         RUNTIME_CHECK(handler, isUnformatted.has_value());
455         if (*isUnformatted) {
456           if (access == Access::Sequential) {
457             BeginSequentialVariableUnformattedInputRecord(handler);
458           }
459         } else { // formatted sequential or stream
460           BeginVariableFormattedInputRecord(handler);
461         }
462       }
463     }
464   }
465   RUNTIME_CHECK(handler,
466       recordLength.has_value() || !IsRecordFile() || handler.InError());
467   return !handler.InError();
468 }
469 
470 void ExternalFileUnit::FinishReadingRecord(IoErrorHandler &handler) {
471   RUNTIME_CHECK(handler, direction_ == Direction::Input && beganReadingRecord_);
472   beganReadingRecord_ = false;
473   if (handler.InError() && handler.GetIoStat() != IostatEor) {
474     // Avoid bogus crashes in END/ERR circumstances; but
475     // still increment the current record number so that
476     // an attempted read of an endfile record, followed by
477     // a BACKSPACE, will still be at EOF.
478     ++currentRecordNumber;
479   } else if (IsRecordFile()) {
480     RUNTIME_CHECK(handler, recordLength.has_value());
481     recordOffsetInFrame_ += *recordLength;
482     if (access != Access::Direct) {
483       RUNTIME_CHECK(handler, isUnformatted.has_value());
484       recordLength.reset();
485       if (isUnformatted.value_or(false)) {
486         // Retain footer in frame for more efficient BACKSPACE
487         frameOffsetInFile_ += recordOffsetInFrame_;
488         recordOffsetInFrame_ = sizeof(std::uint32_t);
489       } else { // formatted
490         if (FrameLength() > recordOffsetInFrame_ &&
491             Frame()[recordOffsetInFrame_] == '\r') {
492           ++recordOffsetInFrame_;
493         }
494         if (FrameLength() > recordOffsetInFrame_ &&
495             Frame()[recordOffsetInFrame_] == '\n') {
496           ++recordOffsetInFrame_;
497         }
498         if (!pinnedFrame || mayPosition()) {
499           frameOffsetInFile_ += recordOffsetInFrame_;
500           recordOffsetInFrame_ = 0;
501         }
502       }
503     }
504     ++currentRecordNumber;
505   } else { // unformatted stream
506     furthestPositionInRecord =
507         std::max(furthestPositionInRecord, positionInRecord);
508     frameOffsetInFile_ += recordOffsetInFrame_ + furthestPositionInRecord;
509   }
510   BeginRecord();
511 }
512 
513 bool ExternalFileUnit::AdvanceRecord(IoErrorHandler &handler) {
514   if (direction_ == Direction::Input) {
515     FinishReadingRecord(handler);
516     return BeginReadingRecord(handler);
517   } else { // Direction::Output
518     bool ok{true};
519     RUNTIME_CHECK(handler, isUnformatted.has_value());
520     positionInRecord = furthestPositionInRecord;
521     if (access == Access::Direct) {
522       if (furthestPositionInRecord <
523           openRecl.value_or(furthestPositionInRecord)) {
524         // Pad remainder of fixed length record
525         WriteFrame(
526             frameOffsetInFile_, recordOffsetInFrame_ + *openRecl, handler);
527         std::memset(Frame() + recordOffsetInFrame_ + furthestPositionInRecord,
528             isUnformatted.value_or(false) ? 0 : ' ',
529             *openRecl - furthestPositionInRecord);
530         furthestPositionInRecord = *openRecl;
531       }
532     } else if (*isUnformatted) {
533       if (access == Access::Sequential) {
534         // Append the length of a sequential unformatted variable-length record
535         // as its footer, then overwrite the reserved first four bytes of the
536         // record with its length as its header.  These four bytes were skipped
537         // over in BeginUnformattedIO<Output>().
538         // TODO: Break very large records up into subrecords with negative
539         // headers &/or footers
540         std::uint32_t length;
541         length = furthestPositionInRecord - sizeof length;
542         ok = ok &&
543             Emit(reinterpret_cast<const char *>(&length), sizeof length,
544                 sizeof length, handler);
545         positionInRecord = 0;
546         ok = ok &&
547             Emit(reinterpret_cast<const char *>(&length), sizeof length,
548                 sizeof length, handler);
549       } else {
550         // Unformatted stream: nothing to do
551       }
552     } else {
553       // Terminate formatted variable length record
554       const char *lineEnding{"\n"};
555       std::size_t lineEndingBytes{1};
556 #ifdef _WIN32
557       if (!isWindowsTextFile()) {
558         lineEnding = "\r\n";
559         lineEndingBytes = 2;
560       }
561 #endif
562       ok = ok && Emit(lineEnding, lineEndingBytes, 1, handler);
563     }
564     if (IsAfterEndfile()) {
565       return false;
566     }
567     CommitWrites();
568     ++currentRecordNumber;
569     if (access != Access::Direct) {
570       impliedEndfile_ = IsRecordFile();
571       if (IsAtEOF()) {
572         endfileRecordNumber.reset();
573       }
574     }
575     return ok;
576   }
577 }
578 
579 void ExternalFileUnit::BackspaceRecord(IoErrorHandler &handler) {
580   if (access == Access::Direct || !IsRecordFile()) {
581     handler.SignalError(IostatBackspaceNonSequential,
582         "BACKSPACE(UNIT=%d) on direct-access file or unformatted stream",
583         unitNumber());
584   } else {
585     if (IsAfterEndfile()) {
586       // BACKSPACE after explicit ENDFILE
587       currentRecordNumber = *endfileRecordNumber;
588     } else {
589       DoImpliedEndfile(handler);
590       if (frameOffsetInFile_ + recordOffsetInFrame_ > 0) {
591         --currentRecordNumber;
592         if (openRecl && access == Access::Direct) {
593           BackspaceFixedRecord(handler);
594         } else {
595           RUNTIME_CHECK(handler, isUnformatted.has_value());
596           if (isUnformatted.value_or(false)) {
597             BackspaceVariableUnformattedRecord(handler);
598           } else {
599             BackspaceVariableFormattedRecord(handler);
600           }
601         }
602       }
603     }
604     BeginRecord();
605   }
606 }
607 
608 void ExternalFileUnit::FlushOutput(IoErrorHandler &handler) {
609   if (!mayPosition()) {
610     auto frameAt{FrameAt()};
611     if (frameOffsetInFile_ >= frameAt &&
612         frameOffsetInFile_ <
613             static_cast<std::int64_t>(frameAt + FrameLength())) {
614       // A Flush() that's about to happen to a non-positionable file
615       // needs to advance frameOffsetInFile_ to prevent attempts at
616       // impossible seeks
617       CommitWrites();
618     }
619   }
620   Flush(handler);
621 }
622 
623 void ExternalFileUnit::FlushIfTerminal(IoErrorHandler &handler) {
624   if (isTerminal()) {
625     FlushOutput(handler);
626   }
627 }
628 
629 void ExternalFileUnit::Endfile(IoErrorHandler &handler) {
630   if (access == Access::Direct) {
631     handler.SignalError(IostatEndfileDirect,
632         "ENDFILE(UNIT=%d) on direct-access file", unitNumber());
633   } else if (!mayWrite()) {
634     handler.SignalError(IostatEndfileUnwritable,
635         "ENDFILE(UNIT=%d) on read-only file", unitNumber());
636   } else if (IsAfterEndfile()) {
637     // ENDFILE after ENDFILE
638   } else {
639     DoEndfile(handler);
640     if (access == Access::Sequential) {
641       // Explicit ENDFILE leaves position *after* the endfile record
642       RUNTIME_CHECK(handler, endfileRecordNumber.has_value());
643       currentRecordNumber = *endfileRecordNumber + 1;
644     }
645   }
646 }
647 
648 void ExternalFileUnit::Rewind(IoErrorHandler &handler) {
649   if (access == Access::Direct) {
650     handler.SignalError(IostatRewindNonSequential,
651         "REWIND(UNIT=%d) on non-sequential file", unitNumber());
652   } else {
653     SetPosition(0, handler);
654     currentRecordNumber = 1;
655   }
656 }
657 
658 void ExternalFileUnit::SetPosition(std::int64_t pos, IoErrorHandler &handler) {
659   DoImpliedEndfile(handler);
660   frameOffsetInFile_ = pos;
661   recordOffsetInFrame_ = 0;
662   BeginRecord();
663 }
664 
665 void ExternalFileUnit::EndIoStatement() {
666   io_.reset();
667   u_.emplace<std::monostate>();
668   lock_.Drop();
669 }
670 
671 void ExternalFileUnit::BeginSequentialVariableUnformattedInputRecord(
672     IoErrorHandler &handler) {
673   std::int32_t header{0}, footer{0};
674   std::size_t need{recordOffsetInFrame_ + sizeof header};
675   std::size_t got{ReadFrame(frameOffsetInFile_, need, handler)};
676   // Try to emit informative errors to help debug corrupted files.
677   const char *error{nullptr};
678   if (got < need) {
679     if (got == recordOffsetInFrame_) {
680       handler.SignalEnd();
681     } else {
682       error = "Unformatted variable-length sequential file input failed at "
683               "record #%jd (file offset %jd): truncated record header";
684     }
685   } else {
686     std::memcpy(&header, Frame() + recordOffsetInFrame_, sizeof header);
687     recordLength = sizeof header + header; // does not include footer
688     need = recordOffsetInFrame_ + *recordLength + sizeof footer;
689     got = ReadFrame(frameOffsetInFile_, need, handler);
690     if (got < need) {
691       error = "Unformatted variable-length sequential file input failed at "
692               "record #%jd (file offset %jd): hit EOF reading record with "
693               "length %jd bytes";
694     } else {
695       std::memcpy(&footer, Frame() + recordOffsetInFrame_ + *recordLength,
696           sizeof footer);
697       if (footer != header) {
698         error = "Unformatted variable-length sequential file input failed at "
699                 "record #%jd (file offset %jd): record header has length %jd "
700                 "that does not match record footer (%jd)";
701       }
702     }
703   }
704   if (error) {
705     handler.SignalError(error, static_cast<std::intmax_t>(currentRecordNumber),
706         static_cast<std::intmax_t>(frameOffsetInFile_),
707         static_cast<std::intmax_t>(header), static_cast<std::intmax_t>(footer));
708     // TODO: error recovery
709   }
710   positionInRecord = sizeof header;
711 }
712 
713 void ExternalFileUnit::BeginVariableFormattedInputRecord(
714     IoErrorHandler &handler) {
715   if (this == defaultInput) {
716     if (defaultOutput) {
717       defaultOutput->FlushOutput(handler);
718     }
719     if (errorOutput) {
720       errorOutput->FlushOutput(handler);
721     }
722   }
723   std::size_t length{0};
724   do {
725     std::size_t need{length + 1};
726     length =
727         ReadFrame(frameOffsetInFile_, recordOffsetInFrame_ + need, handler) -
728         recordOffsetInFrame_;
729     if (length < need) {
730       if (length > 0) {
731         // final record w/o \n
732         recordLength = length;
733       } else {
734         handler.SignalEnd();
735       }
736       break;
737     }
738   } while (!SetVariableFormattedRecordLength());
739 }
740 
741 void ExternalFileUnit::BackspaceFixedRecord(IoErrorHandler &handler) {
742   RUNTIME_CHECK(handler, openRecl.has_value());
743   if (frameOffsetInFile_ < *openRecl) {
744     handler.SignalError(IostatBackspaceAtFirstRecord);
745   } else {
746     frameOffsetInFile_ -= *openRecl;
747   }
748 }
749 
750 void ExternalFileUnit::BackspaceVariableUnformattedRecord(
751     IoErrorHandler &handler) {
752   std::int32_t header{0}, footer{0};
753   auto headerBytes{static_cast<std::int64_t>(sizeof header)};
754   frameOffsetInFile_ += recordOffsetInFrame_;
755   recordOffsetInFrame_ = 0;
756   if (frameOffsetInFile_ <= headerBytes) {
757     handler.SignalError(IostatBackspaceAtFirstRecord);
758     return;
759   }
760   // Error conditions here cause crashes, not file format errors, because the
761   // validity of the file structure before the current record will have been
762   // checked informatively in NextSequentialVariableUnformattedInputRecord().
763   std::size_t got{
764       ReadFrame(frameOffsetInFile_ - headerBytes, headerBytes, handler)};
765   RUNTIME_CHECK(handler, got >= sizeof footer);
766   std::memcpy(&footer, Frame(), sizeof footer);
767   recordLength = footer;
768   RUNTIME_CHECK(handler, frameOffsetInFile_ >= *recordLength + 2 * headerBytes);
769   frameOffsetInFile_ -= *recordLength + 2 * headerBytes;
770   if (frameOffsetInFile_ >= headerBytes) {
771     frameOffsetInFile_ -= headerBytes;
772     recordOffsetInFrame_ = headerBytes;
773   }
774   auto need{static_cast<std::size_t>(
775       recordOffsetInFrame_ + sizeof header + *recordLength)};
776   got = ReadFrame(frameOffsetInFile_, need, handler);
777   RUNTIME_CHECK(handler, got >= need);
778   std::memcpy(&header, Frame() + recordOffsetInFrame_, sizeof header);
779   RUNTIME_CHECK(handler, header == *recordLength);
780 }
781 
782 // There's no portable memrchr(), unfortunately, and strrchr() would
783 // fail on a record with a NUL, so we have to do it the hard way.
784 static const char *FindLastNewline(const char *str, std::size_t length) {
785   for (const char *p{str + length}; p-- > str;) {
786     if (*p == '\n') {
787       return p;
788     }
789   }
790   return nullptr;
791 }
792 
793 void ExternalFileUnit::BackspaceVariableFormattedRecord(
794     IoErrorHandler &handler) {
795   // File offset of previous record's newline
796   auto prevNL{
797       frameOffsetInFile_ + static_cast<std::int64_t>(recordOffsetInFrame_) - 1};
798   if (prevNL < 0) {
799     handler.SignalError(IostatBackspaceAtFirstRecord);
800     return;
801   }
802   while (true) {
803     if (frameOffsetInFile_ < prevNL) {
804       if (const char *p{
805               FindLastNewline(Frame(), prevNL - 1 - frameOffsetInFile_)}) {
806         recordOffsetInFrame_ = p - Frame() + 1;
807         recordLength = prevNL - (frameOffsetInFile_ + recordOffsetInFrame_);
808         break;
809       }
810     }
811     if (frameOffsetInFile_ == 0) {
812       recordOffsetInFrame_ = 0;
813       recordLength = prevNL;
814       break;
815     }
816     frameOffsetInFile_ -= std::min<std::int64_t>(frameOffsetInFile_, 1024);
817     auto need{static_cast<std::size_t>(prevNL + 1 - frameOffsetInFile_)};
818     auto got{ReadFrame(frameOffsetInFile_, need, handler)};
819     RUNTIME_CHECK(handler, got >= need);
820   }
821   RUNTIME_CHECK(handler, Frame()[recordOffsetInFrame_ + *recordLength] == '\n');
822   if (*recordLength > 0 &&
823       Frame()[recordOffsetInFrame_ + *recordLength - 1] == '\r') {
824     --*recordLength;
825   }
826 }
827 
828 void ExternalFileUnit::DoImpliedEndfile(IoErrorHandler &handler) {
829   if (impliedEndfile_) {
830     impliedEndfile_ = false;
831     if (access != Access::Direct && IsRecordFile() && mayPosition()) {
832       DoEndfile(handler);
833     }
834   }
835 }
836 
837 void ExternalFileUnit::DoEndfile(IoErrorHandler &handler) {
838   if (access == Access::Sequential) {
839     endfileRecordNumber = currentRecordNumber;
840   }
841   FlushOutput(handler);
842   Truncate(frameOffsetInFile_ + recordOffsetInFrame_, handler);
843   BeginRecord();
844   impliedEndfile_ = false;
845 }
846 
847 void ExternalFileUnit::CommitWrites() {
848   frameOffsetInFile_ +=
849       recordOffsetInFrame_ + recordLength.value_or(furthestPositionInRecord);
850   recordOffsetInFrame_ = 0;
851   BeginRecord();
852 }
853 
854 ChildIo &ExternalFileUnit::PushChildIo(IoStatementState &parent) {
855   OwningPtr<ChildIo> current{std::move(child_)};
856   Terminator &terminator{parent.GetIoErrorHandler()};
857   OwningPtr<ChildIo> next{New<ChildIo>{terminator}(parent, std::move(current))};
858   child_.reset(next.release());
859   return *child_;
860 }
861 
862 void ExternalFileUnit::PopChildIo(ChildIo &child) {
863   if (child_.get() != &child) {
864     child.parent().GetIoErrorHandler().Crash(
865         "ChildIo being popped is not top of stack");
866   }
867   child_.reset(child.AcquirePrevious().release()); // deletes top child
868 }
869 
870 void ChildIo::EndIoStatement() {
871   io_.reset();
872   u_.emplace<std::monostate>();
873 }
874 
875 bool ChildIo::CheckFormattingAndDirection(Terminator &terminator,
876     const char *what, bool unformatted, Direction direction) {
877   bool parentIsInput{!parent_.get_if<IoDirectionState<Direction::Output>>()};
878   bool parentIsFormatted{parentIsInput
879           ? parent_.get_if<FormattedIoStatementState<Direction::Input>>() !=
880               nullptr
881           : parent_.get_if<FormattedIoStatementState<Direction::Output>>() !=
882               nullptr};
883   bool parentIsUnformatted{!parentIsFormatted};
884   if (unformatted != parentIsUnformatted) {
885     terminator.Crash("Child %s attempted on %s parent I/O unit", what,
886         parentIsUnformatted ? "unformatted" : "formatted");
887     return false;
888   } else if (parentIsInput != (direction == Direction::Input)) {
889     terminator.Crash("Child %s attempted on %s parent I/O unit", what,
890         parentIsInput ? "input" : "output");
891     return false;
892   } else {
893     return true;
894   }
895 }
896 
897 } // namespace Fortran::runtime::io
898