Changeset 23291 in vbox for trunk/include/iprt

Timestamp:

Sep 24, 2009 4:08:19 PM (15 years ago)

Author:

vboxsync

Message:

IPRT: RTPathQueryInfo and RTPathSetTimes should work on symbolic links when specified. Introduced Ex versions of these to work around this issue. Should also address the lack of symlinks in the RTDirReadEx output as well VWRN_NO_DIRENT_INFO on broken links.

Location:

trunk/include/iprt

Files:

• err.h (modified) (1 diff)
• path.h (modified) (9 diffs)

trunk/include/iprt/err.h

@@ -710 +710 @@
 /** Too many symbolic links. */
 #define VERR_TOO_MANY_SYMLINKS              (-156)
+/** The OS does not support setting the time stamps on a symbolic link. */
+#define VERR_NS_SYMLINK_SET_TIME            (-157)
 /** @} */
 

trunk/include/iprt/path.h

@@ -118 +118 @@
 
 
+/** @name Generic RTPath flags
+ * @{ */
+/** Last component: Work on the link. */
+#define RTPATH_F_ON_LINK          RT_BIT_32(0)
+/** Last component: Follow if link. */
+#define RTPATH_F_FOLLOW_LINK      RT_BIT_32(1)
+/** @} */
+
+
+/** Validates a flags parameter containing RTPATH_F_*.
+ * @remarks The parameters will be referneced multiple times. */
+#define RTPATH_F_IS_VALID(fFlags, fIgnore) \
+    (    ((fFlags) & ~(uint32_t)(fIgnore)) == RTPATH_F_ON_LINK \
+      || ((fFlags) & ~(uint32_t)(fIgnore)) == RTPATH_F_FOLLOW_LINK )
+
+
 /**
  * Checks if the path exists.
  *
- * Symbolic links will all be attempted resolved.
+ * Symbolic links will all be attempted resolved and broken links means false.
  *
  * @returns true if it exists and false if it doesn't.
@@ -127 +143 @@
  */
 RTDECL(bool) RTPathExists(const char *pszPath);
+
+/**
+ * Checks if the path exists.
+ *
+ * @returns true if it exists and false if it doesn't.
+ * @param   pszPath     The path to check.
+ * @param   fFlags      RTPATH_F_ON_LINK or RPATH_F_FOLLOW_LINK.
+ */
+RTDECL(bool) RTPathExistsEx(const char *pszPath, uint32_t fFlags);
 
 /**
@@ -500 +525 @@
  * Query information about a file system object.
  *
- * This API will not resolve symbolic links in the last component (just
- * like unix lstat()).
- *
- * @returns VINF_SUCCESS if the object exists, information returned.
- * @returns VERR_PATH_NOT_FOUND if any but the last component in the specified
+ * This API will resolve NOT symbolic links in the last component (just like
+ * unix lstat()).
+ *
+ * @returns IPRT status code.
+ * @retval  VINF_SUCCESS if the object exists, information returned.
+ * @retval  VERR_PATH_NOT_FOUND if any but the last component in the specified
  *          path was not found or was not a directory.
- * @returns VERR_FILE_NOT_FOUND if the object does not exist (but path to the
+ * @retval  VERR_FILE_NOT_FOUND if the object does not exist (but path to the
  *          parent directory exists).
- * @returns some other iprt status code.
  *
  * @param   pszPath     Path to the file system object.
@@ -519 +544 @@
 
 /**
+ * Query information about a file system object.
+ *
+ * @returns IPRT status code.
+ * @retval  VINF_SUCCESS if the object exists, information returned.
+ * @retval  VERR_PATH_NOT_FOUND if any but the last component in the specified
+ *          path was not found or was not a directory.
+ * @retval  VERR_FILE_NOT_FOUND if the object does not exist (but path to the
+ *          parent directory exists).
+ *
+ * @param   pszPath     Path to the file system object.
+ * @param   pObjInfo    Object information structure to be filled on successful return.
+ * @param   enmAdditionalAttribs
+ *                      Which set of additional attributes to request.
+ *                      Use RTFSOBJATTRADD_NOTHING if this doesn't matter.
+ * @param   fFlags      RTPATH_F_ON_LINK or RPATH_F_FOLLOW_LINK.
+ */
+RTR3DECL(int) RTPathQueryInfoEx(const char *pszPath, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAdditionalAttribs, uint32_t fFlags);
+
+/**
  * Changes the mode flags of a file system object.
  *
@@ -573 +617 @@
 
 /**
+ * Changes one or more of the timestamps associated of file system object.
+ *
+ * @returns iprt status code.
+ * @param   pszPath             Path to the file system object.
+ * @param   pAccessTime         Pointer to the new access time.
+ * @param   pModificationTime   Pointer to the new modification time.
+ * @param   pChangeTime         Pointer to the new change time. NULL if not to be changed.
+ * @param   pBirthTime          Pointer to the new time of birth. NULL if not to be changed.
+ * @param   fFlags              RTPATH_F_ON_LINK or RPATH_F_FOLLOW_LINK.
+ *
+ * @remark  The file system might not implement all these time attributes,
+ *          the API will ignore the ones which aren't supported.
+ *
+ * @remark  The file system might not implement the time resolution
+ *          employed by this interface, the time will be chopped to fit.
+ *
+ * @remark  The file system may update the change time even if it's
+ *          not specified.
+ *
+ * @remark  POSIX can only set Access & Modification and will always set both.
+ */
+RTR3DECL(int) RTPathSetTimesEx(const char *pszPath, PCRTTIMESPEC pAccessTime, PCRTTIMESPEC pModificationTime,
+                               PCRTTIMESPEC pChangeTime, PCRTTIMESPEC pBirthTime, uint32_t fFlags);
+
+/**
  * Gets one or more of the timestamps associated of file system object.
  *
@@ -582 +651 @@
  * @param   pBirthTime          Where to store the creation time. NULL is ok.
  *
- * @remark  This is wrapper around RTPathQueryInfo() and exists to complement RTPathSetTimes().
+ * @remark  This is wrapper around RTPathQueryInfo() and exists to complement
+ *          RTPathSetTimes().  If the last component is a symbolic link, it will
+ *          not be resolved.
  */
 RTR3DECL(int) RTPathGetTimes(const char *pszPath, PRTTIMESPEC pAccessTime, PRTTIMESPEC pModificationTime,
@@ -601 +672 @@
 
 /**
+ * Changes the owner and/or group of a file system object.
+ *
+ * @returns iprt status code.
+ * @param   pszPath     Path to the file system object.
+ * @param   uid         The new file owner user id. Use -1 (or ~0) to leave this unchanged.
+ * @param   gid         The new group id. Use -1 (or ~0) to leave this unchanged.
+ * @param   fFlags      RTPATH_F_ON_LINK or RPATH_F_FOLLOW_LINK.
+ */
+RTR3DECL(int) RTPathSetOwnerEx(const char *pszPath, uint32_t uid, uint32_t gid, uint32_t fFlags);
+
+/**
  * Gets the owner and/or group of a file system object.
  *
@@ -608 +690 @@
  * @param   pGid        Where to store the group id. NULL is ok.
  *
- * @remark  This is wrapper around RTPathQueryInfo() and exists to complement RTPathGetOwner().
+ * @remark  This is wrapper around RTPathQueryInfo() and exists to complement
+ *          RTPathGetOwner().  If the last component is a symbolic link, it will
+ *          not be resolved.
  */
 RTR3DECL(int) RTPathGetOwner(const char *pszPath, uint32_t *pUid, uint32_t *pGid);
@@ -622 +706 @@
  * Renames a path within a filesystem.
  *
+ * This will rename symbolic links.  If RTPATHRENAME_FLAGS_REPLACE is used and
+ * pszDst is a symbolic link, it will be replaced and not its target.
+ *
  * @returns IPRT status code.
  * @param   pszSrc      The source path.