UT_DirUtil.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_DirUtil.C (UT Library, C++)
 *
 * COMMENTS:
 */

#ifndef _UT_DIRUTIL_H_
#define _UT_DIRUTIL_H_

#include "UT_API.h"
#include "UT_FileStat.h"
#include <SYS/SYS_Deprecated.h>

#include <time.h>

class UT_FileStat;
class UT_String;
class UT_StringArray;
class UT_StringHolder;

// Absolute path prefixes can be specified as one of 3 type:
// Default: the prefix can be followed by an absolute path, beginning in '/'
//          ie no drive letter support
// AllowAbsolutePathSuffix: the prefix can be followed by an absolute path,
//          beginning in either '/' or a drive letter (ie file:/ file:C:/)
// AlwaysAbsolute: the prefix always specifies an absolute path, regardless
//          if suffix is followed by '/', a drive letter, or something else.
enum UT_AbsolutePrefixType
{
    Default,
    AllowAbsolutePathSuffix,
    AlwaysAbsolute
};

UT_API int UTunixFullPathSpecified(const char *name);
UT_API int UTfullPathSpecified(const char *name);
// This, unlike, UTfullPathSpecified, returns false for ./filename
UT_API bool UTisAbsolutePath(const char *filename);
UT_API bool UTisRootPath(const char *filename);

/// UTgetRootPrefixLength() returns the length of the root part of the file
/// path.
///
/// The remainder of the file path after the root part length will have
/// one of the following forms:
///     '/path/to/file'             => for absolute paths
///     'relative/path/to/file'     => for relative paths
///     ''                          => for root paths
///
/// Some examples of input file paths and output root lengths:
///     '/path/to/file'             => 0
///     'relative/path/to/file'     => 0
///     'C:/path/to/file'           => 2    (Windows only)
///     'C:relative/path/to/file'   => 2    (Windows only)
///     '//path/to/file'            => 1    (Windows only)
///     '//path/to/file'            => 0    (Unix only)
///     'file:///path/to/file'      => 5
///     'file:/path/to/file'        => 5
///     'file:relative/path/to/file'=> 5
UT_API int UTgetRootPrefixLength(const char *filename);

/// Functions to manage the set of prefixes which Houdini treats as being
/// valid ways to start an absolute path.
UT_API const UT_StringArray &UTgetAbsolutePathPrefixes();
/// The "allow_absolute_path_suffix" parameter can be set to true to indicate
/// that this root prefix can be followed by an absolute path to a file on
/// disk. This matters because on Windows, an absolute path can start with
/// "C:", which doesn't look like an absolute path by the normal metric of
/// looking for a leading slash.
UT_API void UTaddAbsolutePathPrefix(const char *prefix,
  UT_AbsolutePrefixType type = Default);

/// Functions to convert absolute paths into relative paths and vice versa,
/// given a path and a "base" path which is used as the root location for
/// relative paths. When basepath is not given, getUnixCwd() will be used.
UT_API void UTmakeAbsoluteFilePath(UT_String &path,
                                   const char *basepath = nullptr);
UT_API void UTmakeAbsoluteFilePath(UT_StringHolder &path,
                                   const char *basepath = nullptr);
UT_API void UTmakeRelativeFilePath(UT_String &path,
                                   const char *basepath = nullptr,
                                   bool allow_relative_path_from_root = true);
UT_API void UTmakeRelativeFilePath(UT_StringHolder &path,
                                   const char *basepath = nullptr,
                                   bool allow_relative_path_from_root = true);

/// Resolves symlinks, symbolic links on a path.
/// Calls ::realpath() or fs::canonical() depdending of the platform.
UT_API void UTrealPath(UT_String &path);
UT_API void UTrealPath(UT_StringHolder &path);

/// Same as UTrealPath but with support for missing files.
UT_API void UTrealPath(UT_String &path, bool support_missing_files);
UT_API void UTrealPath(UT_StringHolder &path, bool support_missing_files);

/// Normalizes a file path. This means ensuring all slashes are forward
/// slashes, removing redundant slashes, and collapsing '..' and '.'
/// components as much as possible (whether they occur at the start or
/// in the middle of the path).
UT_API void UTnormalizeFilePath(UT_String &path);
UT_API void UTnormalizeFilePath(UT_StringHolder &path);

/// If the path starts with "file:", strip off however much prefix is required
/// to get the to "path" path. Note that there may be 0, 1, 2, or 3 slashes
/// after "file:", and behavior may need to change based on OS (e.g. on
/// Windows file:///C:/foo -> C:/foo, otherwise file:///foo/bar -> /foo/bar.
UT_API void UTstripFileUrlPrefix(UT_String &path);
UT_API void UTstripFileUrlPrefix(UT_StringHolder &path);

/// Checks if the file name starts with '.'.  basepath (parent directory)
/// is ignored in non Windows envirenment, whereas in Windows full path
/// is needed to see if the file has the hidden attribute.
UT_API bool UTisHiddenFile(const char *basepath, const char *filename);

/// Returns true if the given path is a readable, _regular_ file, ie. not a
/// directory.
UT_API bool UTisValidRegularFile(const char *path);

/// Returns true if the given path is a readable _directory_.
UT_API bool UTisValidDirectory(const char *path);

/// Returns true if path is a _directory_, without permission checks
UT_API bool UTisDirectory(const char *path);

/// Returns true if path is a _regular_ file, without permission checks
UT_API bool UTisRegularFile(const char *path);

/// Returns true if file path exists, without permission checks.
/// This is optimized for known platforms.
UT_API bool UTfileExists(const char *path);

#ifdef WIN32
    #include <sys/types.h>
    #include <direct.h>
    #include <errno.h>

    // Define dummy value to compare with errno in assertions related
    // to Linux libraries and large file systems. This define now exists on
    // newer versions of Visual Studio. The current value is defined to be the
    // same as the one found in VC10.
    #ifndef EOVERFLOW
        #define EOVERFLOW       132
    #endif

    namespace { struct ut_DirData; }

    typedef void* DIR;
    struct dirent
    {
    public:
        char *d_name;

    private:
        void *myFindData;

        friend UT_API int statLastRead(dirent *, const char *, UT_FileStat &);
        friend struct ut_DirData;
    };
    UT_API DIR *opendir( const char *name );
    UT_API struct dirent *readdir( DIR *dirp );
    UT_API void closedir( DIR *dirp );
    
    /// Get the current working directory
    UT_API char *getUnixCwd( char *buffer, int maxlen );
#else
    #include <sys/types.h>
    #include <sys/stat.h>
    #include <string.h>
    #include <dirent.h>
    #include <unistd.h>
    #include <stdlib.h>

    /// Get the current working directory
    UT_API char *getUnixCwd( char *buffer, int maxlen );
#endif

/// Do the equivalent of a stat on the last file from readdir. This will perform
/// a stat call on Linux.
UT_API int statLastRead(dirent *dp, const char *path, UT_FileStat &file_stat);

/// Specialization that only returns the file type of the directory entry. This
/// should be called instead of statLastRead if you only need the type of the
/// entry.
///
/// Note: On Linux, if this is called and the entry is a symlink or the
/// underlying filesystem doesn't support obtaining file types when accessing a
/// directory, this will incur a stat call.
///
/// Note: On Linux, if check_executable is true, this will incur a stat call.
UT_API int statLastRead(dirent *dp, const char *path,
    UT_FileStat::FileType &file_type, const bool check_executable);

#endif