2 * IPRT - Path Manipulation.
6 * Copyright (C) 2006-2017 Oracle Corporation
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
26 #ifndef ___iprt_path_h
27 #define ___iprt_path_h
29 #include <iprt/cdefs.h>
30 #include <iprt/types.h>
39 /** @defgroup grp_rt_path RTPath - Path Manipulation
45 * Host max path (the reasonable value).
46 * @remarks defined both by iprt/param.h and iprt/path.h.
48 #if !defined(___iprt_param_h) || defined(DOXYGEN_RUNNING)
49 # define RTPATH_MAX (4096 + 4) /* (PATH_MAX + 1) on linux w/ some alignment */
53 * The default allocation tag used by the RTPath allocation APIs.
55 * When not defined before the inclusion of iprt/string.h, this will default to
56 * the pointer to the current file name. The string API will make of use of
57 * this as pointer to a volatile but read-only string.
60 # define RTPATH_TAG (__FILE__)
64 /** @name RTPATH_F_XXX - Generic flags for APIs working on the file system.
66 /** Last component: Work on the link. */
67 #define RTPATH_F_ON_LINK RT_BIT_32(0)
68 /** Last component: Follow if link. */
69 #define RTPATH_F_FOLLOW_LINK RT_BIT_32(1)
70 /** Don't allow symbolic links as part of the path.
71 * @remarks this flag is currently not implemented and will be ignored. */
72 #define RTPATH_F_NO_SYMLINKS RT_BIT_32(2)
75 /** Validates a flags parameter containing RTPATH_F_*.
76 * @remarks The parameters will be referenced multiple times. */
77 #define RTPATH_F_IS_VALID(a_fFlags, a_fIgnore) \
78 ( ((a_fFlags) & ~(uint32_t)((a_fIgnore) | RTPATH_F_NO_SYMLINKS)) == RTPATH_F_ON_LINK \
79 || ((a_fFlags) & ~(uint32_t)((a_fIgnore) | RTPATH_F_NO_SYMLINKS)) == RTPATH_F_FOLLOW_LINK )
82 /** @name RTPATH_STR_F_XXX - Generic flags for APIs working with path strings.
85 /** Host OS path style (default 0 value). */
86 #define RTPATH_STR_F_STYLE_HOST UINT32_C(0x00000000)
87 /** DOS, OS/2 and Windows path style. */
88 #define RTPATH_STR_F_STYLE_DOS UINT32_C(0x00000001)
89 /** Unix path style. */
90 #define RTPATH_STR_F_STYLE_UNIX UINT32_C(0x00000002)
91 /** Reserved path style. */
92 #define RTPATH_STR_F_STYLE_RESERVED UINT32_C(0x00000003)
93 /** The path style mask. */
94 #define RTPATH_STR_F_STYLE_MASK UINT32_C(0x00000003)
95 /** Partial path - no start.
96 * This causes the API to skip the root specification parsing. */
97 #define RTPATH_STR_F_NO_START UINT32_C(0x00000010)
98 /** Partial path - no end.
99 * This causes the API to skip the filename and dir-slash parsing. */
100 #define RTPATH_STR_F_NO_END UINT32_C(0x00000020)
101 /** Partial path - no start and no end. */
102 #define RTPATH_STR_F_MIDDLE (RTPATH_STR_F_NO_START | RTPATH_STR_F_NO_END)
104 /** Reserved for future use. */
105 #define RTPATH_STR_F_RESERVED_MASK UINT32_C(0x0000ffcc)
108 /** Validates a flags parameter containing RTPATH_FSTR_.
109 * @remarks The parameters will be references multiple times. */
110 #define RTPATH_STR_F_IS_VALID(a_fFlags, a_fIgnore) \
111 ( ((a_fFlags) & ~((uint32_t)(a_fIgnore) | RTPATH_STR_F_STYLE_MASK | RTPATH_STR_F_MIDDLE)) == 0 \
112 && ((a_fFlags) & RTPATH_STR_F_STYLE_MASK) != RTPATH_STR_F_STYLE_RESERVED \
113 && ((a_fFlags) & RTPATH_STR_F_RESERVED_MASK) == 0 )
116 /** @def RTPATH_STYLE
117 * The host path style. This is set to RTPATH_STR_F_STYLE_DOS,
118 * RTPATH_STR_F_STYLE_UNIX, or other future styles. */
119 #if defined(RT_OS_OS2) || defined(RT_OS_WINDOWS)
120 # define RTPATH_STYLE RTPATH_STR_F_STYLE_DOS
122 # define RTPATH_STYLE RTPATH_STR_F_STYLE_UNIX
126 /** @def RTPATH_SLASH
127 * The preferred slash character.
129 * @remark IPRT will always accept unix slashes. So, normally you would
130 * never have to use this define.
132 #if RTPATH_STYLE == RTPATH_STR_F_STYLE_DOS
133 # define RTPATH_SLASH '\\'
134 #elif RTPATH_STYLE == RTPATH_STR_F_STYLE_UNIX
135 # define RTPATH_SLASH '/'
137 # error "Unsupported RTPATH_STYLE value."
140 /** @deprecated Use '/'! */
141 #define RTPATH_DELIMITER RTPATH_SLASH
144 /** @def RTPATH_SLASH_STR
145 * The preferred slash character as a string, handy for concatenations
146 * with other strings.
148 * @remark IPRT will always accept unix slashes. So, normally you would
149 * never have to use this define.
151 #if RTPATH_STYLE == RTPATH_STR_F_STYLE_DOS
152 # define RTPATH_SLASH_STR "\\"
153 #elif RTPATH_STYLE == RTPATH_STR_F_STYLE_UNIX
154 # define RTPATH_SLASH_STR "/"
156 # error "Unsupported RTPATH_STYLE value."
160 /** @def RTPATH_IS_SLASH
161 * Checks if a character is a slash.
163 * @returns true if it's a slash and false if not.
164 * @returns @param a_ch Char to check.
166 #if RTPATH_STYLE == RTPATH_STR_F_STYLE_DOS
167 # define RTPATH_IS_SLASH(a_ch) ( (a_ch) == '\\' || (a_ch) == '/' )
168 #elif RTPATH_STYLE == RTPATH_STR_F_STYLE_UNIX
169 # define RTPATH_IS_SLASH(a_ch) ( (a_ch) == '/' )
171 # error "Unsupported RTPATH_STYLE value."
175 /** @def RTPATH_IS_VOLSEP
176 * Checks if a character marks the end of the volume specification.
178 * @remark This is sufficient for the drive letter concept on PC.
179 * However it might be insufficient on other platforms
180 * and even on PC a UNC volume spec won't be detected this way.
181 * Use the RTPath@<too be created@>() instead.
183 * @returns true if it is and false if it isn't.
184 * @returns @param a_ch Char to check.
186 #if RTPATH_STYLE == RTPATH_STR_F_STYLE_DOS
187 # define RTPATH_IS_VOLSEP(a_ch) ( (a_ch) == ':' )
188 #elif RTPATH_STYLE == RTPATH_STR_F_STYLE_UNIX
189 # define RTPATH_IS_VOLSEP(a_ch) (false)
191 # error "Unsupported RTPATH_STYLE value."
195 /** @def RTPATH_IS_SEP
196 * Checks if a character is path component separator
198 * @returns true if it is and false if it isn't.
199 * @returns @param a_ch Char to check.
202 #define RTPATH_IS_SEP(a_ch) ( RTPATH_IS_SLASH(a_ch) || RTPATH_IS_VOLSEP(a_ch) )
206 * Checks if the path exists.
208 * Symbolic links will all be attempted resolved and broken links means false.
210 * @returns true if it exists and false if it doesn't.
211 * @param pszPath The path to check.
213 RTDECL(bool) RTPathExists(const char *pszPath
);
216 * Checks if the path exists.
218 * @returns true if it exists and false if it doesn't.
219 * @param pszPath The path to check.
220 * @param fFlags RTPATH_F_ON_LINK or RTPATH_F_FOLLOW_LINK.
222 RTDECL(bool) RTPathExistsEx(const char *pszPath
, uint32_t fFlags
);
225 * Sets the current working directory of the process.
227 * @returns IPRT status code.
228 * @param pszPath The path to the new working directory.
230 RTDECL(int) RTPathSetCurrent(const char *pszPath
);
233 * Gets the current working directory of the process.
235 * @returns IPRT status code.
236 * @param pszPath Where to store the path.
237 * @param cchPath The size of the buffer pszPath points to.
239 RTDECL(int) RTPathGetCurrent(char *pszPath
, size_t cchPath
);
242 * Gets the current working directory on the specified drive.
244 * On systems without drive letters, the root slash will be returned.
246 * @returns IPRT status code.
247 * @param chDrive The drive we're querying the driver letter on.
248 * @param pszPath Where to store the working directroy path.
249 * @param cbPath The size of the buffer pszPath points to.
251 RTDECL(int) RTPathGetCurrentOnDrive(char chDrive
, char *pszPath
, size_t cbPath
);
254 * Gets the current working drive of the process.
256 * Normally drive letter and colon will be returned, never trailing a root
257 * slash. If the current directory is on a UNC share, the root of the share
258 * will be returned. On systems without drive letters, an empty string is
259 * returned for consistency.
261 * @returns IPRT status code.
262 * @param pszPath Where to store the working drive or UNC root.
263 * @param cbPath The size of the buffer pszPath points to.
265 RTDECL(int) RTPathGetCurrentDrive(char *pszPath
, size_t cbPath
);
268 * Get the real path (no symlinks, no . or .. components), must exist.
270 * @returns iprt status code.
271 * @param pszPath The path to resolve.
272 * @param pszRealPath Where to store the real path.
273 * @param cchRealPath Size of the buffer.
275 RTDECL(int) RTPathReal(const char *pszPath
, char *pszRealPath
, size_t cchRealPath
);
278 * Same as RTPathReal only the result is RTStrDup()'ed.
280 * @returns Pointer to real path. Use RTStrFree() to free this string.
281 * @returns NULL if RTPathReal() or RTStrDup() fails.
282 * @param pszPath The path to resolve.
284 RTDECL(char *) RTPathRealDup(const char *pszPath
);
287 * Get the absolute path (starts from root, no . or .. components), doesn't have
288 * to exist. Note that this method is designed to never perform actual file
289 * system access, therefore symlinks are not resolved.
291 * @returns iprt status code.
292 * @param pszPath The path to resolve.
293 * @param pszAbsPath Where to store the absolute path.
294 * @param cchAbsPath Size of the buffer.
296 RTDECL(int) RTPathAbs(const char *pszPath
, char *pszAbsPath
, size_t cchAbsPath
);
299 * Same as RTPathAbs only the result is RTStrDup()'ed.
301 * @returns Pointer to the absolute path. Use RTStrFree() to free this string.
302 * @returns NULL if RTPathAbs() or RTStrDup() fails.
303 * @param pszPath The path to resolve.
305 RTDECL(char *) RTPathAbsDup(const char *pszPath
);
308 * Get the absolute path (no symlinks, no . or .. components), assuming the
309 * given base path as the current directory. The resulting path doesn't have
312 * @returns iprt status code.
313 * @param pszBase The base path to act like a current directory.
314 * When NULL, the actual cwd is used (i.e. the call
315 * is equivalent to RTPathAbs(pszPath, ...).
316 * @param pszPath The path to resolve.
317 * @param pszAbsPath Where to store the absolute path.
318 * @param cchAbsPath Size of the buffer.
320 RTDECL(int) RTPathAbsEx(const char *pszBase
, const char *pszPath
, char *pszAbsPath
, size_t cchAbsPath
);
323 * Same as RTPathAbsEx only the result is RTStrDup()'ed.
325 * @returns Pointer to the absolute path. Use RTStrFree() to free this string.
326 * @returns NULL if RTPathAbsEx() or RTStrDup() fails.
327 * @param pszBase The base path to act like a current directory.
328 * When NULL, the actual cwd is used (i.e. the call
329 * is equivalent to RTPathAbs(pszPath, ...).
330 * @param pszPath The path to resolve.
332 RTDECL(char *) RTPathAbsExDup(const char *pszBase
, const char *pszPath
);
335 * Strips the filename from a path. Truncates the given string in-place by overwriting the
336 * last path separator character with a null byte in a platform-neutral way.
338 * @param pszPath Path from which filename should be extracted, will be truncated.
339 * If the string contains no path separator, it will be changed to a "." string.
341 RTDECL(void) RTPathStripFilename(char *pszPath
);
344 * Strips the last suffix from a path.
346 * @param pszPath Path which suffix should be stripped.
348 RTDECL(void) RTPathStripSuffix(char *pszPath
);
351 * Strips the trailing slashes of a path name.
353 * Won't strip root slashes.
355 * @returns The new length of pszPath.
356 * @param pszPath Path to strip.
358 RTDECL(size_t) RTPathStripTrailingSlash(char *pszPath
);
361 * Skips the root specification, if present.
363 * @return Pointer to the first char after the root specification. This can be
364 * pointing to the terminator, if the path is only a root
366 * @param pszPath The path to skip ahead in.
368 RTDECL(char *) RTPathSkipRootSpec(const char *pszPath
);
371 * Ensures that the path has a trailing path separator such that file names can
372 * be appended without further work.
374 * This can be helpful when preparing for efficiently combining a directory path
375 * with the filenames returned by RTDirRead. The return value gives you the
376 * position at which you copy the RTDIRENTRY::szName to construct a valid path
379 * @returns The length of the path, 0 on buffer overflow.
380 * @param pszPath The path.
381 * @param cbPath The length of the path buffer @a pszPath points to.
383 RTDECL(size_t) RTPathEnsureTrailingSeparator(char *pszPath
, size_t cbPath
);
386 * Changes all the slashes in the specified path to DOS style.
388 * Unless @a fForce is set, nothing will be done when on a UNIX flavored system
389 * since paths wont work with DOS style slashes there.
391 * @returns @a pszPath.
392 * @param pszPath The path to modify.
393 * @param fForce Whether to force the conversion on non-DOS OSes.
395 RTDECL(char *) RTPathChangeToDosSlashes(char *pszPath
, bool fForce
);
398 * Changes all the slashes in the specified path to unix style.
400 * Unless @a fForce is set, nothing will be done when on a UNIX flavored system
401 * since paths wont work with DOS style slashes there.
403 * @returns @a pszPath.
404 * @param pszPath The path to modify.
405 * @param fForce Whether to force the conversion on non-DOS OSes.
407 RTDECL(char *) RTPathChangeToUnixSlashes(char *pszPath
, bool fForce
);
410 * Simple parsing of the a path.
412 * It figures the length of the directory component, the offset of
413 * the file name and the location of the suffix dot.
415 * @returns The path length.
417 * @param pszPath Path to find filename in.
418 * @param pcchDir Where to put the length of the directory component. If
419 * no directory, this will be 0. Optional.
420 * @param poffName Where to store the filename offset.
421 * If empty string or if it's ending with a slash this
422 * will be set to -1. Optional.
423 * @param poffSuff Where to store the suffix offset (the last dot).
424 * If empty string or if it's ending with a slash this
425 * will be set to -1. Optional.
427 RTDECL(size_t) RTPathParseSimple(const char *pszPath
, size_t *pcchDir
, ssize_t
*poffName
, ssize_t
*poffSuff
);
430 * Finds the filename in a path.
432 * @returns Pointer to filename within pszPath.
433 * @returns NULL if no filename (i.e. empty string or ends with a slash).
434 * @param pszPath Path to find filename in.
436 RTDECL(char *) RTPathFilename(const char *pszPath
);
439 * Finds the filename in a path, extended version.
441 * @returns Pointer to filename within pszPath.
442 * @returns NULL if no filename (i.e. empty string or ends with a slash).
443 * @param pszPath Path to find filename in.
444 * @param fFlags RTPATH_STR_F_STYLE_XXX. Other RTPATH_STR_F_XXX flags
447 RTDECL(char *) RTPathFilenameEx(const char *pszPath
, uint32_t fFlags
);
450 * Finds the suffix part of in a path (last dot and onwards).
452 * @returns Pointer to suffix within pszPath.
453 * @returns NULL if no suffix
454 * @param pszPath Path to find suffix in.
456 * @remarks IPRT terminology: A suffix includes the dot, the extension starts
457 * after the dot. For instance suffix '.txt' and extension 'txt'.
459 RTDECL(char *) RTPathSuffix(const char *pszPath
);
462 * Checks if a path has an extension / suffix.
464 * @returns true if extension / suffix present.
465 * @returns false if no extension / suffix.
466 * @param pszPath Path to check.
468 RTDECL(bool) RTPathHasSuffix(const char *pszPath
);
469 /** Same thing, different name. */
470 #define RTPathHasExt RTPathHasSuffix
473 * Checks if a path includes more than a filename.
475 * @returns true if path present.
476 * @returns false if no path.
477 * @param pszPath Path to check.
479 RTDECL(bool) RTPathHasPath(const char *pszPath
);
480 /** Misspelled, don't use. */
481 #define RTPathHavePath RTPathHasPath
484 * Checks if the path starts with a root specifier or not.
486 * @returns @c true if it starts with root, @c false if not.
488 * @param pszPath Path to check.
490 RTDECL(bool) RTPathStartsWithRoot(const char *pszPath
);
495 * Counts the components in the specified path.
497 * An empty string has zero components. A lone root slash is considered have
498 * one. The paths "/init" and "/bin/" are considered having two components. An
499 * UNC share specifier like "\\myserver\share" will be considered as one single
502 * @returns The number of path components.
503 * @param pszPath The path to parse.
505 RTDECL(size_t) RTPathCountComponents(const char *pszPath
);
508 * Copies the specified number of path components from @a pszSrc and into @a
511 * @returns VINF_SUCCESS or VERR_BUFFER_OVERFLOW. In the latter case the buffer
514 * @param pszDst The destination buffer.
515 * @param cbDst The size of the destination buffer.
516 * @param pszSrc The source path.
517 * @param cComponents The number of components to copy from @a pszSrc.
519 RTDECL(int) RTPathCopyComponents(char *pszDst
, size_t cbDst
, const char *pszSrc
, size_t cComponents
);
521 /** @name Path properties returned by RTPathParse and RTPathSplit.
524 /** Indicates that there is a filename.
525 * If not set, either a lone root spec was given (RTPATH_PROP_UNC,
526 * RTPATH_PROP_ROOT_SLASH, or RTPATH_PROP_VOLUME) or the final component had a
527 * trailing slash (RTPATH_PROP_DIR_SLASH). */
528 #define RTPATH_PROP_FILENAME UINT16_C(0x0001)
529 /** Indicates that a directory was specified using a trailing slash.
530 * @note This is not set for lone root specifications (RTPATH_PROP_UNC,
531 * RTPATH_PROP_ROOT_SLASH, or RTPATH_PROP_VOLUME).
532 * @note The slash is not counted into the last component. However, it is
533 * counted into cchPath. */
534 #define RTPATH_PROP_DIR_SLASH UINT16_C(0x0002)
536 /** The filename has a suffix (extension). */
537 #define RTPATH_PROP_SUFFIX UINT16_C(0x0004)
538 /** Indicates that this is an UNC path (Windows and OS/2 only).
540 * UNC = Universal Naming Convention. It is on the form '//Computer/',
541 * '//Namespace/', '//ComputerName/Resource' and '//Namespace/Resource'.
542 * RTPathParse, RTPathSplit and friends does not consider the 'Resource' as
543 * part of the UNC root specifier. Thus the root specs for the above examples
544 * would be '//ComputerName/' or '//Namespace/'.
546 * Please note that '//something' is not a UNC path, there must be a slash
547 * following the computer or namespace.
549 #define RTPATH_PROP_UNC UINT16_C(0x0010)
550 /** A root slash was specified (unix style root).
551 * (While the path must relative if not set, this being set doesn't make it
554 * This will be set in the following examples: '/', '/bin', 'C:/', 'C:/Windows',
555 * '//./', '//./PhysicalDisk0', '//example.org/', and '//example.org/share'.
557 * It will not be set for the following examples: '.', 'bin/ls', 'C:', and
560 #define RTPATH_PROP_ROOT_SLASH UINT16_C(0x0020)
561 /** A volume is specified (Windows, DOS and OS/2).
562 * For examples: 'C:', 'C:/', and 'A:/AutoExec.bat'. */
563 #define RTPATH_PROP_VOLUME UINT16_C(0x0040)
564 /** The path is absolute, i.e. has a root specifier (root-slash,
565 * volume or UNC) and contains no winding '..' bits, though it may contain
566 * unnecessary slashes (RTPATH_PROP_EXTRA_SLASHES) and '.' components
567 * (RTPATH_PROP_DOT_REFS).
569 * On systems without volumes and UNC (unix style) it will be set for '/',
570 * '/bin/ls', and '/bin//./ls', but not for 'bin/ls', /bin/../usr/bin/env',
571 * '/./bin/ls' or '/.'.
573 * On systems with volumes, it will be set for 'C:/', C:/Windows', and
574 * 'C:/./Windows//', but not for 'C:', 'C:Windows', or 'C:/Windows/../boot.ini'.
576 * On systems with UNC paths, it will be set for '//localhost/',
577 * '//localhost/C$', '//localhost/C$/Windows/System32', '//localhost/.', and
578 * '//localhost/C$//./AutoExec.bat', but not for
579 * '//localhost/C$/Windows/../AutoExec.bat'.
581 * @note For the RTPathAbs definition, this flag needs to be set while both
582 * RTPATH_PROP_EXTRA_SLASHES and RTPATH_PROP_DOT_REFS must be cleared.
584 #define RTPATH_PROP_ABSOLUTE UINT16_C(0x0100)
585 /** Relative path. Inverse of RTPATH_PROP_ABSOLUTE. */
586 #define RTPATH_PROP_RELATIVE UINT16_C(0x0200)
587 /** The path contains unnecessary slashes. Meaning, that if */
588 #define RTPATH_PROP_EXTRA_SLASHES UINT16_C(0x0400)
589 /** The path contains references to the special '.' (dot) directory link. */
590 #define RTPATH_PROP_DOT_REFS UINT16_C(0x0800)
591 /** The path contains references to the special '..' (dot) directory link.
592 * RTPATH_PROP_RELATIVE will always be set together with this. */
593 #define RTPATH_PROP_DOTDOT_REFS UINT16_C(0x1000)
596 /** Macro to determin whether to insert a slash after the first component when
597 * joining it with something else.
598 * (All other components in a split or parsed path requies slashes added.) */
599 #define RTPATH_PROP_FIRST_NEEDS_NO_SLASH(a_fProps) \
600 RT_BOOL( (a_fProps) & (RTPATH_PROP_ROOT_SLASH | RTPATH_PROP_VOLUME | RTPATH_PROP_UNC) )
602 /** Macro to determin whether there is a root specification of any kind
603 * (unix, volumes, unc). */
604 #define RTPATH_PROP_HAS_ROOT_SPEC(a_fProps) \
605 RT_BOOL( (a_fProps) & (RTPATH_PROP_ROOT_SLASH | RTPATH_PROP_VOLUME | RTPATH_PROP_UNC) )
613 * The first component is the root, volume or UNC specifier, if present. Use
614 * RTPATH_PROP_HAS_ROOT_SPEC() on RTPATHPARSED::fProps to determine its
617 * Other than the root component, no component will include directory separators
620 typedef struct RTPATHPARSED
622 /** Number of path components.
623 * This will always be set on VERR_BUFFER_OVERFLOW returns from RTPathParsed
624 * so the caller can calculate the required buffer size. */
626 /** Path property flags, RTPATH_PROP_XXX */
628 /** On success this is the length of the described path, i.e. sum of all
629 * component lengths and necessary separators.
630 * Do NOT use this to index in the source path in case it contains
631 * unnecessary slashes that RTPathParsed has ignored here. */
633 /** Reserved for future use. */
634 uint16_t u16Reserved
;
635 /** The offset of the filename suffix, offset of the NUL char if none. */
637 /** The lenght of the suffix. */
639 /** Array of component descriptors (variable size).
640 * @note Don't try figure the end of the input path by adding up off and cch
641 * of the last component. If RTPATH_PROP_DIR_SLASH is set, there may
642 * be one or more trailing slashes that are unaccounted for! */
645 /** The offset of the component. */
647 /** The length of the component. */
651 /** Pointer to to a parsed path result. */
652 typedef RTPATHPARSED
*PRTPATHPARSED
;
653 /** Pointer to to a const parsed path result. */
654 typedef RTPATHPARSED
*PCRTPATHPARSED
;
660 * @returns IPRT status code.
661 * @retval VERR_INVALID_POINTER if pParsed or pszPath is an invalid pointer.
662 * @retval VERR_INVALID_PARAMETER if cbOutput is less than the RTPATHPARSED
663 * strucuture. No output. (asserted)
664 * @retval VERR_BUFFER_OVERFLOW there are more components in the path than
665 * there is space in aComps. The required amount of space can be
666 * determined from the pParsed->cComps:
668 * RT_OFFSETOF(RTPATHPARSED, aComps[pParsed->cComps])
670 * @retval VERR_PATH_ZERO_LENGTH if the path is empty.
672 * @param pszPath The path to parse.
673 * @param pParsed Where to store the details of the parsed path.
674 * @param cbParsed The size of the buffer. Must be at least the
675 * size of RTPATHPARSED.
676 * @param fFlags Combination of RTPATH_STR_F_XXX flags.
677 * Most users will pass 0.
678 * @sa RTPathSplit, RTPathSplitA.
680 RTDECL(int) RTPathParse(const char *pszPath
, PRTPATHPARSED pParsed
, size_t cbParsed
, uint32_t fFlags
);
683 * Reassembles a path parsed by RTPathParse.
685 * This will be more useful as more APIs manipulating the RTPATHPARSED output
688 * @returns IPRT status code.
689 * @retval VERR_BUFFER_OVERFLOW if @a cbDstPath is less than or equal to
690 * RTPATHPARSED::cchPath.
692 * @param pszSrcPath The source path.
693 * @param pParsed The parser output for @a pszSrcPath.
694 * @param fFlags Combination of RTPATH_STR_F_STYLE_XXX.
695 * Most users will pass 0.
696 * @param pszDstPath Pointer to the buffer where the path is to be
698 * @param cbDstPath The size of the output buffer.
700 RTDECL(int) RTPathParsedReassemble(const char *pszSrcPath
, PRTPATHPARSED pParsed
, uint32_t fFlags
,
701 char *pszDstPath
, size_t cbDstPath
);
705 * Output buffer for RTPathSplit and RTPathSplitA.
707 typedef struct RTPATHSPLIT
709 /** Number of path components.
710 * This will always be set on VERR_BUFFER_OVERFLOW returns from RTPathParsed
711 * so the caller can calculate the required buffer size. */
713 /** Path property flags, RTPATH_PROP_XXX */
715 /** On success this is the length of the described path, i.e. sum of all
716 * component lengths and necessary separators.
717 * Do NOT use this to index in the source path in case it contains
718 * unnecessary slashes that RTPathSplit has ignored here. */
720 /** Reserved (internal use). */
721 uint16_t u16Reserved
;
722 /** The amount of memory used (on success) or required (on
723 * VERR_BUFFER_OVERFLOW) of this structure and it's strings. */
725 /** Pointer to the filename suffix (the dot), if any. Points to the NUL
726 * character of the last component if none or if RTPATH_PROP_DIR_SLASH is
728 const char *pszSuffix
;
729 /** Array of component strings (variable size). */
732 /** Pointer to a split path buffer. */
733 typedef RTPATHSPLIT
*PRTPATHSPLIT
;
734 /** Pointer to a const split path buffer. */
735 typedef RTPATHSPLIT
const *PCRTPATHSPLIT
;
738 * Splits the path into individual component strings, carved from user supplied
739 * the given buffer block.
741 * @returns IPRT status code.
742 * @retval VERR_INVALID_POINTER if pParsed or pszPath is an invalid pointer.
743 * @retval VERR_INVALID_PARAMETER if cbOutput is less than the RTPATHSPLIT
744 * strucuture. No output. (asserted)
745 * @retval VERR_BUFFER_OVERFLOW there are more components in the path than
746 * there is space in aComps. The required amount of space can be
747 * determined from the pParsed->cComps:
749 * RT_OFFSETOF(RTPATHPARSED, aComps[pParsed->cComps])
751 * @retval VERR_PATH_ZERO_LENGTH if the path is empty.
752 * @retval VERR_FILENAME_TOO_LONG if the filename is too long (close to 64 KB).
754 * @param pszPath The path to parse.
755 * @param pSplit Where to store the details of the parsed path.
756 * @param cbSplit The size of the buffer pointed to by @a pSplit
757 * (variable sized array at the end). Must be at
758 * least the size of RTPATHSPLIT.
759 * @param fFlags Combination of RTPATH_STR_F_XXX flags.
760 * Most users will pass 0.
762 * @sa RTPathSplitA, RTPathParse.
764 RTDECL(int) RTPathSplit(const char *pszPath
, PRTPATHSPLIT pSplit
, size_t cbSplit
, uint32_t fFlags
);
767 * Splits the path into individual component strings, allocating the buffer on
768 * the default thread heap.
770 * @returns IPRT status code.
771 * @retval VERR_INVALID_POINTER if pParsed or pszPath is an invalid pointer.
772 * @retval VERR_PATH_ZERO_LENGTH if the path is empty.
774 * @param pszPath The path to parse.
775 * @param ppSplit Where to return the pointer to the output on
776 * success. This must be freed by calling
778 * @param fFlags Combination of RTPATH_STR_F_XXX flags.
779 * Most users will pass 0.
780 * @sa RTPathSplitFree, RTPathSplit, RTPathParse.
782 #define RTPathSplitA(pszPath, ppSplit, fFlags) RTPathSplitATag(pszPath, ppSplit, fFlags, RTPATH_TAG)
785 * Splits the path into individual component strings, allocating the buffer on
786 * the default thread heap.
788 * @returns IPRT status code.
789 * @retval VERR_INVALID_POINTER if pParsed or pszPath is an invalid pointer.
790 * @retval VERR_PATH_ZERO_LENGTH if the path is empty.
792 * @param pszPath The path to parse.
793 * @param ppSplit Where to return the pointer to the output on
794 * success. This must be freed by calling
796 * @param fFlags Combination of RTPATH_STR_F_XXX flags.
797 * Most users will pass 0.
798 * @param pszTag Allocation tag used for statistics and such.
799 * @sa RTPathSplitFree, RTPathSplit, RTPathParse.
801 RTDECL(int) RTPathSplitATag(const char *pszPath
, PRTPATHSPLIT
*ppSplit
, uint32_t fFlags
, const char *pszTag
);
804 * Frees buffer returned by RTPathSplitA.
806 * @param pSplit What RTPathSplitA returned.
809 RTDECL(void) RTPathSplitFree(PRTPATHSPLIT pSplit
);
812 * Reassembles a path parsed by RTPathSplit.
814 * This will be more useful as more APIs manipulating the RTPATHSPLIT output are
817 * @returns IPRT status code.
818 * @retval VERR_BUFFER_OVERFLOW if @a cbDstPath is less than or equal to
819 * RTPATHSPLIT::cchPath.
821 * @param pSplit A split path (see RTPathSplit, RTPathSplitA).
822 * @param fFlags Combination of RTPATH_STR_F_STYLE_XXX.
823 * Most users will pass 0.
824 * @param pszDstPath Pointer to the buffer where the path is to be
826 * @param cbDstPath The size of the output buffer.
828 RTDECL(int) RTPathSplitReassemble(PRTPATHSPLIT pSplit
, uint32_t fFlags
, char *pszDstPath
, size_t cbDstPath
);
831 * Checks if the two paths leads to the file system object.
833 * If the objects exist, we'll query attributes for them. If that's not
834 * conclusive (some OSes) or one of them doesn't exist, we'll use a combination
835 * of RTPathAbs and RTPathCompare to determine the result.
837 * @returns true, false, or VERR_FILENAME_TOO_LONG.
838 * @param pszPath1 The first path.
839 * @param pszPath2 The seoncd path.
841 RTDECL(int) RTPathIsSame(const char *pszPath1
, const char *pszPath2
);
845 * Compares two paths.
847 * The comparison takes platform-dependent details into account,
850 * <li>On DOS-like platforms, both separator chars (|\| and |/|) are considered
852 * <li>On platforms with case-insensitive file systems, mismatching characters
853 * are uppercased and compared again.
856 * @returns @< 0 if the first path less than the second path.
857 * @returns 0 if the first path identical to the second path.
858 * @returns @> 0 if the first path greater than the second path.
860 * @param pszPath1 Path to compare (must be an absolute path).
861 * @param pszPath2 Path to compare (must be an absolute path).
863 * @remarks File system details are currently ignored. This means that you won't
864 * get case-insensitive compares on unix systems when a path goes into a
865 * case-insensitive filesystem like FAT, HPFS, HFS, NTFS, JFS, or
866 * similar. For NT, OS/2 and similar you'll won't get case-sensitive
867 * compares on a case-sensitive file system.
869 RTDECL(int) RTPathCompare(const char *pszPath1
, const char *pszPath2
);
872 * Checks if a path starts with the given parent path.
874 * This means that either the path and the parent path matches completely, or
875 * that the path is to some file or directory residing in the tree given by the
878 * The path comparison takes platform-dependent details into account,
879 * see RTPathCompare() for details.
881 * @returns |true| when \a pszPath starts with \a pszParentPath (or when they
882 * are identical), or |false| otherwise.
884 * @param pszPath Path to check, must be an absolute path.
885 * @param pszParentPath Parent path, must be an absolute path.
886 * No trailing directory slash!
888 * @remarks This API doesn't currently handle root directory compares in a
889 * manner consistent with the other APIs. RTPathStartsWith(pszSomePath,
890 * "/") will not work if pszSomePath isn't "/".
892 RTDECL(bool) RTPathStartsWith(const char *pszPath
, const char *pszParentPath
);
895 * Appends one partial path to another.
897 * The main purpose of this function is to deal correctly with the slashes when
898 * concatenating the two partial paths.
900 * @retval VINF_SUCCESS on success.
901 * @retval VERR_BUFFER_OVERFLOW if the result is too big to fit within
902 * cbPathDst bytes. No changes has been made.
903 * @retval VERR_INVALID_PARAMETER if the string pointed to by pszPath is longer
904 * than cbPathDst-1 bytes (failed to find terminator). Asserted.
906 * @param pszPath The path to append pszAppend to. This serves as both
907 * input and output. This can be empty, in which case
908 * pszAppend is just copied over.
909 * @param cbPathDst The size of the buffer pszPath points to, terminator
910 * included. This should NOT be strlen(pszPath).
911 * @param pszAppend The partial path to append to pszPath. This can be
912 * NULL, in which case nothing is done.
914 * @remarks See the RTPathAppendEx remarks.
916 RTDECL(int) RTPathAppend(char *pszPath
, size_t cbPathDst
, const char *pszAppend
);
919 * Appends one partial path to another.
921 * The main purpose of this function is to deal correctly with the slashes when
922 * concatenating the two partial paths.
924 * @retval VINF_SUCCESS on success.
925 * @retval VERR_BUFFER_OVERFLOW if the result is too big to fit within
926 * cbPathDst bytes. No changes has been made.
927 * @retval VERR_INVALID_PARAMETER if the string pointed to by pszPath is longer
928 * than cbPathDst-1 bytes (failed to find terminator). Asserted.
930 * @param pszPath The path to append pszAppend to. This serves as both
931 * input and output. This can be empty, in which case
932 * pszAppend is just copied over.
933 * @param cbPathDst The size of the buffer pszPath points to, terminator
934 * included. This should NOT be strlen(pszPath).
935 * @param pszAppend The partial path to append to pszPath. This can be
936 * NULL, in which case nothing is done.
937 * @param cchAppendMax The maximum number or characters to take from @a
938 * pszAppend. RTSTR_MAX is fine.
940 * @remarks On OS/2, Window and similar systems, concatenating a drive letter
941 * specifier with a slash prefixed path will result in an absolute
942 * path. Meaning, RTPathAppend(strcpy(szBuf, "C:"), sizeof(szBuf),
943 * "/bar") will result in "C:/bar". (This follows directly from the
944 * behavior when pszPath is empty.)
946 * On the other hand, when joining a drive letter specifier with a
947 * partial path that does not start with a slash, the result is not an
948 * absolute path. Meaning, RTPathAppend(strcpy(szBuf, "C:"),
949 * sizeof(szBuf), "bar") will result in "C:bar".
951 RTDECL(int) RTPathAppendEx(char *pszPath
, size_t cbPathDst
, const char *pszAppend
, size_t cchAppendMax
);
954 * Like RTPathAppend, but with the base path as a separate argument instead of
955 * in the path buffer.
957 * @retval VINF_SUCCESS on success.
958 * @retval VERR_BUFFER_OVERFLOW if the result is too big to fit within
960 * @retval VERR_INVALID_PARAMETER if the string pointed to by pszPath is longer
961 * than cbPathDst-1 bytes (failed to find terminator). Asserted.
963 * @param pszPathDst Where to store the resulting path.
964 * @param cbPathDst The size of the buffer pszPathDst points to,
965 * terminator included.
966 * @param pszPathSrc The base path to copy into @a pszPathDst before
967 * appending @a pszAppend.
968 * @param pszAppend The partial path to append to pszPathSrc. This can
969 * be NULL, in which case nothing is done.
972 RTDECL(int) RTPathJoin(char *pszPathDst
, size_t cbPathDst
, const char *pszPathSrc
,
973 const char *pszAppend
);
976 * Same as RTPathJoin, except that the output buffer is allocated.
978 * @returns Buffer containing the joined up path, call RTStrFree to free. NULL
979 * on allocation failure.
980 * @param pszPathSrc The base path to copy into @a pszPathDst before
981 * appending @a pszAppend.
982 * @param pszAppend The partial path to append to pszPathSrc. This can
983 * be NULL, in which case nothing is done.
986 RTDECL(char *) RTPathJoinA(const char *pszPathSrc
, const char *pszAppend
);
989 * Extended version of RTPathJoin, both inputs can be specified as substrings.
991 * @retval VINF_SUCCESS on success.
992 * @retval VERR_BUFFER_OVERFLOW if the result is too big to fit within
994 * @retval VERR_INVALID_PARAMETER if the string pointed to by pszPath is longer
995 * than cbPathDst-1 bytes (failed to find terminator). Asserted.
997 * @param pszPathDst Where to store the resulting path.
998 * @param cbPathDst The size of the buffer pszPathDst points to,
999 * terminator included.
1000 * @param pszPathSrc The base path to copy into @a pszPathDst before
1001 * appending @a pszAppend.
1002 * @param cchPathSrcMax The maximum number of bytes to copy from @a
1003 * pszPathSrc. RTSTR_MAX is find.
1004 * @param pszAppend The partial path to append to pszPathSrc. This can
1005 * be NULL, in which case nothing is done.
1006 * @param cchAppendMax The maximum number of bytes to copy from @a
1007 * pszAppend. RTSTR_MAX is find.
1010 RTDECL(int) RTPathJoinEx(char *pszPathDst
, size_t cbPathDst
,
1011 const char *pszPathSrc
, size_t cchPathSrcMax
,
1012 const char *pszAppend
, size_t cchAppendMax
);
1015 * Callback for RTPathTraverseList that's called for each element.
1017 * @returns IPRT style status code. Return VERR_TRY_AGAIN to continue, any other
1018 * value will abort the traversing and be returned to the caller.
1020 * @param pchPath Pointer to the start of the current path. This is
1021 * not null terminated.
1022 * @param cchPath The length of the path.
1023 * @param pvUser1 The first user parameter.
1024 * @param pvUser2 The second user parameter.
1026 typedef DECLCALLBACK(int) FNRTPATHTRAVERSER(char const *pchPath
, size_t cchPath
, void *pvUser1
, void *pvUser2
);
1027 /** Pointer to a FNRTPATHTRAVERSER. */
1028 typedef FNRTPATHTRAVERSER
*PFNRTPATHTRAVERSER
;
1031 * Traverses a string that can contain multiple paths separated by a special
1034 * @returns IPRT style status code from the callback or VERR_END_OF_STRING if
1035 * the callback returned VERR_TRY_AGAIN for all paths in the string.
1037 * @param pszPathList The string to traverse.
1038 * @param chSep The separator character. Using the null terminator
1039 * is fine, but the result will simply be that there
1040 * will only be one callback for the entire string
1041 * (save any leading white space).
1042 * @param pfnCallback The callback.
1043 * @param pvUser1 First user argument for the callback.
1044 * @param pvUser2 Second user argument for the callback.
1046 RTDECL(int) RTPathTraverseList(const char *pszPathList
, char chSep
, PFNRTPATHTRAVERSER pfnCallback
, void *pvUser1
, void *pvUser2
);
1050 * Calculate a relative path between the two given paths.
1052 * @returns IPRT status code.
1053 * @retval VINF_SUCCESS on success.
1054 * @retval VERR_BUFFER_OVERFLOW if the result is too big to fit within
1056 * @retval VERR_NOT_SUPPORTED if both paths start with different volume specifiers.
1057 * @param pszPathDst Where to store the resulting path.
1058 * @param cbPathDst The size of the buffer pszPathDst points to,
1059 * terminator included.
1060 * @param pszPathFrom The path to start from creating the relative path.
1061 * @param pszPathTo The path to reach with the created relative path.
1063 RTDECL(int) RTPathCalcRelative(char *pszPathDst
, size_t cbPathDst
,
1064 const char *pszPathFrom
,
1065 const char *pszPathTo
);
1070 * Gets the path to the directory containing the executable.
1072 * @returns iprt status code.
1073 * @param pszPath Buffer where to store the path.
1074 * @param cchPath Buffer size in bytes.
1076 RTDECL(int) RTPathExecDir(char *pszPath
, size_t cchPath
);
1079 * Gets the user home directory.
1081 * @returns iprt status code.
1082 * @param pszPath Buffer where to store the path.
1083 * @param cchPath Buffer size in bytes.
1085 RTDECL(int) RTPathUserHome(char *pszPath
, size_t cchPath
);
1088 * Gets the user documents directory.
1090 * The returned path isn't guaranteed to exist.
1092 * @returns iprt status code.
1093 * @param pszPath Buffer where to store the path.
1094 * @param cchPath Buffer size in bytes.
1096 RTDECL(int) RTPathUserDocuments(char *pszPath
, size_t cchPath
);
1099 * Gets the directory of shared libraries.
1101 * This is not the same as RTPathAppPrivateArch() as Linux depends all shared
1102 * libraries in a common global directory where ld.so can find them.
1105 * Solaris: /opt/@<application@>/@<arch>@ or something
1106 * Windows: @<program files directory@>/@<application@>
1107 * Old path: same as RTPathExecDir()
1109 * @returns iprt status code.
1110 * @param pszPath Buffer where to store the path.
1111 * @param cchPath Buffer size in bytes.
1113 RTDECL(int) RTPathSharedLibs(char *pszPath
, size_t cchPath
);
1116 * Gets the directory for architecture-independent application data, for
1117 * example NLS files, module sources, ...
1119 * Linux: /usr/shared/@<application@>
1120 * Solaris: /opt/@<application@>
1121 * Windows: @<program files directory@>/@<application@>
1122 * Old path: same as RTPathExecDir()
1124 * @returns iprt status code.
1125 * @param pszPath Buffer where to store the path.
1126 * @param cchPath Buffer size in bytes.
1128 RTDECL(int) RTPathAppPrivateNoArch(char *pszPath
, size_t cchPath
);
1131 * Gets the directory for architecture-dependent application data, for
1132 * example modules which can be loaded at runtime.
1134 * Linux: /usr/lib/@<application@>
1135 * Solaris: /opt/@<application@>/@<arch>@ or something
1136 * Windows: @<program files directory@>/@<application@>
1137 * Old path: same as RTPathExecDir()
1139 * @returns iprt status code.
1140 * @param pszPath Buffer where to store the path.
1141 * @param cchPath Buffer size in bytes.
1143 RTDECL(int) RTPathAppPrivateArch(char *pszPath
, size_t cchPath
);
1146 * Gets the toplevel directory for architecture-dependent application data.
1148 * This differs from RTPathAppPrivateArch on Solaris only where it will work
1149 * around the /opt/@<application@>/amd64 and /opt/@<application@>/i386 multi
1150 * architecture installation style.
1152 * Linux: /usr/lib/@<application@>
1153 * Solaris: /opt/@<application@>
1154 * Windows: @<program files directory@>/@<application@>
1155 * Old path: same as RTPathExecDir()
1157 * @returns iprt status code.
1158 * @param pszPath Buffer where to store the path.
1159 * @param cchPath Buffer size in bytes.
1161 RTDECL(int) RTPathAppPrivateArchTop(char *pszPath
, size_t cchPath
);
1164 * Gets the directory for documentation.
1166 * Linux: /usr/share/doc/@<application@>
1167 * Solaris: /opt/@<application@>
1168 * Windows: @<program files directory@>/@<application@>
1169 * Old path: same as RTPathExecDir()
1171 * @returns iprt status code.
1172 * @param pszPath Buffer where to store the path.
1173 * @param cchPath Buffer size in bytes.
1175 RTDECL(int) RTPathAppDocs(char *pszPath
, size_t cchPath
);
1178 * Gets the temporary directory path.
1180 * @returns iprt status code.
1181 * @param pszPath Buffer where to store the path.
1182 * @param cchPath Buffer size in bytes.
1184 RTDECL(int) RTPathTemp(char *pszPath
, size_t cchPath
);
1188 * RTPathGlobl result entry.
1190 typedef struct RTPATHGLOBENTRY
1193 struct RTPATHGLOBENTRY
*pNext
;
1194 /** RTDIRENTRYTYPE value. */
1196 /** Unused explicit padding. */
1198 /** The length of the path. */
1200 /** The path to the file (variable length). */
1203 /** Pointer to a GLOB result entry. */
1204 typedef RTPATHGLOBENTRY
*PRTPATHGLOBENTRY
;
1205 /** Pointer to a const GLOB result entry. */
1206 typedef RTPATHGLOBENTRY
const *PCRTPATHGLOBENTRY
;
1207 /** Pointer to a GLOB result entry pointer. */
1208 typedef PCRTPATHGLOBENTRY
*PPCRTPATHGLOBENTRY
;
1211 * Performs wildcard expansion on a path pattern.
1213 * @returns IPRT status code.
1215 * @param pszPattern The pattern to expand.
1216 * @param fFlags RTPATHGLOB_F_XXX.
1217 * @param ppHead Where to return the head of the result list. This
1218 * is always set to NULL on failure.
1219 * @param pcResults Where to return the number of the result. Optional.
1221 RTDECL(int) RTPathGlob(const char *pszPattern
, uint32_t fFlags
, PPCRTPATHGLOBENTRY ppHead
, uint32_t *pcResults
);
1223 /** @name RTPATHGLOB_F_XXX - RTPathGlob flags
1225 /** Case insensitive. */
1226 #define RTPATHGLOB_F_IGNORE_CASE RT_BIT_32(0)
1227 /** Do not expand \${EnvOrSpecialVariable} in the pattern. */
1228 #define RTPATHGLOB_F_NO_VARIABLES RT_BIT_32(1)
1229 /** Do not interpret a leading tilde as a home directory reference. */
1230 #define RTPATHGLOB_F_NO_TILDE RT_BIT_32(2)
1231 /** Only return the first match. */
1232 #define RTPATHGLOB_F_FIRST_ONLY RT_BIT_32(3)
1233 /** Only match directories (implied if pattern ends with slash). */
1234 #define RTPATHGLOB_F_ONLY_DIRS RT_BIT_32(4)
1235 /** Do not match directories. (Can't be used with RTPATHGLOB_F_ONLY_DIRS or
1236 * patterns containing a trailing slash.) */
1237 #define RTPATHGLOB_F_NO_DIRS RT_BIT_32(5)
1238 /** Disables the '**' wildcard pattern for matching zero or more subdirs. */
1239 #define RTPATHGLOB_F_NO_STARSTAR RT_BIT_32(6)
1240 /** Mask of valid flags. */
1241 #define RTPATHGLOB_F_MASK UINT32_C(0x0000007f)
1245 * Frees the results produced by RTPathGlob.
1247 * @param pHead What RTPathGlob returned. NULL ignored.
1249 RTDECL(void) RTPathGlobFree(PCRTPATHGLOBENTRY pHead
);
1253 * Query information about a file system object.
1255 * This API will resolve NOT symbolic links in the last component (just like
1258 * @returns IPRT status code.
1259 * @retval VINF_SUCCESS if the object exists, information returned.
1260 * @retval VERR_PATH_NOT_FOUND if any but the last component in the specified
1261 * path was not found or was not a directory.
1262 * @retval VERR_FILE_NOT_FOUND if the object does not exist (but path to the
1263 * parent directory exists).
1265 * @param pszPath Path to the file system object.
1266 * @param pObjInfo Object information structure to be filled on successful
1268 * @param enmAdditionalAttribs
1269 * Which set of additional attributes to request.
1270 * Use RTFSOBJATTRADD_NOTHING if this doesn't matter.
1272 RTR3DECL(int) RTPathQueryInfo(const char *pszPath
, PRTFSOBJINFO pObjInfo
, RTFSOBJATTRADD enmAdditionalAttribs
);
1275 * Query information about a file system object.
1277 * @returns IPRT status code.
1278 * @retval VINF_SUCCESS if the object exists, information returned.
1279 * @retval VERR_PATH_NOT_FOUND if any but the last component in the specified
1280 * path was not found or was not a directory.
1281 * @retval VERR_FILE_NOT_FOUND if the object does not exist (but path to the
1282 * parent directory exists).
1284 * @param pszPath Path to the file system object.
1285 * @param pObjInfo Object information structure to be filled on successful return.
1286 * @param enmAdditionalAttribs
1287 * Which set of additional attributes to request.
1288 * Use RTFSOBJATTRADD_NOTHING if this doesn't matter.
1289 * @param fFlags RTPATH_F_ON_LINK or RTPATH_F_FOLLOW_LINK.
1291 RTR3DECL(int) RTPathQueryInfoEx(const char *pszPath
, PRTFSOBJINFO pObjInfo
, RTFSOBJATTRADD enmAdditionalAttribs
, uint32_t fFlags
);
1294 * Changes the mode flags of a file system object.
1296 * The API requires at least one of the mode flag sets (Unix/Dos) to
1297 * be set. The type is ignored.
1299 * This API will resolve symbolic links in the last component since
1300 * mode isn't important for symbolic links.
1302 * @returns iprt status code.
1303 * @param pszPath Path to the file system object.
1304 * @param fMode The new file mode, see @ref grp_rt_fs for details.
1306 RTR3DECL(int) RTPathSetMode(const char *pszPath
, RTFMODE fMode
);
1309 * Gets the mode flags of a file system object.
1311 * @returns iprt status code.
1312 * @param pszPath Path to the file system object.
1313 * @param pfMode Where to store the file mode, see @ref grp_rt_fs for details.
1315 * @remark This is wrapper around RTPathQueryInfoEx(RTPATH_F_FOLLOW_LINK) and
1316 * exists to complement RTPathSetMode().
1318 RTR3DECL(int) RTPathGetMode(const char *pszPath
, PRTFMODE pfMode
);
1321 * Changes one or more of the timestamps associated of file system object.
1323 * This API will not resolve symbolic links in the last component (just
1324 * like unix lutimes()).
1326 * @returns iprt status code.
1327 * @param pszPath Path to the file system object.
1328 * @param pAccessTime Pointer to the new access time.
1329 * @param pModificationTime Pointer to the new modification time.
1330 * @param pChangeTime Pointer to the new change time. NULL if not to be changed.
1331 * @param pBirthTime Pointer to the new time of birth. NULL if not to be changed.
1333 * @remark The file system might not implement all these time attributes,
1334 * the API will ignore the ones which aren't supported.
1336 * @remark The file system might not implement the time resolution
1337 * employed by this interface, the time will be chopped to fit.
1339 * @remark The file system may update the change time even if it's
1342 * @remark POSIX can only set Access & Modification and will always set both.
1344 RTR3DECL(int) RTPathSetTimes(const char *pszPath
, PCRTTIMESPEC pAccessTime
, PCRTTIMESPEC pModificationTime
,
1345 PCRTTIMESPEC pChangeTime
, PCRTTIMESPEC pBirthTime
);
1348 * Changes one or more of the timestamps associated of file system object.
1350 * @returns iprt status code.
1351 * @param pszPath Path to the file system object.
1352 * @param pAccessTime Pointer to the new access time.
1353 * @param pModificationTime Pointer to the new modification time.
1354 * @param pChangeTime Pointer to the new change time. NULL if not to be changed.
1355 * @param pBirthTime Pointer to the new time of birth. NULL if not to be changed.
1356 * @param fFlags RTPATH_F_ON_LINK or RTPATH_F_FOLLOW_LINK.
1358 * @remark The file system might not implement all these time attributes,
1359 * the API will ignore the ones which aren't supported.
1361 * @remark The file system might not implement the time resolution
1362 * employed by this interface, the time will be chopped to fit.
1364 * @remark The file system may update the change time even if it's
1367 * @remark POSIX can only set Access & Modification and will always set both.
1369 RTR3DECL(int) RTPathSetTimesEx(const char *pszPath
, PCRTTIMESPEC pAccessTime
, PCRTTIMESPEC pModificationTime
,
1370 PCRTTIMESPEC pChangeTime
, PCRTTIMESPEC pBirthTime
, uint32_t fFlags
);
1373 * Gets one or more of the timestamps associated of file system object.
1375 * @returns iprt status code.
1376 * @param pszPath Path to the file system object.
1377 * @param pAccessTime Where to store the access time. NULL is ok.
1378 * @param pModificationTime Where to store the modification time. NULL is ok.
1379 * @param pChangeTime Where to store the change time. NULL is ok.
1380 * @param pBirthTime Where to store the creation time. NULL is ok.
1382 * @remark This is wrapper around RTPathQueryInfo() and exists to complement
1383 * RTPathSetTimes(). If the last component is a symbolic link, it will
1386 RTR3DECL(int) RTPathGetTimes(const char *pszPath
, PRTTIMESPEC pAccessTime
, PRTTIMESPEC pModificationTime
,
1387 PRTTIMESPEC pChangeTime
, PRTTIMESPEC pBirthTime
);
1390 * Changes the owner and/or group of a file system object.
1392 * This API will not resolve symbolic links in the last component (just
1393 * like unix lchown()).
1395 * @returns iprt status code.
1396 * @param pszPath Path to the file system object.
1397 * @param uid The new file owner user id. Pass NIL_RTUID to leave
1399 * @param gid The new group id. Pass NIL_RTGUID to leave this
1402 RTR3DECL(int) RTPathSetOwner(const char *pszPath
, uint32_t uid
, uint32_t gid
);
1405 * Changes the owner and/or group of a file system object.
1407 * @returns iprt status code.
1408 * @param pszPath Path to the file system object.
1409 * @param uid The new file owner user id. Pass NIL_RTUID to leave
1411 * @param gid The new group id. Pass NIL_RTGID to leave this
1413 * @param fFlags RTPATH_F_ON_LINK or RTPATH_F_FOLLOW_LINK.
1415 RTR3DECL(int) RTPathSetOwnerEx(const char *pszPath
, uint32_t uid
, uint32_t gid
, uint32_t fFlags
);
1418 * Gets the owner and/or group of a file system object.
1420 * @returns iprt status code.
1421 * @param pszPath Path to the file system object.
1422 * @param pUid Where to store the owner user id. NULL is ok.
1423 * @param pGid Where to store the group id. NULL is ok.
1425 * @remark This is wrapper around RTPathQueryInfo() and exists to complement
1426 * RTPathGetOwner(). If the last component is a symbolic link, it will
1429 RTR3DECL(int) RTPathGetOwner(const char *pszPath
, uint32_t *pUid
, uint32_t *pGid
);
1432 /** @name RTPathRename, RTDirRename & RTFileRename flags.
1434 /** Do not replace anything. */
1435 #define RTPATHRENAME_FLAGS_NO_REPLACE UINT32_C(0)
1436 /** This will replace attempt any target which isn't a directory. */
1437 #define RTPATHRENAME_FLAGS_REPLACE RT_BIT(0)
1438 /** Don't allow symbolic links as part of the path.
1439 * @remarks this flag is currently not implemented and will be ignored. */
1440 #define RTPATHRENAME_FLAGS_NO_SYMLINKS RT_BIT(1)
1444 * Renames a path within a filesystem.
1446 * This will rename symbolic links. If RTPATHRENAME_FLAGS_REPLACE is used and
1447 * pszDst is a symbolic link, it will be replaced and not its target.
1449 * @returns IPRT status code.
1450 * @param pszSrc The source path.
1451 * @param pszDst The destination path.
1452 * @param fRename Rename flags, RTPATHRENAME_FLAGS_*.
1454 RTR3DECL(int) RTPathRename(const char *pszSrc
, const char *pszDst
, unsigned fRename
);
1456 /** @name RTPathUnlink flags.
1458 /** Don't allow symbolic links as part of the path.
1459 * @remarks this flag is currently not implemented and will be ignored. */
1460 #define RTPATHUNLINK_FLAGS_NO_SYMLINKS RT_BIT(0)
1464 * Removes the last component of the path.
1466 * @returns IPRT status code.
1467 * @param pszPath The path.
1468 * @param fUnlink Unlink flags, RTPATHUNLINK_FLAGS_*.
1470 RTR3DECL(int) RTPathUnlink(const char *pszPath
, uint32_t fUnlink
);
1475 * @returns Program exit code.
1477 * @param cArgs The number of arguments.
1478 * @param papszArgs The argument vector. (Note that this may be
1479 * reordered, so the memory must be writable.)
1481 RTDECL(RTEXITCODE
) RTPathRmCmd(unsigned cArgs
, char **papszArgs
);
1483 #endif /* IN_RING3 */