[1] | 1 | /** @file
|
---|
[8245] | 2 | * IPRT - Path Manipulation.
|
---|
[1] | 3 | */
|
---|
| 4 |
|
---|
| 5 | /*
|
---|
[98103] | 6 | * Copyright (C) 2006-2023 Oracle and/or its affiliates.
|
---|
[1] | 7 | *
|
---|
[96407] | 8 | * This file is part of VirtualBox base platform packages, as
|
---|
| 9 | * available from https://www.virtualbox.org.
|
---|
[5999] | 10 | *
|
---|
[96407] | 11 | * This program is free software; you can redistribute it and/or
|
---|
| 12 | * modify it under the terms of the GNU General Public License
|
---|
| 13 | * as published by the Free Software Foundation, in version 3 of the
|
---|
| 14 | * License.
|
---|
| 15 | *
|
---|
| 16 | * This program is distributed in the hope that it will be useful, but
|
---|
| 17 | * WITHOUT ANY WARRANTY; without even the implied warranty of
|
---|
| 18 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
---|
| 19 | * General Public License for more details.
|
---|
| 20 | *
|
---|
| 21 | * You should have received a copy of the GNU General Public License
|
---|
| 22 | * along with this program; if not, see <https://www.gnu.org/licenses>.
|
---|
| 23 | *
|
---|
[5999] | 24 | * The contents of this file may alternatively be used under the terms
|
---|
| 25 | * of the Common Development and Distribution License Version 1.0
|
---|
[96407] | 26 | * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
|
---|
| 27 | * in the VirtualBox distribution, in which case the provisions of the
|
---|
[5999] | 28 | * CDDL are applicable instead of those of the GPL.
|
---|
| 29 | *
|
---|
| 30 | * You may elect to license modified versions of this file under the
|
---|
| 31 | * terms and conditions of either the GPL or the CDDL or both.
|
---|
[96407] | 32 | *
|
---|
| 33 | * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
|
---|
[1] | 34 | */
|
---|
| 35 |
|
---|
[76557] | 36 | #ifndef IPRT_INCLUDED_path_h
|
---|
| 37 | #define IPRT_INCLUDED_path_h
|
---|
[76507] | 38 | #ifndef RT_WITHOUT_PRAGMA_ONCE
|
---|
| 39 | # pragma once
|
---|
| 40 | #endif
|
---|
[1] | 41 |
|
---|
| 42 | #include <iprt/cdefs.h>
|
---|
| 43 | #include <iprt/types.h>
|
---|
| 44 | #ifdef IN_RING3
|
---|
| 45 | # include <iprt/fs.h>
|
---|
| 46 | #endif
|
---|
| 47 |
|
---|
| 48 |
|
---|
| 49 |
|
---|
[20374] | 50 | RT_C_DECLS_BEGIN
|
---|
[1] | 51 |
|
---|
| 52 | /** @defgroup grp_rt_path RTPath - Path Manipulation
|
---|
| 53 | * @ingroup grp_rt
|
---|
| 54 | * @{
|
---|
| 55 | */
|
---|
| 56 |
|
---|
[35218] | 57 | /**
|
---|
| 58 | * Host max path (the reasonable value).
|
---|
| 59 | * @remarks defined both by iprt/param.h and iprt/path.h.
|
---|
| 60 | */
|
---|
[76557] | 61 | #if !defined(IPRT_INCLUDED_param_h) || defined(DOXYGEN_RUNNING)
|
---|
[78048] | 62 | # define RTPATH_MAX (4096 + 4) /* (PATH_MAX + 1) on linux w/ some alignment */
|
---|
[35218] | 63 | #endif
|
---|
[1] | 64 |
|
---|
[78048] | 65 | /**
|
---|
| 66 | * The absolute max host path length we are willing to support.
|
---|
| 67 | * @note Not really suitable for stack buffers.
|
---|
| 68 | */
|
---|
| 69 | #define RTPATH_BIG_MAX (_64K)
|
---|
| 70 |
|
---|
[45394] | 71 | /** @def RTPATH_TAG
|
---|
| 72 | * The default allocation tag used by the RTPath allocation APIs.
|
---|
| 73 | *
|
---|
| 74 | * When not defined before the inclusion of iprt/string.h, this will default to
|
---|
| 75 | * the pointer to the current file name. The string API will make of use of
|
---|
| 76 | * this as pointer to a volatile but read-only string.
|
---|
| 77 | */
|
---|
| 78 | #ifndef RTPATH_TAG
|
---|
[78048] | 79 | # define RTPATH_TAG (__FILE__)
|
---|
[45394] | 80 | #endif
|
---|
[45391] | 81 |
|
---|
[45394] | 82 |
|
---|
[45391] | 83 | /** @name RTPATH_F_XXX - Generic flags for APIs working on the file system.
|
---|
| 84 | * @{ */
|
---|
| 85 | /** Last component: Work on the link. */
|
---|
[69818] | 86 | #define RTPATH_F_ON_LINK RT_BIT_32(0)
|
---|
[45391] | 87 | /** Last component: Follow if link. */
|
---|
[69818] | 88 | #define RTPATH_F_FOLLOW_LINK RT_BIT_32(1)
|
---|
[45391] | 89 | /** Don't allow symbolic links as part of the path.
|
---|
| 90 | * @remarks this flag is currently not implemented and will be ignored. */
|
---|
[69818] | 91 | #define RTPATH_F_NO_SYMLINKS RT_BIT_32(2)
|
---|
| 92 | /** Current RTPATH_F_XXX flag mask. */
|
---|
| 93 | #define RTPATH_F_MASK UINT32_C(0x00000007)
|
---|
[45391] | 94 | /** @} */
|
---|
| 95 |
|
---|
| 96 | /** Validates a flags parameter containing RTPATH_F_*.
|
---|
| 97 | * @remarks The parameters will be referenced multiple times. */
|
---|
| 98 | #define RTPATH_F_IS_VALID(a_fFlags, a_fIgnore) \
|
---|
| 99 | ( ((a_fFlags) & ~(uint32_t)((a_fIgnore) | RTPATH_F_NO_SYMLINKS)) == RTPATH_F_ON_LINK \
|
---|
| 100 | || ((a_fFlags) & ~(uint32_t)((a_fIgnore) | RTPATH_F_NO_SYMLINKS)) == RTPATH_F_FOLLOW_LINK )
|
---|
| 101 |
|
---|
| 102 |
|
---|
| 103 | /** @name RTPATH_STR_F_XXX - Generic flags for APIs working with path strings.
|
---|
| 104 | * @{
|
---|
| 105 | */
|
---|
| 106 | /** Host OS path style (default 0 value). */
|
---|
| 107 | #define RTPATH_STR_F_STYLE_HOST UINT32_C(0x00000000)
|
---|
| 108 | /** DOS, OS/2 and Windows path style. */
|
---|
| 109 | #define RTPATH_STR_F_STYLE_DOS UINT32_C(0x00000001)
|
---|
| 110 | /** Unix path style. */
|
---|
| 111 | #define RTPATH_STR_F_STYLE_UNIX UINT32_C(0x00000002)
|
---|
| 112 | /** Reserved path style. */
|
---|
| 113 | #define RTPATH_STR_F_STYLE_RESERVED UINT32_C(0x00000003)
|
---|
| 114 | /** The path style mask. */
|
---|
| 115 | #define RTPATH_STR_F_STYLE_MASK UINT32_C(0x00000003)
|
---|
| 116 | /** Partial path - no start.
|
---|
| 117 | * This causes the API to skip the root specification parsing. */
|
---|
| 118 | #define RTPATH_STR_F_NO_START UINT32_C(0x00000010)
|
---|
| 119 | /** Partial path - no end.
|
---|
| 120 | * This causes the API to skip the filename and dir-slash parsing. */
|
---|
| 121 | #define RTPATH_STR_F_NO_END UINT32_C(0x00000020)
|
---|
| 122 | /** Partial path - no start and no end. */
|
---|
| 123 | #define RTPATH_STR_F_MIDDLE (RTPATH_STR_F_NO_START | RTPATH_STR_F_NO_END)
|
---|
| 124 |
|
---|
| 125 | /** Reserved for future use. */
|
---|
| 126 | #define RTPATH_STR_F_RESERVED_MASK UINT32_C(0x0000ffcc)
|
---|
| 127 | /** @} */
|
---|
| 128 |
|
---|
| 129 | /** Validates a flags parameter containing RTPATH_FSTR_.
|
---|
| 130 | * @remarks The parameters will be references multiple times. */
|
---|
| 131 | #define RTPATH_STR_F_IS_VALID(a_fFlags, a_fIgnore) \
|
---|
| 132 | ( ((a_fFlags) & ~((uint32_t)(a_fIgnore) | RTPATH_STR_F_STYLE_MASK | RTPATH_STR_F_MIDDLE)) == 0 \
|
---|
| 133 | && ((a_fFlags) & RTPATH_STR_F_STYLE_MASK) != RTPATH_STR_F_STYLE_RESERVED \
|
---|
| 134 | && ((a_fFlags) & RTPATH_STR_F_RESERVED_MASK) == 0 )
|
---|
| 135 |
|
---|
| 136 |
|
---|
| 137 | /** @def RTPATH_STYLE
|
---|
| 138 | * The host path style. This is set to RTPATH_STR_F_STYLE_DOS,
|
---|
| 139 | * RTPATH_STR_F_STYLE_UNIX, or other future styles. */
|
---|
| 140 | #if defined(RT_OS_OS2) || defined(RT_OS_WINDOWS)
|
---|
| 141 | # define RTPATH_STYLE RTPATH_STR_F_STYLE_DOS
|
---|
| 142 | #else
|
---|
| 143 | # define RTPATH_STYLE RTPATH_STR_F_STYLE_UNIX
|
---|
| 144 | #endif
|
---|
| 145 |
|
---|
| 146 |
|
---|
[1] | 147 | /** @def RTPATH_SLASH
|
---|
[16252] | 148 | * The preferred slash character.
|
---|
[1] | 149 | *
|
---|
| 150 | * @remark IPRT will always accept unix slashes. So, normally you would
|
---|
| 151 | * never have to use this define.
|
---|
| 152 | */
|
---|
[45391] | 153 | #if RTPATH_STYLE == RTPATH_STR_F_STYLE_DOS
|
---|
[1] | 154 | # define RTPATH_SLASH '\\'
|
---|
[45391] | 155 | #elif RTPATH_STYLE == RTPATH_STR_F_STYLE_UNIX
|
---|
| 156 | # define RTPATH_SLASH '/'
|
---|
[1] | 157 | #else
|
---|
[45391] | 158 | # error "Unsupported RTPATH_STYLE value."
|
---|
[1] | 159 | #endif
|
---|
| 160 |
|
---|
| 161 | /** @deprecated Use '/'! */
|
---|
| 162 | #define RTPATH_DELIMITER RTPATH_SLASH
|
---|
| 163 |
|
---|
| 164 |
|
---|
| 165 | /** @def RTPATH_SLASH_STR
|
---|
[16252] | 166 | * The preferred slash character as a string, handy for concatenations
|
---|
[1] | 167 | * with other strings.
|
---|
| 168 | *
|
---|
| 169 | * @remark IPRT will always accept unix slashes. So, normally you would
|
---|
| 170 | * never have to use this define.
|
---|
| 171 | */
|
---|
[45391] | 172 | #if RTPATH_STYLE == RTPATH_STR_F_STYLE_DOS
|
---|
[1] | 173 | # define RTPATH_SLASH_STR "\\"
|
---|
[45391] | 174 | #elif RTPATH_STYLE == RTPATH_STR_F_STYLE_UNIX
|
---|
| 175 | # define RTPATH_SLASH_STR "/"
|
---|
[1] | 176 | #else
|
---|
[45391] | 177 | # error "Unsupported RTPATH_STYLE value."
|
---|
[1] | 178 | #endif
|
---|
| 179 |
|
---|
| 180 |
|
---|
| 181 | /** @def RTPATH_IS_SLASH
|
---|
| 182 | * Checks if a character is a slash.
|
---|
| 183 | *
|
---|
| 184 | * @returns true if it's a slash and false if not.
|
---|
[45391] | 185 | * @returns @param a_ch Char to check.
|
---|
[1] | 186 | */
|
---|
[45391] | 187 | #if RTPATH_STYLE == RTPATH_STR_F_STYLE_DOS
|
---|
| 188 | # define RTPATH_IS_SLASH(a_ch) ( (a_ch) == '\\' || (a_ch) == '/' )
|
---|
| 189 | #elif RTPATH_STYLE == RTPATH_STR_F_STYLE_UNIX
|
---|
| 190 | # define RTPATH_IS_SLASH(a_ch) ( (a_ch) == '/' )
|
---|
[1] | 191 | #else
|
---|
[45391] | 192 | # error "Unsupported RTPATH_STYLE value."
|
---|
[1] | 193 | #endif
|
---|
| 194 |
|
---|
| 195 |
|
---|
| 196 | /** @def RTPATH_IS_VOLSEP
|
---|
| 197 | * Checks if a character marks the end of the volume specification.
|
---|
| 198 | *
|
---|
[16252] | 199 | * @remark This is sufficient for the drive letter concept on PC.
|
---|
[1] | 200 | * However it might be insufficient on other platforms
|
---|
| 201 | * and even on PC a UNC volume spec won't be detected this way.
|
---|
[7170] | 202 | * Use the RTPath@<too be created@>() instead.
|
---|
[1] | 203 | *
|
---|
| 204 | * @returns true if it is and false if it isn't.
|
---|
[45391] | 205 | * @returns @param a_ch Char to check.
|
---|
[1] | 206 | */
|
---|
[45391] | 207 | #if RTPATH_STYLE == RTPATH_STR_F_STYLE_DOS
|
---|
| 208 | # define RTPATH_IS_VOLSEP(a_ch) ( (a_ch) == ':' )
|
---|
| 209 | #elif RTPATH_STYLE == RTPATH_STR_F_STYLE_UNIX
|
---|
| 210 | # define RTPATH_IS_VOLSEP(a_ch) (false)
|
---|
[1] | 211 | #else
|
---|
[45391] | 212 | # error "Unsupported RTPATH_STYLE value."
|
---|
[1] | 213 | #endif
|
---|
| 214 |
|
---|
| 215 |
|
---|
| 216 | /** @def RTPATH_IS_SEP
|
---|
| 217 | * Checks if a character is path component separator
|
---|
| 218 | *
|
---|
| 219 | * @returns true if it is and false if it isn't.
|
---|
[45391] | 220 | * @returns @param a_ch Char to check.
|
---|
[1] | 221 | * @
|
---|
| 222 | */
|
---|
[45391] | 223 | #define RTPATH_IS_SEP(a_ch) ( RTPATH_IS_SLASH(a_ch) || RTPATH_IS_VOLSEP(a_ch) )
|
---|
[1] | 224 |
|
---|
[70428] | 225 | #if defined(RT_OS_WINDOWS) || defined(DOXYGEN_RUNNING)
|
---|
| 226 | /** @def RTPATH_NT_PASSTHRU_PREFIX
|
---|
| 227 | * Prefix used to access the NT namespace directly.
|
---|
| 228 | * This forms an invalid UNC name. */
|
---|
| 229 | # define RTPATH_NT_PASSTHRU_PREFIX "\\\\:iprtnt:\\"
|
---|
| 230 | #endif
|
---|
[1] | 231 |
|
---|
| 232 | /**
|
---|
[937] | 233 | * Checks if the path exists.
|
---|
[7170] | 234 | *
|
---|
[23291] | 235 | * Symbolic links will all be attempted resolved and broken links means false.
|
---|
[7170] | 236 | *
|
---|
[937] | 237 | * @returns true if it exists and false if it doesn't.
|
---|
| 238 | * @param pszPath The path to check.
|
---|
| 239 | */
|
---|
| 240 | RTDECL(bool) RTPathExists(const char *pszPath);
|
---|
| 241 |
|
---|
| 242 | /**
|
---|
[23291] | 243 | * Checks if the path exists.
|
---|
| 244 | *
|
---|
| 245 | * @returns true if it exists and false if it doesn't.
|
---|
| 246 | * @param pszPath The path to check.
|
---|
[23294] | 247 | * @param fFlags RTPATH_F_ON_LINK or RTPATH_F_FOLLOW_LINK.
|
---|
[23291] | 248 | */
|
---|
| 249 | RTDECL(bool) RTPathExistsEx(const char *pszPath, uint32_t fFlags);
|
---|
| 250 |
|
---|
| 251 | /**
|
---|
[10911] | 252 | * Sets the current working directory of the process.
|
---|
| 253 | *
|
---|
| 254 | * @returns IPRT status code.
|
---|
| 255 | * @param pszPath The path to the new working directory.
|
---|
| 256 | */
|
---|
| 257 | RTDECL(int) RTPathSetCurrent(const char *pszPath);
|
---|
| 258 |
|
---|
| 259 | /**
|
---|
| 260 | * Gets the current working directory of the process.
|
---|
| 261 | *
|
---|
| 262 | * @returns IPRT status code.
|
---|
| 263 | * @param pszPath Where to store the path.
|
---|
| 264 | * @param cchPath The size of the buffer pszPath points to.
|
---|
| 265 | */
|
---|
| 266 | RTDECL(int) RTPathGetCurrent(char *pszPath, size_t cchPath);
|
---|
| 267 |
|
---|
| 268 | /**
|
---|
[52944] | 269 | * Gets the current working directory on the specified drive.
|
---|
| 270 | *
|
---|
| 271 | * On systems without drive letters, the root slash will be returned.
|
---|
| 272 | *
|
---|
| 273 | * @returns IPRT status code.
|
---|
| 274 | * @param chDrive The drive we're querying the driver letter on.
|
---|
| 275 | * @param pszPath Where to store the working directroy path.
|
---|
| 276 | * @param cbPath The size of the buffer pszPath points to.
|
---|
| 277 | */
|
---|
| 278 | RTDECL(int) RTPathGetCurrentOnDrive(char chDrive, char *pszPath, size_t cbPath);
|
---|
| 279 |
|
---|
| 280 | /**
|
---|
| 281 | * Gets the current working drive of the process.
|
---|
| 282 | *
|
---|
| 283 | * Normally drive letter and colon will be returned, never trailing a root
|
---|
| 284 | * slash. If the current directory is on a UNC share, the root of the share
|
---|
| 285 | * will be returned. On systems without drive letters, an empty string is
|
---|
| 286 | * returned for consistency.
|
---|
| 287 | *
|
---|
| 288 | * @returns IPRT status code.
|
---|
| 289 | * @param pszPath Where to store the working drive or UNC root.
|
---|
| 290 | * @param cbPath The size of the buffer pszPath points to.
|
---|
| 291 | */
|
---|
| 292 | RTDECL(int) RTPathGetCurrentDrive(char *pszPath, size_t cbPath);
|
---|
| 293 |
|
---|
| 294 | /**
|
---|
[1] | 295 | * Get the real path (no symlinks, no . or .. components), must exist.
|
---|
| 296 | *
|
---|
| 297 | * @returns iprt status code.
|
---|
| 298 | * @param pszPath The path to resolve.
|
---|
| 299 | * @param pszRealPath Where to store the real path.
|
---|
| 300 | * @param cchRealPath Size of the buffer.
|
---|
| 301 | */
|
---|
[14054] | 302 | RTDECL(int) RTPathReal(const char *pszPath, char *pszRealPath, size_t cchRealPath);
|
---|
[1] | 303 |
|
---|
| 304 | /**
|
---|
| 305 | * Same as RTPathReal only the result is RTStrDup()'ed.
|
---|
| 306 | *
|
---|
| 307 | * @returns Pointer to real path. Use RTStrFree() to free this string.
|
---|
| 308 | * @returns NULL if RTPathReal() or RTStrDup() fails.
|
---|
| 309 | * @param pszPath The path to resolve.
|
---|
| 310 | */
|
---|
| 311 | RTDECL(char *) RTPathRealDup(const char *pszPath);
|
---|
| 312 |
|
---|
| 313 | /**
|
---|
[15754] | 314 | * Get the absolute path (starts from root, no . or .. components), doesn't have
|
---|
[70891] | 315 | * to exist.
|
---|
[1] | 316 | *
|
---|
[70891] | 317 | * Note that this method is designed to never perform actual file system access,
|
---|
| 318 | * therefore symlinks are not resolved.
|
---|
| 319 | *
|
---|
[1] | 320 | * @returns iprt status code.
|
---|
| 321 | * @param pszPath The path to resolve.
|
---|
| 322 | * @param pszAbsPath Where to store the absolute path.
|
---|
[78048] | 323 | * @param cbAbsPath Size of the buffer.
|
---|
[70891] | 324 | *
|
---|
| 325 | * @note Current implementation is buggy and will remove trailing slashes
|
---|
| 326 | * that would normally specify a directory. Don't depend on this.
|
---|
[1] | 327 | */
|
---|
[78048] | 328 | RTDECL(int) RTPathAbs(const char *pszPath, char *pszAbsPath, size_t cbAbsPath);
|
---|
[1] | 329 |
|
---|
| 330 | /**
|
---|
| 331 | * Same as RTPathAbs only the result is RTStrDup()'ed.
|
---|
| 332 | *
|
---|
| 333 | * @returns Pointer to the absolute path. Use RTStrFree() to free this string.
|
---|
| 334 | * @returns NULL if RTPathAbs() or RTStrDup() fails.
|
---|
| 335 | * @param pszPath The path to resolve.
|
---|
[70891] | 336 | *
|
---|
| 337 | * @note Current implementation is buggy and will remove trailing slashes
|
---|
| 338 | * that would normally specify a directory. Don't depend on this.
|
---|
[1] | 339 | */
|
---|
| 340 | RTDECL(char *) RTPathAbsDup(const char *pszPath);
|
---|
| 341 |
|
---|
| 342 | /**
|
---|
| 343 | * Get the absolute path (no symlinks, no . or .. components), assuming the
|
---|
[78048] | 344 | * given base path as the current directory.
|
---|
| 345 | *
|
---|
| 346 | * The resulting path doesn't have to exist.
|
---|
| 347 | *
|
---|
| 348 | * @returns iprt status code.
|
---|
| 349 | * @param pszBase The base path to act like a current directory.
|
---|
| 350 | * When NULL, the actual cwd is used (i.e. the call
|
---|
| 351 | * is equivalent to RTPathAbs(pszPath, ...).
|
---|
| 352 | * @param pszPath The path to resolve.
|
---|
| 353 | * @param fFlags One of the RTPATH_STR_F_STYLE_XXX flags combined
|
---|
| 354 | * with any of the RTPATHABS_F_XXX ones. Most
|
---|
| 355 | * users will pass RTPATH_STR_F_STYLE_HOST (0).
|
---|
| 356 | * @param pszAbsPath Where to store the absolute path.
|
---|
| 357 | * @param pcbAbsPath Hold the size of the buffer when called. The return
|
---|
| 358 | * value is the string length on success, and the
|
---|
| 359 | * required (or slightly more in some case) buffer
|
---|
| 360 | * size, including terminator, on VERR_BUFFER_OVERFLOW
|
---|
| 361 | * failures.
|
---|
| 362 | */
|
---|
[78098] | 363 | RTDECL(int) RTPathAbsEx(const char *pszBase, const char *pszPath, uint32_t fFlags, char *pszAbsPath, size_t *pcbAbsPath);
|
---|
[78048] | 364 |
|
---|
| 365 | /** @name RTPATHABS_F_XXX - Flags for RTPathAbsEx.
|
---|
| 366 | * @note The RTPATH_F_STR_XXX style flags also applies.
|
---|
| 367 | * @{ */
|
---|
| 368 | /** Treat specified base directory as a root that cannot be ascended beyond. */
|
---|
[78153] | 369 | #define RTPATHABS_F_STOP_AT_BASE RT_BIT_32(16)
|
---|
[78048] | 370 | /** Treat CWD as a root that cannot be ascended beyond. */
|
---|
[78153] | 371 | #define RTPATHABS_F_STOP_AT_CWD RT_BIT_32(17)
|
---|
| 372 | /** Ensure trailing slash in the result. */
|
---|
| 373 | #define RTPATHABS_F_ENSURE_TRAILING_SLASH RT_BIT_32(18)
|
---|
[78048] | 374 | /** @} */
|
---|
| 375 |
|
---|
| 376 | /**
|
---|
[1] | 377 | * Same as RTPathAbsEx only the result is RTStrDup()'ed.
|
---|
| 378 | *
|
---|
[78104] | 379 | * @returns Pointer to the absolute path. Use RTStrFree() to free this string.
|
---|
| 380 | * @retval NULL if RTPathAbsEx() or RTStrDup() fails.
|
---|
| 381 | *
|
---|
[1] | 382 | * @param pszBase The base path to act like a current directory.
|
---|
| 383 | * When NULL, the actual cwd is used (i.e. the call
|
---|
| 384 | * is equivalent to RTPathAbs(pszPath, ...).
|
---|
| 385 | * @param pszPath The path to resolve.
|
---|
[78104] | 386 | * @param fFlags One of the RTPATH_STR_F_STYLE_XXX flags combined
|
---|
| 387 | * with any of the RTPATHABS_F_XXX ones. Most
|
---|
| 388 | * users will pass RTPATH_STR_F_STYLE_HOST (0).
|
---|
[1] | 389 | */
|
---|
[78104] | 390 | RTDECL(char *) RTPathAbsExDup(const char *pszBase, const char *pszPath, uint32_t fFlags);
|
---|
[1] | 391 |
|
---|
| 392 | /**
|
---|
[16516] | 393 | * Strips the filename from a path. Truncates the given string in-place by overwriting the
|
---|
| 394 | * last path separator character with a null byte in a platform-neutral way.
|
---|
[1] | 395 | *
|
---|
[16516] | 396 | * @param pszPath Path from which filename should be extracted, will be truncated.
|
---|
| 397 | * If the string contains no path separator, it will be changed to a "." string.
|
---|
[1] | 398 | */
|
---|
| 399 | RTDECL(void) RTPathStripFilename(char *pszPath);
|
---|
| 400 |
|
---|
| 401 | /**
|
---|
[49039] | 402 | * Strips the last suffix from a path.
|
---|
[1] | 403 | *
|
---|
[49039] | 404 | * @param pszPath Path which suffix should be stripped.
|
---|
[1] | 405 | */
|
---|
[49039] | 406 | RTDECL(void) RTPathStripSuffix(char *pszPath);
|
---|
[1] | 407 |
|
---|
| 408 | /**
|
---|
| 409 | * Strips the trailing slashes of a path name.
|
---|
| 410 | *
|
---|
[25923] | 411 | * Won't strip root slashes.
|
---|
| 412 | *
|
---|
| 413 | * @returns The new length of pszPath.
|
---|
[1] | 414 | * @param pszPath Path to strip.
|
---|
| 415 | */
|
---|
[25923] | 416 | RTDECL(size_t) RTPathStripTrailingSlash(char *pszPath);
|
---|
[1] | 417 |
|
---|
| 418 | /**
|
---|
[67132] | 419 | * Skips the root specification, if present.
|
---|
| 420 | *
|
---|
| 421 | * @return Pointer to the first char after the root specification. This can be
|
---|
| 422 | * pointing to the terminator, if the path is only a root
|
---|
| 423 | * specification.
|
---|
| 424 | * @param pszPath The path to skip ahead in.
|
---|
| 425 | */
|
---|
| 426 | RTDECL(char *) RTPathSkipRootSpec(const char *pszPath);
|
---|
| 427 |
|
---|
| 428 | /**
|
---|
[57572] | 429 | * Ensures that the path has a trailing path separator such that file names can
|
---|
| 430 | * be appended without further work.
|
---|
| 431 | *
|
---|
| 432 | * This can be helpful when preparing for efficiently combining a directory path
|
---|
| 433 | * with the filenames returned by RTDirRead. The return value gives you the
|
---|
| 434 | * position at which you copy the RTDIRENTRY::szName to construct a valid path
|
---|
| 435 | * to it.
|
---|
| 436 | *
|
---|
| 437 | * @returns The length of the path, 0 on buffer overflow.
|
---|
| 438 | * @param pszPath The path.
|
---|
| 439 | * @param cbPath The length of the path buffer @a pszPath points to.
|
---|
| 440 | */
|
---|
| 441 | RTDECL(size_t) RTPathEnsureTrailingSeparator(char *pszPath, size_t cbPath);
|
---|
| 442 |
|
---|
| 443 | /**
|
---|
[80832] | 444 | * Same as RTPathEnsureTrailingSeparator but with selectable path style.
|
---|
| 445 | *
|
---|
| 446 | * @returns The length of the path, 0 on buffer overflow.
|
---|
| 447 | * @param pszPath The path.
|
---|
| 448 | * @param cbPath The length of the path buffer @a pszPath points to.
|
---|
| 449 | * @param fFlags The path style, RTPATH_STR_F_STYLE_XXX.
|
---|
| 450 | * @sa RTPathEnsureTrailingSeparator
|
---|
| 451 | */
|
---|
| 452 | RTDECL(size_t) RTPathEnsureTrailingSeparatorEx(char *pszPath, size_t cbPath, uint32_t fFlags);
|
---|
| 453 |
|
---|
| 454 | /**
|
---|
[33540] | 455 | * Changes all the slashes in the specified path to DOS style.
|
---|
[26520] | 456 | *
|
---|
| 457 | * Unless @a fForce is set, nothing will be done when on a UNIX flavored system
|
---|
| 458 | * since paths wont work with DOS style slashes there.
|
---|
| 459 | *
|
---|
| 460 | * @returns @a pszPath.
|
---|
| 461 | * @param pszPath The path to modify.
|
---|
| 462 | * @param fForce Whether to force the conversion on non-DOS OSes.
|
---|
| 463 | */
|
---|
| 464 | RTDECL(char *) RTPathChangeToDosSlashes(char *pszPath, bool fForce);
|
---|
| 465 |
|
---|
| 466 | /**
|
---|
[33540] | 467 | * Changes all the slashes in the specified path to unix style.
|
---|
[26520] | 468 | *
|
---|
| 469 | * Unless @a fForce is set, nothing will be done when on a UNIX flavored system
|
---|
| 470 | * since paths wont work with DOS style slashes there.
|
---|
| 471 | *
|
---|
| 472 | * @returns @a pszPath.
|
---|
| 473 | * @param pszPath The path to modify.
|
---|
| 474 | * @param fForce Whether to force the conversion on non-DOS OSes.
|
---|
| 475 | */
|
---|
| 476 | RTDECL(char *) RTPathChangeToUnixSlashes(char *pszPath, bool fForce);
|
---|
| 477 |
|
---|
| 478 | /**
|
---|
[79570] | 479 | * Purges a string so it can be used as a file according to fFlags.
|
---|
| 480 | *
|
---|
| 481 | * Illegal filename characters are replaced by '_'.
|
---|
| 482 | *
|
---|
| 483 | * @returns pszString
|
---|
| 484 | * @param pszString The string to purge.
|
---|
| 485 | * @param fFlags One of the RTPATH_STR_F_STYLE_XXX flags. Most users
|
---|
| 486 | * will pass RTPATH_STR_F_STYLE_HOST (0).
|
---|
| 487 | */
|
---|
| 488 | RTDECL(char *) RTPathPurgeFilename(char *pszString, uint32_t fFlags);
|
---|
| 489 |
|
---|
| 490 | /**
|
---|
[45375] | 491 | * Simple parsing of the a path.
|
---|
[14050] | 492 | *
|
---|
| 493 | * It figures the length of the directory component, the offset of
|
---|
[11836] | 494 | * the file name and the location of the suffix dot.
|
---|
| 495 | *
|
---|
| 496 | * @returns The path length.
|
---|
[14050] | 497 | *
|
---|
[11836] | 498 | * @param pszPath Path to find filename in.
|
---|
[25645] | 499 | * @param pcchDir Where to put the length of the directory component. If
|
---|
| 500 | * no directory, this will be 0. Optional.
|
---|
[11836] | 501 | * @param poffName Where to store the filename offset.
|
---|
| 502 | * If empty string or if it's ending with a slash this
|
---|
| 503 | * will be set to -1. Optional.
|
---|
| 504 | * @param poffSuff Where to store the suffix offset (the last dot).
|
---|
| 505 | * If empty string or if it's ending with a slash this
|
---|
| 506 | * will be set to -1. Optional.
|
---|
| 507 | */
|
---|
[45375] | 508 | RTDECL(size_t) RTPathParseSimple(const char *pszPath, size_t *pcchDir, ssize_t *poffName, ssize_t *poffSuff);
|
---|
[11836] | 509 |
|
---|
| 510 | /**
|
---|
[1] | 511 | * Finds the filename in a path.
|
---|
| 512 | *
|
---|
| 513 | * @returns Pointer to filename within pszPath.
|
---|
| 514 | * @returns NULL if no filename (i.e. empty string or ends with a slash).
|
---|
| 515 | * @param pszPath Path to find filename in.
|
---|
| 516 | */
|
---|
| 517 | RTDECL(char *) RTPathFilename(const char *pszPath);
|
---|
[76094] | 518 | RTDECL(PRTUTF16) RTPathFilenameUtf16(PCRTUTF16 pwszPath);
|
---|
[1] | 519 |
|
---|
| 520 | /**
|
---|
[46104] | 521 | * Finds the filename in a path, extended version.
|
---|
| 522 | *
|
---|
| 523 | * @returns Pointer to filename within pszPath.
|
---|
| 524 | * @returns NULL if no filename (i.e. empty string or ends with a slash).
|
---|
| 525 | * @param pszPath Path to find filename in.
|
---|
| 526 | * @param fFlags RTPATH_STR_F_STYLE_XXX. Other RTPATH_STR_F_XXX flags
|
---|
| 527 | * will be ignored.
|
---|
| 528 | */
|
---|
| 529 | RTDECL(char *) RTPathFilenameEx(const char *pszPath, uint32_t fFlags);
|
---|
[76094] | 530 | RTDECL(PRTUTF16) RTPathFilenameExUtf16(PCRTUTF16 pwszPath, uint32_t fFlags);
|
---|
[46104] | 531 |
|
---|
| 532 | /**
|
---|
[85382] | 533 | * Finds the common path in a given set of paths.
|
---|
[85311] | 534 | *
|
---|
[85382] | 535 | * The paths are not made absolute or real, they are taken as given.
|
---|
[85311] | 536 | *
|
---|
[85383] | 537 | * @returns The common path length as represented by \a papszPaths[0], 0 if not
|
---|
| 538 | * found or invalid input.
|
---|
[85382] | 539 | * @param cPaths Number of paths in \a papszPaths.
|
---|
[85383] | 540 | * @param papszPaths Array of paths to find common path for. The paths must
|
---|
| 541 | * not contains ".." sequences, as that's too complicated
|
---|
| 542 | * to handle.
|
---|
[85311] | 543 | */
|
---|
[85382] | 544 | RTDECL(size_t) RTPathFindCommon(size_t cPaths, const char * const *papszPaths);
|
---|
[85311] | 545 |
|
---|
| 546 | /**
|
---|
[85382] | 547 | * Finds the common path in a given set of paths, extended version.
|
---|
[85311] | 548 | *
|
---|
[85382] | 549 | * The paths are not made absolute or real, they are taken as given.
|
---|
[85311] | 550 | *
|
---|
[85383] | 551 | * @returns The common path length as represented by \a papszPaths[0], 0 if not
|
---|
| 552 | * found or invalid input.
|
---|
[85382] | 553 | * @param cPaths Number of paths in \a papszPaths.
|
---|
[85383] | 554 | * @param papszPaths Array of paths to find common path for. The paths must
|
---|
| 555 | * not contains ".." sequences, as that's too complicated
|
---|
| 556 | * to handle.
|
---|
[85384] | 557 | * @param fFlags RTPATH_STR_F_STYLE_XXX, RTPATH_STR_F_NO_START, and
|
---|
| 558 | * RTPATHFINDCOMMON_F_IGNORE_DOTDOT as desired. Other
|
---|
| 559 | * RTPATH_STR_F_XXX flags will be ignored.
|
---|
[85311] | 560 | */
|
---|
[85382] | 561 | RTDECL(size_t) RTPathFindCommonEx(size_t cPaths, const char * const *papszPaths, uint32_t fFlags);
|
---|
[85311] | 562 |
|
---|
[85384] | 563 | /** @name RTPATHFINDCOMMON_F_XXX - Flags for RTPathFindCommonEx.
|
---|
| 564 | * @{ */
|
---|
| 565 | /** Ignore the dangers of '..' components. */
|
---|
| 566 | #define RTPATHFINDCOMMON_F_IGNORE_DOTDOT RT_BIT_32(16)
|
---|
| 567 | /** @} */
|
---|
| 568 |
|
---|
[85311] | 569 | /**
|
---|
[49039] | 570 | * Finds the suffix part of in a path (last dot and onwards).
|
---|
[1] | 571 | *
|
---|
[49039] | 572 | * @returns Pointer to suffix within pszPath.
|
---|
| 573 | * @returns NULL if no suffix
|
---|
| 574 | * @param pszPath Path to find suffix in.
|
---|
| 575 | *
|
---|
| 576 | * @remarks IPRT terminology: A suffix includes the dot, the extension starts
|
---|
| 577 | * after the dot. For instance suffix '.txt' and extension 'txt'.
|
---|
[1] | 578 | */
|
---|
[49039] | 579 | RTDECL(char *) RTPathSuffix(const char *pszPath);
|
---|
[1] | 580 |
|
---|
| 581 | /**
|
---|
[49039] | 582 | * Checks if a path has an extension / suffix.
|
---|
[1] | 583 | *
|
---|
[49039] | 584 | * @returns true if extension / suffix present.
|
---|
| 585 | * @returns false if no extension / suffix.
|
---|
[1] | 586 | * @param pszPath Path to check.
|
---|
| 587 | */
|
---|
[49039] | 588 | RTDECL(bool) RTPathHasSuffix(const char *pszPath);
|
---|
| 589 | /** Same thing, different name. */
|
---|
| 590 | #define RTPathHasExt RTPathHasSuffix
|
---|
[1] | 591 |
|
---|
| 592 | /**
|
---|
| 593 | * Checks if a path includes more than a filename.
|
---|
| 594 | *
|
---|
| 595 | * @returns true if path present.
|
---|
| 596 | * @returns false if no path.
|
---|
| 597 | * @param pszPath Path to check.
|
---|
| 598 | */
|
---|
[40979] | 599 | RTDECL(bool) RTPathHasPath(const char *pszPath);
|
---|
| 600 | /** Misspelled, don't use. */
|
---|
| 601 | #define RTPathHavePath RTPathHasPath
|
---|
[1] | 602 |
|
---|
| 603 | /**
|
---|
[33245] | 604 | * Checks if the path starts with a root specifier or not.
|
---|
| 605 | *
|
---|
| 606 | * @returns @c true if it starts with root, @c false if not.
|
---|
| 607 | *
|
---|
| 608 | * @param pszPath Path to check.
|
---|
| 609 | */
|
---|
| 610 | RTDECL(bool) RTPathStartsWithRoot(const char *pszPath);
|
---|
| 611 |
|
---|
[78702] | 612 | /**
|
---|
| 613 | * Determins the length of the parent part of the given path.
|
---|
| 614 | *
|
---|
| 615 | * @returns The length of the parent section of the path, including the final
|
---|
| 616 | * path separator. Returns 0 if only filename or empty path.
|
---|
| 617 | * @param pszPath The path to evaluate.
|
---|
| 618 | *
|
---|
| 619 | * @note Will stop at the server for UNC paths, so given "//server/share/"
|
---|
| 620 | * the parent length will be 9.
|
---|
| 621 | */
|
---|
| 622 | RTDECL(size_t) RTPathParentLength(const char *pszPath);
|
---|
[67132] | 623 |
|
---|
[78702] | 624 | /**
|
---|
| 625 | * Determins the length of the parent part of the given path, extended variant.
|
---|
| 626 | *
|
---|
| 627 | * @returns The length of the parent section of the path, including the final
|
---|
| 628 | * path separator. Returns 0 if only filename or empty path.
|
---|
| 629 | * @param pszPath The path to evaluate.
|
---|
| 630 | * @param fFlags RTPATH_STR_F_STYLE_XXX and RTPATH_STR_F_NO_START.
|
---|
| 631 | * Asserts and ignores RTPATH_STR_F_NO_END.
|
---|
| 632 | *
|
---|
| 633 | * @note Will stop at the server for UNC paths, so given "//server/share/"
|
---|
| 634 | * the parent length will be 9.
|
---|
| 635 | */
|
---|
| 636 | RTDECL(size_t) RTPathParentLengthEx(const char *pszPath, uint32_t fFlags);
|
---|
[67132] | 637 |
|
---|
[33245] | 638 | /**
|
---|
[26476] | 639 | * Counts the components in the specified path.
|
---|
| 640 | *
|
---|
| 641 | * An empty string has zero components. A lone root slash is considered have
|
---|
| 642 | * one. The paths "/init" and "/bin/" are considered having two components. An
|
---|
| 643 | * UNC share specifier like "\\myserver\share" will be considered as one single
|
---|
| 644 | * component.
|
---|
| 645 | *
|
---|
| 646 | * @returns The number of path components.
|
---|
| 647 | * @param pszPath The path to parse.
|
---|
| 648 | */
|
---|
| 649 | RTDECL(size_t) RTPathCountComponents(const char *pszPath);
|
---|
| 650 |
|
---|
| 651 | /**
|
---|
| 652 | * Copies the specified number of path components from @a pszSrc and into @a
|
---|
| 653 | * pszDst.
|
---|
| 654 | *
|
---|
| 655 | * @returns VINF_SUCCESS or VERR_BUFFER_OVERFLOW. In the latter case the buffer
|
---|
| 656 | * is not touched.
|
---|
| 657 | *
|
---|
| 658 | * @param pszDst The destination buffer.
|
---|
| 659 | * @param cbDst The size of the destination buffer.
|
---|
| 660 | * @param pszSrc The source path.
|
---|
| 661 | * @param cComponents The number of components to copy from @a pszSrc.
|
---|
| 662 | */
|
---|
| 663 | RTDECL(int) RTPathCopyComponents(char *pszDst, size_t cbDst, const char *pszSrc, size_t cComponents);
|
---|
| 664 |
|
---|
[45389] | 665 | /** @name Path properties returned by RTPathParse and RTPathSplit.
|
---|
| 666 | * @{ */
|
---|
| 667 |
|
---|
| 668 | /** Indicates that there is a filename.
|
---|
| 669 | * If not set, either a lone root spec was given (RTPATH_PROP_UNC,
|
---|
| 670 | * RTPATH_PROP_ROOT_SLASH, or RTPATH_PROP_VOLUME) or the final component had a
|
---|
| 671 | * trailing slash (RTPATH_PROP_DIR_SLASH). */
|
---|
| 672 | #define RTPATH_PROP_FILENAME UINT16_C(0x0001)
|
---|
| 673 | /** Indicates that a directory was specified using a trailing slash.
|
---|
| 674 | * @note This is not set for lone root specifications (RTPATH_PROP_UNC,
|
---|
| 675 | * RTPATH_PROP_ROOT_SLASH, or RTPATH_PROP_VOLUME).
|
---|
[45394] | 676 | * @note The slash is not counted into the last component. However, it is
|
---|
| 677 | * counted into cchPath. */
|
---|
[45389] | 678 | #define RTPATH_PROP_DIR_SLASH UINT16_C(0x0002)
|
---|
| 679 |
|
---|
| 680 | /** The filename has a suffix (extension). */
|
---|
| 681 | #define RTPATH_PROP_SUFFIX UINT16_C(0x0004)
|
---|
| 682 | /** Indicates that this is an UNC path (Windows and OS/2 only).
|
---|
| 683 | *
|
---|
| 684 | * UNC = Universal Naming Convention. It is on the form '//Computer/',
|
---|
| 685 | * '//Namespace/', '//ComputerName/Resource' and '//Namespace/Resource'.
|
---|
| 686 | * RTPathParse, RTPathSplit and friends does not consider the 'Resource' as
|
---|
| 687 | * part of the UNC root specifier. Thus the root specs for the above examples
|
---|
| 688 | * would be '//ComputerName/' or '//Namespace/'.
|
---|
| 689 | *
|
---|
| 690 | * Please note that '//something' is not a UNC path, there must be a slash
|
---|
| 691 | * following the computer or namespace.
|
---|
| 692 | */
|
---|
| 693 | #define RTPATH_PROP_UNC UINT16_C(0x0010)
|
---|
| 694 | /** A root slash was specified (unix style root).
|
---|
| 695 | * (While the path must relative if not set, this being set doesn't make it
|
---|
| 696 | * absolute.)
|
---|
| 697 | *
|
---|
| 698 | * This will be set in the following examples: '/', '/bin', 'C:/', 'C:/Windows',
|
---|
| 699 | * '//./', '//./PhysicalDisk0', '//example.org/', and '//example.org/share'.
|
---|
| 700 | *
|
---|
| 701 | * It will not be set for the following examples: '.', 'bin/ls', 'C:', and
|
---|
| 702 | * 'C:Windows'.
|
---|
| 703 | */
|
---|
| 704 | #define RTPATH_PROP_ROOT_SLASH UINT16_C(0x0020)
|
---|
| 705 | /** A volume is specified (Windows, DOS and OS/2).
|
---|
| 706 | * For examples: 'C:', 'C:/', and 'A:/AutoExec.bat'. */
|
---|
| 707 | #define RTPATH_PROP_VOLUME UINT16_C(0x0040)
|
---|
| 708 | /** The path is absolute, i.e. has a root specifier (root-slash,
|
---|
| 709 | * volume or UNC) and contains no winding '..' bits, though it may contain
|
---|
| 710 | * unnecessary slashes (RTPATH_PROP_EXTRA_SLASHES) and '.' components
|
---|
| 711 | * (RTPATH_PROP_DOT_REFS).
|
---|
| 712 | *
|
---|
| 713 | * On systems without volumes and UNC (unix style) it will be set for '/',
|
---|
| 714 | * '/bin/ls', and '/bin//./ls', but not for 'bin/ls', /bin/../usr/bin/env',
|
---|
| 715 | * '/./bin/ls' or '/.'.
|
---|
| 716 | *
|
---|
| 717 | * On systems with volumes, it will be set for 'C:/', C:/Windows', and
|
---|
| 718 | * 'C:/./Windows//', but not for 'C:', 'C:Windows', or 'C:/Windows/../boot.ini'.
|
---|
| 719 | *
|
---|
| 720 | * On systems with UNC paths, it will be set for '//localhost/',
|
---|
| 721 | * '//localhost/C$', '//localhost/C$/Windows/System32', '//localhost/.', and
|
---|
| 722 | * '//localhost/C$//./AutoExec.bat', but not for
|
---|
| 723 | * '//localhost/C$/Windows/../AutoExec.bat'.
|
---|
| 724 | *
|
---|
| 725 | * @note For the RTPathAbs definition, this flag needs to be set while both
|
---|
| 726 | * RTPATH_PROP_EXTRA_SLASHES and RTPATH_PROP_DOT_REFS must be cleared.
|
---|
| 727 | */
|
---|
| 728 | #define RTPATH_PROP_ABSOLUTE UINT16_C(0x0100)
|
---|
| 729 | /** Relative path. Inverse of RTPATH_PROP_ABSOLUTE. */
|
---|
| 730 | #define RTPATH_PROP_RELATIVE UINT16_C(0x0200)
|
---|
| 731 | /** The path contains unnecessary slashes. Meaning, that if */
|
---|
| 732 | #define RTPATH_PROP_EXTRA_SLASHES UINT16_C(0x0400)
|
---|
| 733 | /** The path contains references to the special '.' (dot) directory link. */
|
---|
| 734 | #define RTPATH_PROP_DOT_REFS UINT16_C(0x0800)
|
---|
| 735 | /** The path contains references to the special '..' (dot) directory link.
|
---|
| 736 | * RTPATH_PROP_RELATIVE will always be set together with this. */
|
---|
| 737 | #define RTPATH_PROP_DOTDOT_REFS UINT16_C(0x1000)
|
---|
[78048] | 738 | /** Special UNC root.
|
---|
| 739 | * The share name is not sacred when this is set. */
|
---|
| 740 | #define RTPATH_PROP_SPECIAL_UNC UINT16_C(0x2000)
|
---|
[45389] | 741 |
|
---|
| 742 |
|
---|
| 743 | /** Macro to determin whether to insert a slash after the first component when
|
---|
| 744 | * joining it with something else.
|
---|
| 745 | * (All other components in a split or parsed path requies slashes added.) */
|
---|
| 746 | #define RTPATH_PROP_FIRST_NEEDS_NO_SLASH(a_fProps) \
|
---|
[45394] | 747 | RT_BOOL( (a_fProps) & (RTPATH_PROP_ROOT_SLASH | RTPATH_PROP_VOLUME | RTPATH_PROP_UNC) )
|
---|
[45389] | 748 |
|
---|
| 749 | /** Macro to determin whether there is a root specification of any kind
|
---|
| 750 | * (unix, volumes, unc). */
|
---|
| 751 | #define RTPATH_PROP_HAS_ROOT_SPEC(a_fProps) \
|
---|
[45394] | 752 | RT_BOOL( (a_fProps) & (RTPATH_PROP_ROOT_SLASH | RTPATH_PROP_VOLUME | RTPATH_PROP_UNC) )
|
---|
[45389] | 753 |
|
---|
| 754 | /** @} */
|
---|
| 755 |
|
---|
| 756 |
|
---|
[26476] | 757 | /**
|
---|
[45389] | 758 | * Parsed path.
|
---|
| 759 | *
|
---|
| 760 | * The first component is the root, volume or UNC specifier, if present. Use
|
---|
| 761 | * RTPATH_PROP_HAS_ROOT_SPEC() on RTPATHPARSED::fProps to determine its
|
---|
[57613] | 762 | * presence.
|
---|
[45389] | 763 | *
|
---|
| 764 | * Other than the root component, no component will include directory separators
|
---|
| 765 | * (slashes).
|
---|
| 766 | */
|
---|
| 767 | typedef struct RTPATHPARSED
|
---|
| 768 | {
|
---|
| 769 | /** Number of path components.
|
---|
| 770 | * This will always be set on VERR_BUFFER_OVERFLOW returns from RTPathParsed
|
---|
| 771 | * so the caller can calculate the required buffer size. */
|
---|
| 772 | uint16_t cComps;
|
---|
| 773 | /** Path property flags, RTPATH_PROP_XXX */
|
---|
| 774 | uint16_t fProps;
|
---|
| 775 | /** On success this is the length of the described path, i.e. sum of all
|
---|
| 776 | * component lengths and necessary separators.
|
---|
| 777 | * Do NOT use this to index in the source path in case it contains
|
---|
| 778 | * unnecessary slashes that RTPathParsed has ignored here. */
|
---|
| 779 | uint16_t cchPath;
|
---|
| 780 | /** Reserved for future use. */
|
---|
| 781 | uint16_t u16Reserved;
|
---|
| 782 | /** The offset of the filename suffix, offset of the NUL char if none. */
|
---|
| 783 | uint16_t offSuffix;
|
---|
[81204] | 784 | /** The length of the suffix. */
|
---|
[45389] | 785 | uint16_t cchSuffix;
|
---|
| 786 | /** Array of component descriptors (variable size).
|
---|
| 787 | * @note Don't try figure the end of the input path by adding up off and cch
|
---|
| 788 | * of the last component. If RTPATH_PROP_DIR_SLASH is set, there may
|
---|
| 789 | * be one or more trailing slashes that are unaccounted for! */
|
---|
[84509] | 790 | RT_FLEXIBLE_ARRAY_EXTENSION
|
---|
[45389] | 791 | struct
|
---|
| 792 | {
|
---|
| 793 | /** The offset of the component. */
|
---|
| 794 | uint16_t off;
|
---|
| 795 | /** The length of the component. */
|
---|
| 796 | uint16_t cch;
|
---|
[78051] | 797 | } aComps[RT_FLEXIBLE_ARRAY];
|
---|
[45389] | 798 | } RTPATHPARSED;
|
---|
| 799 | /** Pointer to to a parsed path result. */
|
---|
| 800 | typedef RTPATHPARSED *PRTPATHPARSED;
|
---|
| 801 | /** Pointer to to a const parsed path result. */
|
---|
| 802 | typedef RTPATHPARSED *PCRTPATHPARSED;
|
---|
| 803 |
|
---|
[78187] | 804 | /** Stupid hack for MSC and flexible arrays. */
|
---|
| 805 | #define RTPATHPARSED_MIN_SIZE (sizeof(uint16_t) * (6 + 4))
|
---|
[45389] | 806 |
|
---|
[78187] | 807 |
|
---|
[45389] | 808 | /**
|
---|
| 809 | * Parses the path.
|
---|
| 810 | *
|
---|
| 811 | * @returns IPRT status code.
|
---|
| 812 | * @retval VERR_INVALID_POINTER if pParsed or pszPath is an invalid pointer.
|
---|
| 813 | * @retval VERR_INVALID_PARAMETER if cbOutput is less than the RTPATHPARSED
|
---|
| 814 | * strucuture. No output. (asserted)
|
---|
| 815 | * @retval VERR_BUFFER_OVERFLOW there are more components in the path than
|
---|
| 816 | * there is space in aComps. The required amount of space can be
|
---|
| 817 | * determined from the pParsed->cComps:
|
---|
| 818 | * @code
|
---|
| 819 | * RT_OFFSETOF(RTPATHPARSED, aComps[pParsed->cComps])
|
---|
| 820 | * @endcode
|
---|
| 821 | * @retval VERR_PATH_ZERO_LENGTH if the path is empty.
|
---|
| 822 | *
|
---|
| 823 | * @param pszPath The path to parse.
|
---|
| 824 | * @param pParsed Where to store the details of the parsed path.
|
---|
| 825 | * @param cbParsed The size of the buffer. Must be at least the
|
---|
| 826 | * size of RTPATHPARSED.
|
---|
[45391] | 827 | * @param fFlags Combination of RTPATH_STR_F_XXX flags.
|
---|
| 828 | * Most users will pass 0.
|
---|
[45389] | 829 | * @sa RTPathSplit, RTPathSplitA.
|
---|
| 830 | */
|
---|
[45400] | 831 | RTDECL(int) RTPathParse(const char *pszPath, PRTPATHPARSED pParsed, size_t cbParsed, uint32_t fFlags);
|
---|
[45389] | 832 |
|
---|
| 833 | /**
|
---|
[45400] | 834 | * Reassembles a path parsed by RTPathParse.
|
---|
| 835 | *
|
---|
| 836 | * This will be more useful as more APIs manipulating the RTPATHPARSED output
|
---|
| 837 | * are added.
|
---|
| 838 | *
|
---|
| 839 | * @returns IPRT status code.
|
---|
[78048] | 840 | * @retval VERR_BUFFER_OVERFLOW if the destination buffer is too small.
|
---|
| 841 | * The necessary length is @a pParsed->cchPath + 1 (updated).
|
---|
[45400] | 842 | *
|
---|
| 843 | * @param pszSrcPath The source path.
|
---|
[78048] | 844 | * @param pParsed The parser output for @a pszSrcPath. Caller may
|
---|
| 845 | * eliminate elements by setting their length to
|
---|
| 846 | * zero. The cchPath member is updated.
|
---|
[45400] | 847 | * @param fFlags Combination of RTPATH_STR_F_STYLE_XXX.
|
---|
| 848 | * Most users will pass 0.
|
---|
| 849 | * @param pszDstPath Pointer to the buffer where the path is to be
|
---|
| 850 | * reassembled.
|
---|
| 851 | * @param cbDstPath The size of the output buffer.
|
---|
| 852 | */
|
---|
| 853 | RTDECL(int) RTPathParsedReassemble(const char *pszSrcPath, PRTPATHPARSED pParsed, uint32_t fFlags,
|
---|
| 854 | char *pszDstPath, size_t cbDstPath);
|
---|
| 855 |
|
---|
| 856 |
|
---|
| 857 | /**
|
---|
[45389] | 858 | * Output buffer for RTPathSplit and RTPathSplitA.
|
---|
| 859 | */
|
---|
| 860 | typedef struct RTPATHSPLIT
|
---|
| 861 | {
|
---|
| 862 | /** Number of path components.
|
---|
| 863 | * This will always be set on VERR_BUFFER_OVERFLOW returns from RTPathParsed
|
---|
| 864 | * so the caller can calculate the required buffer size. */
|
---|
| 865 | uint16_t cComps;
|
---|
| 866 | /** Path property flags, RTPATH_PROP_XXX */
|
---|
| 867 | uint16_t fProps;
|
---|
| 868 | /** On success this is the length of the described path, i.e. sum of all
|
---|
| 869 | * component lengths and necessary separators.
|
---|
| 870 | * Do NOT use this to index in the source path in case it contains
|
---|
[45394] | 871 | * unnecessary slashes that RTPathSplit has ignored here. */
|
---|
[45389] | 872 | uint16_t cchPath;
|
---|
| 873 | /** Reserved (internal use). */
|
---|
| 874 | uint16_t u16Reserved;
|
---|
| 875 | /** The amount of memory used (on success) or required (on
|
---|
| 876 | * VERR_BUFFER_OVERFLOW) of this structure and it's strings. */
|
---|
| 877 | uint32_t cbNeeded;
|
---|
| 878 | /** Pointer to the filename suffix (the dot), if any. Points to the NUL
|
---|
| 879 | * character of the last component if none or if RTPATH_PROP_DIR_SLASH is
|
---|
| 880 | * present. */
|
---|
| 881 | const char *pszSuffix;
|
---|
| 882 | /** Array of component strings (variable size). */
|
---|
[84509] | 883 | RT_FLEXIBLE_ARRAY_EXTENSION
|
---|
[78051] | 884 | char *apszComps[RT_FLEXIBLE_ARRAY];
|
---|
[45389] | 885 | } RTPATHSPLIT;
|
---|
| 886 | /** Pointer to a split path buffer. */
|
---|
| 887 | typedef RTPATHSPLIT *PRTPATHSPLIT;
|
---|
| 888 | /** Pointer to a const split path buffer. */
|
---|
| 889 | typedef RTPATHSPLIT const *PCRTPATHSPLIT;
|
---|
| 890 |
|
---|
| 891 | /**
|
---|
| 892 | * Splits the path into individual component strings, carved from user supplied
|
---|
| 893 | * the given buffer block.
|
---|
| 894 | *
|
---|
| 895 | * @returns IPRT status code.
|
---|
| 896 | * @retval VERR_INVALID_POINTER if pParsed or pszPath is an invalid pointer.
|
---|
| 897 | * @retval VERR_INVALID_PARAMETER if cbOutput is less than the RTPATHSPLIT
|
---|
| 898 | * strucuture. No output. (asserted)
|
---|
| 899 | * @retval VERR_BUFFER_OVERFLOW there are more components in the path than
|
---|
| 900 | * there is space in aComps. The required amount of space can be
|
---|
| 901 | * determined from the pParsed->cComps:
|
---|
| 902 | * @code
|
---|
| 903 | * RT_OFFSETOF(RTPATHPARSED, aComps[pParsed->cComps])
|
---|
| 904 | * @endcode
|
---|
| 905 | * @retval VERR_PATH_ZERO_LENGTH if the path is empty.
|
---|
| 906 | * @retval VERR_FILENAME_TOO_LONG if the filename is too long (close to 64 KB).
|
---|
| 907 | *
|
---|
| 908 | * @param pszPath The path to parse.
|
---|
| 909 | * @param pSplit Where to store the details of the parsed path.
|
---|
| 910 | * @param cbSplit The size of the buffer pointed to by @a pSplit
|
---|
| 911 | * (variable sized array at the end). Must be at
|
---|
| 912 | * least the size of RTPATHSPLIT.
|
---|
[45394] | 913 | * @param fFlags Combination of RTPATH_STR_F_XXX flags.
|
---|
| 914 | * Most users will pass 0.
|
---|
[45389] | 915 | *
|
---|
| 916 | * @sa RTPathSplitA, RTPathParse.
|
---|
| 917 | */
|
---|
[45394] | 918 | RTDECL(int) RTPathSplit(const char *pszPath, PRTPATHSPLIT pSplit, size_t cbSplit, uint32_t fFlags);
|
---|
[45389] | 919 |
|
---|
| 920 | /**
|
---|
| 921 | * Splits the path into individual component strings, allocating the buffer on
|
---|
| 922 | * the default thread heap.
|
---|
| 923 | *
|
---|
| 924 | * @returns IPRT status code.
|
---|
| 925 | * @retval VERR_INVALID_POINTER if pParsed or pszPath is an invalid pointer.
|
---|
| 926 | * @retval VERR_PATH_ZERO_LENGTH if the path is empty.
|
---|
| 927 | *
|
---|
| 928 | * @param pszPath The path to parse.
|
---|
| 929 | * @param ppSplit Where to return the pointer to the output on
|
---|
| 930 | * success. This must be freed by calling
|
---|
| 931 | * RTPathSplitFree().
|
---|
[45394] | 932 | * @param fFlags Combination of RTPATH_STR_F_XXX flags.
|
---|
| 933 | * Most users will pass 0.
|
---|
[45389] | 934 | * @sa RTPathSplitFree, RTPathSplit, RTPathParse.
|
---|
| 935 | */
|
---|
[45400] | 936 | #define RTPathSplitA(pszPath, ppSplit, fFlags) RTPathSplitATag(pszPath, ppSplit, fFlags, RTPATH_TAG)
|
---|
[45389] | 937 |
|
---|
| 938 | /**
|
---|
[45394] | 939 | * Splits the path into individual component strings, allocating the buffer on
|
---|
| 940 | * the default thread heap.
|
---|
| 941 | *
|
---|
| 942 | * @returns IPRT status code.
|
---|
| 943 | * @retval VERR_INVALID_POINTER if pParsed or pszPath is an invalid pointer.
|
---|
| 944 | * @retval VERR_PATH_ZERO_LENGTH if the path is empty.
|
---|
| 945 | *
|
---|
| 946 | * @param pszPath The path to parse.
|
---|
| 947 | * @param ppSplit Where to return the pointer to the output on
|
---|
| 948 | * success. This must be freed by calling
|
---|
| 949 | * RTPathSplitFree().
|
---|
| 950 | * @param fFlags Combination of RTPATH_STR_F_XXX flags.
|
---|
| 951 | * Most users will pass 0.
|
---|
| 952 | * @param pszTag Allocation tag used for statistics and such.
|
---|
| 953 | * @sa RTPathSplitFree, RTPathSplit, RTPathParse.
|
---|
| 954 | */
|
---|
| 955 | RTDECL(int) RTPathSplitATag(const char *pszPath, PRTPATHSPLIT *ppSplit, uint32_t fFlags, const char *pszTag);
|
---|
| 956 |
|
---|
| 957 | /**
|
---|
[45389] | 958 | * Frees buffer returned by RTPathSplitA.
|
---|
| 959 | *
|
---|
| 960 | * @param pSplit What RTPathSplitA returned.
|
---|
| 961 | * @sa RTPathSplitA
|
---|
| 962 | */
|
---|
| 963 | RTDECL(void) RTPathSplitFree(PRTPATHSPLIT pSplit);
|
---|
| 964 |
|
---|
[45400] | 965 | /**
|
---|
| 966 | * Reassembles a path parsed by RTPathSplit.
|
---|
| 967 | *
|
---|
| 968 | * This will be more useful as more APIs manipulating the RTPATHSPLIT output are
|
---|
| 969 | * added.
|
---|
| 970 | *
|
---|
| 971 | * @returns IPRT status code.
|
---|
| 972 | * @retval VERR_BUFFER_OVERFLOW if @a cbDstPath is less than or equal to
|
---|
| 973 | * RTPATHSPLIT::cchPath.
|
---|
| 974 | *
|
---|
[57926] | 975 | * @param pSplit A split path (see RTPathSplit, RTPathSplitA).
|
---|
[45400] | 976 | * @param fFlags Combination of RTPATH_STR_F_STYLE_XXX.
|
---|
| 977 | * Most users will pass 0.
|
---|
| 978 | * @param pszDstPath Pointer to the buffer where the path is to be
|
---|
| 979 | * reassembled.
|
---|
| 980 | * @param cbDstPath The size of the output buffer.
|
---|
| 981 | */
|
---|
| 982 | RTDECL(int) RTPathSplitReassemble(PRTPATHSPLIT pSplit, uint32_t fFlags, char *pszDstPath, size_t cbDstPath);
|
---|
[45389] | 983 |
|
---|
| 984 | /**
|
---|
[46162] | 985 | * Checks if the two paths leads to the file system object.
|
---|
| 986 | *
|
---|
| 987 | * If the objects exist, we'll query attributes for them. If that's not
|
---|
| 988 | * conclusive (some OSes) or one of them doesn't exist, we'll use a combination
|
---|
| 989 | * of RTPathAbs and RTPathCompare to determine the result.
|
---|
| 990 | *
|
---|
| 991 | * @returns true, false, or VERR_FILENAME_TOO_LONG.
|
---|
| 992 | * @param pszPath1 The first path.
|
---|
| 993 | * @param pszPath2 The seoncd path.
|
---|
| 994 | */
|
---|
| 995 | RTDECL(int) RTPathIsSame(const char *pszPath1, const char *pszPath2);
|
---|
| 996 |
|
---|
| 997 |
|
---|
| 998 | /**
|
---|
[1] | 999 | * Compares two paths.
|
---|
| 1000 | *
|
---|
| 1001 | * The comparison takes platform-dependent details into account,
|
---|
| 1002 | * such as:
|
---|
| 1003 | * <ul>
|
---|
[19926] | 1004 | * <li>On DOS-like platforms, both separator chars (|\| and |/|) are considered
|
---|
[1] | 1005 | * to be equal.
|
---|
| 1006 | * <li>On platforms with case-insensitive file systems, mismatching characters
|
---|
| 1007 | * are uppercased and compared again.
|
---|
| 1008 | * </ul>
|
---|
| 1009 | *
|
---|
[19926] | 1010 | * @returns @< 0 if the first path less than the second path.
|
---|
| 1011 | * @returns 0 if the first path identical to the second path.
|
---|
| 1012 | * @returns @> 0 if the first path greater than the second path.
|
---|
[1] | 1013 | *
|
---|
| 1014 | * @param pszPath1 Path to compare (must be an absolute path).
|
---|
| 1015 | * @param pszPath2 Path to compare (must be an absolute path).
|
---|
| 1016 | *
|
---|
[19926] | 1017 | * @remarks File system details are currently ignored. This means that you won't
|
---|
[33540] | 1018 | * get case-insensitive compares on unix systems when a path goes into a
|
---|
[19926] | 1019 | * case-insensitive filesystem like FAT, HPFS, HFS, NTFS, JFS, or
|
---|
[33540] | 1020 | * similar. For NT, OS/2 and similar you'll won't get case-sensitive
|
---|
[19926] | 1021 | * compares on a case-sensitive file system.
|
---|
[1] | 1022 | */
|
---|
| 1023 | RTDECL(int) RTPathCompare(const char *pszPath1, const char *pszPath2);
|
---|
| 1024 |
|
---|
| 1025 | /**
|
---|
| 1026 | * Checks if a path starts with the given parent path.
|
---|
| 1027 | *
|
---|
[19926] | 1028 | * This means that either the path and the parent path matches completely, or
|
---|
| 1029 | * that the path is to some file or directory residing in the tree given by the
|
---|
| 1030 | * parent directory.
|
---|
[1] | 1031 | *
|
---|
| 1032 | * The path comparison takes platform-dependent details into account,
|
---|
| 1033 | * see RTPathCompare() for details.
|
---|
| 1034 | *
|
---|
[19926] | 1035 | * @returns |true| when \a pszPath starts with \a pszParentPath (or when they
|
---|
| 1036 | * are identical), or |false| otherwise.
|
---|
| 1037 | *
|
---|
[1] | 1038 | * @param pszPath Path to check, must be an absolute path.
|
---|
| 1039 | * @param pszParentPath Parent path, must be an absolute path.
|
---|
| 1040 | * No trailing directory slash!
|
---|
| 1041 | *
|
---|
[19926] | 1042 | * @remarks This API doesn't currently handle root directory compares in a
|
---|
[33540] | 1043 | * manner consistent with the other APIs. RTPathStartsWith(pszSomePath,
|
---|
[19926] | 1044 | * "/") will not work if pszSomePath isn't "/".
|
---|
[1] | 1045 | */
|
---|
| 1046 | RTDECL(bool) RTPathStartsWith(const char *pszPath, const char *pszParentPath);
|
---|
| 1047 |
|
---|
[19926] | 1048 | /**
|
---|
| 1049 | * Appends one partial path to another.
|
---|
| 1050 | *
|
---|
[19927] | 1051 | * The main purpose of this function is to deal correctly with the slashes when
|
---|
| 1052 | * concatenating the two partial paths.
|
---|
[19926] | 1053 | *
|
---|
[19928] | 1054 | * @retval VINF_SUCCESS on success.
|
---|
| 1055 | * @retval VERR_BUFFER_OVERFLOW if the result is too big to fit within
|
---|
| 1056 | * cbPathDst bytes. No changes has been made.
|
---|
| 1057 | * @retval VERR_INVALID_PARAMETER if the string pointed to by pszPath is longer
|
---|
| 1058 | * than cbPathDst-1 bytes (failed to find terminator). Asserted.
|
---|
[19926] | 1059 | *
|
---|
| 1060 | * @param pszPath The path to append pszAppend to. This serves as both
|
---|
| 1061 | * input and output. This can be empty, in which case
|
---|
| 1062 | * pszAppend is just copied over.
|
---|
[19928] | 1063 | * @param cbPathDst The size of the buffer pszPath points to, terminator
|
---|
| 1064 | * included. This should NOT be strlen(pszPath).
|
---|
[19926] | 1065 | * @param pszAppend The partial path to append to pszPath. This can be
|
---|
| 1066 | * NULL, in which case nothing is done.
|
---|
| 1067 | *
|
---|
[34214] | 1068 | * @remarks See the RTPathAppendEx remarks.
|
---|
| 1069 | */
|
---|
| 1070 | RTDECL(int) RTPathAppend(char *pszPath, size_t cbPathDst, const char *pszAppend);
|
---|
| 1071 |
|
---|
| 1072 | /**
|
---|
| 1073 | * Appends one partial path to another.
|
---|
| 1074 | *
|
---|
| 1075 | * The main purpose of this function is to deal correctly with the slashes when
|
---|
| 1076 | * concatenating the two partial paths.
|
---|
| 1077 | *
|
---|
| 1078 | * @retval VINF_SUCCESS on success.
|
---|
| 1079 | * @retval VERR_BUFFER_OVERFLOW if the result is too big to fit within
|
---|
| 1080 | * cbPathDst bytes. No changes has been made.
|
---|
| 1081 | * @retval VERR_INVALID_PARAMETER if the string pointed to by pszPath is longer
|
---|
| 1082 | * than cbPathDst-1 bytes (failed to find terminator). Asserted.
|
---|
| 1083 | *
|
---|
| 1084 | * @param pszPath The path to append pszAppend to. This serves as both
|
---|
| 1085 | * input and output. This can be empty, in which case
|
---|
| 1086 | * pszAppend is just copied over.
|
---|
| 1087 | * @param cbPathDst The size of the buffer pszPath points to, terminator
|
---|
| 1088 | * included. This should NOT be strlen(pszPath).
|
---|
| 1089 | * @param pszAppend The partial path to append to pszPath. This can be
|
---|
| 1090 | * NULL, in which case nothing is done.
|
---|
| 1091 | * @param cchAppendMax The maximum number or characters to take from @a
|
---|
| 1092 | * pszAppend. RTSTR_MAX is fine.
|
---|
[96610] | 1093 | * @param fFlags Combination of RTPATH_STR_F_STYLE_XXX.
|
---|
| 1094 | * Most users will pass 0 / RTPATH_STR_F_STYLE_HOST.
|
---|
[34214] | 1095 | *
|
---|
[19926] | 1096 | * @remarks On OS/2, Window and similar systems, concatenating a drive letter
|
---|
[19927] | 1097 | * specifier with a slash prefixed path will result in an absolute
|
---|
| 1098 | * path. Meaning, RTPathAppend(strcpy(szBuf, "C:"), sizeof(szBuf),
|
---|
| 1099 | * "/bar") will result in "C:/bar". (This follows directly from the
|
---|
| 1100 | * behavior when pszPath is empty.)
|
---|
| 1101 | *
|
---|
| 1102 | * On the other hand, when joining a drive letter specifier with a
|
---|
| 1103 | * partial path that does not start with a slash, the result is not an
|
---|
| 1104 | * absolute path. Meaning, RTPathAppend(strcpy(szBuf, "C:"),
|
---|
| 1105 | * sizeof(szBuf), "bar") will result in "C:bar".
|
---|
[19926] | 1106 | */
|
---|
[96610] | 1107 | RTDECL(int) RTPathAppendEx(char *pszPath, size_t cbPathDst, const char *pszAppend, size_t cchAppendMax, uint32_t fFlags);
|
---|
[1] | 1108 |
|
---|
[22109] | 1109 | /**
|
---|
[26133] | 1110 | * Like RTPathAppend, but with the base path as a separate argument instead of
|
---|
| 1111 | * in the path buffer.
|
---|
| 1112 | *
|
---|
| 1113 | * @retval VINF_SUCCESS on success.
|
---|
| 1114 | * @retval VERR_BUFFER_OVERFLOW if the result is too big to fit within
|
---|
| 1115 | * cbPathDst bytes.
|
---|
| 1116 | * @retval VERR_INVALID_PARAMETER if the string pointed to by pszPath is longer
|
---|
| 1117 | * than cbPathDst-1 bytes (failed to find terminator). Asserted.
|
---|
| 1118 | *
|
---|
| 1119 | * @param pszPathDst Where to store the resulting path.
|
---|
| 1120 | * @param cbPathDst The size of the buffer pszPathDst points to,
|
---|
| 1121 | * terminator included.
|
---|
| 1122 | * @param pszPathSrc The base path to copy into @a pszPathDst before
|
---|
| 1123 | * appending @a pszAppend.
|
---|
| 1124 | * @param pszAppend The partial path to append to pszPathSrc. This can
|
---|
| 1125 | * be NULL, in which case nothing is done.
|
---|
| 1126 | *
|
---|
| 1127 | */
|
---|
| 1128 | RTDECL(int) RTPathJoin(char *pszPathDst, size_t cbPathDst, const char *pszPathSrc,
|
---|
| 1129 | const char *pszAppend);
|
---|
| 1130 |
|
---|
| 1131 | /**
|
---|
[33450] | 1132 | * Same as RTPathJoin, except that the output buffer is allocated.
|
---|
| 1133 | *
|
---|
| 1134 | * @returns Buffer containing the joined up path, call RTStrFree to free. NULL
|
---|
| 1135 | * on allocation failure.
|
---|
| 1136 | * @param pszPathSrc The base path to copy into @a pszPathDst before
|
---|
| 1137 | * appending @a pszAppend.
|
---|
| 1138 | * @param pszAppend The partial path to append to pszPathSrc. This can
|
---|
| 1139 | * be NULL, in which case nothing is done.
|
---|
| 1140 | *
|
---|
| 1141 | */
|
---|
| 1142 | RTDECL(char *) RTPathJoinA(const char *pszPathSrc, const char *pszAppend);
|
---|
| 1143 |
|
---|
| 1144 | /**
|
---|
[34214] | 1145 | * Extended version of RTPathJoin, both inputs can be specified as substrings.
|
---|
| 1146 | *
|
---|
| 1147 | * @retval VINF_SUCCESS on success.
|
---|
| 1148 | * @retval VERR_BUFFER_OVERFLOW if the result is too big to fit within
|
---|
| 1149 | * cbPathDst bytes.
|
---|
| 1150 | * @retval VERR_INVALID_PARAMETER if the string pointed to by pszPath is longer
|
---|
| 1151 | * than cbPathDst-1 bytes (failed to find terminator). Asserted.
|
---|
| 1152 | *
|
---|
| 1153 | * @param pszPathDst Where to store the resulting path.
|
---|
| 1154 | * @param cbPathDst The size of the buffer pszPathDst points to,
|
---|
| 1155 | * terminator included.
|
---|
| 1156 | * @param pszPathSrc The base path to copy into @a pszPathDst before
|
---|
| 1157 | * appending @a pszAppend.
|
---|
| 1158 | * @param cchPathSrcMax The maximum number of bytes to copy from @a
|
---|
| 1159 | * pszPathSrc. RTSTR_MAX is find.
|
---|
| 1160 | * @param pszAppend The partial path to append to pszPathSrc. This can
|
---|
| 1161 | * be NULL, in which case nothing is done.
|
---|
| 1162 | * @param cchAppendMax The maximum number of bytes to copy from @a
|
---|
| 1163 | * pszAppend. RTSTR_MAX is find.
|
---|
[96610] | 1164 | * @param fFlags Combination of RTPATH_STR_F_STYLE_XXX.
|
---|
| 1165 | * Most users will pass 0 / RTPATH_STR_F_STYLE_HOST.
|
---|
[34214] | 1166 | *
|
---|
| 1167 | */
|
---|
| 1168 | RTDECL(int) RTPathJoinEx(char *pszPathDst, size_t cbPathDst,
|
---|
| 1169 | const char *pszPathSrc, size_t cchPathSrcMax,
|
---|
[96610] | 1170 | const char *pszAppend, size_t cchAppendMax, uint32_t fFlags);
|
---|
[34214] | 1171 |
|
---|
| 1172 | /**
|
---|
[22109] | 1173 | * Callback for RTPathTraverseList that's called for each element.
|
---|
| 1174 | *
|
---|
[40826] | 1175 | * @returns IPRT style status code. Return VERR_TRY_AGAIN to continue, any other
|
---|
[22109] | 1176 | * value will abort the traversing and be returned to the caller.
|
---|
| 1177 | *
|
---|
| 1178 | * @param pchPath Pointer to the start of the current path. This is
|
---|
| 1179 | * not null terminated.
|
---|
| 1180 | * @param cchPath The length of the path.
|
---|
| 1181 | * @param pvUser1 The first user parameter.
|
---|
| 1182 | * @param pvUser2 The second user parameter.
|
---|
| 1183 | */
|
---|
[85121] | 1184 | typedef DECLCALLBACKTYPE(int, FNRTPATHTRAVERSER,(char const *pchPath, size_t cchPath, void *pvUser1, void *pvUser2));
|
---|
[22109] | 1185 | /** Pointer to a FNRTPATHTRAVERSER. */
|
---|
| 1186 | typedef FNRTPATHTRAVERSER *PFNRTPATHTRAVERSER;
|
---|
[19926] | 1187 |
|
---|
[22109] | 1188 | /**
|
---|
| 1189 | * Traverses a string that can contain multiple paths separated by a special
|
---|
| 1190 | * character.
|
---|
| 1191 | *
|
---|
| 1192 | * @returns IPRT style status code from the callback or VERR_END_OF_STRING if
|
---|
[40826] | 1193 | * the callback returned VERR_TRY_AGAIN for all paths in the string.
|
---|
[22109] | 1194 | *
|
---|
| 1195 | * @param pszPathList The string to traverse.
|
---|
| 1196 | * @param chSep The separator character. Using the null terminator
|
---|
| 1197 | * is fine, but the result will simply be that there
|
---|
| 1198 | * will only be one callback for the entire string
|
---|
| 1199 | * (save any leading white space).
|
---|
| 1200 | * @param pfnCallback The callback.
|
---|
| 1201 | * @param pvUser1 First user argument for the callback.
|
---|
| 1202 | * @param pvUser2 Second user argument for the callback.
|
---|
| 1203 | */
|
---|
| 1204 | RTDECL(int) RTPathTraverseList(const char *pszPathList, char chSep, PFNRTPATHTRAVERSER pfnCallback, void *pvUser1, void *pvUser2);
|
---|
| 1205 |
|
---|
| 1206 |
|
---|
[44615] | 1207 | /**
|
---|
[44623] | 1208 | * Calculate a relative path between the two given paths.
|
---|
[44615] | 1209 | *
|
---|
| 1210 | * @returns IPRT status code.
|
---|
| 1211 | * @retval VINF_SUCCESS on success.
|
---|
| 1212 | * @retval VERR_BUFFER_OVERFLOW if the result is too big to fit within
|
---|
| 1213 | * cbPathDst bytes.
|
---|
| 1214 | * @retval VERR_NOT_SUPPORTED if both paths start with different volume specifiers.
|
---|
| 1215 | * @param pszPathDst Where to store the resulting path.
|
---|
| 1216 | * @param cbPathDst The size of the buffer pszPathDst points to,
|
---|
| 1217 | * terminator included.
|
---|
| 1218 | * @param pszPathFrom The path to start from creating the relative path.
|
---|
[76589] | 1219 | * @param fFromFile Whether @a pszPathFrom is a file and we should work
|
---|
| 1220 | * relative to it's parent directory (@c true), or if
|
---|
| 1221 | * we should assume @a pszPathFrom is a directory and
|
---|
| 1222 | * work relative to it.
|
---|
[44615] | 1223 | * @param pszPathTo The path to reach with the created relative path.
|
---|
| 1224 | */
|
---|
[76589] | 1225 | RTDECL(int) RTPathCalcRelative(char *pszPathDst, size_t cbPathDst, const char *pszPathFrom, bool fFromFile, const char *pszPathTo);
|
---|
[44615] | 1226 |
|
---|
[1] | 1227 | #ifdef IN_RING3
|
---|
| 1228 |
|
---|
| 1229 | /**
|
---|
[19924] | 1230 | * Gets the path to the directory containing the executable.
|
---|
[1] | 1231 | *
|
---|
| 1232 | * @returns iprt status code.
|
---|
| 1233 | * @param pszPath Buffer where to store the path.
|
---|
| 1234 | * @param cchPath Buffer size in bytes.
|
---|
| 1235 | */
|
---|
[19924] | 1236 | RTDECL(int) RTPathExecDir(char *pszPath, size_t cchPath);
|
---|
[1] | 1237 |
|
---|
| 1238 | /**
|
---|
| 1239 | * Gets the user home directory.
|
---|
| 1240 | *
|
---|
| 1241 | * @returns iprt status code.
|
---|
| 1242 | * @param pszPath Buffer where to store the path.
|
---|
| 1243 | * @param cchPath Buffer size in bytes.
|
---|
| 1244 | */
|
---|
[14050] | 1245 | RTDECL(int) RTPathUserHome(char *pszPath, size_t cchPath);
|
---|
[1] | 1246 |
|
---|
| 1247 | /**
|
---|
[36611] | 1248 | * Gets the user documents directory.
|
---|
| 1249 | *
|
---|
[45265] | 1250 | * The returned path isn't guaranteed to exist.
|
---|
[36611] | 1251 | *
|
---|
| 1252 | * @returns iprt status code.
|
---|
| 1253 | * @param pszPath Buffer where to store the path.
|
---|
| 1254 | * @param cchPath Buffer size in bytes.
|
---|
| 1255 | */
|
---|
| 1256 | RTDECL(int) RTPathUserDocuments(char *pszPath, size_t cchPath);
|
---|
| 1257 |
|
---|
| 1258 | /**
|
---|
[19924] | 1259 | * Gets the directory of shared libraries.
|
---|
[2769] | 1260 | *
|
---|
[19924] | 1261 | * This is not the same as RTPathAppPrivateArch() as Linux depends all shared
|
---|
[35218] | 1262 | * libraries in a common global directory where ld.so can find them.
|
---|
[19924] | 1263 | *
|
---|
[3860] | 1264 | * Linux: /usr/lib
|
---|
[35218] | 1265 | * Solaris: /opt/@<application@>/@<arch>@ or something
|
---|
[7170] | 1266 | * Windows: @<program files directory@>/@<application@>
|
---|
[19924] | 1267 | * Old path: same as RTPathExecDir()
|
---|
[3860] | 1268 | *
|
---|
[2769] | 1269 | * @returns iprt status code.
|
---|
| 1270 | * @param pszPath Buffer where to store the path.
|
---|
| 1271 | * @param cchPath Buffer size in bytes.
|
---|
| 1272 | */
|
---|
[14050] | 1273 | RTDECL(int) RTPathSharedLibs(char *pszPath, size_t cchPath);
|
---|
[2769] | 1274 |
|
---|
| 1275 | /**
|
---|
[3860] | 1276 | * Gets the directory for architecture-independent application data, for
|
---|
| 1277 | * example NLS files, module sources, ...
|
---|
[2769] | 1278 | *
|
---|
[7170] | 1279 | * Linux: /usr/shared/@<application@>
|
---|
[35218] | 1280 | * Solaris: /opt/@<application@>
|
---|
[7170] | 1281 | * Windows: @<program files directory@>/@<application@>
|
---|
[19924] | 1282 | * Old path: same as RTPathExecDir()
|
---|
[3860] | 1283 | *
|
---|
[2769] | 1284 | * @returns iprt status code.
|
---|
| 1285 | * @param pszPath Buffer where to store the path.
|
---|
| 1286 | * @param cchPath Buffer size in bytes.
|
---|
| 1287 | */
|
---|
[14050] | 1288 | RTDECL(int) RTPathAppPrivateNoArch(char *pszPath, size_t cchPath);
|
---|
[2769] | 1289 |
|
---|
| 1290 | /**
|
---|
[3860] | 1291 | * Gets the directory for architecture-dependent application data, for
|
---|
| 1292 | * example modules which can be loaded at runtime.
|
---|
| 1293 | *
|
---|
[7170] | 1294 | * Linux: /usr/lib/@<application@>
|
---|
[35218] | 1295 | * Solaris: /opt/@<application@>/@<arch>@ or something
|
---|
[7170] | 1296 | * Windows: @<program files directory@>/@<application@>
|
---|
[19924] | 1297 | * Old path: same as RTPathExecDir()
|
---|
[3860] | 1298 | *
|
---|
| 1299 | * @returns iprt status code.
|
---|
| 1300 | * @param pszPath Buffer where to store the path.
|
---|
| 1301 | * @param cchPath Buffer size in bytes.
|
---|
| 1302 | */
|
---|
[14050] | 1303 | RTDECL(int) RTPathAppPrivateArch(char *pszPath, size_t cchPath);
|
---|
[3860] | 1304 |
|
---|
| 1305 | /**
|
---|
[35218] | 1306 | * Gets the toplevel directory for architecture-dependent application data.
|
---|
| 1307 | *
|
---|
| 1308 | * This differs from RTPathAppPrivateArch on Solaris only where it will work
|
---|
| 1309 | * around the /opt/@<application@>/amd64 and /opt/@<application@>/i386 multi
|
---|
| 1310 | * architecture installation style.
|
---|
| 1311 | *
|
---|
| 1312 | * Linux: /usr/lib/@<application@>
|
---|
| 1313 | * Solaris: /opt/@<application@>
|
---|
| 1314 | * Windows: @<program files directory@>/@<application@>
|
---|
| 1315 | * Old path: same as RTPathExecDir()
|
---|
| 1316 | *
|
---|
| 1317 | * @returns iprt status code.
|
---|
| 1318 | * @param pszPath Buffer where to store the path.
|
---|
| 1319 | * @param cchPath Buffer size in bytes.
|
---|
| 1320 | */
|
---|
| 1321 | RTDECL(int) RTPathAppPrivateArchTop(char *pszPath, size_t cchPath);
|
---|
| 1322 |
|
---|
| 1323 | /**
|
---|
[2778] | 1324 | * Gets the directory for documentation.
|
---|
[2769] | 1325 | *
|
---|
[7170] | 1326 | * Linux: /usr/share/doc/@<application@>
|
---|
[35218] | 1327 | * Solaris: /opt/@<application@>
|
---|
[7170] | 1328 | * Windows: @<program files directory@>/@<application@>
|
---|
[19924] | 1329 | * Old path: same as RTPathExecDir()
|
---|
[3860] | 1330 | *
|
---|
[2769] | 1331 | * @returns iprt status code.
|
---|
| 1332 | * @param pszPath Buffer where to store the path.
|
---|
| 1333 | * @param cchPath Buffer size in bytes.
|
---|
| 1334 | */
|
---|
[14052] | 1335 | RTDECL(int) RTPathAppDocs(char *pszPath, size_t cchPath);
|
---|
[2769] | 1336 |
|
---|
| 1337 | /**
|
---|
[20018] | 1338 | * Gets the temporary directory path.
|
---|
| 1339 | *
|
---|
| 1340 | * @returns iprt status code.
|
---|
| 1341 | * @param pszPath Buffer where to store the path.
|
---|
| 1342 | * @param cchPath Buffer size in bytes.
|
---|
| 1343 | */
|
---|
| 1344 | RTDECL(int) RTPathTemp(char *pszPath, size_t cchPath);
|
---|
| 1345 |
|
---|
[57613] | 1346 |
|
---|
[20018] | 1347 | /**
|
---|
[57613] | 1348 | * RTPathGlobl result entry.
|
---|
| 1349 | */
|
---|
| 1350 | typedef struct RTPATHGLOBENTRY
|
---|
| 1351 | {
|
---|
| 1352 | /** List entry. */
|
---|
| 1353 | struct RTPATHGLOBENTRY *pNext;
|
---|
| 1354 | /** RTDIRENTRYTYPE value. */
|
---|
| 1355 | uint8_t uType;
|
---|
| 1356 | /** Unused explicit padding. */
|
---|
| 1357 | uint8_t bUnused;
|
---|
| 1358 | /** The length of the path. */
|
---|
| 1359 | uint16_t cchPath;
|
---|
| 1360 | /** The path to the file (variable length). */
|
---|
| 1361 | char szPath[1];
|
---|
| 1362 | } RTPATHGLOBENTRY;
|
---|
| 1363 | /** Pointer to a GLOB result entry. */
|
---|
| 1364 | typedef RTPATHGLOBENTRY *PRTPATHGLOBENTRY;
|
---|
| 1365 | /** Pointer to a const GLOB result entry. */
|
---|
| 1366 | typedef RTPATHGLOBENTRY const *PCRTPATHGLOBENTRY;
|
---|
| 1367 | /** Pointer to a GLOB result entry pointer. */
|
---|
| 1368 | typedef PCRTPATHGLOBENTRY *PPCRTPATHGLOBENTRY;
|
---|
| 1369 |
|
---|
| 1370 | /**
|
---|
| 1371 | * Performs wildcard expansion on a path pattern.
|
---|
| 1372 | *
|
---|
| 1373 | * @returns IPRT status code.
|
---|
| 1374 | *
|
---|
| 1375 | * @param pszPattern The pattern to expand.
|
---|
| 1376 | * @param fFlags RTPATHGLOB_F_XXX.
|
---|
| 1377 | * @param ppHead Where to return the head of the result list. This
|
---|
| 1378 | * is always set to NULL on failure.
|
---|
| 1379 | * @param pcResults Where to return the number of the result. Optional.
|
---|
| 1380 | */
|
---|
| 1381 | RTDECL(int) RTPathGlob(const char *pszPattern, uint32_t fFlags, PPCRTPATHGLOBENTRY ppHead, uint32_t *pcResults);
|
---|
| 1382 |
|
---|
| 1383 | /** @name RTPATHGLOB_F_XXX - RTPathGlob flags
|
---|
| 1384 | * @{ */
|
---|
| 1385 | /** Case insensitive. */
|
---|
| 1386 | #define RTPATHGLOB_F_IGNORE_CASE RT_BIT_32(0)
|
---|
| 1387 | /** Do not expand \${EnvOrSpecialVariable} in the pattern. */
|
---|
| 1388 | #define RTPATHGLOB_F_NO_VARIABLES RT_BIT_32(1)
|
---|
| 1389 | /** Do not interpret a leading tilde as a home directory reference. */
|
---|
| 1390 | #define RTPATHGLOB_F_NO_TILDE RT_BIT_32(2)
|
---|
| 1391 | /** Only return the first match. */
|
---|
| 1392 | #define RTPATHGLOB_F_FIRST_ONLY RT_BIT_32(3)
|
---|
| 1393 | /** Only match directories (implied if pattern ends with slash). */
|
---|
| 1394 | #define RTPATHGLOB_F_ONLY_DIRS RT_BIT_32(4)
|
---|
| 1395 | /** Do not match directories. (Can't be used with RTPATHGLOB_F_ONLY_DIRS or
|
---|
| 1396 | * patterns containing a trailing slash.) */
|
---|
| 1397 | #define RTPATHGLOB_F_NO_DIRS RT_BIT_32(5)
|
---|
| 1398 | /** Disables the '**' wildcard pattern for matching zero or more subdirs. */
|
---|
| 1399 | #define RTPATHGLOB_F_NO_STARSTAR RT_BIT_32(6)
|
---|
| 1400 | /** Mask of valid flags. */
|
---|
| 1401 | #define RTPATHGLOB_F_MASK UINT32_C(0x0000007f)
|
---|
| 1402 | /** @} */
|
---|
| 1403 |
|
---|
| 1404 | /**
|
---|
| 1405 | * Frees the results produced by RTPathGlob.
|
---|
| 1406 | *
|
---|
| 1407 | * @param pHead What RTPathGlob returned. NULL ignored.
|
---|
| 1408 | */
|
---|
| 1409 | RTDECL(void) RTPathGlobFree(PCRTPATHGLOBENTRY pHead);
|
---|
| 1410 |
|
---|
| 1411 |
|
---|
| 1412 | /**
|
---|
[1] | 1413 | * Query information about a file system object.
|
---|
| 1414 | *
|
---|
[23291] | 1415 | * This API will resolve NOT symbolic links in the last component (just like
|
---|
| 1416 | * unix lstat()).
|
---|
[1] | 1417 | *
|
---|
[23291] | 1418 | * @returns IPRT status code.
|
---|
| 1419 | * @retval VINF_SUCCESS if the object exists, information returned.
|
---|
| 1420 | * @retval VERR_PATH_NOT_FOUND if any but the last component in the specified
|
---|
[1] | 1421 | * path was not found or was not a directory.
|
---|
[23291] | 1422 | * @retval VERR_FILE_NOT_FOUND if the object does not exist (but path to the
|
---|
[1] | 1423 | * parent directory exists).
|
---|
| 1424 | *
|
---|
| 1425 | * @param pszPath Path to the file system object.
|
---|
[34002] | 1426 | * @param pObjInfo Object information structure to be filled on successful
|
---|
| 1427 | * return.
|
---|
[1] | 1428 | * @param enmAdditionalAttribs
|
---|
| 1429 | * Which set of additional attributes to request.
|
---|
| 1430 | * Use RTFSOBJATTRADD_NOTHING if this doesn't matter.
|
---|
| 1431 | */
|
---|
| 1432 | RTR3DECL(int) RTPathQueryInfo(const char *pszPath, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAdditionalAttribs);
|
---|
| 1433 |
|
---|
| 1434 | /**
|
---|
[23291] | 1435 | * Query information about a file system object.
|
---|
| 1436 | *
|
---|
| 1437 | * @returns IPRT status code.
|
---|
| 1438 | * @retval VINF_SUCCESS if the object exists, information returned.
|
---|
| 1439 | * @retval VERR_PATH_NOT_FOUND if any but the last component in the specified
|
---|
| 1440 | * path was not found or was not a directory.
|
---|
| 1441 | * @retval VERR_FILE_NOT_FOUND if the object does not exist (but path to the
|
---|
| 1442 | * parent directory exists).
|
---|
| 1443 | *
|
---|
| 1444 | * @param pszPath Path to the file system object.
|
---|
| 1445 | * @param pObjInfo Object information structure to be filled on successful return.
|
---|
| 1446 | * @param enmAdditionalAttribs
|
---|
| 1447 | * Which set of additional attributes to request.
|
---|
| 1448 | * Use RTFSOBJATTRADD_NOTHING if this doesn't matter.
|
---|
[23294] | 1449 | * @param fFlags RTPATH_F_ON_LINK or RTPATH_F_FOLLOW_LINK.
|
---|
[23291] | 1450 | */
|
---|
| 1451 | RTR3DECL(int) RTPathQueryInfoEx(const char *pszPath, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAdditionalAttribs, uint32_t fFlags);
|
---|
| 1452 |
|
---|
| 1453 | /**
|
---|
[1] | 1454 | * Changes the mode flags of a file system object.
|
---|
| 1455 | *
|
---|
| 1456 | * The API requires at least one of the mode flag sets (Unix/Dos) to
|
---|
| 1457 | * be set. The type is ignored.
|
---|
| 1458 | *
|
---|
| 1459 | * This API will resolve symbolic links in the last component since
|
---|
| 1460 | * mode isn't important for symbolic links.
|
---|
| 1461 | *
|
---|
| 1462 | * @returns iprt status code.
|
---|
| 1463 | * @param pszPath Path to the file system object.
|
---|
| 1464 | * @param fMode The new file mode, see @ref grp_rt_fs for details.
|
---|
| 1465 | */
|
---|
| 1466 | RTR3DECL(int) RTPathSetMode(const char *pszPath, RTFMODE fMode);
|
---|
| 1467 |
|
---|
| 1468 | /**
|
---|
| 1469 | * Gets the mode flags of a file system object.
|
---|
| 1470 | *
|
---|
| 1471 | * @returns iprt status code.
|
---|
| 1472 | * @param pszPath Path to the file system object.
|
---|
| 1473 | * @param pfMode Where to store the file mode, see @ref grp_rt_fs for details.
|
---|
| 1474 | *
|
---|
[31404] | 1475 | * @remark This is wrapper around RTPathQueryInfoEx(RTPATH_F_FOLLOW_LINK) and
|
---|
| 1476 | * exists to complement RTPathSetMode().
|
---|
[1] | 1477 | */
|
---|
| 1478 | RTR3DECL(int) RTPathGetMode(const char *pszPath, PRTFMODE pfMode);
|
---|
| 1479 |
|
---|
| 1480 | /**
|
---|
| 1481 | * Changes one or more of the timestamps associated of file system object.
|
---|
| 1482 | *
|
---|
| 1483 | * This API will not resolve symbolic links in the last component (just
|
---|
| 1484 | * like unix lutimes()).
|
---|
| 1485 | *
|
---|
| 1486 | * @returns iprt status code.
|
---|
| 1487 | * @param pszPath Path to the file system object.
|
---|
| 1488 | * @param pAccessTime Pointer to the new access time.
|
---|
[16252] | 1489 | * @param pModificationTime Pointer to the new modification time.
|
---|
[1] | 1490 | * @param pChangeTime Pointer to the new change time. NULL if not to be changed.
|
---|
| 1491 | * @param pBirthTime Pointer to the new time of birth. NULL if not to be changed.
|
---|
| 1492 | *
|
---|
| 1493 | * @remark The file system might not implement all these time attributes,
|
---|
| 1494 | * the API will ignore the ones which aren't supported.
|
---|
| 1495 | *
|
---|
| 1496 | * @remark The file system might not implement the time resolution
|
---|
| 1497 | * employed by this interface, the time will be chopped to fit.
|
---|
| 1498 | *
|
---|
| 1499 | * @remark The file system may update the change time even if it's
|
---|
| 1500 | * not specified.
|
---|
| 1501 | *
|
---|
| 1502 | * @remark POSIX can only set Access & Modification and will always set both.
|
---|
| 1503 | */
|
---|
| 1504 | RTR3DECL(int) RTPathSetTimes(const char *pszPath, PCRTTIMESPEC pAccessTime, PCRTTIMESPEC pModificationTime,
|
---|
| 1505 | PCRTTIMESPEC pChangeTime, PCRTTIMESPEC pBirthTime);
|
---|
| 1506 |
|
---|
| 1507 | /**
|
---|
[23291] | 1508 | * Changes one or more of the timestamps associated of file system object.
|
---|
| 1509 | *
|
---|
| 1510 | * @returns iprt status code.
|
---|
| 1511 | * @param pszPath Path to the file system object.
|
---|
| 1512 | * @param pAccessTime Pointer to the new access time.
|
---|
| 1513 | * @param pModificationTime Pointer to the new modification time.
|
---|
| 1514 | * @param pChangeTime Pointer to the new change time. NULL if not to be changed.
|
---|
| 1515 | * @param pBirthTime Pointer to the new time of birth. NULL if not to be changed.
|
---|
[23294] | 1516 | * @param fFlags RTPATH_F_ON_LINK or RTPATH_F_FOLLOW_LINK.
|
---|
[23291] | 1517 | *
|
---|
| 1518 | * @remark The file system might not implement all these time attributes,
|
---|
| 1519 | * the API will ignore the ones which aren't supported.
|
---|
| 1520 | *
|
---|
| 1521 | * @remark The file system might not implement the time resolution
|
---|
| 1522 | * employed by this interface, the time will be chopped to fit.
|
---|
| 1523 | *
|
---|
| 1524 | * @remark The file system may update the change time even if it's
|
---|
| 1525 | * not specified.
|
---|
| 1526 | *
|
---|
| 1527 | * @remark POSIX can only set Access & Modification and will always set both.
|
---|
| 1528 | */
|
---|
| 1529 | RTR3DECL(int) RTPathSetTimesEx(const char *pszPath, PCRTTIMESPEC pAccessTime, PCRTTIMESPEC pModificationTime,
|
---|
| 1530 | PCRTTIMESPEC pChangeTime, PCRTTIMESPEC pBirthTime, uint32_t fFlags);
|
---|
| 1531 |
|
---|
| 1532 | /**
|
---|
[1] | 1533 | * Gets one or more of the timestamps associated of file system object.
|
---|
| 1534 | *
|
---|
| 1535 | * @returns iprt status code.
|
---|
| 1536 | * @param pszPath Path to the file system object.
|
---|
| 1537 | * @param pAccessTime Where to store the access time. NULL is ok.
|
---|
[16252] | 1538 | * @param pModificationTime Where to store the modification time. NULL is ok.
|
---|
[1] | 1539 | * @param pChangeTime Where to store the change time. NULL is ok.
|
---|
| 1540 | * @param pBirthTime Where to store the creation time. NULL is ok.
|
---|
| 1541 | *
|
---|
[23291] | 1542 | * @remark This is wrapper around RTPathQueryInfo() and exists to complement
|
---|
| 1543 | * RTPathSetTimes(). If the last component is a symbolic link, it will
|
---|
| 1544 | * not be resolved.
|
---|
[1] | 1545 | */
|
---|
| 1546 | RTR3DECL(int) RTPathGetTimes(const char *pszPath, PRTTIMESPEC pAccessTime, PRTTIMESPEC pModificationTime,
|
---|
| 1547 | PRTTIMESPEC pChangeTime, PRTTIMESPEC pBirthTime);
|
---|
| 1548 |
|
---|
| 1549 | /**
|
---|
| 1550 | * Changes the owner and/or group of a file system object.
|
---|
| 1551 | *
|
---|
| 1552 | * This API will not resolve symbolic links in the last component (just
|
---|
| 1553 | * like unix lchown()).
|
---|
| 1554 | *
|
---|
| 1555 | * @returns iprt status code.
|
---|
| 1556 | * @param pszPath Path to the file system object.
|
---|
[34230] | 1557 | * @param uid The new file owner user id. Pass NIL_RTUID to leave
|
---|
| 1558 | * this unchanged.
|
---|
| 1559 | * @param gid The new group id. Pass NIL_RTGUID to leave this
|
---|
| 1560 | * unchanged.
|
---|
[1] | 1561 | */
|
---|
| 1562 | RTR3DECL(int) RTPathSetOwner(const char *pszPath, uint32_t uid, uint32_t gid);
|
---|
| 1563 |
|
---|
| 1564 | /**
|
---|
[23291] | 1565 | * Changes the owner and/or group of a file system object.
|
---|
| 1566 | *
|
---|
| 1567 | * @returns iprt status code.
|
---|
| 1568 | * @param pszPath Path to the file system object.
|
---|
[34230] | 1569 | * @param uid The new file owner user id. Pass NIL_RTUID to leave
|
---|
| 1570 | * this unchanged.
|
---|
| 1571 | * @param gid The new group id. Pass NIL_RTGID to leave this
|
---|
| 1572 | * unchanged.
|
---|
[23294] | 1573 | * @param fFlags RTPATH_F_ON_LINK or RTPATH_F_FOLLOW_LINK.
|
---|
[23291] | 1574 | */
|
---|
| 1575 | RTR3DECL(int) RTPathSetOwnerEx(const char *pszPath, uint32_t uid, uint32_t gid, uint32_t fFlags);
|
---|
| 1576 |
|
---|
| 1577 | /**
|
---|
[1] | 1578 | * Gets the owner and/or group of a file system object.
|
---|
| 1579 | *
|
---|
| 1580 | * @returns iprt status code.
|
---|
| 1581 | * @param pszPath Path to the file system object.
|
---|
| 1582 | * @param pUid Where to store the owner user id. NULL is ok.
|
---|
| 1583 | * @param pGid Where to store the group id. NULL is ok.
|
---|
| 1584 | *
|
---|
[23291] | 1585 | * @remark This is wrapper around RTPathQueryInfo() and exists to complement
|
---|
| 1586 | * RTPathGetOwner(). If the last component is a symbolic link, it will
|
---|
| 1587 | * not be resolved.
|
---|
[1] | 1588 | */
|
---|
| 1589 | RTR3DECL(int) RTPathGetOwner(const char *pszPath, uint32_t *pUid, uint32_t *pGid);
|
---|
| 1590 |
|
---|
| 1591 |
|
---|
| 1592 | /** @name RTPathRename, RTDirRename & RTFileRename flags.
|
---|
| 1593 | * @{ */
|
---|
[33802] | 1594 | /** Do not replace anything. */
|
---|
| 1595 | #define RTPATHRENAME_FLAGS_NO_REPLACE UINT32_C(0)
|
---|
[1] | 1596 | /** This will replace attempt any target which isn't a directory. */
|
---|
[5605] | 1597 | #define RTPATHRENAME_FLAGS_REPLACE RT_BIT(0)
|
---|
[39641] | 1598 | /** Don't allow symbolic links as part of the path.
|
---|
| 1599 | * @remarks this flag is currently not implemented and will be ignored. */
|
---|
[39612] | 1600 | #define RTPATHRENAME_FLAGS_NO_SYMLINKS RT_BIT(1)
|
---|
[1] | 1601 | /** @} */
|
---|
| 1602 |
|
---|
| 1603 | /**
|
---|
| 1604 | * Renames a path within a filesystem.
|
---|
| 1605 | *
|
---|
[23291] | 1606 | * This will rename symbolic links. If RTPATHRENAME_FLAGS_REPLACE is used and
|
---|
| 1607 | * pszDst is a symbolic link, it will be replaced and not its target.
|
---|
| 1608 | *
|
---|
[1] | 1609 | * @returns IPRT status code.
|
---|
| 1610 | * @param pszSrc The source path.
|
---|
| 1611 | * @param pszDst The destination path.
|
---|
| 1612 | * @param fRename Rename flags, RTPATHRENAME_FLAGS_*.
|
---|
| 1613 | */
|
---|
| 1614 | RTR3DECL(int) RTPathRename(const char *pszSrc, const char *pszDst, unsigned fRename);
|
---|
| 1615 |
|
---|
[39612] | 1616 | /** @name RTPathUnlink flags.
|
---|
| 1617 | * @{ */
|
---|
[39641] | 1618 | /** Don't allow symbolic links as part of the path.
|
---|
| 1619 | * @remarks this flag is currently not implemented and will be ignored. */
|
---|
[39612] | 1620 | #define RTPATHUNLINK_FLAGS_NO_SYMLINKS RT_BIT(0)
|
---|
| 1621 | /** @} */
|
---|
| 1622 |
|
---|
| 1623 | /**
|
---|
| 1624 | * Removes the last component of the path.
|
---|
| 1625 | *
|
---|
| 1626 | * @returns IPRT status code.
|
---|
| 1627 | * @param pszPath The path.
|
---|
| 1628 | * @param fUnlink Unlink flags, RTPATHUNLINK_FLAGS_*.
|
---|
| 1629 | */
|
---|
| 1630 | RTR3DECL(int) RTPathUnlink(const char *pszPath, uint32_t fUnlink);
|
---|
| 1631 |
|
---|
[44278] | 1632 | /**
|
---|
| 1633 | * A /bin/rm tool.
|
---|
| 1634 | *
|
---|
| 1635 | * @returns Program exit code.
|
---|
| 1636 | *
|
---|
| 1637 | * @param cArgs The number of arguments.
|
---|
| 1638 | * @param papszArgs The argument vector. (Note that this may be
|
---|
| 1639 | * reordered, so the memory must be writable.)
|
---|
| 1640 | */
|
---|
| 1641 | RTDECL(RTEXITCODE) RTPathRmCmd(unsigned cArgs, char **papszArgs);
|
---|
| 1642 |
|
---|
[74460] | 1643 | # ifdef RT_OS_WINDOWS
|
---|
| 1644 |
|
---|
| 1645 | /**
|
---|
| 1646 | * Converts the given UTF-8 path into a native windows path.
|
---|
| 1647 | *
|
---|
| 1648 | * @returns IPRT status code.
|
---|
| 1649 | * @param ppwszPath Where to return the path. This will always be
|
---|
| 1650 | * set to NULL on failure. Use RTPathWinFree to
|
---|
| 1651 | * free it when done.
|
---|
| 1652 | * @param pszPath The UTF-8 path to convert.
|
---|
| 1653 | * @param fFlags MBZ, reserved for future hacks.
|
---|
| 1654 | * @sa RTPathWinFree, RTNtPathFromWinUtf8, RTNtPathRelativeFromUtf8.
|
---|
| 1655 | */
|
---|
| 1656 | RTDECL(int) RTPathWinFromUtf8(PRTUTF16 *ppwszPath, const char *pszPath, uint32_t fFlags);
|
---|
| 1657 |
|
---|
| 1658 | /**
|
---|
| 1659 | * Frees a native windows path returned by RTPathWinFromUtf8
|
---|
| 1660 | *
|
---|
| 1661 | * @param pwszPath The path to free. NULL is ignored.
|
---|
| 1662 | */
|
---|
| 1663 | RTDECL(void) RTPathWinFree(PRTUTF16 pwszPath);
|
---|
| 1664 |
|
---|
| 1665 | # endif /* RT_OS_WINDOWS */
|
---|
| 1666 |
|
---|
[1] | 1667 | #endif /* IN_RING3 */
|
---|
| 1668 |
|
---|
| 1669 | /** @} */
|
---|
| 1670 |
|
---|
[20374] | 1671 | RT_C_DECLS_END
|
---|
[1] | 1672 |
|
---|
[76585] | 1673 | #endif /* !IPRT_INCLUDED_path_h */
|
---|
[1] | 1674 |
|
---|