src/base/output.hh

   1 /*
   2  * Copyright (c) 2015 ARM Limited
   3  * All rights reserved
   4  *
   5  * The license below extends only to copyright in the software and shall
   6  * not be construed as granting a license to any other intellectual
   7  * property including but not limited to intellectual property relating
   8  * to a hardware implementation of the functionality of the software
   9  * licensed hereunder.  You may use the software subject to the license
  10  * terms below provided that you ensure that this notice is replicated
  11  * unmodified and in its entirety in all distributions of the software,
  12  * modified or unmodified, in source code or in binary form.
  13  *
  14  * Copyright (c) 2013 Andreas Sandberg
  15  * Copyright (c) 2005 The Regents of The University of Michigan
  16  * All rights reserved.
  17  *
  18  * Redistribution and use in source and binary forms, with or without
  19  * modification, are permitted provided that the following conditions are
  20  * met: redistributions of source code must retain the above copyright
  21  * notice, this list of conditions and the following disclaimer;
  22  * redistributions in binary form must reproduce the above copyright
  23  * notice, this list of conditions and the following disclaimer in the
  24  * documentation and/or other materials provided with the distribution;
  25  * neither the name of the copyright holders nor the names of its
  26  * contributors may be used to endorse or promote products derived from
  27  * this software without specific prior written permission.
  28  *
  29  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  30  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  31  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  32  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  33  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  34  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  35  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  36  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  37  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  38  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  39  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  40  */
  41
  42 #ifndef __BASE_OUTPUT_HH__
  43 #define __BASE_OUTPUT_HH__
  44
  45 #include <ios>
  46 #include <map>
  47 #include <string>
  48
  49 #include "base/compiler.hh"
  50
  51 class OutputDirectory;
  52
  53 class OutputStream
  54 {
  55   public:
  56     virtual ~OutputStream();
  57
  58     /** Get the output underlying output stream */
  59     std::ostream *stream() const { return _stream; };
  60
  61     /**
  62      * Can the file be recreated if the output directory is moved?
  63      *
  64      * @return true if the file will be created in the new location,
  65      * false otherwise.
  66      */
  67     virtual bool recreateable() const { return false; }
  68
  69     /** Get the file name in the output directory */
  70     const std::string &name() const { return _name; }
  71
  72   protected:
  73     friend class OutputDirectory;
  74
  75     /** Wrap an existing stream */
  76     OutputStream(const std::string &name,
  77                  std::ostream *stream);
  78
  79     /* Prevent copying */
  80     OutputStream(const OutputStream &f);
  81
  82     /** Re-create the in a new location if recreateable. */
  83     virtual void relocate(const OutputDirectory &dir);
  84
  85     /** Name in output directory */
  86     const std::string _name;
  87
  88     /** Underlying output stream */
  89     std::ostream *const _stream;
  90 };
  91
  92 template<class StreamType>
  93 class OutputFile
  94     : public OutputStream
  95 {
  96   public:
  97     typedef StreamType stream_type_t;
  98
  99     virtual ~OutputFile();
 100
 101     /**
 102      * Can the file be recreated if the output directory is moved?
 103      *
 104      * @return true if the file will be created in the new location,
 105      * false otherwise.
 106      */
 107     bool recreateable() const override { return _recreateable; }
 108
 109   protected:
 110     friend class OutputDirectory;
 111
 112     OutputFile(const OutputDirectory &dir,
 113                const std::string &name,
 114                std::ios_base::openmode mode,
 115                bool recreateable);
 116
 117     /* Prevent copying */
 118     OutputFile(const OutputFile<StreamType> &f);
 119
 120     /** Re-create the file in a new location if it is relocatable. */
 121     void relocate(const OutputDirectory &dir) override;
 122
 123     /** File mode when opened */
 124     const std::ios_base::openmode _mode;
 125
 126     /** Can the file be recreated in a new location? */
 127     const bool _recreateable;
 128
 129     /** Pointer to the file stream */
 130     stream_type_t *const _fstream;
 131 };
 132
 133 /** Interface for creating files in a gem5 output directory. */
 134 class OutputDirectory
 135 {
 136   private:
 137     /** File names and associated stream handles */
 138     typedef std::map<std::string, OutputStream *> file_map_t;
 139
 140     /** Output subdirectories */
 141     typedef std::map<std::string, OutputDirectory *> dir_map_t;
 142
 143     /** Open file streams within this directory */
 144     file_map_t files;
 145
 146     /** Output sub-directories */
 147     dir_map_t dirs;
 148
 149     /** Name of this directory */
 150     std::string dir;
 151
 152     /** System-specific path separator character */
 153     static const char PATH_SEPARATOR = '/';
 154
 155     static OutputStream stdout;
 156     static OutputStream stderr;
 157
 158   protected:
 159     /**
 160      * Determines whether given file name corresponds to standard output
 161      * streams.
 162      *
 163      * @param name name of file to check
 164      * @return output stream for standard output or error stream if name
 165      *         corresponds to one or the other; NULL otherwise
 166      */
 167     static OutputStream *checkForStdio(const std::string &name);
 168
 169   public:
 170     /** Constructor. */
 171     OutputDirectory();
 172
 173     /** Constructor. */
 174     OutputDirectory(const std::string &name);
 175
 176     /** Destructor. */
 177     ~OutputDirectory();
 178
 179     /**
 180      * Returns relative file names prepended with name of this directory.
 181      * Returns absolute file names unaltered.
 182      *
 183      * @param name file name to prepend with directory name
 184      * @return file name prepended with base directory name or unaltered
 185      *          absolute file name
 186      */
 187     std::string resolve(const std::string &name) const;
 188
 189     /**
 190      * Sets name of this directory.
 191      * @param dir name of this directory
 192      */
 193     void setDirectory(const std::string &dir);
 194
 195     /**
 196      * Gets name of this directory.
 197      * @return name of this directory
 198      */
 199     const std::string &directory() const;
 200
 201     /**
 202      * Creates a file in this directory (optionally compressed).
 203      *
 204      * Will open a file as a compressed stream if filename ends in .gz, unless
 205      * explicitly disabled.
 206      *
 207      * Relative output paths will result in the creation of a
 208      * recreateable (see OutputFile) output file in the current output
 209      * directory. Files created with an absolute path will not be
 210      * recreateable.
 211      *
 212      * @param name name of file to create (without this directory's name
 213      *          leading it)
 214      * @param binary true to create a binary file; false otherwise
 215      * @param no_gz true to disable opening the file as a gzip compressed output
 216      *     stream; false otherwise
 217      * @return OutputStream instance representing the created file
 218      */
 219     OutputStream *create(const std::string &name,
 220                          bool binary = false,
 221                          bool no_gz = false);
 222
 223     /**
 224      * Open a file in this directory (optionally compressed).
 225      *
 226      * Will open a file as a compressed stream if filename ends in .gz, unless
 227      * explicitly disabled.
 228      *
 229      * @param filename file to open
 230      * @param mode attributes to open file with
 231      * @param recreateable Set to true if the file can be recreated in a new
 232      *     location.
 233      * @param no_gz true to disable opening the file as a gzip compressed output
 234      *     stream; false otherwise
 235      * @return OutputStream instance representing the opened file
 236      */
 237     OutputStream *open(const std::string &name,
 238                        std::ios_base::openmode mode,
 239                        bool recreateable = true,
 240                        bool no_gz = false);
 241
 242     /**
 243      * Closes an output file and free the corresponding OutputFile.
 244      *
 245      * The output file must have been opened by the same
 246      * OutputDirectory instance as the one closing it, or sim will
 247      * fail.
 248      *
 249      * @param file OutputStream instance in this OutputDirectory.
 250      */
 251     void close(OutputStream *file);
 252
 253     /**
 254      * Finds stream associated with an open file or stdout/stderr.
 255      *
 256      * @param name of file
 257      * @return stream to specified file or NULL if file does not exist
 258      */
 259     OutputStream *find(const std::string &name) const;
 260
 261     OutputStream *findOrCreate(const std::string &name, bool binary = false);
 262
 263     /**
 264      * Determines whether a file name corresponds to a file in this directory.
 265      * @param name name of file to evaluate
 266      * @return true iff file has been opened in this directory or exists on the
 267      *          file system within this directory
 268      */
 269     bool isFile(const std::string &name) const;
 270
 271     /**
 272      * Test if a path is absolute.
 273      */
 274     static inline bool isAbsolute(const std::string &name) {
 275         return name[0] == PATH_SEPARATOR;
 276     }
 277
 278     /**
 279      * Creates a subdirectory within this directory.
 280      * @param name name of subdirectory
 281      * @return the new subdirectory's name suffixed with a path separator
 282      */
 283     OutputDirectory *createSubdirectory(const std::string &name);
 284
 285     /**
 286      * Removes a specified file or subdirectory.
 287      *
 288      * Will cause sim to fail for most errors.  However, it will only warn the
 289      * user if a directory could not be removed.  This is in place to
 290      * accommodate slow file systems where file deletions within a subdirectory
 291      * may not be recognized quickly enough thereby causing the subsequent call
 292      * to remove the directory to fail (seemingly unempty directory).
 293      *
 294      * @param name name of file or subdirectory to remove; name should not
 295      *              be prepended with the name of this directory object
 296      * @param recursive set to true to attempt to recursively delete a
 297      *                  subdirectory and its contents
 298      */
 299     void remove(const std::string &name, bool recursive=false);
 300 };
 301
 302 extern OutputDirectory simout;
 303
 304 #endif // __BASE_OUTPUT_HH__