Logo Search packages:      
Sourcecode: virtualbox-ose version File versions  Download package

fs.h

Go to the documentation of this file.
/** @file
 * IPRT - Filesystem.
 */

/*
 * Copyright (C) 2006-2007 Oracle Corporation
 *
 * This file is part of VirtualBox Open Source Edition (OSE), as
 * available from http://www.virtualbox.org. This file is free software;
 * you can redistribute it and/or modify it under the terms of the GNU
 * General Public License (GPL) as published by the Free Software
 * Foundation, in version 2 as it comes in the "COPYING" file of the
 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
 *
 * The contents of this file may alternatively be used under the terms
 * of the Common Development and Distribution License Version 1.0
 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
 * VirtualBox OSE distribution, in which case the provisions of the
 * CDDL are applicable instead of those of the GPL.
 *
 * You may elect to license modified versions of this file under the
 * terms and conditions of either the GPL or the CDDL or both.
 */

#ifndef ___iprt_fs_h
#define ___iprt_fs_h

#include <iprt/cdefs.h>
#include <iprt/types.h>
#include <iprt/time.h>


RT_C_DECLS_BEGIN

/** @defgroup grp_rt_fs    RTFs - Filesystem and Volume
 * @ingroup grp_rt
 * @{
 */


/** @name Filesystem Object Mode Flags.
 *
 * There are two sets of flags: the unix mode flags and the dos
 * attributes.
 *
 * APIs returning mode flags will provide both sets.
 *
 * When specifying mode flags to any API at least one of
 * them must be given. If one set is missing the API will
 * synthesize it from the one given if it requires it.
 *
 * Both sets match their x86 ABIs, the DOS/NT one is simply shifted
 * up 16 bits. The DOS/NT range is bits 16 to 31 inclusively. The
 * Unix range is bits 0 to 15 (inclusively).
 *
 * @{
 */

/** Set user id on execution (S_ISUID). */
00061 #define RTFS_UNIX_ISUID             0004000U
/** Set group id on execution (S_ISGID). */
00063 #define RTFS_UNIX_ISGID             0002000U
/** Sticky bit (S_ISVTX / S_ISTXT). */
00065 #define RTFS_UNIX_ISTXT             0001000U

/** Owner RWX mask (S_IRWXU). */
00068 #define RTFS_UNIX_IRWXU             0000700U
/** Owner readable (S_IRUSR). */
00070 #define RTFS_UNIX_IRUSR             0000400U
/** Owner writable (S_IWUSR). */
00072 #define RTFS_UNIX_IWUSR             0000200U
/** Owner executable (S_IXUSR). */
00074 #define RTFS_UNIX_IXUSR             0000100U

/** Group RWX mask (S_IRWXG). */
00077 #define RTFS_UNIX_IRWXG             0000070U
/** Group readable (S_IRGRP). */
00079 #define RTFS_UNIX_IRGRP             0000040U
/** Group writable (S_IWGRP). */
00081 #define RTFS_UNIX_IWGRP             0000020U
/** Group executable (S_IXGRP). */
00083 #define RTFS_UNIX_IXGRP             0000010U

/** Other RWX mask (S_IRWXO). */
00086 #define RTFS_UNIX_IRWXO             0000007U
/** Other readable (S_IROTH). */
00088 #define RTFS_UNIX_IROTH             0000004U
/** Other writable (S_IWOTH). */
00090 #define RTFS_UNIX_IWOTH             0000002U
/** Other executable (S_IXOTH). */
00092 #define RTFS_UNIX_IXOTH             0000001U

/** Named pipe (fifo) (S_IFIFO). */
00095 #define RTFS_TYPE_FIFO              0010000U
/** Character device (S_IFCHR). */
00097 #define RTFS_TYPE_DEV_CHAR          0020000U
/** Directory (S_IFDIR). */
00099 #define RTFS_TYPE_DIRECTORY         0040000U
/** Block device (S_IFBLK). */
00101 #define RTFS_TYPE_DEV_BLOCK         0060000U
/** Regular file (S_IFREG). */
00103 #define RTFS_TYPE_FILE              0100000U
/** Symbolic link (S_IFLNK). */
00105 #define RTFS_TYPE_SYMLINK           0120000U
/** Socket (S_IFSOCK). */
00107 #define RTFS_TYPE_SOCKET            0140000U
/** Whiteout (S_IFWHT). */
00109 #define RTFS_TYPE_WHITEOUT          0160000U
/** Type mask (S_IFMT). */
00111 #define RTFS_TYPE_MASK              0170000U

/** Unix attribute mask. */
00114 #define RTFS_UNIX_MASK              0xffffU
/** The mask of all the NT, OS/2 and DOS attributes. */
00116 #define RTFS_DOS_MASK               (0x7fffU << RTFS_DOS_SHIFT)

/** The shift value. */
00119 #define RTFS_DOS_SHIFT              16
/** The mask of the OS/2 and DOS attributes. */
00121 #define RTFS_DOS_MASK_OS2           (0x003fU << RTFS_DOS_SHIFT)
/** The mask of the NT attributes. */
00123 #define RTFS_DOS_MASK_NT            (0x7fffU << RTFS_DOS_SHIFT)

/** Readonly object. */
00126 #define RTFS_DOS_READONLY           (0x0001U << RTFS_DOS_SHIFT)
/** Hidden object. */
00128 #define RTFS_DOS_HIDDEN             (0x0002U << RTFS_DOS_SHIFT)
/** System object. */
00130 #define RTFS_DOS_SYSTEM             (0x0004U << RTFS_DOS_SHIFT)
/** Directory. */
00132 #define RTFS_DOS_DIRECTORY          (0x0010U << RTFS_DOS_SHIFT)
/** Archived object.
 * This bit is set by the filesystem after each modification of a file. */
00135 #define RTFS_DOS_ARCHIVED           (0x0020U << RTFS_DOS_SHIFT)
/** Undocumented / Reserved, used to be the FAT volume label. */
00137 #define RTFS_DOS_NT_DEVICE          (0x0040U << RTFS_DOS_SHIFT)
/** Normal object, no other attribute set (NT). */
00139 #define RTFS_DOS_NT_NORMAL          (0x0080U << RTFS_DOS_SHIFT)
/** Temporary object (NT). */
00141 #define RTFS_DOS_NT_TEMPORARY       (0x0100U << RTFS_DOS_SHIFT)
/** Sparse file (NT). */
00143 #define RTFS_DOS_NT_SPARSE_FILE     (0x0200U << RTFS_DOS_SHIFT)
/** Reparse point (NT). */
00145 #define RTFS_DOS_NT_REPARSE_POINT   (0x0400U << RTFS_DOS_SHIFT)
/** Compressed object (NT).
 * For a directory, compression is the default for new files. */
00148 #define RTFS_DOS_NT_COMPRESSED      (0x0800U << RTFS_DOS_SHIFT)
/** Physically offline data (NT).
 * MSDN say, don't mess with this one. */
00151 #define RTFS_DOS_NT_OFFLINE         (0x1000U << RTFS_DOS_SHIFT)
/** Not content indexed by the content indexing service (NT). */
00153 #define RTFS_DOS_NT_NOT_CONTENT_INDEXED (0x2000U << RTFS_DOS_SHIFT)
/** Encryped object (NT).
 * For a directory, encrypted is the default for new files. */
00156 #define RTFS_DOS_NT_ENCRYPTED       (0x4000U << RTFS_DOS_SHIFT)

/** @} */


/** @name Filesystem Object Type Predicates.
 * @{ */
/** Checks the mode flags indicate a named pipe (fifo) (S_ISFIFO). */
00164 #define RTFS_IS_FIFO(fMode)         ( ((fMode) & RTFS_TYPE_MASK) == RTFS_TYPE_FIFO )
/** Checks the mode flags indicate a character device (S_ISCHR). */
00166 #define RTFS_IS_DEV_CHAR(fMode)     ( ((fMode) & RTFS_TYPE_MASK) == RTFS_TYPE_DEV_CHAR )
/** Checks the mode flags indicate a directory (S_ISDIR). */
00168 #define RTFS_IS_DIRECTORY(fMode)    ( ((fMode) & RTFS_TYPE_MASK) == RTFS_TYPE_DIRECTORY )
/** Checks the mode flags indicate a block device (S_ISBLK). */
00170 #define RTFS_IS_DEV_BLOCK(fMode)    ( ((fMode) & RTFS_TYPE_MASK) == RTFS_TYPE_DEV_BLOCK )
/** Checks the mode flags indicate a regular file (S_ISREG). */
00172 #define RTFS_IS_FILE(fMode)         ( ((fMode) & RTFS_TYPE_MASK) == RTFS_TYPE_FILE )
/** Checks the mode flags indicate a symbolic link (S_ISLNK). */
00174 #define RTFS_IS_SYMLINK(fMode)      ( ((fMode) & RTFS_TYPE_MASK) == RTFS_TYPE_SYMLINK )
/** Checks the mode flags indicate a socket (S_ISSOCK). */
00176 #define RTFS_IS_SOCKET(fMode)       ( ((fMode) & RTFS_TYPE_MASK) == RTFS_TYPE_SOCKET )
/** Checks the mode flags indicate a whiteout (S_ISWHT). */
00178 #define RTFS_IS_WHITEOUT(fMode)     ( ((fMode) & RTFS_TYPE_MASK) == RTFS_TYPE_WHITEOUT )
/** @} */


/**
 * Filesystem type IDs returned by RTFsQueryType.
 *
 * This enum is subject to changes and must not be used as part of any ABI or
 * binary format (file, network, etc).
 *
 * @remarks When adding new entries, please update RTFsTypeName().  Also, try
 *          add them to the most natural group.
 */
00191 typedef enum RTFSTYPE
{
    /** Unknown file system. */
00194     RTFSTYPE_UNKNOWN = 0,

    /** Universal Disk Format. */
00197     RTFSTYPE_UDF,
    /** ISO 9660, aka Compact Disc File System (CDFS). */
00199     RTFSTYPE_ISO9660,
    /** Filesystem in Userspace. */
00201     RTFSTYPE_FUSE,
    /** VirtualBox shared folders.  */
00203     RTFSTYPE_VBOXSHF,

    /* Linux: */
    RTFSTYPE_EXT,
    RTFSTYPE_EXT2,
    RTFSTYPE_EXT3,
    RTFSTYPE_EXT4,
    RTFSTYPE_XFS,
    RTFSTYPE_CIFS,
    RTFSTYPE_SMBFS,
    RTFSTYPE_TMPFS,
    RTFSTYPE_SYSFS,
    RTFSTYPE_PROC,

    /* Windows: */
    /** New Technology File System. */
00219     RTFSTYPE_NTFS,
    /** FAT12, FAT16 and FAT32 lumped into one basket.
     * The partition size limit of FAT12 and FAT16 will be the factor
     * limiting the file size (except, perhaps for the 64KB cluster case on
     * non-Windows hosts). */
00224     RTFSTYPE_FAT,

    /* Solaris: */
    /** Zettabyte File System.  */
00228     RTFSTYPE_ZFS,
    /** Unix File System. */
00230     RTFSTYPE_UFS,
    /** Network File System. */
00232     RTFSTYPE_NFS,

    /* Mac OS X: */
    /** Hierarchical File System. */
00236     RTFSTYPE_HFS,
    /** @todo RTFSTYPE_HFS_PLUS? */
00238     RTFSTYPE_AUTOFS,
    RTFSTYPE_DEVFS,

    /* *BSD: */

    /* OS/2: */
    /** High Performance File System. */
00245     RTFSTYPE_HPFS,
    /** Journaled File System (v2).  */
00247     RTFSTYPE_JFS,

    /** The end of valid Filesystem types IDs. */
00250     RTFSTYPE_END,
    /** The usual 32-bit type blow up. */
00252     RTFSTYPE_32BIT_HACK = 0x7fffffff
} RTFSTYPE;
/** Pointer to a Filesystem type ID. */
00255 typedef RTFSTYPE *PRTFSTYPE;


/**
 * The available additional information in a RTFSOBJATTR object.
 */
00261 typedef enum RTFSOBJATTRADD
{
    /** No additional information is available / requested. */
00264     RTFSOBJATTRADD_NOTHING = 1,
    /** The additional unix attributes (RTFSOBJATTR::u::Unix) are available / requested. */
00266     RTFSOBJATTRADD_UNIX,
    /** The additional extended attribute size (RTFSOBJATTR::u::EASize) is available / requested. */
00268     RTFSOBJATTRADD_EASIZE,
    /** The last valid item (inclusive).
     * The valid range is RTFSOBJATTRADD_NOTHING thru RTFSOBJATTRADD_LAST.  */
00271     RTFSOBJATTRADD_LAST = RTFSOBJATTRADD_EASIZE,

    /** The usual 32-bit hack. */
00274     RTFSOBJATTRADD_32BIT_SIZE_HACK = 0x7fffffff
} RTFSOBJATTRADD;


/**
 * Filesystem object attributes.
 */
#pragma pack(1)
00282 typedef struct RTFSOBJATTR
{
    /** Mode flags (st_mode). RTFS_UNIX_*, RTFS_TYPE_*, and RTFS_DOS_*. */
00285     RTFMODE         fMode;

    /** The additional attributes available. */
00288     RTFSOBJATTRADD  enmAdditional;

    /**
     * Additional attributes.
     *
     * Unless explicitly specified to an API, the API can provide additional
     * data as it is provided by the underlying OS.
     */
00296     union RTFSOBJATTRUNION
    {
        /** Additional Unix Attributes
         * These are available when RTFSOBJATTRADD is set in fUnix.
         */
00301          struct RTFSOBJATTRUNIX
         {
            /** The user owning the filesystem object (st_uid).
             * This field is ~0U if not supported. */
00305             RTUID           uid;

            /** The group the filesystem object is assigned (st_gid).
             * This field is ~0U if not supported. */
00309             RTGID           gid;

            /** Number of hard links to this filesystem object (st_nlink).
             * This field is 1 if the filesystem doesn't support hardlinking or
             * the information isn't available.
             */
00315             uint32_t        cHardlinks;

            /** The device number of the device which this filesystem object resides on (st_dev).
             * This field is 0 if this information is not available. */
00319             RTDEV           INodeIdDevice;

            /** The unique identifier (within the filesystem) of this filesystem object (st_ino).
             * Together with INodeIdDevice, this field can be used as a OS wide unique id
             * when both their values are not 0.
             * This field is 0 if the information is not available. */
00325             RTINODE         INodeId;

            /** User flags (st_flags).
             * This field is 0 if this information is not available. */
00329             uint32_t        fFlags;

            /** The current generation number (st_gen).
             * This field is 0 if this information is not available. */
00333             uint32_t        GenerationId;

            /** The device number of a character or block device type object (st_rdev).
             * This field is 0 if the file isn't of a character or block device type and
             * when the OS doesn't subscribe to the major+minor device idenfication scheme. */
00338             RTDEV           Device;
        } Unix;

        /**
         * Extended attribute size is available when RTFS_DOS_HAVE_EA_SIZE is set.
         */
00344         struct RTFSOBJATTREASIZE
        {
            /** Size of EAs. */
00347             RTFOFF          cb;
        } EASize;
    } u;
} RTFSOBJATTR;
#pragma pack()
/** Pointer to a filesystem object attributes structure. */
00353 typedef RTFSOBJATTR *PRTFSOBJATTR;
/** Pointer to a const filesystem object attributes structure. */
00355 typedef const RTFSOBJATTR *PCRTFSOBJATTR;


/**
 * Filesystem object information structure.
 *
 * This is returned by the RTPathQueryInfo(), RTFileQueryInfo() and RTDirRead() APIs.
 */
#pragma pack(1)
00364 typedef struct RTFSOBJINFO
{
   /** Logical size (st_size).
    * For normal files this is the size of the file.
    * For symbolic links, this is the length of the path name contained
    * in the symbolic link.
    * For other objects this fields needs to be specified.
    */
00372    RTFOFF       cbObject;

   /** Disk allocation size (st_blocks * DEV_BSIZE). */
00375    RTFOFF       cbAllocated;

   /** Time of last access (st_atime). */
00378    RTTIMESPEC   AccessTime;

   /** Time of last data modification (st_mtime). */
00381    RTTIMESPEC   ModificationTime;

   /** Time of last status change (st_ctime).
    * If not available this is set to ModificationTime.
    */
00386    RTTIMESPEC   ChangeTime;

   /** Time of file birth (st_birthtime).
    * If not available this is set to ChangeTime.
    */
00391    RTTIMESPEC   BirthTime;

   /** Attributes. */
00394    RTFSOBJATTR  Attr;

} RTFSOBJINFO;
#pragma pack()
/** Pointer to a filesystem object information structure. */
00399 typedef RTFSOBJINFO *PRTFSOBJINFO;
/** Pointer to a const filesystem object information structure. */
00401 typedef const RTFSOBJINFO *PCRTFSOBJINFO;


#ifdef IN_RING3

/**
 * Query the sizes of a filesystem.
 *
 * @returns iprt status code.
 * @param   pszFsPath       Path within the mounted filesystem.
 * @param   pcbTotal        Where to store the total filesystem space. (Optional)
 * @param   pcbFree         Where to store the remaining free space in the filesystem. (Optional)
 * @param   pcbBlock        Where to store the block size. (Optional)
 * @param   pcbSector       Where to store the sector size. (Optional)
 *
 * @sa      RTFileQueryFsSizes
 */
RTR3DECL(int) RTFsQuerySizes(const char *pszFsPath, PRTFOFF pcbTotal, RTFOFF *pcbFree,
                             uint32_t *pcbBlock, uint32_t *pcbSector);

/**
 * Query the mountpoint of a filesystem.
 *
 * @returns iprt status code.
 * @returns VERR_BUFFER_OVERFLOW if cbMountpoint isn't enough.
 * @param   pszFsPath       Path within the mounted filesystem.
 * @param   pszMountpoint   Where to store the mountpoint path.
 * @param   cbMountpoint    Size of the buffer pointed to by pszMountpoint.
 */
RTR3DECL(int) RTFsQueryMountpoint(const char *pszFsPath, char *pszMountpoint, size_t cbMountpoint);

/**
 * Query the label of a filesystem.
 *
 * @returns iprt status code.
 * @returns VERR_BUFFER_OVERFLOW if cbLabel isn't enough.
 * @param   pszFsPath       Path within the mounted filesystem.
 * @param   pszLabel        Where to store the label.
 * @param   cbLabel         Size of the buffer pointed to by pszLabel.
 */
RTR3DECL(int) RTFsQueryLabel(const char *pszFsPath, char *pszLabel, size_t cbLabel);

/**
 * Query the serial number of a filesystem.
 *
 * @returns iprt status code.
 * @param   pszFsPath       Path within the mounted filesystem.
 * @param   pu32Serial      Where to store the serial number.
 */
RTR3DECL(int) RTFsQuerySerial(const char *pszFsPath, uint32_t *pu32Serial);

/**
 * Query the name of the filesystem driver.
 *
 * @returns iprt status code.
 * @returns VERR_BUFFER_OVERFLOW if cbFsDriver isn't enough.
 * @param   pszFsPath       Path within the mounted filesystem.
 * @param   pszFsDriver     Where to store the filesystem driver name.
 * @param   cbFsDriver      Size of the buffer pointed to by pszFsDriver.
 */
RTR3DECL(int) RTFsQueryDriver(const char *pszFsPath, char *pszFsDriver, size_t cbFsDriver);

/**
 * Query the name of the filesystem the file is located on.
 *
 * @returns iprt status code.
 * @param   pszFsPath       Path within the mounted filesystem.  It must exist.
 *                          In case this is a symlink, the file it refers to is
 *                          evaluated.
 * @param   penmType        Where to store the filesystem type, this is always
 *                          set.  See RTFSTYPE for the values.
 */
RTR3DECL(int) RTFsQueryType(const char *pszFsPath, PRTFSTYPE penmType);

#endif /* IN_RING3 */

/**
 * Gets the name of a filesystem type.
 *
 * @returns Pointer to a read-only string containing the name.
 * @param   enmType         A valid filesystem ID.  If outside the valid range,
 *                          the returned string will be pointing to a static
 *                          memory buffer which will be changed on subsequent
 *                          calls to this function by any thread.
 */
RTDECL(const char *) RTFsTypeName(RTFSTYPE enmType);

/**
 * Filesystem properties.
 */
00491 typedef struct RTFSPROPERTIES
{
    /** The maximum size of a filesystem object name.
     * This does not include the '\\0'. */
00495     uint32_t cbMaxComponent;

    /** True if the filesystem is remote.
     * False if the filesystem is local. */
00499     bool    fRemote;

    /** True if the filesystem is case sensitive.
     * False if the filesystem is case insensitive. */
00503     bool    fCaseSensitive;

    /** True if the filesystem is mounted read only.
     * False if the filesystem is mounted read write. */
00507     bool    fReadOnly;

    /** True if the filesystem can encode unicode object names.
     * False if it can't. */
00511     bool    fSupportsUnicode;

    /** True if the filesystem is compresses.
     * False if it isn't or we don't know. */
00515     bool    fCompressed;

    /** True if the filesystem compresses of individual files.
     * False if it doesn't or we don't know. */
00519     bool    fFileCompression;

    /** @todo more? */
} RTFSPROPERTIES;
/** Pointer to a filesystem properties structure. */
00524 typedef RTFSPROPERTIES *PRTFSPROPERTIES;

#ifdef IN_RING3

/**
 * Query the properties of a mounted filesystem.
 *
 * @returns iprt status code.
 * @param   pszFsPath       Path within the mounted filesystem.
 * @param   pProperties     Where to store the properties.
 */
RTR3DECL(int) RTFsQueryProperties(const char *pszFsPath, PRTFSPROPERTIES pProperties);


/**
 * Mountpoint enumerator callback.
 *
 * @returns iprt status code. Failure terminates the enumeration.
 * @param   pszMountpoint   The mountpoint name.
 * @param   pvUser          The user argument.
 */
typedef DECLCALLBACK(int) FNRTFSMOUNTPOINTENUM(const char *pszMountpoint, void *pvUser);
/** Pointer to a FNRTFSMOUNTPOINTENUM(). */
typedef FNRTFSMOUNTPOINTENUM *PFNRTFSMOUNTPOINTENUM;

/**
 * Enumerate mount points.
 *
 * @returns iprt status code.
 * @param   pfnCallback     The callback function.
 * @param   pvUser          The user argument to the callback.
 */
RTR3DECL(int) RTFsMountpointsEnum(PFNRTFSMOUNTPOINTENUM pfnCallback, void *pvUser);


#endif /* IN_RING3 */

/** @} */

RT_C_DECLS_END

#endif /* ___iprt_fs_h */


Generated by  Doxygen 1.6.0   Back to index