Changeset 77632 in vbox for trunk/include/iprt

Timestamp:

Mar 10, 2019 1:33:52 PM (6 years ago)

Author:

vboxsync

Message:

IPRT: Adding RTFileSgRead and RTFileSgWrite (for FsPerf). bugref:9172

Location:

trunk/include/iprt

Files:

• file.h (modified) (7 diffs)
• mangling.h (modified) (1 diff)

trunk/include/iprt/file.h

@@ -370 +370 @@
  * @param   pvBuf       Where to put the bytes we read.
  * @param   cbToRead    How much to read.
- * @param   *pcbRead    How much we actually read .
+ * @param   pcbRead     How much we actually read .
  *                      If NULL an error will be returned for a partial read.
  */
@@ -383 +383 @@
  * @param   pvBuf       Where to put the bytes we read.
  * @param   cbToRead    How much to read.
- * @param   *pcbRead    How much we actually read .
+ * @param   pcbRead     How much we actually read .
  *                      If NULL an error will be returned for a partial read.
+ *
+ * @note    OS/2 requires separate seek and write calls.
+ *
  * @note    Whether the file position is modified or not is host specific.
  */
 RTDECL(int)  RTFileReadAt(RTFILE File, RTFOFF off, void *pvBuf, size_t cbToRead, size_t *pcbRead);
+
+/**
+ * Read bytes from a file at a given offset into a S/G buffer.
+ *
+ * @returns iprt status code.
+ * @param   hFile       Handle to the file.
+ * @param   pSgBuf      Pointer to the S/G buffer to read into.
+ * @param   cbToRead    How much to read.
+ * @param   pcbRead     How much we actually read .
+ *                      If NULL an error will be returned for a partial read.
+ *
+ * @note    It is not possible to guarantee atomicity on all platforms, so
+ *          caller must take care wrt concurrent access to @a hFile.
+ */
+RTDECL(int)  RTFileSgRead(RTFILE hFile, PRTSGBUF pSgBuf, size_t cbToRead, size_t *pcbRead);
 
 /**
@@ -397 +415 @@
  * @param   pSgBuf      Pointer to the S/G buffer to read into.
  * @param   cbToRead    How much to read.
- * @param   *pcbRead    How much we actually read .
+ * @param   pcbRead     How much we actually read .
  *                      If NULL an error will be returned for a partial read.
+ *
  * @note    Whether the file position is modified or not is host specific.
+ *
+ * @note    It is not possible to guarantee atomicity on all platforms, so
+ *          caller must take care wrt concurrent access to @a hFile.
  */
 RTDECL(int)  RTFileSgReadAt(RTFILE hFile, RTFOFF off, PRTSGBUF pSgBuf, size_t cbToRead, size_t *pcbRead);
@@ -410 +432 @@
  * @param   pvBuf       What to write.
  * @param   cbToWrite   How much to write.
- * @param   *pcbWritten How much we actually wrote.
+ * @param   pcbWritten  How much we actually wrote.
  *                      If NULL an error will be returned for a partial write.
  */
@@ -423 +445 @@
  * @param   pvBuf       What to write.
  * @param   cbToWrite   How much to write.
- * @param   *pcbWritten How much we actually wrote.
+ * @param   pcbWritten  How much we actually wrote.
  *                      If NULL an error will be returned for a partial write.
  *
+ * @note    OS/2 requires separate seek and write calls.
+ *
  * @note    Whether the file position is modified or not is host specific.
+ *
  * @note    Whether @a off is used when @a hFile was opened with RTFILE_O_APPEND
  *          is also host specific.  Currently Linux is the the only one
@@ -432 +457 @@
  */
 RTDECL(int)  RTFileWriteAt(RTFILE hFile, RTFOFF off, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten);
+
+/**
+ * Write bytes from a S/G buffer to a file.
+ *
+ * @returns iprt status code.
+ * @param   hFile       Handle to the file.
+ * @param   pSgBuf      What to write.
+ * @param   cbToWrite   How much to write.
+ * @param   pcbWritten  How much we actually wrote.
+ *                      If NULL an error will be returned for a partial write.
+ *
+ * @note    It is not possible to guarantee atomicity on all platforms, so
+ *          caller must take care wrt concurrent access to @a hFile.
+ */
+RTDECL(int)  RTFileSgWrite(RTFILE hFile, PRTSGBUF pSgBuf, size_t cbToWrite, size_t *pcbWritten);
 
 /**
@@ -441 +481 @@
  * @param   pSgBuf      What to write.
  * @param   cbToWrite   How much to write.
- * @param   *pcbWritten How much we actually wrote.
+ * @param   pcbWritten  How much we actually wrote.
  *                      If NULL an error will be returned for a partial write.
  *
+ * @note    It is not possible to guarantee atomicity on all platforms, so
+ *          caller must take care wrt concurrent access to @a hFile.
+ *
  * @note    Whether the file position is modified or not is host specific.
+ *
  * @note    Whether @a off is used when @a hFile was opened with RTFILE_O_APPEND
  *          is also host specific.  Currently Linux is the the only one

trunk/include/iprt/mangling.h

@@ -956 +956 @@
 # define RTFileSetSize                                  RT_MANGLER(RTFileSetSize)
 # define RTFileSetTimes                                 RT_MANGLER(RTFileSetTimes)
+# define RTFileSgRead                                   RT_MANGLER(RTFileSgRead)
 # define RTFileSgReadAt                                 RT_MANGLER(RTFileSgReadAt)
+# define RTFileSgWrite                                  RT_MANGLER(RTFileSgWrite)
 # define RTFileSgWriteAt                                RT_MANGLER(RTFileSgWriteAt)
 # define RTFileTell                                     RT_MANGLER(RTFileTell)