Changeset 69977 in vbox for trunk/include/iprt

Timestamp:

Dec 7, 2017 1:02:36 PM (7 years ago)

Author:

vboxsync

Message:

IPRT/vfs: Implemented RTVFsFileSetSize, RTVfsFileGetMaxSize and RTvfsFileQueryMaxSize.

Location:

trunk/include/iprt

Files:

• file.h (modified) (2 diffs)
• mangling.h (modified) (2 diffs)
• vfs.h (modified) (1 diff)
• vfslowlevel.h (modified) (3 diffs)

trunk/include/iprt/file.h

@@ -1137 +1137 @@
 /** @} */
 
-/** @name RTFileSetAllocationSize flags
+/**
+ * Sets the current size of the file ensuring that all required blocks
+ * are allocated on the underlying medium.
+ *
+ * @returns IPRT status code.
+ * @retval  VERR_NOT_SUPPORTED if either this operation is not supported on the
+ *          current host in an efficient manner or the given combination of
+ *          flags is not supported.
+ * @param   hFile           The handle to the file.
+ * @param   cbSize          The new size of the file to allocate.
+ * @param   fFlags          Combination of RTFILE_ALLOC_SIZE_F_*
+ */
+RTDECL(int) RTFileSetAllocationSize(RTFILE hFile, uint64_t cbSize, uint32_t fFlags);
+
+/** @name RTFILE_ALLOC_SIZE_F_XXX - RTFileSetAllocationSize flags
  * @{ */
 /** Default flags. */
 #define RTFILE_ALLOC_SIZE_F_DEFAULT         0
-/** Do not change the size of the file if the given size is
- * bigger than the current file size. Useful to preallocate
- * blocks beyond the current size for appending data in an efficient
- * manner. Might not be supported on all hosts and will return
+/** Do not change the size of the file if the given size is bigger than the
+ * current file size.
+ *
+ * Useful to preallocate blocks beyond the current size for appending data in an
+ * efficient manner. Might not be supported on all hosts and will return
  * VERR_NOT_SUPPORTED in that case. */
 #define RTFILE_ALLOC_SIZE_F_KEEP_SIZE       RT_BIT(0)
@@ -1151 +1166 @@
 /** @} */
 
-/**
- * Sets the current size of the file ensuring that all required blocks
- * are allocated on the underlying medium.
- *
- * @returns IPRT status code.
- * @retval  VERR_NOT_SUPPORTED if either this operation is not supported on the current host
- *                             in an efficient manner or the given combination of flags is
- *                             not supported.
- * @param   hFile           The handle to the file.
- * @param   cbSize          The new size of the file to allocate.
- * @param   fFlags          Combination of RTFILE_ALLOC_SIZE_F_*
- */
-RTDECL(int) RTFileSetAllocationSize(RTFILE hFile, uint64_t cbSize, uint32_t fFlags);
 
 #ifdef IN_RING3

trunk/include/iprt/mangling.h

@@ -2474 +2474 @@
 # define RTVfsFileGetOpenFlags                          RT_MANGLER(RTVfsFileGetOpenFlags)
 # define RTVfsFileGetSize                               RT_MANGLER(RTVfsFileGetSize)
+# define RTVfsFileGetMaxSize                            RT_MANGLER(RTVfsFileGetMaxSize)
 # define RTVfsFileOpen                                  RT_MANGLER(RTVfsFileOpen)
 # define RTVfsFileOpenNormal                            RT_MANGLER(RTVfsFileOpenNormal)
 # define RTVfsFilePoll                                  RT_MANGLER(RTVfsFilePoll)
 # define RTVfsFileQueryInfo                             RT_MANGLER(RTVfsFileQueryInfo)
+# define RTVfsFileQueryMaxSize                          RT_MANGLER(RTVfsFileQueryMaxSize)
 # define RTVfsFileRead                                  RT_MANGLER(RTVfsFileRead)
 # define RTVfsFileReadAt                                RT_MANGLER(RTVfsFileReadAt)
@@ -2484 +2486 @@
 # define RTVfsFileRetainDebug                           RT_MANGLER(RTVfsFileRetainDebug)
 # define RTVfsFileSeek                                  RT_MANGLER(RTVfsFileSeek)
+# define RTVfsFileSetSize                               RT_MANGLER(RTVfsFileSetSize)
 # define RTVfsFileSgRead                                RT_MANGLER(RTVfsFileSgRead)
 # define RTVfsFileSgWrite                               RT_MANGLER(RTVfsFileSgWrite)

trunk/include/iprt/vfs.h

@@ -1404 +1404 @@
 RTDECL(int)         RTVfsFileSeek(RTVFSFILE hVfsFile, RTFOFF offSeek, uint32_t uMethod, uint64_t *poffActual);
 
-RTDECL(int)         RTVfsFileSetSize(RTVFSFILE hVfsFile, uint64_t cbSize);
+/**
+ * Sets the size of a file.
+ *
+ * This may also be used for preallocating space
+ * (RTVFSFILE_SIZE_F_PREALLOC_KEEP_SIZE).
+ *
+ * @returns IPRT status code.
+ * @retval  VERR_ACCESS_DENIED if handle isn't writable.
+ * @retval  VERR_WRITE_PROTECT if read-only file system.
+ * @retval  VERR_FILE_TOO_BIG if cbSize is larger than what the file system can
+ *          theoretically deal with.
+ * @retval  VERR_DISK_FULL if the file system if full.
+ * @retval  VERR_NOT_SUPPORTED if fFlags indicates some operation that's not
+ *          supported by the file system / host operating system.
+ *
+ * @param   hVfsFile        The VFS file handle.
+ * @param   cbSize          The new file size.
+ * @param   fFlags          RTVFSFILE_SIZE_F_NORMAL, RTVFSFILE_SIZE_F_GROW, or
+ *                          RTVFSFILE_SIZE_F_GROW_KEEP_SIZE.
+ *
+ * @sa      RTFileSetSize, RTFileSetAllocationSize
+ */
+RTDECL(int)         RTVfsFileSetSize(RTVFSFILE hVfsFile, uint64_t cbSize, uint32_t fFlags);
+
+/** @name RTVFSFILE_SIZE_F_XXX - RTVfsFileSetSize flags.
+ * @{ */
+/** Normal truncate or grow (zero'ed) like RTFileSetSize . */
+#define RTVFSFILE_SIZE_F_NORMAL             UINT32_C(0x00000001)
+/** Only grow the file, ignore call if cbSize would trunacte the file.
+ * This is what RTFileSetAllocationSize does by default.  */
+#define RTVFSFILE_SIZE_F_GROW               UINT32_C(0x00000002)
+/** Only grow the file, ignore call if cbSize would trunacte the file.
+ * This is what RTFileSetAllocationSize does by default.  */
+#define RTVFSFILE_SIZE_F_GROW_KEEP_SIZE     UINT32_C(0x00000003)
+/** Action mask. */
+#define RTVFSFILE_SIZE_F_ACTION_MASK        UINT32_C(0x00000003)
+/** Validate the flags.
+ * Will reference @a a_fFlags more than once.  */
+#define RTVFSFILE_SIZE_F_IS_VALID(a_fFlags) \
+    ( !((a_fFlags) & ~RTVFSFILE_SIZE_F_ACTION_MASK) && ((a_fFlags) & RTVFSFILE_SIZE_F_ACTION_MASK) != 0 )
+/** @} */
+
+
+/** Mask of valid flags. */
+#define RTFILE_ALLOC_SIZE_F_VALID           (RTFILE_ALLOC_SIZE_F_KEEP_SIZE)
+/** @} */
+
+
 RTDECL(int)         RTVfsFileGetSize(RTVFSFILE hVfsFile, uint64_t *pcbSize);
 RTDECL(RTFOFF)      RTVfsFileGetMaxSize(RTVFSFILE hVfsFile);
-RTDECL(int)         RTVfsFileGetMaxSizeEx(RTVFSFILE hVfsFile, PRTFOFF pcbMax);
+RTDECL(int)         RTVfsFileQueryMaxSize(RTVFSFILE hVfsFile, uint64_t *pcbMax);
 
 /**

trunk/include/iprt/vfslowlevel.h

@@ -1004 +1004 @@
 
     /**
-     * Get the current file/stream size.
+     * Get the current file size.
      *
      * @returns IPRT status code.
@@ -1012 +1012 @@
      */
     DECLCALLBACKMEMBER(int, pfnQuerySize)(void *pvThis, uint64_t *pcbFile);
+
+    /**
+     * Change the file size.
+     *
+     * @returns IPRT status code.
+     * @retval  VERR_ACCESS_DENIED if handle isn't writable.
+     * @retval  VERR_WRITE_PROTECT if read-only file system.
+     * @retval  VERR_FILE_TOO_BIG if cbSize is larger than what the file system can
+     *          theoretically deal with.
+     * @retval  VERR_DISK_FULL if the file system if full.
+     * @retval  VERR_NOT_SUPPORTED if fFlags indicates some operation that's not
+     *          supported by the file system / host operating system.
+     *
+     * @param   pvThis      The implementation specific file data.
+     * @param   pcbFile     Where to store the current file size.
+     * @param   fFlags      RTVFSFILE_SET_SIZE_F_XXX.
+     * @note    Optional.  If NULL, VERR_WRITE_PROTECT will be returned.
+     * @sa      RTFileSetSize, RTFileSetAllocationSize
+     */
+    DECLCALLBACKMEMBER(int, pfnSetSize)(void *pvThis, uint64_t cbFile, uint32_t fFlags);
+
+    /**
+     * Determine the maximum file size.
+     *
+     * This won't take amount of freespace into account, just the limitations of the
+     * underlying file system / host operating system.
+     *
+     * @returns IPRT status code.
+     * @param   pvThis      The implementation specific file data.
+     * @param   pcbMax      Where to return the max file size.
+     * @note    Optional.  If NULL, VERR_NOT_IMPLEMENTED will be returned.
+     * @sa      RTFileGetMaxSizeEx
+     */
+    DECLCALLBACKMEMBER(int, pfnQueryMaxSize)(void *pvThis, uint64_t *pcbMax);
 
     /** @todo There will be more methods here. */
@@ -1022 +1056 @@
 
 /** The RTVFSFILEOPS structure version. */
-#define RTVFSFILEOPS_VERSION        RT_MAKE_U32_FROM_U8(0xff,0x7f,1,0)
+#define RTVFSFILEOPS_VERSION        RT_MAKE_U32_FROM_U8(0xff,0x7f,2,0)
 
 /**