path.h@ 62896

Last change on this file since 62896 was 62473, checked in by vboxsync, 8 years ago
(C) 2016
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 56.7 KB

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

Note: See TracBrowser for help on using the repository browser.

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

Download in other formats: