Changeset 21810 in vbox for trunk/include

Timestamp:

Jul 27, 2009 1:01:15 PM (16 years ago)

Author:

vboxsync

svn:sync-xref-src-repo-rev:

50418

Message:

IPRT: r=bird: RTZip - dunno if anything works after my changes because there isn't any testcase. Please add one.

• Fixed numerous allocation related issues (missing checks for success and leaks).
• RTTarList wouldn't set *pcFiles and *ppapszFiles if no files were found.
• Don't pass pcbRead and pcbWritten to RTFileRead/Write if it is unacceptable to do partial reads and writes.
• for (;;) instead of do while (0).
• Always specify all three flag categories for RTFileOpen calls!
• Adding > 4GB files to a tar file on 32-bit would fill up the disk.
• Missing rc check in rtTarCheckheader when converting the checksum.
• Don't override errors with VERR_FILE_IO_ERROR, VERR_FILE_NOT_FOUND or in one case VINF_SUCCESS.
• Use RT_ZERO instead of memset.
• Use Assert*Return for input validation. The if (bad) {AssertMsgFailed(); return failure; } style checking found around IPRT is from before the Assert*Return macro was added.
• Added todos for inefficient 512 bytes at a time copying.
• Added todos for interface renaming to conform with IPRT conventions.

File:

• trunk/include/iprt/tar.h (modified) (4 diffs)

trunk/include/iprt/tar.h

@@ -44 +44 @@
  * Check if the specified file exists in the Tar archive.
  *
+ * (The matching is case sensitive.)
+ *
+ * @note    Currently only regular files are supported.
+ *
  * @returns iprt status code.
- * @retval VINF_SUCCESS when the file exists in the Tar archive
- * @retval VERR_FILE_NOT_FOUND when the file not exists in the Tar archive
- *
- * @note Currently only regular files are supported.
+ * @retval  VINF_SUCCESS when the file exists in the Tar archive.
+ * @retval  VERR_FILE_NOT_FOUND when the file not exists in the Tar archive.
  *
  * @param   pszTarFile      Tar file to check.
  * @param   pszFile         Filename to check for.
+ *
+ * @todo    r=bird: rename to RTTarQueryFileExists (or bool RTTarFileExist).
  */
 RTR3DECL(int) RTTarExists(const char *pszTarFile, const char *pszFile);
@@ -58 +62 @@
  * Create a file list from a Tar archive.
  *
+ * @note    Currently only regular files are supported.
+ *
  * @returns iprt status code.
  *
- * @note Currently only regular files are supported.
- *
  * @param   pszTarFile      Tar file to list files from.
- * @param   ppapszFiles     On success the array with the filenames.
+ * @param   ppapszFiles     On success an array with array with the filenames is
+ *                          returned. The names must be freed with RTStrFree and
+ *                          the array with RTMemFree.
  * @param   pcFiles         On success the number of entries in ppapszFiles.
  */
@@ -71 +77 @@
  * Extract a set of files from a Tar archive.
  *
- * The output directory has to exists. Also note that this function is atomic.
- * If an error occurs all previously extracted files will be deleted.
+ * Also note that this function is atomic. If an error occurs all previously
+ * extracted files will be deleted.
  *
- * @note Currently only regular files are supported. Also some of the header
- * fields are not used (uid, gid, uname, gname, mtime).
+ * (The matching is case sensitive.)
+ *
+ * @note    Currently only regular files are supported. Also some of the heade
+ *          fields are not used (uid, gid, uname, gname, mtime).
  *
  * @returns iprt status code.
  *
  * @param   pszTarFile      Tar file to extract files from.
- * @param   pszOutputDir    Where to store the extracted files.
+ * @param   pszOutputDir    Where to store the extracted files. Must exist.
  * @param   papszFiles      Which files should be extracted.
  * @param   cFiles          The number of files in papszFiles.
+ *
+ * @todo    r=bird: Rename to RTTarExtractFiles.
  */
 RTR3DECL(int) RTTarExtract(const char *pszTarFile, const char *pszOutputDir, const char * const *papszFiles, size_t cFiles);
@@ -89 +99 @@
  * Extract a file by index from a Tar archive.
  *
- * The index is starting by zero. The output directory has to exists.
- *
- * @note Currently only regular files are supported. Also some of the header
- * fields are not used (uid, gid, uname, gname, mtime).
+ * @note    Currently only regular files are supported. Also some of the header
+ *          fields are not used (uid, gid, uname, gname, mtime).
  *
  * @returns iprt status code.
- * @retval VERR_FILE_NOT_FOUND when the index isn't valid
+ * @retval  VERR_FILE_NOT_FOUND when the index isn't valid.
  *
  * @param   pszTarFile      Tar file to extract the file from.
- * @param   pszOutputDir    Where to store the extracted file.
- * @param   iIndex          Which file should be extracted.
- * @param   ppszFileName    On success the filename of the extracted file.
+ * @param   pszOutputDir    Where to store the extracted file. Must exist.
+ * @param   iIndex          Which file should be extracted, 0 based.
+ * @param   ppszFileName    On success the filename of the extracted file. Must
+ *                          be freed with RTStrFree.
+ *
+ * @todo    r=bird: Rename to RTTarExtractByIndex.
  */
-RTR3DECL(int) RTTarExtractIndex(const char *pszTarFile, const char *pszOutputDir, size_t iIndex, char** ppszFileName);
+RTR3DECL(int) RTTarExtractIndex(const char *pszTarFile, const char *pszOutputDir, size_t iIndex, char **ppszFileName);
 
 /**