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:

Return pointer to object identified by namecycle if and only if the actual object is a type suitable to be stored as a pointer to a "expectedClass" If expectedClass is null, no check is performed. More...

Use this method to signal that a method (defined in a base class) may not be called in a derived class (in principle against good design since a child class should not provide less functionality than its parent, however, sometimes it is necessary). More...

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.

Option

Description

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 (default).

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.

If option = "" (default), READ is assumed. 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 and algorithm:

compress = 100 * algorithm + level

Level

Explanation

0

objects written to this file will not be compressed.

1

minimal compression level but fast.

...

....

9

maximal compression level but slower and might use more memory.

(For the currently supported algorithms, the maximum level is 9) If compress is negative it indicates the compression level is not set yet. The enumeration ROOT::RCompressionSetting::EAlgorithm associates each algorithm with a number. There is a utility function to help to set the value of compress. For example, ROOT::CompressionSettings(ROOT::kLZMA, 1) will build an integer which will set the compression to use the LZMA algorithm and compression level 1. These are defined in the header file Compression.h. Note that the compression settings may be changed at any time. The new compression settings will only apply to branches created or attached after the setting is changed and other objects written after the setting is changed. 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:

When opening the file, the system checks the validity of this directory. If something wrong is detected, an automatic Recovery is performed. In this case, the file is scanned sequentially reading all logical blocks and attempting to rebuild a correct directory (see TFile::Recover). One can disable the automatic recovery procedure when reading one or more files by setting the environment variable "TFile.Recover: 0" in the system.rootrc file.

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.

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.

Number of bytes in record if negative, this is a deleted record if 0, cannot read record, wrong value of argument first

[out]

objlen

Uncompressed object size

[out]

keylen

Length of logical record header

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. Note that the arguments objlen and keylen are returned only if maxbytes >=16

If defined, the string 'prefix' is added when testing the locality of a 'name' with network-like structure (i.e. root://host//path); if the file is local, on return 'prefix' will contain the actual local path of the file.

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.

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).

Generate source code necessary to access the objects stored in the file.

Generate code in directory dirname for all classes specified in argument classes If classes = "*" (default and currently the only supported value), the function generates an include file for each class in the StreamerInfo list for which a TClass object does not exist.

The code generated includes:

dirnameProjectHeaders.h, which contains one #include statement per generated header file

dirnameProjectSource.cxx,which contains all the constructors and destructors implementation. and one header per class that is not nested inside another class. The header file name is the fully qualified name of the class after all the special characters "<>,:" are replaced by underscored. For example for std::pair<edm::Vertex,int> the file name is pair_edm__Vertex_int_.h

In the generated classes, map, multimap when the first template parameter is a class are replaced by a vector of pair. set and multiset when the tempalte parameter is a class are replaced by a vector. This is required since we do not have the code needed to order and/or compare the object of the classes. This is a quick explanation of the options available:

Option

Details

new (default)

A new directory dirname is created. If dirname already exist, an error message is printed and the function returns.

recreate

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.

update

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".

genreflex

Use genreflex rather than rootcint to generate the dictionary.

par

Create a PAR file with the minimal set of code needed to read the content of the ROOT file. The name of the PAR file is basename(dirname), with extension '.par' enforced; the PAR file will be created at dirname(dirname).

If, in addition to one of the 3 above options, the option "+" is specified, the function will generate:

a script called MAKEP to build the shared lib

a dirnameLinkDef.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. If the option "+" and "nocompile" are specified, the utility files are generated as in the option "+" but they are not executed. 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 MAKEP

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");

The following feature is not yet enabled: One can restrict the list of classes to be generated by using expressions like:

The type of the file can be 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 specified by 'url'. If 'url' is a '|'-separated list of file URLs, the 'URLs' are tried sequentially in the specified order until a successful open. 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.

For TFile implementations supporting asynchronous file open, see TFile::AsyncOpen(...), it is possible to request a timeout with the option TIMEOUT=<secs>: the timeout must be specified in seconds and it will be internally checked with granularity of one millisec. For remote files there is the option: CACHEREAD opens an existing file for reading through the file cache. The file will be downloaded to the cache and opened from there. If the download fails, it will be opened remotely. The file will be downloaded to the directory specified by SetCacheFileDir().

The value 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.

The key with name holding the list of TStreamerInfo objects is read. The corresponding TClass objects are updated. Note that this function is not called if the static member fgReadInfo is false. (see TFile::SetReadStreamerInfo)

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. This function is automatically called when opening a file. If the file is open in read only mode, the file is not modified. If open in update mode and the function finds something to recover, a new directory header is written to the file. When opening the file gain no message from Recover will be reported. If keys have been recovered, the file is usable and you can safely read the corresponding objects. If the file is not usable (a zombie), you can test for this case with code like:

If the file has been recovered, the bit kRecovered is set in the TFile object in memory. You can test if the file has been recovered with

if (f.TestBit(TFile::kRecovered)) {... the file has been recovered}

When writing TTrees to a file, it is important to save the Tree header at regular intervals (see TTree::AutoSave). If a file containing a Tree is recovered, the last Tree header written to the file will be used. In this case all the entries in all the branches written before writing the header are valid entries. One can disable the automatic recovery procedure by setting

For example, it is possible to change 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.

This relinquishes ownership of the previous cache, so if you do not already have a pointer to the previous cache (and there was a previous cache), you ought to retrieve (and delete it if needed) using:

TFileCacheRead *older = myfile->GetCacheRead();

The action specifies how to behave when detaching a cache from the the TFile. If set to (default) kDisconnect, the contents of the cache will be flushed when it is removed from the file, and it will disconnect the cache object from the file. In almost all cases, this is what you want. If you want to disconnect the cache temporarily from this tree and re-attach later to the same fil, you can set action to kDoNotDisconnect. This will allow things like prefetching to continue in the background while it is no longer the default cache for the TTree. Except for a few expert use cases, kDisconnect is likely the correct setting.

WARNING: if action=kDoNotDisconnect, you MUST delete the cache before TFile.

If fgReadInfo is true (default) TFile::ReadStreamerInfo is called when opening the file. It may be interesting to set fgReadInfo to false to speedup the file opening time or in case libraries containing classes referenced by the file have not yet been loaded. if fgReadInfo is false, one can still read the StreamerInfo with myfile.ReadStreamerInfo();

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).