UT_FileUtil.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        UT_FileUtil.h ( UT Library, C++)
 *
 * COMMENTS:    This verb class provides a wide assortment of
 *      file utility functions.
 */

#ifndef __UT_FileUtil__
#define __UT_FileUtil__

#include "UT_API.h"
#include "UT_Assert.h"
#include "UT_NTUtil.h"          // for mode_t
#include <SYS/SYS_Compiler.h>
#include <SYS/SYS_Types.h>
#include <SYS/SYS_Stdio.h>

#include <iosfwd>
#include <stdio.h>
#include <time.h>

class UT_String;
class UT_WorkBuffer;
class UT_FileStat;

// Here are flags used the by the file utility functions:
// If this is set, the showPrompt will be called before any destructive
// action.
#define UT_FILEUTIL_PROMPT      1
// If this is set, the original directory will be included in the
// sweep.
#define UT_FILEUTIL_INCLUSIVE   2

// The standard return code is 0 for success, negative for failure.
// An appropriate error is passed to the error method which can
// be overridden to do something more interesting than dumping to
// the console.
class UT_API UT_FileUtil
{
public:
    enum UT_RemoveDepth { IF_EMPTY, ALL_CONTENTS };


    UT_FileUtil()               {}
    virtual ~UT_FileUtil()      {}

    UT_FileUtil(const UT_FileUtil &) = delete;
    UT_FileUtil &operator=(const UT_FileUtil &) = delete;
    
    /// Returns the file size of that file in the given path. Returns -1 on
    /// error.
    static int64        getFileSize(const char *path);

    /// Returns the file modification time of the file in the given path.
    /// Returns -1 on error.
    static time_t       getFileModTime(const char *path);

    /// Returns the latest file modification time recusively of all files
    /// in the given path including the path itself.  If the given path 
    /// can be a regular file.
    ///
    /// If you've already statted the file in question, you can pass it as an
    /// argument to avoid an additional stat call internally.
    ///
    /// Returns -1 if no timestamps can be retrieved.
    static time_t       getRecursiveDirMaxModTime(const char *path);
    static time_t       getRecursiveDirMaxModTime(const char *path, const UT_FileStat &fstat);

    /// Return the maximum number of file descriptors that are available
    /// for this process.
    static int          getMaxFileDescriptors();

    /// Shorten the given path if possible. Only possibly has an effect on
    /// Windows. Returns true if successful. Upon returning false, the contents
    /// of result will be undefined.
    static bool         getShortPathName(UT_WorkBuffer &result,
                                         const char *path);

    /// Follow the specified symbolic link to the contents, recursing if the
    /// contents are themselves another symbolic link.  This method will fail
    /// if the specified path is not to a symbolic link, or if the link does
    /// not point to an existing file when allow_dangling_link is false.
    static int          resolveSymbolicLinks(const char *path,
                                             UT_WorkBuffer &contents,
                                             bool allow_dangling_link = false);

    // Copies a file on disk from the source to the dest.
    // This is only good for smallish files as we allocate a file size
    // memory buffer.
    static int          copyFile(const char *srcname, const char *dstname,
                                 std::ostream *error_os = nullptr);
    // Recursively copy a directory
    static int          copyDir(const char *srcname, const char *dstname);
    // Copies a file from a disk into a stream.  This is good for
    // building a .cpio archive.
    static int          copyFileToStream(const char *srcname, std::ostream &os);

    // Move a file, returns 0 on success.
    static int          moveFile(const char *srcname, const char *dstname);
    // Delete a file
    static int          removeFile(const char *fname);

    // Delete a directory
    static int          removeDir(const char *dname,
                                  UT_RemoveDepth depth = IF_EMPTY);

    /// Make a single directory.  All leading path components must exist.
    /// The function returns true if the path already exists or if the path was
    /// made.
    /// @param path @n The path to create
    /// @param mode @n The unix file mode
    /// @param ignore_umask @n
    ///   By default, the users umask will be used in conjunction with the
    ///   mode.  This parameter will @b force the mode to be the given value.
    static bool         makeDir(const char *path, mode_t mode=0777,
                                bool ignore_umask = false);

    /// Make a directory and all the parent directories needed
    /// @param path @n The path to create
    /// @param mode @n The unix file mode
    /// @param ignore_umask @n
    ///   By default, the users umask will be used in conjunction with the
    ///   mode.  This parameter will @b force the mode to be the given value.
    static bool         makeDirs(const char *path, mode_t mode=0777,
                                bool ignore_umask = false);

    /// Locks a file for exclusive access. Will not return until the file lock
    /// is achiveved or an error occurs. Equivalent to calling writeLockFile().
    /// @returns true if the file lock succeeded, and false otherwise.
    /// @note
    /// - On Linux, if any file descriptor referring to this file is
    /// closed, the lock will be automatically be closed. Be very careful!
    /// - On Windows, this is NOT re-entrant (unlike Linux). Treat these locks
    /// as NOT re-entrant unless you want deadlocking on Windows.
    static bool         lockFile(int fd);

    /// Unlocks a file that was locked for exclusive access with lockFile, 
    /// above.
    /// Returns true if the unlock succeeded, and false otherwise.
    static bool         unlockFile(int fd);

    /// Locks a file for write access. Will not return until the file lock
    /// is achiveved or an error occurs.
    /// @returns true if the file lock succeeded, and false otherwise.
    /// @note
    /// - On Linux, if any file descriptor referring to this file is
    /// closed, the lock will be automatically be closed. Be very careful!
    /// - On Windows, this is NOT re-entrant (unlike Linux). Treat these locks
    /// as NOT re-entrant unless you want deadlocking on Windows.
    static bool         writeLockFile(int fd);

    /// Locks a file for read access. Will not return until the file lock
    /// is achiveved or an error occurs.
    /// @returns true if the file lock succeeded, and false otherwise.
    /// @note
    /// - On Linux, if any file descriptor referring to this file is closed,
    /// the lock will be automatically be closed. Be very careful!
    /// - On Windows, this is NOT re-entrant (unlike Linux). Treat these locks
    /// as NOT re-entrant unless you want deadlocking on Windows.
    static bool         readLockFile(int fd);

    // This navigates up the given path the specified number of levels.
    // It adds a \0 at the correct slash, leaving path to be the
    // proper path name.
    // eg:  upDirectory("foo/bar.vex", 1) = "foo"
    //      upDriectory("foo/bar/", 1) = "foo"
    static void         upDirectory(char *path, int levels);

    // This scans the (ascii) file fname for any line which starts
    // with the prefix.  If readonly is not true, it writes out a new
    // version of the file lacking those lines.  The return is the
    // number of lines that would be removed, or negative if error.
    static int          removeLinesFromFile(const char *fname, 
                                const char *prefix, int readonly = 0);

    // This is of the form
    // removeOverrideFiles("d:/hsite/houdini5",
    //                 "subnet/Sop", 
    //                 "foo.ds", "Dialog Script", UT_FILEUTIL_PROMPT);
    // If the stripinfo is specified, it will do a removeLinesFromFile
    // with stripinfo rather than delete.
    int                 removeOverrideFiles(const char *newbasepath, 
                                    const char *relpath, const char *fname, 
                                    const char *english, int flags,
                                    const char *stripinfo = 0);

    /// Parses the file in search of the given XML element and outputs 
    /// its contents into the string argument. Returns true uppon success
    /// or false on failure.
    static bool         readXMLElementFromFile( const char * xml_file_path,
                                    const char * element_name,
                                    UT_String  & element_data );

    // These are UI methods you can override to gain different behaviours
    // for your instance:
    // Severity is the same as UI_Manager::UI_ErrorType.
    virtual void        showError(const char *error, int severity = 2);
    // 0 means Cancel, 1 OK.
    virtual int         showPrompt(const char *prompt);

};

class UT_EmptyFileLock {};

/// A class that allows you to create and lock a file for exclusive access.
/// When instances of this class go out of scope, the locked file is
/// automatically unlocked and closed.
class SYS_NO_DISCARD_RESULT UT_AutoFileLock
{
public:
    /// Construct without lock. Use lock() with filename to acquire one.
    explicit UT_AutoFileLock(UT_EmptyFileLock)
    {
    }

    /// Open and lock a file for exclusive reading and writing. 
    UT_AutoFileLock(const char *filename)
    {
        lock(filename, /*exclusive*/true);
    }

    /// Open and lock a file for read-only (exclusive=false),
    /// or for read-write (exclusive=true). If filename does not exist, then
    /// it is opened as read-write.
    UT_AutoFileLock(const char *filename, bool exclusive)
    {
        lock(filename, exclusive);
    }

    ~UT_AutoFileLock()
    {
        unlock();
    }

    /// Open and lock a file for read-only (exclusive=false),
    /// or for read-write (exclusive=true). If filename does not exist, then
    /// it is opened as read-write.
    void lock(const char *filename, bool exclusive)
    {
        if (myFile)
        {
            UT_ASSERT(!"Can't relock");
            return;
        }

        // Try opening it as if it exists first, then try creating it.
        myFile = SYSfopen(filename, exclusive ? "rb+" : "rb");
        if (myFile)
        {
            if (exclusive)
                myLockSucceeded = UT_FileUtil::writeLockFile(fileno(myFile));
            else
                myLockSucceeded = UT_FileUtil::readLockFile(fileno(myFile));
        }
        else
        {
            myFile = SYSfopen(filename, "wb+");
            if (myFile)
                myLockSucceeded = UT_FileUtil::writeLockFile(fileno(myFile));
            else
                myLockSucceeded = false;
        }
    }

    void unlock()
    {
        if (myFile)
        {
            if (myLockSucceeded)
            {
                UT_FileUtil::unlockFile(fileno(myFile));
                myLockSucceeded = false;
            }

            fclose(myFile);
            myFile = nullptr;
        }
    }

    /// Get the file pointer for this locked file.
    FILE *getFile() const
    {
        return myFile;
    }

    /// Return whether the file is actually locked.
    bool isLocked() const
    {
        return myLockSucceeded;
    }

private:
    FILE *myFile = nullptr;
    bool myLockSucceeded = false;
};

#endif