library: libCore #include "TDirectory.h"

# TDirectory

class description - source file - inheritance tree (.pdf)

## class TDirectory : public TNamed

| Inheritance Chart:
`TObject`
| <- | `TNamed`
| <- | `TDirectory` |
<- |
`TFile` | <- |
`TDCacheFile` |
`TNetFile` | <- |
`TCastorFile` |
`TXNetFile` |
`TRFIOFile` |
`TWebFile` |
`TXMLFile` |
`TROOT` |

        private:

                     TDirectory(const TDirectory& directory)
                void operator=(const TDirectory&)

        protected:

                 Bool_t cd1(const char* path)
          static Bool_t Cd1(const char* path)

        public:

                              TDirectory()
                              TDirectory(const char* name, const char* title, Option_t* option = "")
                      virtual ~TDirectory()
                         void Add(TObject* obj)
                 virtual void Append(TObject* obj)
                        Int_t AppendKey(TKey* key)
                 virtual void Browse(TBrowser* b)
                         void Build()
               virtual Bool_t cd(const char* path = "0")
                static Bool_t Cd(const char* path)
               static TClass* Class()
                 virtual void Clear(Option_t* option = "")
                 virtual void Close(Option_t* option = "")
                 virtual void Copy(TObject&) const
                  static void DecodeNameCycle(const char* namecycle, char* name, Short_t& cycle)
                 virtual void Delete(const char* namecycle = "")
                 virtual void DeleteAll(Option_t* option = "")
                 virtual void Draw(Option_t* option = "")
                  static void EncodeNameCycle(char* buffer, const char* name, Short_t cycle)
                 virtual void FillBuffer(char*& buffer)
                virtual TKey* FindKey(const char* keyname) const
                virtual TKey* FindKeyAny(const char* keyname) const
             virtual TObject* FindObject(const char* name) const
             virtual TObject* FindObject(const TObject* obj) const
             virtual TObject* FindObjectAny(const char* name) const
             virtual TObject* Get(const char* namecycle)
                virtual Int_t GetBufferSize() const
               const TDatime& GetCreationDate() const
               virtual TFile* GetFile() const
                virtual TKey* GetKey(const char* name, Short_t cycle = 9999) const
                       TList* GetList() const
                       TList* GetListOfKeys() const
               const TDatime& GetModificationDate() const
                     TObject* GetMother() const
                virtual Int_t GetNbytesKeys() const
                virtual Int_t GetNkeys() const
                         void GetObject(const char* namecycle, void*& ptr)
                virtual void* GetObjectChecked(const char* namecycle, const char* classname)
                virtual void* GetObjectChecked(const char* namecycle, const TClass* cl)
                virtual void* GetObjectUnchecked(const char* namecycle)
          virtual const char* GetPath() const
             virtual Long64_t GetSeekDir() const
             virtual Long64_t GetSeekKeys() const
             virtual Long64_t GetSeekParent() const
                        TUUID GetUUID() const
              virtual TClass* IsA() const
               virtual Bool_t IsFolder() const
                       Bool_t IsModified() const
                       Bool_t IsWritable() const
                 virtual void ls(Option_t* option = "") const
          virtual TDirectory* mkdir(const char* name, const char* title = "")
                 virtual void Paint(Option_t* option = "")
                 virtual void Print(Option_t* option = "") const
                 virtual void Purge(Short_t nkeep = 1)
                 virtual void pwd() const
                 virtual void ReadAll(Option_t* option = "")
                virtual Int_t ReadKeys()
                 virtual void RecursiveRemove(TObject* obj)
                 virtual void Save()
                 virtual void SaveSelf(Bool_t force = kFALSE)
                 virtual void SetBufferSize(Int_t bufsize)
                         void SetModified()
                         void SetMother(const TObject* mother)
                         void SetWritable(Bool_t writable = kTRUE)
                 virtual void ShowMembers(TMemberInspector& insp, char* parent)
                virtual Int_t Sizeof() const
                 virtual void Streamer(TBuffer& b)
                         void StreamerNVirtual(TBuffer& b)
                virtual Int_t Write(const char* name = "0", Int_t opt = 0, Int_t bufsiz = 0)
                virtual Int_t Write(const char* name = "0", Int_t opt = 0, Int_t bufsiz = 0) const
                 virtual void WriteDirHeader()
                 virtual void WriteKeys()
                        Int_t WriteObject(const void* obj, const char* name, Option_t* option = "")
                virtual Int_t WriteObjectAny(const void* obj, const char* classname, const char* name, Option_t* option = "")
                virtual Int_t WriteObjectAny(const void* obj, const TClass* cl, const char* name, Option_t* option = "")
                virtual Int_t WriteTObject(const TObject* obj, const char* name = "0", Option_t* option = "")

### Data Members

        protected:

            Bool_t fModified    true if directory has been modified
            Bool_t fWritable    true if directory is writable
           TDatime fDatimeC     Date and time when directory is created
           TDatime fDatimeM     Date and time of last modification
             Int_t fNbytesKeys  Number of bytes for the keys
             Int_t fNbytesName  Number of bytes in TNamed at creation time
             Int_t fBufferSize  Default buffer size to create new TKeys
          Long64_t fSeekDir     Location of directory on file
          Long64_t fSeekParent  Location of parent directory on file
          Long64_t fSeekKeys    Location of Keys record on file
            TFile* fFile        pointer to current file in memory
          TObject* fMother      pointer to mother of the directory
            TList* fList        Pointer to objects list in memory
            TList* fKeys        Pointer to keys list in memory
             TUUID fUUID        Unique identifier

        public:

          static const enum TDirectory:: kCloseDirectory

## Class Description

/* */

TDirectory() : TNamed()

    *-*-*-*-*-*-*-*-*-*-*-*Directory default constructor-*-*-*-*-*-*-*-*-*-*-*-*
    *-*                    =============================

TDirectory(const char *name, const char *title, Option_t *classname) : TNamed(name, title)

    *-*-*-*-*-*-*-*-*-*-*-* Create a new Directory *-*-*-*-*-*-*-*-*-*-*-*-*-*
    *-*                     ======================
      A new directory with name,title is created in the current directory
      The directory header information is immediatly saved on the file
      A new key is added in the parent directory

      When this constructor is called from a class directly derived
      from TDirectory, the third argument classname MUST be specified.
      In this case, classname must be the name of the derived class.

      Note that the directory name cannot contain slashes.

TDirectory(const TDirectory &directory) : TNamed(directory)

~TDirectory()

    *-*-*-*-*-*-*-*-*-*-*-*Directory destructor*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
    *-*                    ====================

void Append(TObject *obj)

     Append object to this directory.

Int_t AppendKey(TKey *key)

    *-*-*-*-*-*-*Insert key in the linked list of keys of this directory*-*-*-*
    *-*          =======================================================

void Browse(TBrowser *b)

void Build()

    *-*-*-*-*-*-*-*-*-*-*-*Initialise directory to defaults*-*-*-*-*-*-*-*-*-*
    *-*                    ================================

Bool_t cd(const char *path)

     Change current directory to "this" directory . Using path one can
     change the current directory to "path". The absolute path syntax is:
     file.root:/dir1/dir2
     where file.root is the file and /dir1/dir2 the desired subdirectory
     in the file. Relative syntax is relative to "this" directory. E.g:
     ../aa. Returns kTRUE in case of success.

Bool_t cd1(const char *apath)

     Change current directory to "this" directory . Using path one can
     change the current directory to "path". The absolute path syntax is:
     file.root:/dir1/dir2
     where file.root is the file and /dir1/dir2 the desired subdirectory
     in the file. Relative syntax is relative to "this" directory. E.g:
     ../aa. Returns kFALSE in case path does not exist.

Bool_t Cd(const char *path)

     Change current directory to "path". The absolute path syntax is:
     file.root:/dir1/dir2
     where file.root is the file and /dir1/dir2 the desired subdirectory
     in the file. Relative syntax is relative to the current directory
     gDirectory, e.g.: ../aa. Returns kTRUE in case of success.

Bool_t Cd1(const char *apath)

     Change current directory to "path". The path syntax is:
     file.root:/dir1/dir2
     where file.root is the file and /dir1/dir2 the desired subdirectory
     in the file. Returns kFALSE in case path does not exist.

void Clear(Option_t *)

    *-*-*-*Delete all objects from a Directory list-*-*-*-*-*
    *-*    =======================================

void Close(Option_t *)

    *-*-*-*Delete all objects from memory and directory structure itself-*-*-*-*
           ============================================================

void DeleteAll(Option_t *)

    *-*-*-*-*-*-*-*-*Delete all objects from memory*-*-*-*-*-*-*-*-*-*
                     ==============================

void Delete(const char *namecycle)

    *-*-*-*-*-*-*-* Delete Objects or/and keys in a directory *-*-*-*-*-*-*-*
    *-*             =========================================
       namecycle has the format name;cycle
       namecycle = "" same as namecycle ="T*"
       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

       To delete one directory, you must specify the directory cycle,
          eg.  file.Delete("dir1;1");

       examples:
         foo   : delete object named foo in memory
         foo*  : delete all objects with a name starting with foo
         foo;1 : delete cycle 1 of foo on file
         foo;* : delete all cycles of foo on file 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 FillBuffer(char *&buffer)

    *-*-*-*-*-*-*-*-*-*-*-*Encode directory header into output buffer*-*-*-*-*-*
    *-*                    =========================================

TKey* FindKey(const char *keyname) const

     Find key with name keyname in the current directory

TKey* FindKeyAny(const char *keyname) const

     Find key with name keyname in the current directory or
     its subdirectories.
     NOTE that If a key is found, the directory containing the key becomes
     the current directory

TObject* FindObject(const TObject *obj) const

     Find object in the list of memory objects.

TObject* FindObject(const char *name) const

     Find object by name in the list of memory objects.

TObject* FindObjectAny(const char *aname) const

     Find object by name in the list of memory objects of the current
     directory or its sub-directories.
     After this call the current directory is not changed.
     To automatically set the current directory where the object is found,
     use FindKeyAny(aname)->ReadObj().

TObject* Get(const char *namecycle)

      return pointer to object identified by namecycle

       namecycle has the format name;cycle
       name  = * is illegal, cycle = * is illegal
       cycle = "" or cycle = 9999 ==> apply to a memory object

       examples:
         foo   : get object named foo in memory
                 if object is not in memory, try with highest cycle from file
         foo;1 : get cycle 1 of foo on file

      The retrieved object should in principle derive from TObject.
      If not, the function TDirectory::GetObject should be called.
      However, this function will still work for a non-TObject, providing that
      the calling application cast the return type to the correct type (which
      is the actual type of the object).

      NOTE:
      The method GetObject offer better protection and avoid the need
      for any cast:
          MyClass *obj;
          directory->GetObject("some object",obj);
          if (obj) { ... the object exist and inherits from MyClass ... }

      VERY IMPORTANT NOTE:
      In case the class of this object derives from TObject but not
      as a first inheritance, one must use dynamic_cast<>().
      Example 1: Normal case:
          class MyClass : public TObject, public AnotherClass
       then on return, one can do:
          MyClass *obj = (MyClass*)directory->Get("some object of MyClass");

      Example 2: Special case:
          class MyClass : public AnotherClass, public TObject
      then on return, one must do:
          MyClass *obj = dynamic_cast<MyClass*>(directory->Get("some object of MyClass"));

      Of course, dynamic_cast<> can also be used in the example 1.

void* GetObjectUnchecked(const char *namecycle)

     return pointer to object identified by namecycle.
     The returned object may or may not derive from TObject.

       namecycle has the format name;cycle
       name  = * is illegal, cycle = * is illegal
       cycle = "" or cycle = 9999 ==> apply to a memory object

      VERY IMPORTANT NOTE:
      The calling application must cast the returned object to
      the final type, eg
          MyClass *obj = (MyClass*)directory->GetObject("some object of MyClass");

void* GetObjectChecked(const char *namecycle, const char* classname)

     See documentation of TDirectory::GetObjectCheck(const char *namecycle, const TClass *cl)

void* GetObjectChecked(const char *namecycle, const TClass* cl)

     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 "cl"
     If cl is null, no check is performed.

       namecycle has the format name;cycle
       name  = * is illegal, cycle = * is illegal
       cycle = "" or cycle = 9999 ==> apply to a memory object

      VERY IMPORTANT NOTE:
      The calling application must cast the returned pointer to
      the type described by the 2 arguments (i.e. cl):
          MyClass *obj = (MyClass*)directory->GetObjectChecked("some object of MyClass","MyClass"));

      Note: We recommend using the method TDirectory::GetObject:
          MyClass *obj = 0;
          directory->GetObject("some object inheriting from MyClass",obj);
          if (obj) { ... we found what we are looking for ... }

Int_t GetBufferSize() const

     Return the buffer size to create new TKeys.
     If the stored fBufferSize is null, the value returned is the average
     buffer size of objects in the file so far.

TKey* GetKey(const char *name, Short_t cycle) const

    *-*-*-*-*-*-*-*-*-*-*Return pointer to key with name,cycle*-*-*-*-*-*-*-*
    *-*                  =====================================
      if cycle = 9999 returns highest cycle

const char* GetPath() const

     Returns the full path of the directory. E.g. file:/dir1/dir2.
     The returned path will be re-used by the next call to GetPath().

TDirectory* mkdir(const char *name, const char *title)

     Create a sub-directory and return a pointer to the created directory.
     Returns 0 in case of error.
     Returns 0 if a directory with the same name already exists.
     Note that the directory name cannot contain slashes.

void ls(Option_t *option) const

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

      The option can has the following format:
         [-d |-m][<regexp>]
      Option -d means: only list objects in the file
             -m means: only list objects in memory
      The <regexp> will be used to match the name of the objects.
      By default memory and disk objects are listed.

void Paint(Option_t *option)

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

void Print(Option_t *option) const

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

void Purge(Short_t)

     Purge lowest key cycles in a directory.
     By default, only the highest cycle of a key is kept. Keys for which
     the "KEEP" flag has been set are not removed. See TKey::Keep().

void pwd() const

     Print the path of the directory.

void ReadAll(Option_t *)

     Read objects from a ROOT db file directory into memory.
     If an object is already in memory, the memory copy is deleted
     and the object is again read from the file.

Int_t ReadKeys()

    *-*-*-*-*-*-*-*-*-*-*-*-*Read the KEYS linked list*-*-*-*-*-*-*-*-*-*-*-*-*
    *-*                      =========================
      Every directory has a linked list (fKeys). This linked list has been
      written on the file via WriteKeys as a single data record.

      It is interesting to call this function in the following situation.
      Assume another process1 is connecting this directory in Update mode
        -Process1 is adding/updating objects in this directory
        -You want to see the latest status from process1.
      Example Process1:
        obj1.Write();
        obj2.Write();
        gDirectory->SaveSelf();

      Example Process2
        gDirectory->ReadKeys();
        obj1->Draw();

      This is an efficient way (without opening/closing files) to view
      the latest updates of a file being modified by another process
      as it is typically the case in a data acquisition system.

void RecursiveRemove(TObject *obj)

    *-*-*-*-*-*-*-*Recursively remove object from a Directory*-*-*-*-*-*-*-*
    *-*            =========================================

void Save()

    *-*-*-*-*-*-*-*-*-*Save recursively all directory keys and headers-*-*-*-*-*
    *-*                ===============================================

void SaveSelf(Bool_t force)

    *-*-*-*-*-*-*-*-*-*Save Directory keys and header*-*-*-*-*-*-*-*-*-*-*-*
    *-*                ==============================
      If the directory has been modified (fModified set), write the keys
      and the directory header. This function assumes the cd is correctly set.

      It is recommended to use this function in the following situation:
      Assume a process1 using a directory in Update mode
        -New objects or modified objects have been written to the directory
        -You do not want to close the file
        -You want your changes be visible from another process2 already connected
         to this directory in read mode
        -Call this function
        -In process2, use TDirectory::ReadKeys to refresh the directory

void SetBufferSize(Int_t bufsize)

     set the default buffer size when creating new TKeys
     see also TDirectory::GetBufferSize

void SetWritable(Bool_t writable)

      Set the new value of fWritable recursively

Int_t Sizeof() const

    *-*-*-*-*-*-*Return the size in bytes of the directory header*-*-*-*-*-*-*
    *-*          ================================================
    Int_t nbytes = sizeof(Version_t);    2
    nbytes     += fDatimeC.Sizeof();
    nbytes     += fDatimeM.Sizeof();
    nbytes     += sizeof fNbytesKeys;    4
    nbytes     += sizeof fNbytesName;    4
    nbytes     += sizeof fSeekDir;       4 or 8
    nbytes     += sizeof fSeekParent;    4 or 8
    nbytes     += sizeof fSeekKeys;      4 or 8
    nbytes     += fUUID.Sizeof();

void Streamer(TBuffer &b)

    *-*-*-*-*-*-*-*-*Stream a class object*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
    *-*              =========================================

Int_t Write(const char *, Int_t opt, Int_t bufsiz)

     Write all objects in memory to disk.
     Loop on all objects in memory (including subdirectories).
     A new key is created in the KEYS linked list for each object.
     For allowed options see TObject::Write().
     The directory header info is rewritten on the directory header record.

Int_t Write(const char *n, Int_t opt, Int_t bufsize) const

     One can not save a const TDirectory object.

Int_t WriteTObject(const TObject *obj, const char *name, Option_t *option)

     Write object obj to this directory
     The data structure corresponding to this object is serialized.
     The corresponding buffer is written to this directory
     with an associated key with name "name".

     Writing an object to a file involves the following steps:

      -Creation of a support TKey object in the directory.
       The TKey object creates a TBuffer object.

      -The TBuffer object is filled via the class::Streamer function.

      -If the file is compressed (default) a second buffer is created to
       hold the compressed buffer.

      -Reservation of the corresponding space in the file by looking
       in the TFree list of free blocks of the file.

      -The buffer is written to the file.

      By default, the buffersize will be taken from the average buffer size
      of all objects written to the current file so far.
      Use TDirectory::SetBufferSize to force a given buffer size.

      If a name is specified, it will be the name of the key.
      If name is not given, the name of the key will be the name as returned
      by obj->GetName().

      The option can be a combination of:
        "SingleKey", "Overwrite" or "WriteDelete"
      Using the "Overwrite" option a previous key with the same name is
      overwritten. The previous key is deleted before writing the new object.
      Using the "WriteDelete" option a previous key with the same name is
      deleted only after the new object has been written. This option
      is safer than kOverwrite but it is slower.
      The "SingleKey" option is only used by TCollection::Write() to write
      a container with a single key instead of each object in the container
      with its own key.

      An object is read from this directory via TDirectory::Get.

      The function returns the total number of bytes written to the directory.
      It returns 0 if the object cannot be written.

Int_t WriteObjectAny(const void *obj, const char *classname, const char *name, Option_t *option)

     Write object from pointer of class classname in this directory
     obj may not derive from TObject
     see TDirectory::WriteObject for comments

     VERY IMPORTANT NOTE:
        The value passed as 'obj' needs to be from a pointer to the type described by classname
        For example with:
          TopClass *top;
          BottomClass *bottom;
          top = bottom;
        you can do:
          directory->WriteObjectAny(top,"top","name of object");
          directory->WriteObjectAny(bottom,"bottom","name of object");
        BUT YOU CAN NOT DO (it will fail in particular with multiple inheritance):
          directory->WriteObjectAny(top,"bottom","name of object");

     We STRONGLY recommend to use
          TopClass *top = ....;
          directory->WriteObject(top,"name of object")

Int_t WriteObjectAny(const void *obj, const TClass *cl, const char *name, Option_t *option)

     Write object of class with dictionary cl in this directory
     obj may not derive from TObject
     To get the TClass* cl pointer, one can use
        TClass *cl = gROOT->GetClass("classname");
     An alternative is to call the function WriteObjectAny above.
     see TDirectory::WriteObject for comments

void WriteDirHeader()

    *-*-*-*-*-*-*-*-*-*-*Overwrite the Directory header record*-*-*-*-*-*-*-*-*
    *-*                  =====================================

void WriteKeys()

    *-*-*-*-*-*-*-*-*-*-*-*Write KEYS linked list on the file *-*-*-*-*-*-*-*
    *-*                    ==================================
      The linked list of keys (fKeys) is written as a single data record

void EncodeNameCycle(char *buffer, const char *name, Short_t cycle)

     Encode the name and cycle into buffer like: "aap;2".

void DecodeNameCycle(const char *buffer, char *name, Short_t &cycle)

     Decode a namecycle "aap;2" into name "aap" and cycle "2".

### Inline Functions

                      void operator=(const TDirectory&)
                      void Add(TObject* obj)
                      void Copy(TObject&) const
            const TDatime& GetCreationDate() const
                    TFile* GetFile() const
                    TList* GetList() const
                    TList* GetListOfKeys() const
            const TDatime& GetModificationDate() const
                  TObject* GetMother() const
                     Int_t GetNbytesKeys() const
                     Int_t GetNkeys() const
                  Long64_t GetSeekDir() const
                  Long64_t GetSeekParent() const
                  Long64_t GetSeekKeys() const
                     TUUID GetUUID() const
                    Bool_t IsFolder() const
                    Bool_t IsModified() const
                    Bool_t IsWritable() const
                      void SetModified()
                      void SetMother(const TObject* mother)
                   TClass* Class()
                   TClass* IsA() const
                      void ShowMembers(TMemberInspector& insp, char* parent)
                      void StreamerNVirtual(TBuffer& b)
                     Int_t WriteObject(const void* obj, const char* name, Option_t* option = "")
                      void GetObject(const char* namecycle, void*& ptr)

Author: Rene Brun 28/11/94
Last update: root/base:$Name: $:$Id: TDirectory.cxx,v 1.66 2005/06/23 06:24:27 brun Exp $
Copyright (C) 1995-2000, Rene Brun and Fons Rademakers. *