VirtualBox

source: vbox/trunk/include/iprt/path.h@ 103224

Last change on this file since 103224 was 98103, checked in by vboxsync, 21 months ago

Copyright year updates by scm.

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

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette