TFile

class TFile : public TDirectory

    private:

            TFile(const TFile&)
       void operator=(const TFile&)

    protected:

                void Init(Bool_t create)
       virtual Int_t SysClose(Int_t fd)
       virtual Int_t SysOpen(const char* pathname, Int_t flags, UInt_t mode)
       virtual Int_t SysRead(Int_t fd, void* buf, Int_t len)
      virtual Seek_t SysSeek(Int_t fd, Seek_t offset, Int_t whence)
       virtual Int_t SysStat(Int_t fd, Long_t* id, Long_t* size, Long_t* flags, Long_t* modtime)
       virtual Int_t SysSync(Int_t fd)
       virtual Int_t SysWrite(Int_t fd, const void* buf, Int_t len)

    public:

                        TFile()
                        TFile(const char* fname, const Option_t* option, const char* ftitle, Int_t compress = 1)
                virtual ~TFile()
         static TClass* Class()
           virtual void Close(const Option_t* option)
           virtual void Copy(TObject&) const
           virtual void Delete(const char* namecycle)
           virtual void Draw(const Option_t* option)
           virtual void DrawMap(const char* keys = "*", const Option_t* option)
           virtual void FillBuffer(char*& buffer)
           virtual void Flush()
                  Int_t GetBestBuffer() const
               Double_t GetBytesRead() const
               Double_t GetBytesWritten() const
               TArrayC* GetClassIndex() const
                Float_t GetCompressionFactor()
                  Int_t GetCompressionLevel() const
         virtual Seek_t GetEND() const
          virtual Int_t GetErrno() const
                  Int_t GetFd() const
        static Double_t GetFileBytesRead()
        static Double_t GetFileBytesWritten()
                 TList* GetListOfFree() const
             TObjArray* GetListOfProcessIDs() const
          virtual Int_t GetNbytesFree() const
          virtual Int_t GetNbytesInfo() const
          virtual Int_t GetNfree() const
          virtual Int_t GetNProcessIDs() const
      virtual Option_t* GetOption() const
                  Int_t GetRecordHeader(char* buf, Seek_t first, Int_t maxbytes, Int_t& nbytes, Int_t& objlen, Int_t& keylen)
         virtual Seek_t GetSeekFree() const
         virtual Seek_t GetSeekInfo() const
         virtual Seek_t GetSize() const
                 TList* GetStreamerInfoList()
                  Int_t GetVersion() const
           virtual void IncrementProcessIDs()
        virtual TClass* IsA() const
         virtual Bool_t IsOpen() const
           virtual void ls(const Option_t* option) const
           virtual void MakeFree(Seek_t first, Seek_t last)
           virtual void MakeProject(const char* dirname, const char* classes = "*", const Option_t* option = "new")
           virtual void Map()
          static TFile* Open(const char* name, const Option_t* option, const char* ftitle, Int_t compress = 1, Int_t netopt = 0)
           virtual void Paint(const Option_t* option)
           virtual void Print(const Option_t* option) const
         virtual Bool_t ReadBuffer(char* buf, Int_t len)
           virtual void ReadFree()
           virtual void ReadStreamerInfo()
          virtual Int_t Recover()
          virtual Int_t ReOpen(const Option_t* mode)
           virtual void ResetErrno() const
           virtual void Seek(Seek_t offset, TFile::ERelativeTo pos = kBeg)
           virtual void SetCompressionLevel(Int_t level = 1)
           virtual void SetEND(Seek_t last)
            static void SetFileBytesRead(Double_t bytes = 0)
            static void SetFileBytesWritten(Double_t bytes = 0)
           virtual void SetOption(const Option_t* option = ">")
           virtual void ShowMembers(TMemberInspector& insp, char* parent)
           virtual void ShowStreamerInfo()
          virtual Int_t Sizeof() const
           virtual void Streamer(TBuffer& b)
                   void StreamerNVirtual(TBuffer& b)
                   void SumBuffer(Int_t bufsize)
           virtual void UseCache(Int_t maxCacheSize = 10, Int_t pageSize = TCache::kDfltPageSize)
          virtual Int_t Write(const char* name = "0", Int_t opt = 0, Int_t bufsiz = 0)
         virtual Bool_t WriteBuffer(const char* buf, Int_t len)
           virtual void WriteFree()
           virtual void WriteHeader()
           virtual void WriteStreamerInfo()

Data Members

    protected:

             Double_t fSumBuffer    Sum of buffer sizes of objects written so far
             Double_t fSum2Buffer   Sum of squares of buffer sizes of objects written so far
             Double_t fBytesWrite   Number of bytes written to this file
             Double_t fBytesRead    Number of bytes read from this file
               Seek_t fBEGIN        First used byte in file
               Seek_t fEND          Last used byte in file
               Seek_t fSeekFree     Location on disk of free segments structure
               Seek_t fSeekInfo     Location on disk of StreamerInfo record
                Int_t fD            File descriptor
                Int_t fVersion      File format version
                Int_t fCompress     Compression level from 0(not compressed) to 9 (max compression)
                Int_t fNbytesFree   Number of bytes for free segments structure
                Int_t fNbytesInfo   Number of bytes for StreamerInfo record
                Int_t fWritten      Number of objects written so far
                Int_t fNProcessIDs  Number of TProcessID written to this file
              TString fRealName     Effective real file name (not original url)
              TString fOption       File options
               Char_t fUnits        Number of bytes for file pointers
               TList* fFree         Free segments linked list table
             TArrayC* fClassIndex   !Index of TStreamerInfo classes written to this file
              TCache* fCache        !Page cache used to reduce number of small I/O's
           TObjArray* fProcessIDs   !Array of pointers to TProcessIDs
      static Double_t fgBytesWrite  Number of bytes written by all TFile objects
      static Double_t fgBytesRead   Number of bytes read by all TFile objects

    public:

            static const enum TFile:: kStartBigFile   
            static const enum TFile:: kRecovered      
            static const enum TFile:: kHasReferences  
            static const enum TFile:: kDevNull        
            static const enum TFile:: kWriteError     
      static const TFile::ERelativeTo kBeg            
      static const TFile::ERelativeTo kCur            
      static const TFile::ERelativeTo kEnd            

See also

TNetFile, TRFIOFile, TWebFile

Class Description

*-*-*-*-*-*-*-*-*-*-*-*File default Constructor*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
*-*                    ========================

*-*-*-*-*-*-*-*-*-*-*-*File Constructor*-*--*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
*-*                    ================
  If Option = NEW or CREATE   create a new file and open it for writing,
                              if the file already exists the file is
                              not opened.
            = RECREATE        create a new file, if the file already
                              exists it will be overwritten.
            = UPDATE          open an existing file for writing.
                              if no file exists, it is created.
            = READ            open an existing file for reading.
  If the constructor failed in any way IsZombie() will return true.
  Use IsOpen() to check if the file is (still) open.

  The parameter name is used to identify the file in the current job
    name may be different in a job writing the file and another job
    reading/writing the file.
  When the file is created, the name of the file seen from the file system
    is fname. It is recommended to specify fname as "file.root"
    The suffix root will be used by object browsers to automatically
    identify ROOT files.
  The title of the file (ftitle) will be shown by the ROOT browsers.

  A ROOT file (like a Unix file system) may contain objects and
    directories. There are no restrictions for the number of levels
    of directories.

  A ROOT file is designed such that one can write in the file in pure
    sequential mode (case of BATCH jobs). In this case, the file may be
    read sequentially again without using the file index written
    at the end of the file. In case of a job crash, all the information
    on the file is therefore protected.
  A ROOT file can be used interactively. In this case, one has the
    possibility to delete existing objects and add new ones.
  When an object is deleted from the file, the freed space is added
  into the FREE linked list (fFree). The FREE list consists of a chain
  of consecutive free segments on the file. At the same time, the first
  4 bytes of the freed record on the file are overwritten by GAPSIZE
  where GAPSIZE = -(Number of bytes occupied by the record).

  compress = 0 objects written to this file will not be compressed.
  compress = 1 minimal compression level but fast.
  ....
  compress = 9 maximal compression level but slow.

  Note that the compression level may be changed at any time.
  The new compression level will only apply to newly written objects.
  The function TFile::Map shows the compression factor
  for each object written to this file.
  The function TFile::GetCompressionFactor returns the global
  compression factor for this file.

  A ROOT file is a suite of consecutive data records with the following
    format (see also the TKey class);
 TKey ---------------------
      byte 1->4  Nbytes    = Length of compressed object (in bytes)
           5->6  Version   = TKey version identifier
           7->10 ObjLen    = Length of uncompressed object
          11->14 Datime    = Date and time when object was written to file
          15->16 KeyLen    = Length of the key structure (in bytes)
          17->18 Cycle     = Cycle of key
          19->22 SeekKey   = Pointer to record itself (consistency check)
          23->26 SeekPdir  = Pointer to directory header
          27->27 lname     = Number of bytes in the class name
          28->.. ClassName = Object Class Name
          ..->.. lname     = Number of bytes in the object name
          ..->.. Name      = lName bytes with the name of the object
          ..->.. lTitle    = Number of bytes in the object title
          ..->.. Title     = Title of the object
          -----> DATA      = Data bytes associated to the object

  The first data record starts at byte fBEGIN (currently set to kBEGIN)
  Bytes 1->kBEGIN contain the file description:
       byte  1->4  "root"      = Root file identifier
             5->8  fVersion    = File format version
             9->12 fBEGIN      = Pointer to first data record
            13->16 fEND        = Pointer to first free word at the EOF
            17->20 fSeekFree   = Pointer to FREE data record
            21->24 fNbytesFree = Number of bytes in FREE data record
            25->28 nfree       = Number of free data records
            29->32 fNbytesName = Number of bytes in TNamed at creation time
            33->33 fUnits      = Number of bytes for file pointers
            34->37 fCompress   = Zip compression level
            38->41 fSeekInfo   = Pointer to TStreamerInfo record
            42->45 fNbytesInfo = Number of bytes in TStreamerInfo record
            46->62 fUUID       = Universal Unique ID

/*

*/


  The structure of a directory is shown in TDirectory::TDirectory

*-*-*-*-*-*-*-*-*-*-*-*File destructor*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
*-*                    ===============

 Initialize a TFile object.

*-*-*-*-*-*-*-*-*-*-*-*Close a file*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
*-*                    ============

*-*-*-*-*-*-*-*-*-*-*-*-*Delete object namecycle*-*-*-*-*-*-*-*-*-*-*-*-*-*
*-*                      =======================
  namecycle identifies an object in the top directory of the file
   namecycle has the format name;cycle
   name  = * means all
   cycle = * means all cycles (memory and keys)
   cycle = "" or cycle = 9999 ==> apply to a memory object
   When name=* use T* to delete subdirectories also

   examples:
     foo   : delete object named foo in memory
     foo;1 : delete cycle 1 of foo on file
     foo;* : delete all cycles of foo on disk and also from memory
     *;2   : delete all objects on file having the cycle 2
     *;*   : delete all objects from memory and file
    T*;*   : delete all objects from memory and file and all subdirectories

*-*-*-*-*-*-*-*-*-*-*-*Fill Graphics Structure and Paint-*-*-*-*-*-*-*-*-*-*
*-*                    =================================
 Loop on all objects (memory or file) and all subdirectories

 Draw map of objects in this file

 Synchornize a file's in-core and on-disk states.

*-*-*-*-*-*-*-*-*-*-*-*Encode file output buffer*-*-*-*-*-*-*
*-*                    =========================
 The file output buffer contains only the FREE data record

*-*-*-*-*-*-*-*Return the best buffer size of objects on this file*-*-*-*-*-*
*-*            ===================================================

  The best buffer size is estimated based on the current mean value
  and standard deviation of all objects written so far to this file.
  Returns mean value + one standard deviation.

*-*-*-*-*-*-*-*-*-*Return the file compression factor*-*-*-*-*-*-*-*-*-*
*-*                =================================

  Add total number of compressed/uncompressed bytes for each key.
  return ratio of the two.

 Method returning errno. Is overriden in TRFIOFile.

 Method resetting the errno. Is overridden in TRFIOFile.

*-*-*-*-*-*-*-*-*Read the logical record header starting at position first
*-*              =========================================================
 maxbytes bytes are read into buf
 the function reads nread bytes where nread is the minimum of maxbytes
 and the number of bytes before the end of file.
 the function returns nread.
 In output arguments:
    nbytes : number of bytes in record
             if negative, this is a deleted record
             if 0, cannot read record, wrong value of argument first
    objlen : uncompressed object size
    keylen : length of logical record header
 Note that the arguments objlen and keylen are returned only if maxbytes >=16

 Returns the current file size. Returns -1 in case the file could not
 be stat'ed.

 Read the list of TStreamerInfo objects written to this file.
 The function returns a TList. It is the user'responsability
 to delete the list created by this function.

 Using the list, one can access additional information,eg:
   TFile f("myfile.root");
   TList *list = f.GetStreamerInfoList();
   TStreamerInfo *info = (TStreamerInfo*)list->FindObject("MyClass");
   Int_t classversionid = info->GetClassVersion();
   delete list;

*-*-*-*-*-*-*-*-*-*-*-*List File contents*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
*-*                    ==================
  Indentation is used to identify the file tree
  Subdirectories are listed first
  then objects in memory
  then objects on the file

 Returns kTRUE in case file is open and kFALSE if file is not open.

*-*-*-*-*-*-*-*-*-*-*-*Mark unused bytes on the file*-*-*-*-*-*-*-*-*-*-*
*-*                    =============================
  The list of free segments is in the fFree linked list
  When an object is deleted from the file, the freed space is added
  into the FREE linked list (fFree). The FREE list consists of a chain
  of consecutive free segments on the file. At the same time, the first
  4 bytes of the freed record on the file are overwritten by GAPSIZE
  where GAPSIZE = -(Number of bytes occupied by the record).

*-*-*-*-*-*-*-*-*-*List the contents of a file sequentially*-*-*-*-*-*
*-*                ========================================

  For each logical record found, it prints
     Date/Time  Record_Adress Logical_Record_Length  ClassName  CompressionFactor

  Example of output
  20010404/150437  At:64        N=150       TFile
  20010404/150440  At:214       N=28326     TBasket        CX =  1.13
  20010404/150440  At:28540     N=29616     TBasket        CX =  1.08
  20010404/150440  At:58156     N=29640     TBasket        CX =  1.08
  20010404/150440  At:87796     N=29076     TBasket        CX =  1.10
  20010404/150440  At:116872    N=10151     TBasket        CX =  3.15
  20010404/150441  At:127023    N=28341     TBasket        CX =  1.13
  20010404/150441  At:155364    N=29594     TBasket        CX =  1.08
  20010404/150441  At:184958    N=29616     TBasket        CX =  1.08
  20010404/150441  At:214574    N=29075     TBasket        CX =  1.10
  20010404/150441  At:243649    N=9583      TBasket        CX =  3.34
  20010404/150442  At:253232    N=28324     TBasket        CX =  1.13
  20010404/150442  At:281556    N=29641     TBasket        CX =  1.08
  20010404/150442  At:311197    N=29633     TBasket        CX =  1.08
  20010404/150442  At:340830    N=29091     TBasket        CX =  1.10
  20010404/150442  At:369921    N=10341     TBasket        CX =  3.09
  20010404/150442  At:380262    N=509       TH1F           CX =  1.93
  20010404/150442  At:380771    N=1769      TH2F           CX =  4.32
  20010404/150442  At:382540    N=1849      TProfile       CX =  1.65
  20010404/150442  At:384389    N=18434     TNtuple        CX =  4.51
  20010404/150442  At:402823    N=307       KeysList
  20010404/150443  At:403130    N=4548      StreamerInfo   CX =  3.65
  20010404/150443  At:407678    N=86        FreeSegments
  20010404/150443  At:407764    N=1         END

*-*-*-*-*-*-*-*-*-*-*-*Paint all objects in the file*-*-*-*-*-*-*-*-*-*-*
*-*                    =============================

*-*-*-*-*-*-*-*-*-*-*-*Print all objects in the file*-*-*-*-*-*-*-*-*-*-*
*-*                    =============================

 Read a buffer from the file. This is the basic low level read operation.
 Returns kTRUE in case of failure.

*-*-*-*-*-*-*-*-*-*-*-*-*Read the FREE linked list*-*-*-*-*-*-*-*-*-*-*-*-*
*-*                      =========================
  Every file has a linked list (fFree) of free segments
  This linked list has been written on the file via WriteFree
  as a single data record

*-*-*-*-*-*-*-*-*Attempt to recover file if not correctly closed*-*-*-*-*
*-*              ===============================================

  The function returns the number of keys that have been recovered.
  If no keys can be recovered, the file will be declared Zombie by
  the calling function.

 Reopen a file with a different access mode, like from READ to
 UPDATE or from NEW, CREATE, RECREATE, UPDATE to READ. Thus the
 mode argument can be either "READ" or "UPDATE". The method returns
 0 in case the mode was successfully modified, 1 in case the mode
 did not change (was already as requested or wrong input arguments)
 and -1 in case of failure, in which case the file cannot be used
 anymore. The current directory (gFile) is changed to this file.

 Seek to a specific position in the file. Pos it either kBeg, kCur or kEnd.

*-*-*-*-*-*-*-*-*-*Set level of compression for this file*-*-*-*-*-*-*-*
*-*                ======================================

  level = 0 objects written to this file will not be compressed.
  level = 1 minimal compression level but fast.
  ....
  level = 9 maximal compression level but slow.

  Note that the compression level may be changed at any time.
  The new compression level will only apply to newly written objects.
  The function TFile::Map shows the compression factor
  for each object written to this file.
  The function TFile::GetCompressionFactor returns the global
  compression factor for this file.

*-*-*-*-*-*-*Return the size in bytes of the file header-*-*-*-*-*-*-*-*
*-*          ===========================================

 Stream a TFile object.

*-*-*-*-*Increment statistics for buffer sizes of objects in this file*-*-*
*-*      =============================================================

 Activate caching. Use maxCacheSize to specify the maximum cache size
 in MB's (default is 10 MB) and pageSize to specify the page size
 (default is 512 KB). To turn off the cache use maxCacheSize=0.
 Not needed for normal disk files since the operating system will
 do proper caching (via the "buffer cache"). Use it for TNetFile,
 TWebFile, TRFIOFile, TDCacheFile, etc.

*-*-*-*-*-*-*-*-*-*Write memory objects to this file*-*-*-*-*-*-*-*-*-*
*-*                =================================
  Loop on all objects in memory (including subdirectories).
  A new key is created in the KEYS linked list for each object.
  The list of keys is then saved on the file (via WriteKeys)
  as a single data record.
  For values of opt see TObject::Write().
  The directory header info is rewritten on the directory header record.
  The linked list of FREE segments is written.
  The file header is written (bytes 1->fBEGIN).

 Write a buffer to the file. This is the basic low level write operation.
 Returns kTRUE in case of failure.

*-*-*-*-*-*-*-*-*-*-*-*Write FREE linked list on the file *-*-*-*-*-*-*-*
*-*                    ==================================
  The linked list of FREE segments (fFree) is written as a single data
  record

*-*-*-*-*-*-*-*-*-*-*-*Write File Header*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
*-*                    =================

 Generate code in directory dirname for all classes specified in argument classes
 If classes = "*" (default), the function generates an include file for each
 class in the StreamerInfo list for which a TClass object does not exist.
 One can restrict the list of classes to be generated by using expressions like:
   classes = "Ali*" generate code only for classes starting with Ali
   classes = "myClass" generate code for class MyClass only.

 if option = "new" (default) a new directory dirname is created.
                   If dirname already exist, an error message is printed
                   and the function returns.
 if option = "recreate", then;
                   if dirname does not exist, it is created (like in "new")
                   if dirname already exist, all existing files in dirname
                   are deleted before creating the new files.
 if option = "update", then new classes are added to the existing directory.
                   Existing classes with the same name are replaced by the
                   new definition. If the directory dirname doest not exist,
                   same effect as "new".
 if, in addition to one of the 3 above options, the option "+" is specified,
 the function will generate:
   - a script called MAKE to build the shared lib
   - a LinkDef.h file
   - rootcint will be run to generate a dirnameProjectDict.cxx file
   - dirnameProjectDict.cxx will be compiled with the current options in compiledata.h
   - a shared lib dirname.so will be created.
 if the option "++" is specified, the generated shared lib is dynamically
 linked with the current executable module.
 example:
  file.MakeProject("demo","*","recreate++");
  - creates a new directory demo unless it already exist
  - clear the previous directory content
  - generate the xxx.h files for all classes xxx found in this file
    and not yet known to the CINT dictionary.
  - creates the build script MAKE
  - creates a LinkDef.h file
  - runs rootcint generating demoProjectDict.cxx
  - compiles demoProjectDict.cxx into demoProjectDict.o
  - generates a shared lib demo.so
  - dynamically links the shared lib demo.so to the executable
  If only the option "+" had been specified, one can still link the
  shared lib to the current executable module with:
     gSystem->load("demo/demo.so");

 Read the list of StreamerInfo from this file
 The key with name holding the list of TStreamerInfo objects is read.
 The corresponding TClass objects are updated.

 Show the StreamerInfo of all classes written to this file.

  Write the list of TStreamerInfo as a single object in this file
  The class Streamer description for all classes written to this file
  is saved.
  see class TStreamerInfo

 Static member function allowing the creation/opening of either a
 TFile, TNetFile, TWebFile or any TFile derived class for which an
 plugin library handler has been registered with the plugin manager
 (for the plugin manager see the TPluginManager class). The returned
 type of TFile depends on the file name. If the file starts with
 "root:", "roots:" or "rootk:" a TNetFile object will be returned,
 with "http:" a TWebFile, with "file:" a local TFile, etc. (see the
 list of TFile plugin handlers for regular axpressions that will be
 checked) and as last a local file will be tried.
 Before opening a file via TNetFile a check is made to see if the URL
 specifies a local file. If that is the case the file will be opened
 via a normal TFile. To force the opening of a local file via a
 TNetFile use either TNetFile directly or specify as host "localhost".
 For the meaning of the options and other arguments see the constructors
 of the individual file classes. In case of error returns 0.

 Interface to system open. All arguments like in POSIX open().

 Interface to system close. All arguments like in POSIX close().

 Interface to system read. All arguments like in POSIX read().

 Interface to system write. All arguments like in POSIX write().

 Interface to system lseek. All arguments like in POSIX lseek()
 except that the offset and return value are of a type which will
 be able to handle 64 bit file systems in the future.

 Return file stat information. The interface and return value is
 identical to TSystem::GetPathInfo(). The function returns 0 in
 case of success and 1 if the file could not be stat'ed.

 Interface to system fsync. All arguments like in POSIX fsync().

Inline Functions

               void operator=(const TFile&)
               void Copy(TObject&) const
           TArrayC* GetClassIndex() const
              Int_t GetCompressionLevel() const
             Seek_t GetEND() const
              Int_t GetFd() const
         TObjArray* GetListOfProcessIDs() const
             TList* GetListOfFree() const
              Int_t GetNfree() const
              Int_t GetNProcessIDs() const
          Option_t* GetOption() const
           Double_t GetBytesRead() const
           Double_t GetBytesWritten() const
              Int_t GetVersion() const
              Int_t GetNbytesInfo() const
              Int_t GetNbytesFree() const
             Seek_t GetSeekFree() const
             Seek_t GetSeekInfo() const
               void IncrementProcessIDs()
               void SetEND(Seek_t last)
               void SetOption(const Option_t* option = ">")
            TClass* Class()
            TClass* IsA() const
               void ShowMembers(TMemberInspector& insp, char* parent)
               void StreamerNVirtual(TBuffer& b)