VirtualBox

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

Last change on this file since 76585 was 76585, checked in by vboxsync, 6 years ago

*: scm --fix-header-guard-endif

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