Changeset 8925

Timestamp:

05/19/08 18:59:11 (8 months ago)

Author:

vboxsync

Message:

New file APIs for reading (or mapping) a file into memory: RTFileReadAll, RTFileReadAllEx, RTFileReadAllByHandle, RTFileReadAllByHandleEx and RTFileReadAllFree.

Files:

• trunk/include/iprt/file.h (modified) (1 diff)
• trunk/src/VBox/Runtime/Makefile.kmk (modified) (1 diff)
• trunk/src/VBox/Runtime/generic/RTFileReadAll-generic.cpp (added)
• trunk/src/VBox/Runtime/generic/RTFileReadAllByHandle-generic.cpp (added)
• trunk/src/VBox/Runtime/generic/RTFileReadAllByHandleEx-generic.cpp (added)
• trunk/src/VBox/Runtime/generic/RTFileReadAllEx-generic.cpp (added)
• trunk/src/VBox/Runtime/generic/RTFileReadAllFree-generic.cpp (added)

trunk/include/iprt/file.h

@@ -657 +657 @@
-RTR3DECL(int) RTFileIoCtl(RTFILE File, int iRequest, void *pvData, unsigned cbData, int *piRet);
-
+/**
+ * Reads the file into memory.
+ *
+ * The caller must free the memory using RTFileReadAllFree().
+ *
+ * @returns IPRT status code.
+ * @param   pszFilename     The name of the file.
+ * @param   ppvFile         Where to store the pointer to the memory on successful return.
+ * @param   pcbFile         Where to store the size of the file on successful return.
+ *
+ * @remarks Note that this function may be implemented using memory mapping, which means
+ *          that the file may remain open until RTFileReadAllFree() is called. It also
+ *          means that the return memory may reflect the state of the file when it's
+ *          accessed instead of when this call was done. So, in short, don't use this
+ *          API for volatile files, then rather use the extended variant with a
+ *          yet-to-be-defined.
+ */
+RTDECL(int) RTFileReadAll(const char *pszFilename, void **ppvFile, size_t *pcbFile);
+
+/**
+ * Reads the file into memory.
+ *
+ * The caller must free the memory using RTFileReadAllFree().
+ *
+ * @returns IPRT status code.
+ * @param   pszFilename     The name of the file.
+ * @param   off             The offset to start reading at.
+ * @param   cbMax           The maximum number of bytes to read into memory. Specify RTFOFF_MAX
+ *                          to read to the end of the file.
+ * @param   fFlags          Flags for the future, must be 0.
+ * @param   ppvFile         Where to store the pointer to the memory on successful return.
+ * @param   pcbFile         Where to store the size of the file on successful return.
+ *
+ * @remarks See the remarks for RTFileReadAll.
+ */
+RTDECL(int) RTFileReadAllEx(const char *pszFilename, RTFOFF off, RTFOFF cbMax, uint32_t fFlags, void **ppvFile, size_t *pcbFile);
+
+/**
+ * Reads the file into memory.
+ *
+ * The caller must free the memory using RTFileReadAllFree().
+ *
+ * @returns IPRT status code.
+ * @param   File            The handle to the file.
+ * @param   ppvFile         Where to store the pointer to the memory on successful return.
+ * @param   pcbFile         Where to store the size of the file on successful return.
+ *
+ * @remarks See the remarks for RTFileReadAll.
+ */
+RTDECL(int) RTFileReadAllByHandle(RTFILE File, void **ppvFile, size_t *pcbFile);
+
+/**
+ * Reads the file into memory.
+ *
+ * The caller must free the memory using RTFileReadAllFree().
+ *
+ * @returns IPRT status code.
+ * @param   File            The handle to the file.
+ * @param   off             The offset to start reading at.
+ * @param   cbMax           The maximum number of bytes to read into memory. Specify RTFOFF_MAX
+ *                          to read to the end of the file.
+ * @param   fFlags          Flags for the future, must be 0.
+ * @param   ppvFile         Where to store the pointer to the memory on successful return.
+ * @param   pcbFile         Where to store the size of the file on successful return.
+ *
+ * @remarks See the remarks for RTFileReadAll.
+ */
+RTDECL(int) RTFileReadAllByHandleEx(RTFILE File, RTFOFF off, RTFOFF cbMax, uint32_t fFlags, void **ppvFile, size_t *pcbFile);
+
+/**
+ * Frees the memory returned by one of the RTFileReadAll(), RTFileReadAllEx(),
+ * RTFileReadAllByHandle() and RTFileReadAllByHandleEx() functions.
+ *
+ * @param   pvFile          Pointer to the memory.
+ * @param   cbFile          The size of the memory.
+ */
+RTDECL(int) RTFileReadAllFree(void **ppvFile, size_t *pcbFile);
+
-#endif /* IN_RING3 */
-

trunk/src/VBox/Runtime/Makefile.kmk

@@ -226 +226 @@
-        generic/env-generic.cpp \
-        generic/RTFileCopy-generic.cpp \
+        generic/RTFileReadAll-generic.cpp \
+        generic/RTFileReadAllEx-generic.cpp \
+        generic/RTFileReadAllByHandle-generic.cpp \
+        generic/RTFileReadAllByHandleEx-generic.cpp \
+        generic/RTFileReadAllFree-generic.cpp \
-        generic/RTLogWriteStdErr-generic.cpp \
-        generic/RTLogWriteStdOut-generic.cpp \