[fpc-devel]Source files involved in (text) file handling (Q & A)

[Tom Verhoeff]

I am looking into the handling of text files within FreePascal
programs.  I have found that the text file type is defined in

	fpc/rtl/inc/textrec.inc and text.inc via TextRec,
	  and system.inc (for def. of type FileFunc),
              systemh.inc (for routine headers)

However, text.inc refers to routines named

	Do_Open, Do_Read, Do_Write, DoClose, Do_IsDevice, Do_FilePos, Do_Seek

which work on file handles, and I cannot find their definitions.

It is also not clear to me which higher level file includes
system.inc and text.inc (textrec.inc is included in system.inc).

    Apologies!  I did some more tracking and found that rtl/linux/
    has syslinux.pp, which includes system.pp, which includes
    sysunixh.inc and sysunix.inc (located in rtl/unix/). Then
    sysunixh.inc includes systemh.inc, and and sysunix.inc includes
    system.inc and text.inc.  Furthermore sysunix.inc has the
    definitions for Do_xxx under Low Level File Routines in terms of
    routines named sys_xxx define in rtl/linux/syscalls.inc.  A rather
    contorted maze, if I may say so, :-).  In summary:

    fpc/
      rtl/
        inc/
          textrec.inc  defines type TextRec
          text.inc     implements routines Assign, Reset, Rewrite, Close, etc.
                       on TextRec, using FileFunc, in terms of routines
                       Do_Open, Do_Read, Do_Write, Do_Close on handles
                       (Do_Open is exceptional and works on var f that
                       must have handle and mode as first two fields)
          systemh.inc  declares routines Assign, Reset, Rewrite, Close, etc.
                       on Text
          system.inc   defines type FileFunc = Procedure(var t: TextRec);
        linux/
          syscalls.inc implements Sys_Open, Sys_Read, Sys_Write, Sys_Close, etc.
          syslinux.pp  includes system.pp
          system.pp    includes rtl/unix/{sysunixh,sysunix}.inc
        unix/
          sysunixh.inc includes rtl/inc/systemh.inc
          sysunix.inc  includes rtl/{inc/{sytem,text},linux/syscalls}.inc,
                       implements Do_Open, Do_Read, Do_Write, Do_Close, etc.
                       in terms of Sys_xxxx

  (I had no interest in tracing the Windows branch.)

By the way, in the implementation for SeekEof (in text.inc), I read
that the file position is NOT actually advanced, UNLESS the file is
associated with a device.  The implementation for SeekEoln always
advances the file position.  The documentation (ref.pdf) states that
both SeekEof and SeekEoln advance the file position.  An experiment
shows that the implementation is right (small wonder :-).

Reason for my interest is that I wanted to know why FilePos
and Seek are not implemented for text files.  The answer seems to
be that there is a problem if they are associated with devices,
which are not seekable.  I would like to have FilePos and Seek
when the text files are not associated with a device, and that seems
doable somehow.  They could just return an error if the text file
is not seekable.  I would probably also be happy if SeekEoln would
NOT advance the file position whenever possible (just like SeekEof).

I hope this message may still be useful in some archive.

Thanks for your attention,

	Tom Verhoeff