TFile()
File default Constructor.
TFile(const char *fname1, Option_t *option, const char *ftitle, Int_t compress)
Opens or creates a local ROOT file whose name is fname1. It is
recommended to specify fname1 as "<file>.root". The suffix ".root"
will be used by object browsers to automatically identify the file as
a ROOT file. If the constructor fails in any way IsZombie() will
return true. Use IsOpen() to check if the file is (still) open.
To open non-local files use the static TFile::Open() method, that
will take care of opening the files using the correct remote file
access plugin.
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.
= NET used by derived remote file access
classes, not a user callable option
= WEB used by derived remote http access
class, not a user callable option
The file can be specified as a URL of the form:
file:///user/rdm/bla.root or file:/user/rdm/bla.root
The file can also be a member of an archive, in which case it is
specified as:
multi.zip#file.root or multi.zip#0
which will open file.root which is a member of the file multi.zip
archive or member 1 from the archive. For more on archive file
support see the TArchiveFile class.
TFile and its remote access plugins can also be used to open any
file, i.e. also non ROOT files, using:
file.tar?filetype=raw
This is convenient because the many remote file access plugins allow
easy access to/from the many different mass storage systems.
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).
Option compress is used to specify the compression level:
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.
In case the file does not exist or is not a valid ROOT file,
it is made a Zombie. One can detect this situation with a code like:
TFile f("file.root");
if (f.IsZombie()) {
cout << "Error opening file" << endl;
exit(-1);
}
A ROOT file is a suite of consecutive data records (TKey's) with
the following format (see also the TKey class). If the key is
located past the 32 bit file limit (> 2 GB) then some fields will
be 8 instead of 4 bytes:
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 [19->26] SeekKey = Pointer to record itself (consistency check)
23->26 [27->34] SeekPdir = Pointer to directory header
27->27 [35->35] lname = Number of bytes in the class name
28->.. [36->..] 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, when fVersion >= 1000000
it is a large file (> 2 GB) and the offsets will be 8 bytes long and
fUnits will be set to 8:
1->4 "root" = Root file identifier
5->8 fVersion = File format version
9->12 fBEGIN = Pointer to first data record
13->16 [13->20] fEND = Pointer to first free word at the EOF
17->20 [21->28] fSeekFree = Pointer to FREE data record
21->24 [29->32] fNbytesFree = Number of bytes in FREE data record
25->28 [33->36] nfree = Number of free data records
29->32 [37->40] fNbytesName = Number of bytes in TNamed at creation time
33->33 [41->41] fUnits = Number of bytes for file pointers
34->37 [42->45] fCompress = Zip compression level
38->41 [46->53] fSeekInfo = Pointer to TStreamerInfo record
42->45 [54->57] fNbytesInfo = Number of bytes in TStreamerInfo record
46->63 [58->75] fUUID = Universal Unique ID
The structure of a directory is shown in TDirectory::TDirectory
void Init(Bool_t create)
Initialize a TFile object.
TFile implementations providing asynchronous open functionality need to
override this method to run the appropriate checks before calling this
standard initialization part. See TXNetFile::Init for an example.
void Close(Option_t *option)
Close a file.
If option == "R", all TProcessIDs referenced by this file are deleted.
Calling TFile::Close("R") might be necessary in case one reads a long list
of files having TRef, writing some of the referenced objects or TRef
to a new file. If the TRef or referenced objects of the file being closed
will not be referenced again, it is possible to minimize the size
of the TProcessID data structures in memory by forcing a delete of
the unused TProcessID.
void Delete(const char *namecycle)
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
void Draw(Option_t *option)
Fill Graphics Structure and Paint.
Loop on all objects (memory or file) and all subdirectories.
void Flush()
Synchronize a file's in-core and on-disk states.
void FillBuffer(char *&buffer)
Encode file output buffer.
The file output buffer contains only the FREE data record.
Int_t GetBestBuffer()
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.
Float_t GetCompressionFactor()
Return the file compression factor.
Add total number of compressed/uncompressed bytes for each key.
return ratio of the two.
Int_t GetRecordHeader(char *buf, Long64_t first, Int_t maxbytes, Int_t &nbytes, Int_t &objlen, Int_t &keylen)
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
Long64_t GetSize()
Returns the current file size. Returns -1 in case the file could not
be stat'ed.
void ls(Option_t *option)
List File contents.
Indentation is used to identify the file tree.
Subdirectories are listed first, then objects in memory,
then objects on the file.
void MakeFree(Long64_t first, Long64_t last)
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).
void Map()
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
Bool_t ReadBuffers(char *buf, Long64_t *pos, Int_t *len, Int_t nbuf)
Read the nbuf blocks described in arrays pos and len,
where pos[i] is the seek position of block i of length len[i].
Note that for nbuf=1, this call is equivalent to TFile::ReafBuffer.
This function is overloaded by TNetFile, TWebFile, etc.
Returns kTRUE in case of failure.
Int_t ReadBufferViaCache(char *buf, Int_t len)
Read buffer via cache. Returns 0 if cache is not active, 1 in case
read via cache was successful, 2 in case read via cache failed.
void ReadFree()
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.
Int_t Recover()
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.
Int_t ReOpen(Option_t *mode)
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.
void SetCompressionLevel(Int_t level)
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.
Int_t Sizeof()
Return the size in bytes of the file header.
void SumBuffer(Int_t bufsize)
Increment statistics for buffer sizes of objects in this file.
Int_t Write(const char *, Int_t opt, Int_t bufsiz)
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).
Int_t WriteBufferViaCache(const char *buf, Int_t len)
Write buffer via cache. Returns 0 if cache is not active, 1 in case
write via cache was successful, 2 in case write via cache failed.
void WriteFree()
Write FREE linked list on the file.
The linked list of FREE segments (fFree) is written as a single data
record.
void ShowStreamerInfo()
Show the StreamerInfo of all classes written to this file.
TFile * Open(const char *name, Option_t *option, const char *ftitle, Int_t compress, Int_t netopt)
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 in $ROOTSYS/etc/system.rootrc for regular
expressions 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".
The netopt argument is only used by TNetFile. For the meaning of the
options and other arguments see the constructors of the individual
file classes. In case of error returns 0.
TFileOpenHandle * AsyncOpen(const char *name, Option_t *option, const char *ftitle, Int_t compress, Int_t netopt)
Static member function to submit an open request. The request will be
processed asynchronously. See TFile::Open(const char *, ...) for an
explanation of the arguments. A handler is returned which is to be passed
to TFile::Open(TFileOpenHandle *) to get the real TFile instance once
the file is open.
This call never blocks and it is provided to allow parallel submission
of file opening operations expected to take a long time.
TFile::Open(TFileOpenHandle *) may block if the file is not yet ready.
The sequence
TFile::Open(TFile::AsyncOpen(const char *, ...))
is equivalent to
TFile::Open(const char *, ...) .
To be effective, the underlying TFile implementation must be able to
support asynchronous open functionality. Currently, only TXNetFile
supports it. If the functionality is not implemented, this call acts
transparently by returning an handle with the arguments for the
standard synchronous open run by TFile::Open(TFileOpenHandle *).
The retuned handle will be adopted by TFile after opening completion
in TFile::Open(TFileOpenHandle *); if opening is not finalized the
handle must be deleted by the caller.
TFile * Open(TFileOpenHandle *fh)
Waits for the completion of an asynchronous open request.
Returns the associated TFile, transferring ownership of the
handle to the TFile instance.
Int_t SysOpen(const char *pathname, Int_t flags, UInt_t mode)
Interface to system open. All arguments like in POSIX open().
Int_t SysWrite(Int_t fd, const void *buf, Int_t len)
Interface to system write. All arguments like in POSIX write().
Long64_t SysSeek(Int_t fd, Long64_t offset, Int_t whence)
Interface to system lseek. All arguments like in POSIX lseek()
except that the offset and return value are of a type which are
able to handle 64 bit file systems.
Int_t SysSync(Int_t fd)
Interface to system fsync. All arguments like in POSIX fsync().
Long64_t GetFileBytesWritten()
Static function returning the total number of bytes written to all files.
Does not take into account what might still be in the write caches.
Bool_t Matches(const char *url)
Return kTRUE if 'url' matches the coordinates of this file.
The check is implementation dependent and may need to be overload
by each TFile implememtation relying on this check.
The default implementation checks teh file name only.
const TUrl * GetEndpointUrl(const char* name)
Get final URL for file being opened asynchronously.
Returns 0 is the information is not yet available.
Author: Rene Brun 28/11/94
Last update: root/base:$Name: $:$Id: TFile.cxx,v 1.178 2006/06/30 14:24:05 rdm Exp $
Copyright (C) 1995-2000, Rene Brun and Fons Rademakers. *
ROOT page - Class index - Class Hierarchy - Top of the page
This page has been automatically generated. If you have any comments or suggestions about the page layout send a mail to ROOT support, or contact the developers with any questions or problems regarding ROOT.