2 * IPRT - Path Manipulation.
6 * Copyright (C) 2006-2016 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 * Ensures that the path has a trailing path separator such that file names can
362 * be appended without further work.
364 * This can be helpful when preparing for efficiently combining a directory path
365 * with the filenames returned by RTDirRead. The return value gives you the
366 * position at which you copy the RTDIRENTRY::szName to construct a valid path
369 * @returns The length of the path, 0 on buffer overflow.
370 * @param pszPath The path.
371 * @param cbPath The length of the path buffer @a pszPath points to.
373 RTDECL(size_t) RTPathEnsureTrailingSeparator(char *pszPath
, size_t cbPath
);
376 * Changes all the slashes in the specified path to DOS style.
378 * Unless @a fForce is set, nothing will be done when on a UNIX flavored system
379 * since paths wont work with DOS style slashes there.
381 * @returns @a pszPath.
382 * @param pszPath The path to modify.
383 * @param fForce Whether to force the conversion on non-DOS OSes.
385 RTDECL(char *) RTPathChangeToDosSlashes(char *pszPath
, bool fForce
);
388 * Changes all the slashes in the specified path to unix style.
390 * Unless @a fForce is set, nothing will be done when on a UNIX flavored system
391 * since paths wont work with DOS style slashes there.
393 * @returns @a pszPath.
394 * @param pszPath The path to modify.
395 * @param fForce Whether to force the conversion on non-DOS OSes.
397 RTDECL(char *) RTPathChangeToUnixSlashes(char *pszPath
, bool fForce
);
400 * Simple parsing of the a path.
402 * It figures the length of the directory component, the offset of
403 * the file name and the location of the suffix dot.
405 * @returns The path length.
407 * @param pszPath Path to find filename in.
408 * @param pcchDir Where to put the length of the directory component. If
409 * no directory, this will be 0. Optional.
410 * @param poffName Where to store the filename offset.
411 * If empty string or if it's ending with a slash this
412 * will be set to -1. Optional.
413 * @param poffSuff Where to store the suffix offset (the last dot).
414 * If empty string or if it's ending with a slash this
415 * will be set to -1. Optional.
417 RTDECL(size_t) RTPathParseSimple(const char *pszPath
, size_t *pcchDir
, ssize_t
*poffName
, ssize_t
*poffSuff
);
420 * Finds the filename in a path.
422 * @returns Pointer to filename within pszPath.
423 * @returns NULL if no filename (i.e. empty string or ends with a slash).
424 * @param pszPath Path to find filename in.
426 RTDECL(char *) RTPathFilename(const char *pszPath
);
429 * Finds the filename in a path, extended version.
431 * @returns Pointer to filename within pszPath.
432 * @returns NULL if no filename (i.e. empty string or ends with a slash).
433 * @param pszPath Path to find filename in.
434 * @param fFlags RTPATH_STR_F_STYLE_XXX. Other RTPATH_STR_F_XXX flags
437 RTDECL(char *) RTPathFilenameEx(const char *pszPath
, uint32_t fFlags
);
440 * Finds the suffix part of in a path (last dot and onwards).
442 * @returns Pointer to suffix within pszPath.
443 * @returns NULL if no suffix
444 * @param pszPath Path to find suffix in.
446 * @remarks IPRT terminology: A suffix includes the dot, the extension starts
447 * after the dot. For instance suffix '.txt' and extension 'txt'.
449 RTDECL(char *) RTPathSuffix(const char *pszPath
);
452 * Checks if a path has an extension / suffix.
454 * @returns true if extension / suffix present.
455 * @returns false if no extension / suffix.
456 * @param pszPath Path to check.
458 RTDECL(bool) RTPathHasSuffix(const char *pszPath
);
459 /** Same thing, different name. */
460 #define RTPathHasExt RTPathHasSuffix
463 * Checks if a path includes more than a filename.
465 * @returns true if path present.
466 * @returns false if no path.
467 * @param pszPath Path to check.
469 RTDECL(bool) RTPathHasPath(const char *pszPath
);
470 /** Misspelled, don't use. */
471 #define RTPathHavePath RTPathHasPath
474 * Checks if the path starts with a root specifier or not.
476 * @returns @c true if it starts with root, @c false if not.
478 * @param pszPath Path to check.
480 RTDECL(bool) RTPathStartsWithRoot(const char *pszPath
);
483 * Counts the components in the specified path.
485 * An empty string has zero components. A lone root slash is considered have
486 * one. The paths "/init" and "/bin/" are considered having two components. An
487 * UNC share specifier like "\\myserver\share" will be considered as one single
490 * @returns The number of path components.
491 * @param pszPath The path to parse.
493 RTDECL(size_t) RTPathCountComponents(const char *pszPath
);
496 * Copies the specified number of path components from @a pszSrc and into @a
499 * @returns VINF_SUCCESS or VERR_BUFFER_OVERFLOW. In the latter case the buffer
502 * @param pszDst The destination buffer.
503 * @param cbDst The size of the destination buffer.
504 * @param pszSrc The source path.
505 * @param cComponents The number of components to copy from @a pszSrc.
507 RTDECL(int) RTPathCopyComponents(char *pszDst
, size_t cbDst
, const char *pszSrc
, size_t cComponents
);
509 /** @name Path properties returned by RTPathParse and RTPathSplit.
512 /** Indicates that there is a filename.
513 * If not set, either a lone root spec was given (RTPATH_PROP_UNC,
514 * RTPATH_PROP_ROOT_SLASH, or RTPATH_PROP_VOLUME) or the final component had a
515 * trailing slash (RTPATH_PROP_DIR_SLASH). */
516 #define RTPATH_PROP_FILENAME UINT16_C(0x0001)
517 /** Indicates that a directory was specified using a trailing slash.
518 * @note This is not set for lone root specifications (RTPATH_PROP_UNC,
519 * RTPATH_PROP_ROOT_SLASH, or RTPATH_PROP_VOLUME).
520 * @note The slash is not counted into the last component. However, it is
521 * counted into cchPath. */
522 #define RTPATH_PROP_DIR_SLASH UINT16_C(0x0002)
524 /** The filename has a suffix (extension). */
525 #define RTPATH_PROP_SUFFIX UINT16_C(0x0004)
526 /** Indicates that this is an UNC path (Windows and OS/2 only).
528 * UNC = Universal Naming Convention. It is on the form '//Computer/',
529 * '//Namespace/', '//ComputerName/Resource' and '//Namespace/Resource'.
530 * RTPathParse, RTPathSplit and friends does not consider the 'Resource' as
531 * part of the UNC root specifier. Thus the root specs for the above examples
532 * would be '//ComputerName/' or '//Namespace/'.
534 * Please note that '//something' is not a UNC path, there must be a slash
535 * following the computer or namespace.
537 #define RTPATH_PROP_UNC UINT16_C(0x0010)
538 /** A root slash was specified (unix style root).
539 * (While the path must relative if not set, this being set doesn't make it
542 * This will be set in the following examples: '/', '/bin', 'C:/', 'C:/Windows',
543 * '//./', '//./PhysicalDisk0', '//example.org/', and '//example.org/share'.
545 * It will not be set for the following examples: '.', 'bin/ls', 'C:', and
548 #define RTPATH_PROP_ROOT_SLASH UINT16_C(0x0020)
549 /** A volume is specified (Windows, DOS and OS/2).
550 * For examples: 'C:', 'C:/', and 'A:/AutoExec.bat'. */
551 #define RTPATH_PROP_VOLUME UINT16_C(0x0040)
552 /** The path is absolute, i.e. has a root specifier (root-slash,
553 * volume or UNC) and contains no winding '..' bits, though it may contain
554 * unnecessary slashes (RTPATH_PROP_EXTRA_SLASHES) and '.' components
555 * (RTPATH_PROP_DOT_REFS).
557 * On systems without volumes and UNC (unix style) it will be set for '/',
558 * '/bin/ls', and '/bin//./ls', but not for 'bin/ls', /bin/../usr/bin/env',
559 * '/./bin/ls' or '/.'.
561 * On systems with volumes, it will be set for 'C:/', C:/Windows', and
562 * 'C:/./Windows//', but not for 'C:', 'C:Windows', or 'C:/Windows/../boot.ini'.
564 * On systems with UNC paths, it will be set for '//localhost/',
565 * '//localhost/C$', '//localhost/C$/Windows/System32', '//localhost/.', and
566 * '//localhost/C$//./AutoExec.bat', but not for
567 * '//localhost/C$/Windows/../AutoExec.bat'.
569 * @note For the RTPathAbs definition, this flag needs to be set while both
570 * RTPATH_PROP_EXTRA_SLASHES and RTPATH_PROP_DOT_REFS must be cleared.
572 #define RTPATH_PROP_ABSOLUTE UINT16_C(0x0100)
573 /** Relative path. Inverse of RTPATH_PROP_ABSOLUTE. */
574 #define RTPATH_PROP_RELATIVE UINT16_C(0x0200)
575 /** The path contains unnecessary slashes. Meaning, that if */
576 #define RTPATH_PROP_EXTRA_SLASHES UINT16_C(0x0400)
577 /** The path contains references to the special '.' (dot) directory link. */
578 #define RTPATH_PROP_DOT_REFS UINT16_C(0x0800)
579 /** The path contains references to the special '..' (dot) directory link.
580 * RTPATH_PROP_RELATIVE will always be set together with this. */
581 #define RTPATH_PROP_DOTDOT_REFS UINT16_C(0x1000)
584 /** Macro to determin whether to insert a slash after the first component when
585 * joining it with something else.
586 * (All other components in a split or parsed path requies slashes added.) */
587 #define RTPATH_PROP_FIRST_NEEDS_NO_SLASH(a_fProps) \
588 RT_BOOL( (a_fProps) & (RTPATH_PROP_ROOT_SLASH | RTPATH_PROP_VOLUME | RTPATH_PROP_UNC) )
590 /** Macro to determin whether there is a root specification of any kind
591 * (unix, volumes, unc). */
592 #define RTPATH_PROP_HAS_ROOT_SPEC(a_fProps) \
593 RT_BOOL( (a_fProps) & (RTPATH_PROP_ROOT_SLASH | RTPATH_PROP_VOLUME | RTPATH_PROP_UNC) )
601 * The first component is the root, volume or UNC specifier, if present. Use
602 * RTPATH_PROP_HAS_ROOT_SPEC() on RTPATHPARSED::fProps to determine its
605 * Other than the root component, no component will include directory separators
608 typedef struct RTPATHPARSED
610 /** Number of path components.
611 * This will always be set on VERR_BUFFER_OVERFLOW returns from RTPathParsed
612 * so the caller can calculate the required buffer size. */
614 /** Path property flags, RTPATH_PROP_XXX */
616 /** On success this is the length of the described path, i.e. sum of all
617 * component lengths and necessary separators.
618 * Do NOT use this to index in the source path in case it contains
619 * unnecessary slashes that RTPathParsed has ignored here. */
621 /** Reserved for future use. */
622 uint16_t u16Reserved
;
623 /** The offset of the filename suffix, offset of the NUL char if none. */
625 /** The lenght of the suffix. */
627 /** Array of component descriptors (variable size).
628 * @note Don't try figure the end of the input path by adding up off and cch
629 * of the last component. If RTPATH_PROP_DIR_SLASH is set, there may
630 * be one or more trailing slashes that are unaccounted for! */
633 /** The offset of the component. */
635 /** The length of the component. */
639 /** Pointer to to a parsed path result. */
640 typedef RTPATHPARSED
*PRTPATHPARSED
;
641 /** Pointer to to a const parsed path result. */
642 typedef RTPATHPARSED
*PCRTPATHPARSED
;
648 * @returns IPRT status code.
649 * @retval VERR_INVALID_POINTER if pParsed or pszPath is an invalid pointer.
650 * @retval VERR_INVALID_PARAMETER if cbOutput is less than the RTPATHPARSED
651 * strucuture. No output. (asserted)
652 * @retval VERR_BUFFER_OVERFLOW there are more components in the path than
653 * there is space in aComps. The required amount of space can be
654 * determined from the pParsed->cComps:
656 * RT_OFFSETOF(RTPATHPARSED, aComps[pParsed->cComps])
658 * @retval VERR_PATH_ZERO_LENGTH if the path is empty.
660 * @param pszPath The path to parse.
661 * @param pParsed Where to store the details of the parsed path.
662 * @param cbParsed The size of the buffer. Must be at least the
663 * size of RTPATHPARSED.
664 * @param fFlags Combination of RTPATH_STR_F_XXX flags.
665 * Most users will pass 0.
666 * @sa RTPathSplit, RTPathSplitA.
668 RTDECL(int) RTPathParse(const char *pszPath
, PRTPATHPARSED pParsed
, size_t cbParsed
, uint32_t fFlags
);
671 * Reassembles a path parsed by RTPathParse.
673 * This will be more useful as more APIs manipulating the RTPATHPARSED output
676 * @returns IPRT status code.
677 * @retval VERR_BUFFER_OVERFLOW if @a cbDstPath is less than or equal to
678 * RTPATHPARSED::cchPath.
680 * @param pszSrcPath The source path.
681 * @param pParsed The parser output for @a pszSrcPath.
682 * @param fFlags Combination of RTPATH_STR_F_STYLE_XXX.
683 * Most users will pass 0.
684 * @param pszDstPath Pointer to the buffer where the path is to be
686 * @param cbDstPath The size of the output buffer.
688 RTDECL(int) RTPathParsedReassemble(const char *pszSrcPath
, PRTPATHPARSED pParsed
, uint32_t fFlags
,
689 char *pszDstPath
, size_t cbDstPath
);
693 * Output buffer for RTPathSplit and RTPathSplitA.
695 typedef struct RTPATHSPLIT
697 /** Number of path components.
698 * This will always be set on VERR_BUFFER_OVERFLOW returns from RTPathParsed
699 * so the caller can calculate the required buffer size. */
701 /** Path property flags, RTPATH_PROP_XXX */
703 /** On success this is the length of the described path, i.e. sum of all
704 * component lengths and necessary separators.
705 * Do NOT use this to index in the source path in case it contains
706 * unnecessary slashes that RTPathSplit has ignored here. */
708 /** Reserved (internal use). */
709 uint16_t u16Reserved
;
710 /** The amount of memory used (on success) or required (on
711 * VERR_BUFFER_OVERFLOW) of this structure and it's strings. */
713 /** Pointer to the filename suffix (the dot), if any. Points to the NUL
714 * character of the last component if none or if RTPATH_PROP_DIR_SLASH is
716 const char *pszSuffix
;
717 /** Array of component strings (variable size). */
720 /** Pointer to a split path buffer. */
721 typedef RTPATHSPLIT
*PRTPATHSPLIT
;
722 /** Pointer to a const split path buffer. */
723 typedef RTPATHSPLIT
const *PCRTPATHSPLIT
;
726 * Splits the path into individual component strings, carved from user supplied
727 * the given buffer block.
729 * @returns IPRT status code.
730 * @retval VERR_INVALID_POINTER if pParsed or pszPath is an invalid pointer.
731 * @retval VERR_INVALID_PARAMETER if cbOutput is less than the RTPATHSPLIT
732 * strucuture. No output. (asserted)
733 * @retval VERR_BUFFER_OVERFLOW there are more components in the path than
734 * there is space in aComps. The required amount of space can be
735 * determined from the pParsed->cComps:
737 * RT_OFFSETOF(RTPATHPARSED, aComps[pParsed->cComps])
739 * @retval VERR_PATH_ZERO_LENGTH if the path is empty.
740 * @retval VERR_FILENAME_TOO_LONG if the filename is too long (close to 64 KB).
742 * @param pszPath The path to parse.
743 * @param pSplit Where to store the details of the parsed path.
744 * @param cbSplit The size of the buffer pointed to by @a pSplit
745 * (variable sized array at the end). Must be at
746 * least the size of RTPATHSPLIT.
747 * @param fFlags Combination of RTPATH_STR_F_XXX flags.
748 * Most users will pass 0.
750 * @sa RTPathSplitA, RTPathParse.
752 RTDECL(int) RTPathSplit(const char *pszPath
, PRTPATHSPLIT pSplit
, size_t cbSplit
, uint32_t fFlags
);
755 * Splits the path into individual component strings, allocating the buffer on
756 * the default thread heap.
758 * @returns IPRT status code.
759 * @retval VERR_INVALID_POINTER if pParsed or pszPath is an invalid pointer.
760 * @retval VERR_PATH_ZERO_LENGTH if the path is empty.
762 * @param pszPath The path to parse.
763 * @param ppSplit Where to return the pointer to the output on
764 * success. This must be freed by calling
766 * @param fFlags Combination of RTPATH_STR_F_XXX flags.
767 * Most users will pass 0.
768 * @sa RTPathSplitFree, RTPathSplit, RTPathParse.
770 #define RTPathSplitA(pszPath, ppSplit, fFlags) RTPathSplitATag(pszPath, ppSplit, fFlags, RTPATH_TAG)
773 * Splits the path into individual component strings, allocating the buffer on
774 * the default thread heap.
776 * @returns IPRT status code.
777 * @retval VERR_INVALID_POINTER if pParsed or pszPath is an invalid pointer.
778 * @retval VERR_PATH_ZERO_LENGTH if the path is empty.
780 * @param pszPath The path to parse.
781 * @param ppSplit Where to return the pointer to the output on
782 * success. This must be freed by calling
784 * @param fFlags Combination of RTPATH_STR_F_XXX flags.
785 * Most users will pass 0.
786 * @param pszTag Allocation tag used for statistics and such.
787 * @sa RTPathSplitFree, RTPathSplit, RTPathParse.
789 RTDECL(int) RTPathSplitATag(const char *pszPath
, PRTPATHSPLIT
*ppSplit
, uint32_t fFlags
, const char *pszTag
);
792 * Frees buffer returned by RTPathSplitA.
794 * @param pSplit What RTPathSplitA returned.
797 RTDECL(void) RTPathSplitFree(PRTPATHSPLIT pSplit
);
800 * Reassembles a path parsed by RTPathSplit.
802 * This will be more useful as more APIs manipulating the RTPATHSPLIT output are
805 * @returns IPRT status code.
806 * @retval VERR_BUFFER_OVERFLOW if @a cbDstPath is less than or equal to
807 * RTPATHSPLIT::cchPath.
809 * @param pSplit A split path (see RTPathSplit, RTPathSplitA).
810 * @param fFlags Combination of RTPATH_STR_F_STYLE_XXX.
811 * Most users will pass 0.
812 * @param pszDstPath Pointer to the buffer where the path is to be
814 * @param cbDstPath The size of the output buffer.
816 RTDECL(int) RTPathSplitReassemble(PRTPATHSPLIT pSplit
, uint32_t fFlags
, char *pszDstPath
, size_t cbDstPath
);
819 * Checks if the two paths leads to the file system object.
821 * If the objects exist, we'll query attributes for them. If that's not
822 * conclusive (some OSes) or one of them doesn't exist, we'll use a combination
823 * of RTPathAbs and RTPathCompare to determine the result.
825 * @returns true, false, or VERR_FILENAME_TOO_LONG.
826 * @param pszPath1 The first path.
827 * @param pszPath2 The seoncd path.
829 RTDECL(int) RTPathIsSame(const char *pszPath1
, const char *pszPath2
);
833 * Compares two paths.
835 * The comparison takes platform-dependent details into account,
838 * <li>On DOS-like platforms, both separator chars (|\| and |/|) are considered
840 * <li>On platforms with case-insensitive file systems, mismatching characters
841 * are uppercased and compared again.
844 * @returns @< 0 if the first path less than the second path.
845 * @returns 0 if the first path identical to the second path.
846 * @returns @> 0 if the first path greater than the second path.
848 * @param pszPath1 Path to compare (must be an absolute path).
849 * @param pszPath2 Path to compare (must be an absolute path).
851 * @remarks File system details are currently ignored. This means that you won't
852 * get case-insensitive compares on unix systems when a path goes into a
853 * case-insensitive filesystem like FAT, HPFS, HFS, NTFS, JFS, or
854 * similar. For NT, OS/2 and similar you'll won't get case-sensitive
855 * compares on a case-sensitive file system.
857 RTDECL(int) RTPathCompare(const char *pszPath1
, const char *pszPath2
);
860 * Checks if a path starts with the given parent path.
862 * This means that either the path and the parent path matches completely, or
863 * that the path is to some file or directory residing in the tree given by the
866 * The path comparison takes platform-dependent details into account,
867 * see RTPathCompare() for details.
869 * @returns |true| when \a pszPath starts with \a pszParentPath (or when they
870 * are identical), or |false| otherwise.
872 * @param pszPath Path to check, must be an absolute path.
873 * @param pszParentPath Parent path, must be an absolute path.
874 * No trailing directory slash!
876 * @remarks This API doesn't currently handle root directory compares in a
877 * manner consistent with the other APIs. RTPathStartsWith(pszSomePath,
878 * "/") will not work if pszSomePath isn't "/".
880 RTDECL(bool) RTPathStartsWith(const char *pszPath
, const char *pszParentPath
);
883 * Appends one partial path to another.
885 * The main purpose of this function is to deal correctly with the slashes when
886 * concatenating the two partial paths.
888 * @retval VINF_SUCCESS on success.
889 * @retval VERR_BUFFER_OVERFLOW if the result is too big to fit within
890 * cbPathDst bytes. No changes has been made.
891 * @retval VERR_INVALID_PARAMETER if the string pointed to by pszPath is longer
892 * than cbPathDst-1 bytes (failed to find terminator). Asserted.
894 * @param pszPath The path to append pszAppend to. This serves as both
895 * input and output. This can be empty, in which case
896 * pszAppend is just copied over.
897 * @param cbPathDst The size of the buffer pszPath points to, terminator
898 * included. This should NOT be strlen(pszPath).
899 * @param pszAppend The partial path to append to pszPath. This can be
900 * NULL, in which case nothing is done.
902 * @remarks See the RTPathAppendEx remarks.
904 RTDECL(int) RTPathAppend(char *pszPath
, size_t cbPathDst
, const char *pszAppend
);
907 * Appends one partial path to another.
909 * The main purpose of this function is to deal correctly with the slashes when
910 * concatenating the two partial paths.
912 * @retval VINF_SUCCESS on success.
913 * @retval VERR_BUFFER_OVERFLOW if the result is too big to fit within
914 * cbPathDst bytes. No changes has been made.
915 * @retval VERR_INVALID_PARAMETER if the string pointed to by pszPath is longer
916 * than cbPathDst-1 bytes (failed to find terminator). Asserted.
918 * @param pszPath The path to append pszAppend to. This serves as both
919 * input and output. This can be empty, in which case
920 * pszAppend is just copied over.
921 * @param cbPathDst The size of the buffer pszPath points to, terminator
922 * included. This should NOT be strlen(pszPath).
923 * @param pszAppend The partial path to append to pszPath. This can be
924 * NULL, in which case nothing is done.
925 * @param cchAppendMax The maximum number or characters to take from @a
926 * pszAppend. RTSTR_MAX is fine.
928 * @remarks On OS/2, Window and similar systems, concatenating a drive letter
929 * specifier with a slash prefixed path will result in an absolute
930 * path. Meaning, RTPathAppend(strcpy(szBuf, "C:"), sizeof(szBuf),
931 * "/bar") will result in "C:/bar". (This follows directly from the
932 * behavior when pszPath is empty.)
934 * On the other hand, when joining a drive letter specifier with a
935 * partial path that does not start with a slash, the result is not an
936 * absolute path. Meaning, RTPathAppend(strcpy(szBuf, "C:"),
937 * sizeof(szBuf), "bar") will result in "C:bar".
939 RTDECL(int) RTPathAppendEx(char *pszPath
, size_t cbPathDst
, const char *pszAppend
, size_t cchAppendMax
);
942 * Like RTPathAppend, but with the base path as a separate argument instead of
943 * in the path buffer.
945 * @retval VINF_SUCCESS on success.
946 * @retval VERR_BUFFER_OVERFLOW if the result is too big to fit within
948 * @retval VERR_INVALID_PARAMETER if the string pointed to by pszPath is longer
949 * than cbPathDst-1 bytes (failed to find terminator). Asserted.
951 * @param pszPathDst Where to store the resulting path.
952 * @param cbPathDst The size of the buffer pszPathDst points to,
953 * terminator included.
954 * @param pszPathSrc The base path to copy into @a pszPathDst before
955 * appending @a pszAppend.
956 * @param pszAppend The partial path to append to pszPathSrc. This can
957 * be NULL, in which case nothing is done.
960 RTDECL(int) RTPathJoin(char *pszPathDst
, size_t cbPathDst
, const char *pszPathSrc
,
961 const char *pszAppend
);
964 * Same as RTPathJoin, except that the output buffer is allocated.
966 * @returns Buffer containing the joined up path, call RTStrFree to free. NULL
967 * on allocation failure.
968 * @param pszPathSrc The base path to copy into @a pszPathDst before
969 * appending @a pszAppend.
970 * @param pszAppend The partial path to append to pszPathSrc. This can
971 * be NULL, in which case nothing is done.
974 RTDECL(char *) RTPathJoinA(const char *pszPathSrc
, const char *pszAppend
);
977 * Extended version of RTPathJoin, both inputs can be specified as substrings.
979 * @retval VINF_SUCCESS on success.
980 * @retval VERR_BUFFER_OVERFLOW if the result is too big to fit within
982 * @retval VERR_INVALID_PARAMETER if the string pointed to by pszPath is longer
983 * than cbPathDst-1 bytes (failed to find terminator). Asserted.
985 * @param pszPathDst Where to store the resulting path.
986 * @param cbPathDst The size of the buffer pszPathDst points to,
987 * terminator included.
988 * @param pszPathSrc The base path to copy into @a pszPathDst before
989 * appending @a pszAppend.
990 * @param cchPathSrcMax The maximum number of bytes to copy from @a
991 * pszPathSrc. RTSTR_MAX is find.
992 * @param pszAppend The partial path to append to pszPathSrc. This can
993 * be NULL, in which case nothing is done.
994 * @param cchAppendMax The maximum number of bytes to copy from @a
995 * pszAppend. RTSTR_MAX is find.
998 RTDECL(int) RTPathJoinEx(char *pszPathDst
, size_t cbPathDst
,
999 const char *pszPathSrc
, size_t cchPathSrcMax
,
1000 const char *pszAppend
, size_t cchAppendMax
);
1003 * Callback for RTPathTraverseList that's called for each element.
1005 * @returns IPRT style status code. Return VERR_TRY_AGAIN to continue, any other
1006 * value will abort the traversing and be returned to the caller.
1008 * @param pchPath Pointer to the start of the current path. This is
1009 * not null terminated.
1010 * @param cchPath The length of the path.
1011 * @param pvUser1 The first user parameter.
1012 * @param pvUser2 The second user parameter.
1014 typedef DECLCALLBACK(int) FNRTPATHTRAVERSER(char const *pchPath
, size_t cchPath
, void *pvUser1
, void *pvUser2
);
1015 /** Pointer to a FNRTPATHTRAVERSER. */
1016 typedef FNRTPATHTRAVERSER
*PFNRTPATHTRAVERSER
;
1019 * Traverses a string that can contain multiple paths separated by a special
1022 * @returns IPRT style status code from the callback or VERR_END_OF_STRING if
1023 * the callback returned VERR_TRY_AGAIN for all paths in the string.
1025 * @param pszPathList The string to traverse.
1026 * @param chSep The separator character. Using the null terminator
1027 * is fine, but the result will simply be that there
1028 * will only be one callback for the entire string
1029 * (save any leading white space).
1030 * @param pfnCallback The callback.
1031 * @param pvUser1 First user argument for the callback.
1032 * @param pvUser2 Second user argument for the callback.
1034 RTDECL(int) RTPathTraverseList(const char *pszPathList
, char chSep
, PFNRTPATHTRAVERSER pfnCallback
, void *pvUser1
, void *pvUser2
);
1038 * Calculate a relative path between the two given paths.
1040 * @returns IPRT status code.
1041 * @retval VINF_SUCCESS on success.
1042 * @retval VERR_BUFFER_OVERFLOW if the result is too big to fit within
1044 * @retval VERR_NOT_SUPPORTED if both paths start with different volume specifiers.
1045 * @param pszPathDst Where to store the resulting path.
1046 * @param cbPathDst The size of the buffer pszPathDst points to,
1047 * terminator included.
1048 * @param pszPathFrom The path to start from creating the relative path.
1049 * @param pszPathTo The path to reach with the created relative path.
1051 RTDECL(int) RTPathCalcRelative(char *pszPathDst
, size_t cbPathDst
,
1052 const char *pszPathFrom
,
1053 const char *pszPathTo
);
1058 * Gets the path to the directory containing the executable.
1060 * @returns iprt status code.
1061 * @param pszPath Buffer where to store the path.
1062 * @param cchPath Buffer size in bytes.
1064 RTDECL(int) RTPathExecDir(char *pszPath
, size_t cchPath
);
1067 * Gets the user home directory.
1069 * @returns iprt status code.
1070 * @param pszPath Buffer where to store the path.
1071 * @param cchPath Buffer size in bytes.
1073 RTDECL(int) RTPathUserHome(char *pszPath
, size_t cchPath
);
1076 * Gets the user documents directory.
1078 * The returned path isn't guaranteed to exist.
1080 * @returns iprt status code.
1081 * @param pszPath Buffer where to store the path.
1082 * @param cchPath Buffer size in bytes.
1084 RTDECL(int) RTPathUserDocuments(char *pszPath
, size_t cchPath
);
1087 * Gets the directory of shared libraries.
1089 * This is not the same as RTPathAppPrivateArch() as Linux depends all shared
1090 * libraries in a common global directory where ld.so can find them.
1093 * Solaris: /opt/@<application@>/@<arch>@ or something
1094 * Windows: @<program files directory@>/@<application@>
1095 * Old path: same as RTPathExecDir()
1097 * @returns iprt status code.
1098 * @param pszPath Buffer where to store the path.
1099 * @param cchPath Buffer size in bytes.
1101 RTDECL(int) RTPathSharedLibs(char *pszPath
, size_t cchPath
);
1104 * Gets the directory for architecture-independent application data, for
1105 * example NLS files, module sources, ...
1107 * Linux: /usr/shared/@<application@>
1108 * Solaris: /opt/@<application@>
1109 * Windows: @<program files directory@>/@<application@>
1110 * Old path: same as RTPathExecDir()
1112 * @returns iprt status code.
1113 * @param pszPath Buffer where to store the path.
1114 * @param cchPath Buffer size in bytes.
1116 RTDECL(int) RTPathAppPrivateNoArch(char *pszPath
, size_t cchPath
);
1119 * Gets the directory for architecture-dependent application data, for
1120 * example modules which can be loaded at runtime.
1122 * Linux: /usr/lib/@<application@>
1123 * Solaris: /opt/@<application@>/@<arch>@ or something
1124 * Windows: @<program files directory@>/@<application@>
1125 * Old path: same as RTPathExecDir()
1127 * @returns iprt status code.
1128 * @param pszPath Buffer where to store the path.
1129 * @param cchPath Buffer size in bytes.
1131 RTDECL(int) RTPathAppPrivateArch(char *pszPath
, size_t cchPath
);
1134 * Gets the toplevel directory for architecture-dependent application data.
1136 * This differs from RTPathAppPrivateArch on Solaris only where it will work
1137 * around the /opt/@<application@>/amd64 and /opt/@<application@>/i386 multi
1138 * architecture installation style.
1140 * Linux: /usr/lib/@<application@>
1141 * Solaris: /opt/@<application@>
1142 * Windows: @<program files directory@>/@<application@>
1143 * Old path: same as RTPathExecDir()
1145 * @returns iprt status code.
1146 * @param pszPath Buffer where to store the path.
1147 * @param cchPath Buffer size in bytes.
1149 RTDECL(int) RTPathAppPrivateArchTop(char *pszPath
, size_t cchPath
);
1152 * Gets the directory for documentation.
1154 * Linux: /usr/share/doc/@<application@>
1155 * Solaris: /opt/@<application@>
1156 * Windows: @<program files directory@>/@<application@>
1157 * Old path: same as RTPathExecDir()
1159 * @returns iprt status code.
1160 * @param pszPath Buffer where to store the path.
1161 * @param cchPath Buffer size in bytes.
1163 RTDECL(int) RTPathAppDocs(char *pszPath
, size_t cchPath
);
1166 * Gets the temporary directory path.
1168 * @returns iprt status code.
1169 * @param pszPath Buffer where to store the path.
1170 * @param cchPath Buffer size in bytes.
1172 RTDECL(int) RTPathTemp(char *pszPath
, size_t cchPath
);
1176 * RTPathGlobl result entry.
1178 typedef struct RTPATHGLOBENTRY
1181 struct RTPATHGLOBENTRY
*pNext
;
1182 /** RTDIRENTRYTYPE value. */
1184 /** Unused explicit padding. */
1186 /** The length of the path. */
1188 /** The path to the file (variable length). */
1191 /** Pointer to a GLOB result entry. */
1192 typedef RTPATHGLOBENTRY
*PRTPATHGLOBENTRY
;
1193 /** Pointer to a const GLOB result entry. */
1194 typedef RTPATHGLOBENTRY
const *PCRTPATHGLOBENTRY
;
1195 /** Pointer to a GLOB result entry pointer. */
1196 typedef PCRTPATHGLOBENTRY
*PPCRTPATHGLOBENTRY
;
1199 * Performs wildcard expansion on a path pattern.
1201 * @returns IPRT status code.
1203 * @param pszPattern The pattern to expand.
1204 * @param fFlags RTPATHGLOB_F_XXX.
1205 * @param ppHead Where to return the head of the result list. This
1206 * is always set to NULL on failure.
1207 * @param pcResults Where to return the number of the result. Optional.
1209 RTDECL(int) RTPathGlob(const char *pszPattern
, uint32_t fFlags
, PPCRTPATHGLOBENTRY ppHead
, uint32_t *pcResults
);
1211 /** @name RTPATHGLOB_F_XXX - RTPathGlob flags
1213 /** Case insensitive. */
1214 #define RTPATHGLOB_F_IGNORE_CASE RT_BIT_32(0)
1215 /** Do not expand \${EnvOrSpecialVariable} in the pattern. */
1216 #define RTPATHGLOB_F_NO_VARIABLES RT_BIT_32(1)
1217 /** Do not interpret a leading tilde as a home directory reference. */
1218 #define RTPATHGLOB_F_NO_TILDE RT_BIT_32(2)
1219 /** Only return the first match. */
1220 #define RTPATHGLOB_F_FIRST_ONLY RT_BIT_32(3)
1221 /** Only match directories (implied if pattern ends with slash). */
1222 #define RTPATHGLOB_F_ONLY_DIRS RT_BIT_32(4)
1223 /** Do not match directories. (Can't be used with RTPATHGLOB_F_ONLY_DIRS or
1224 * patterns containing a trailing slash.) */
1225 #define RTPATHGLOB_F_NO_DIRS RT_BIT_32(5)
1226 /** Disables the '**' wildcard pattern for matching zero or more subdirs. */
1227 #define RTPATHGLOB_F_NO_STARSTAR RT_BIT_32(6)
1228 /** Mask of valid flags. */
1229 #define RTPATHGLOB_F_MASK UINT32_C(0x0000007f)
1233 * Frees the results produced by RTPathGlob.
1235 * @param pHead What RTPathGlob returned. NULL ignored.
1237 RTDECL(void) RTPathGlobFree(PCRTPATHGLOBENTRY pHead
);
1241 * Query information about a file system object.
1243 * This API will resolve NOT symbolic links in the last component (just like
1246 * @returns IPRT status code.
1247 * @retval VINF_SUCCESS if the object exists, information returned.
1248 * @retval VERR_PATH_NOT_FOUND if any but the last component in the specified
1249 * path was not found or was not a directory.
1250 * @retval VERR_FILE_NOT_FOUND if the object does not exist (but path to the
1251 * parent directory exists).
1253 * @param pszPath Path to the file system object.
1254 * @param pObjInfo Object information structure to be filled on successful
1256 * @param enmAdditionalAttribs
1257 * Which set of additional attributes to request.
1258 * Use RTFSOBJATTRADD_NOTHING if this doesn't matter.
1260 RTR3DECL(int) RTPathQueryInfo(const char *pszPath
, PRTFSOBJINFO pObjInfo
, RTFSOBJATTRADD enmAdditionalAttribs
);
1263 * Query information about a file system object.
1265 * @returns IPRT status code.
1266 * @retval VINF_SUCCESS if the object exists, information returned.
1267 * @retval VERR_PATH_NOT_FOUND if any but the last component in the specified
1268 * path was not found or was not a directory.
1269 * @retval VERR_FILE_NOT_FOUND if the object does not exist (but path to the
1270 * parent directory exists).
1272 * @param pszPath Path to the file system object.
1273 * @param pObjInfo Object information structure to be filled on successful return.
1274 * @param enmAdditionalAttribs
1275 * Which set of additional attributes to request.
1276 * Use RTFSOBJATTRADD_NOTHING if this doesn't matter.
1277 * @param fFlags RTPATH_F_ON_LINK or RTPATH_F_FOLLOW_LINK.
1279 RTR3DECL(int) RTPathQueryInfoEx(const char *pszPath
, PRTFSOBJINFO pObjInfo
, RTFSOBJATTRADD enmAdditionalAttribs
, uint32_t fFlags
);
1282 * Changes the mode flags of a file system object.
1284 * The API requires at least one of the mode flag sets (Unix/Dos) to
1285 * be set. The type is ignored.
1287 * This API will resolve symbolic links in the last component since
1288 * mode isn't important for symbolic links.
1290 * @returns iprt status code.
1291 * @param pszPath Path to the file system object.
1292 * @param fMode The new file mode, see @ref grp_rt_fs for details.
1294 RTR3DECL(int) RTPathSetMode(const char *pszPath
, RTFMODE fMode
);
1297 * Gets the mode flags of a file system object.
1299 * @returns iprt status code.
1300 * @param pszPath Path to the file system object.
1301 * @param pfMode Where to store the file mode, see @ref grp_rt_fs for details.
1303 * @remark This is wrapper around RTPathQueryInfoEx(RTPATH_F_FOLLOW_LINK) and
1304 * exists to complement RTPathSetMode().
1306 RTR3DECL(int) RTPathGetMode(const char *pszPath
, PRTFMODE pfMode
);
1309 * Changes one or more of the timestamps associated of file system object.
1311 * This API will not resolve symbolic links in the last component (just
1312 * like unix lutimes()).
1314 * @returns iprt status code.
1315 * @param pszPath Path to the file system object.
1316 * @param pAccessTime Pointer to the new access time.
1317 * @param pModificationTime Pointer to the new modification time.
1318 * @param pChangeTime Pointer to the new change time. NULL if not to be changed.
1319 * @param pBirthTime Pointer to the new time of birth. NULL if not to be changed.
1321 * @remark The file system might not implement all these time attributes,
1322 * the API will ignore the ones which aren't supported.
1324 * @remark The file system might not implement the time resolution
1325 * employed by this interface, the time will be chopped to fit.
1327 * @remark The file system may update the change time even if it's
1330 * @remark POSIX can only set Access & Modification and will always set both.
1332 RTR3DECL(int) RTPathSetTimes(const char *pszPath
, PCRTTIMESPEC pAccessTime
, PCRTTIMESPEC pModificationTime
,
1333 PCRTTIMESPEC pChangeTime
, PCRTTIMESPEC pBirthTime
);
1336 * Changes one or more of the timestamps associated of file system object.
1338 * @returns iprt status code.
1339 * @param pszPath Path to the file system object.
1340 * @param pAccessTime Pointer to the new access time.
1341 * @param pModificationTime Pointer to the new modification time.
1342 * @param pChangeTime Pointer to the new change time. NULL if not to be changed.
1343 * @param pBirthTime Pointer to the new time of birth. NULL if not to be changed.
1344 * @param fFlags RTPATH_F_ON_LINK or RTPATH_F_FOLLOW_LINK.
1346 * @remark The file system might not implement all these time attributes,
1347 * the API will ignore the ones which aren't supported.
1349 * @remark The file system might not implement the time resolution
1350 * employed by this interface, the time will be chopped to fit.
1352 * @remark The file system may update the change time even if it's
1355 * @remark POSIX can only set Access & Modification and will always set both.
1357 RTR3DECL(int) RTPathSetTimesEx(const char *pszPath
, PCRTTIMESPEC pAccessTime
, PCRTTIMESPEC pModificationTime
,
1358 PCRTTIMESPEC pChangeTime
, PCRTTIMESPEC pBirthTime
, uint32_t fFlags
);
1361 * Gets one or more of the timestamps associated of file system object.
1363 * @returns iprt status code.
1364 * @param pszPath Path to the file system object.
1365 * @param pAccessTime Where to store the access time. NULL is ok.
1366 * @param pModificationTime Where to store the modification time. NULL is ok.
1367 * @param pChangeTime Where to store the change time. NULL is ok.
1368 * @param pBirthTime Where to store the creation time. NULL is ok.
1370 * @remark This is wrapper around RTPathQueryInfo() and exists to complement
1371 * RTPathSetTimes(). If the last component is a symbolic link, it will
1374 RTR3DECL(int) RTPathGetTimes(const char *pszPath
, PRTTIMESPEC pAccessTime
, PRTTIMESPEC pModificationTime
,
1375 PRTTIMESPEC pChangeTime
, PRTTIMESPEC pBirthTime
);
1378 * Changes the owner and/or group of a file system object.
1380 * This API will not resolve symbolic links in the last component (just
1381 * like unix lchown()).
1383 * @returns iprt status code.
1384 * @param pszPath Path to the file system object.
1385 * @param uid The new file owner user id. Pass NIL_RTUID to leave
1387 * @param gid The new group id. Pass NIL_RTGUID to leave this
1390 RTR3DECL(int) RTPathSetOwner(const char *pszPath
, uint32_t uid
, uint32_t gid
);
1393 * Changes the owner and/or group of a file system object.
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_RTGID to leave this
1401 * @param fFlags RTPATH_F_ON_LINK or RTPATH_F_FOLLOW_LINK.
1403 RTR3DECL(int) RTPathSetOwnerEx(const char *pszPath
, uint32_t uid
, uint32_t gid
, uint32_t fFlags
);
1406 * Gets the owner and/or group of a file system object.
1408 * @returns iprt status code.
1409 * @param pszPath Path to the file system object.
1410 * @param pUid Where to store the owner user id. NULL is ok.
1411 * @param pGid Where to store the group id. NULL is ok.
1413 * @remark This is wrapper around RTPathQueryInfo() and exists to complement
1414 * RTPathGetOwner(). If the last component is a symbolic link, it will
1417 RTR3DECL(int) RTPathGetOwner(const char *pszPath
, uint32_t *pUid
, uint32_t *pGid
);
1420 /** @name RTPathRename, RTDirRename & RTFileRename flags.
1422 /** Do not replace anything. */
1423 #define RTPATHRENAME_FLAGS_NO_REPLACE UINT32_C(0)
1424 /** This will replace attempt any target which isn't a directory. */
1425 #define RTPATHRENAME_FLAGS_REPLACE RT_BIT(0)
1426 /** Don't allow symbolic links as part of the path.
1427 * @remarks this flag is currently not implemented and will be ignored. */
1428 #define RTPATHRENAME_FLAGS_NO_SYMLINKS RT_BIT(1)
1432 * Renames a path within a filesystem.
1434 * This will rename symbolic links. If RTPATHRENAME_FLAGS_REPLACE is used and
1435 * pszDst is a symbolic link, it will be replaced and not its target.
1437 * @returns IPRT status code.
1438 * @param pszSrc The source path.
1439 * @param pszDst The destination path.
1440 * @param fRename Rename flags, RTPATHRENAME_FLAGS_*.
1442 RTR3DECL(int) RTPathRename(const char *pszSrc
, const char *pszDst
, unsigned fRename
);
1444 /** @name RTPathUnlink flags.
1446 /** Don't allow symbolic links as part of the path.
1447 * @remarks this flag is currently not implemented and will be ignored. */
1448 #define RTPATHUNLINK_FLAGS_NO_SYMLINKS RT_BIT(0)
1452 * Removes the last component of the path.
1454 * @returns IPRT status code.
1455 * @param pszPath The path.
1456 * @param fUnlink Unlink flags, RTPATHUNLINK_FLAGS_*.
1458 RTR3DECL(int) RTPathUnlink(const char *pszPath
, uint32_t fUnlink
);
1463 * @returns Program exit code.
1465 * @param cArgs The number of arguments.
1466 * @param papszArgs The argument vector. (Note that this may be
1467 * reordered, so the memory must be writable.)
1469 RTDECL(RTEXITCODE
) RTPathRmCmd(unsigned cArgs
, char **papszArgs
);
1471 #endif /* IN_RING3 */