path.h@ 47791

Last change on this file since 47791 was 46162, checked in by vboxsync, 12 years ago
Simple RTPathIsSame implementation.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 52.5 KB

Line
1	/** @file
2	* IPRT - Path Manipulation.
3	*/
4
5	/*
6	* Copyright (C) 2006-2013 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	* Get the real path (no symlinks, no . or .. components), must exist.
243	*
244	* @returns iprt status code.
245	* @param pszPath The path to resolve.
246	* @param pszRealPath Where to store the real path.
247	* @param cchRealPath Size of the buffer.
248	*/
249	RTDECL(int) RTPathReal(const char pszPath, char pszRealPath, size_t cchRealPath);
250
251	/**
252	* Same as RTPathReal only the result is RTStrDup()'ed.
253	*
254	* @returns Pointer to real path. Use RTStrFree() to free this string.
255	* @returns NULL if RTPathReal() or RTStrDup() fails.
256	* @param pszPath The path to resolve.
257	*/
258	RTDECL(char ) RTPathRealDup(const char pszPath);
259
260	/**
261	* Get the absolute path (starts from root, no . or .. components), doesn't have
262	* to exist. Note that this method is designed to never perform actual file
263	* system access, therefore symlinks are not resolved.
264	*
265	* @returns iprt status code.
266	* @param pszPath The path to resolve.
267	* @param pszAbsPath Where to store the absolute path.
268	* @param cchAbsPath Size of the buffer.
269	*/
270	RTDECL(int) RTPathAbs(const char pszPath, char pszAbsPath, size_t cchAbsPath);
271
272	/**
273	* Same as RTPathAbs only the result is RTStrDup()'ed.
274	*
275	* @returns Pointer to the absolute path. Use RTStrFree() to free this string.
276	* @returns NULL if RTPathAbs() or RTStrDup() fails.
277	* @param pszPath The path to resolve.
278	*/
279	RTDECL(char ) RTPathAbsDup(const char pszPath);
280
281	/**
282	* Get the absolute path (no symlinks, no . or .. components), assuming the
283	* given base path as the current directory. The resulting path doesn't have
284	* to exist.
285	*
286	* @returns iprt status code.
287	* @param pszBase The base path to act like a current directory.
288	* When NULL, the actual cwd is used (i.e. the call
289	* is equivalent to RTPathAbs(pszPath, ...).
290	* @param pszPath The path to resolve.
291	* @param pszAbsPath Where to store the absolute path.
292	* @param cchAbsPath Size of the buffer.
293	*/
294	RTDECL(int) RTPathAbsEx(const char pszBase, const char pszPath, char *pszAbsPath, size_t cchAbsPath);
295
296	/**
297	* Same as RTPathAbsEx only the result is RTStrDup()'ed.
298	*
299	* @returns Pointer to the absolute path. Use RTStrFree() to free this string.
300	* @returns NULL if RTPathAbsEx() or RTStrDup() fails.
301	* @param pszBase The base path to act like a current directory.
302	* When NULL, the actual cwd is used (i.e. the call
303	* is equivalent to RTPathAbs(pszPath, ...).
304	* @param pszPath The path to resolve.
305	*/
306	RTDECL(char ) RTPathAbsExDup(const char pszBase, const char *pszPath);
307
308	/**
309	* Strips the filename from a path. Truncates the given string in-place by overwriting the
310	* last path separator character with a null byte in a platform-neutral way.
311	*
312	* @param pszPath Path from which filename should be extracted, will be truncated.
313	* If the string contains no path separator, it will be changed to a "." string.
314	*/
315	RTDECL(void) RTPathStripFilename(char *pszPath);
316
317	/**
318	* Strips the extension from a path.
319	*
320	* @param pszPath Path which extension should be stripped.
321	*/
322	RTDECL(void) RTPathStripExt(char *pszPath);
323
324	/**
325	* Strips the trailing slashes of a path name.
326	*
327	* Won't strip root slashes.
328	*
329	* @returns The new length of pszPath.
330	* @param pszPath Path to strip.
331	*/
332	RTDECL(size_t) RTPathStripTrailingSlash(char *pszPath);
333
334	/**
335	* Changes all the slashes in the specified path to DOS style.
336	*
337	* Unless @a fForce is set, nothing will be done when on a UNIX flavored system
338	* since paths wont work with DOS style slashes there.
339	*
340	* @returns @a pszPath.
341	* @param pszPath The path to modify.
342	* @param fForce Whether to force the conversion on non-DOS OSes.
343	*/
344	RTDECL(char ) RTPathChangeToDosSlashes(char pszPath, bool fForce);
345
346	/**
347	* Changes all the slashes in the specified path to unix style.
348	*
349	* Unless @a fForce is set, nothing will be done when on a UNIX flavored system
350	* since paths wont work with DOS style slashes there.
351	*
352	* @returns @a pszPath.
353	* @param pszPath The path to modify.
354	* @param fForce Whether to force the conversion on non-DOS OSes.
355	*/
356	RTDECL(char ) RTPathChangeToUnixSlashes(char pszPath, bool fForce);
357
358	/**
359	* Simple parsing of the a path.
360	*
361	* It figures the length of the directory component, the offset of
362	* the file name and the location of the suffix dot.
363	*
364	* @returns The path length.
365	*
366	* @param pszPath Path to find filename in.
367	* @param pcchDir Where to put the length of the directory component. If
368	* no directory, this will be 0. Optional.
369	* @param poffName Where to store the filename offset.
370	* If empty string or if it's ending with a slash this
371	* will be set to -1. Optional.
372	* @param poffSuff Where to store the suffix offset (the last dot).
373	* If empty string or if it's ending with a slash this
374	* will be set to -1. Optional.
375	*/
376	RTDECL(size_t) RTPathParseSimple(const char pszPath, size_t pcchDir, ssize_t poffName, ssize_t poffSuff);
377
378	/**
379	* Finds the filename in a path.
380	*
381	* @returns Pointer to filename within pszPath.
382	* @returns NULL if no filename (i.e. empty string or ends with a slash).
383	* @param pszPath Path to find filename in.
384	*/
385	RTDECL(char ) RTPathFilename(const char pszPath);
386
387	/**
388	* Finds the filename in a path, extended version.
389	*
390	* @returns Pointer to filename within pszPath.
391	* @returns NULL if no filename (i.e. empty string or ends with a slash).
392	* @param pszPath Path to find filename in.
393	* @param fFlags RTPATH_STR_F_STYLE_XXX. Other RTPATH_STR_F_XXX flags
394	* will be ignored.
395	*/
396	RTDECL(char ) RTPathFilenameEx(const char pszPath, uint32_t fFlags);
397
398	/**
399	* Finds the extension part of in a path.
400	*
401	* @returns Pointer to extension within pszPath.
402	* @returns NULL if no extension.
403	* @param pszPath Path to find extension in.
404	*/
405	RTDECL(char ) RTPathExt(const char pszPath);
406
407	/**
408	* Checks if a path has an extension.
409	*
410	* @returns true if extension present.
411	* @returns false if no extension.
412	* @param pszPath Path to check.
413	*/
414	RTDECL(bool) RTPathHasExt(const char *pszPath);
415	/** Misspelled, don't use. */
416	#define RTPathHaveExt RTPathHasExt
417
418	/**
419	* Checks if a path includes more than a filename.
420	*
421	* @returns true if path present.
422	* @returns false if no path.
423	* @param pszPath Path to check.
424	*/
425	RTDECL(bool) RTPathHasPath(const char *pszPath);
426	/** Misspelled, don't use. */
427	#define RTPathHavePath RTPathHasPath
428
429	/**
430	* Checks if the path starts with a root specifier or not.
431	*
432	* @returns @c true if it starts with root, @c false if not.
433	*
434	* @param pszPath Path to check.
435	*/
436	RTDECL(bool) RTPathStartsWithRoot(const char *pszPath);
437
438	/**
439	* Counts the components in the specified path.
440	*
441	* An empty string has zero components. A lone root slash is considered have
442	* one. The paths "/init" and "/bin/" are considered having two components. An
443	* UNC share specifier like "\\myserver\share" will be considered as one single
444	* component.
445	*
446	* @returns The number of path components.
447	* @param pszPath The path to parse.
448	*/
449	RTDECL(size_t) RTPathCountComponents(const char *pszPath);
450
451	/**
452	* Copies the specified number of path components from @a pszSrc and into @a
453	* pszDst.
454	*
455	* @returns VINF_SUCCESS or VERR_BUFFER_OVERFLOW. In the latter case the buffer
456	* is not touched.
457	*
458	* @param pszDst The destination buffer.
459	* @param cbDst The size of the destination buffer.
460	* @param pszSrc The source path.
461	* @param cComponents The number of components to copy from @a pszSrc.
462	*/
463	RTDECL(int) RTPathCopyComponents(char pszDst, size_t cbDst, const char pszSrc, size_t cComponents);
464
465	/** @name Path properties returned by RTPathParse and RTPathSplit.
466	* @{ */
467
468	/** Indicates that there is a filename.
469	* If not set, either a lone root spec was given (RTPATH_PROP_UNC,
470	* RTPATH_PROP_ROOT_SLASH, or RTPATH_PROP_VOLUME) or the final component had a
471	* trailing slash (RTPATH_PROP_DIR_SLASH). */
472	#define RTPATH_PROP_FILENAME UINT16_C(0x0001)
473	/** Indicates that a directory was specified using a trailing slash.
474	* @note This is not set for lone root specifications (RTPATH_PROP_UNC,
475	* RTPATH_PROP_ROOT_SLASH, or RTPATH_PROP_VOLUME).
476	* @note The slash is not counted into the last component. However, it is
477	* counted into cchPath. */
478	#define RTPATH_PROP_DIR_SLASH UINT16_C(0x0002)
479
480	/** The filename has a suffix (extension). */
481	#define RTPATH_PROP_SUFFIX UINT16_C(0x0004)
482	/** Indicates that this is an UNC path (Windows and OS/2 only).
483	*
484	* UNC = Universal Naming Convention. It is on the form '//Computer/',
485	* '//Namespace/', '//ComputerName/Resource' and '//Namespace/Resource'.
486	* RTPathParse, RTPathSplit and friends does not consider the 'Resource' as
487	* part of the UNC root specifier. Thus the root specs for the above examples
488	* would be '//ComputerName/' or '//Namespace/'.
489	*
490	* Please note that '//something' is not a UNC path, there must be a slash
491	* following the computer or namespace.
492	*/
493	#define RTPATH_PROP_UNC UINT16_C(0x0010)
494	/** A root slash was specified (unix style root).
495	* (While the path must relative if not set, this being set doesn't make it
496	* absolute.)
497	*
498	* This will be set in the following examples: '/', '/bin', 'C:/', 'C:/Windows',
499	* '//./', '//./PhysicalDisk0', '//example.org/', and '//example.org/share'.
500	*
501	* It will not be set for the following examples: '.', 'bin/ls', 'C:', and
502	* 'C:Windows'.
503	*/
504	#define RTPATH_PROP_ROOT_SLASH UINT16_C(0x0020)
505	/** A volume is specified (Windows, DOS and OS/2).
506	* For examples: 'C:', 'C:/', and 'A:/AutoExec.bat'. */
507	#define RTPATH_PROP_VOLUME UINT16_C(0x0040)
508	/** The path is absolute, i.e. has a root specifier (root-slash,
509	* volume or UNC) and contains no winding '..' bits, though it may contain
510	* unnecessary slashes (RTPATH_PROP_EXTRA_SLASHES) and '.' components
511	* (RTPATH_PROP_DOT_REFS).
512	*
513	* On systems without volumes and UNC (unix style) it will be set for '/',
514	* '/bin/ls', and '/bin//./ls', but not for 'bin/ls', /bin/../usr/bin/env',
515	* '/./bin/ls' or '/.'.
516	*
517	* On systems with volumes, it will be set for 'C:/', C:/Windows', and
518	* 'C:/./Windows//', but not for 'C:', 'C:Windows', or 'C:/Windows/../boot.ini'.
519	*
520	* On systems with UNC paths, it will be set for '//localhost/',
521	* '//localhost/C$', '//localhost/C$/Windows/System32', '//localhost/.', and
522	* '//localhost/C$//./AutoExec.bat', but not for
523	* '//localhost/C$/Windows/../AutoExec.bat'.
524	*
525	* @note For the RTPathAbs definition, this flag needs to be set while both
526	* RTPATH_PROP_EXTRA_SLASHES and RTPATH_PROP_DOT_REFS must be cleared.
527	*/
528	#define RTPATH_PROP_ABSOLUTE UINT16_C(0x0100)
529	/** Relative path. Inverse of RTPATH_PROP_ABSOLUTE. */
530	#define RTPATH_PROP_RELATIVE UINT16_C(0x0200)
531	/** The path contains unnecessary slashes. Meaning, that if */
532	#define RTPATH_PROP_EXTRA_SLASHES UINT16_C(0x0400)
533	/** The path contains references to the special '.' (dot) directory link. */
534	#define RTPATH_PROP_DOT_REFS UINT16_C(0x0800)
535	/** The path contains references to the special '..' (dot) directory link.
536	* RTPATH_PROP_RELATIVE will always be set together with this. */
537	#define RTPATH_PROP_DOTDOT_REFS UINT16_C(0x1000)
538
539
540	/** Macro to determin whether to insert a slash after the first component when
541	* joining it with something else.
542	* (All other components in a split or parsed path requies slashes added.) */
543	#define RTPATH_PROP_FIRST_NEEDS_NO_SLASH(a_fProps) \
544	RT_BOOL( (a_fProps) & (RTPATH_PROP_ROOT_SLASH \| RTPATH_PROP_VOLUME \| RTPATH_PROP_UNC) )
545
546	/** Macro to determin whether there is a root specification of any kind
547	* (unix, volumes, unc). */
548	#define RTPATH_PROP_HAS_ROOT_SPEC(a_fProps) \
549	RT_BOOL( (a_fProps) & (RTPATH_PROP_ROOT_SLASH \| RTPATH_PROP_VOLUME \| RTPATH_PROP_UNC) )
550
551	/** @} */
552
553
554	/**
555	* Parsed path.
556	*
557	* The first component is the root, volume or UNC specifier, if present. Use
558	* RTPATH_PROP_HAS_ROOT_SPEC() on RTPATHPARSED::fProps to determine its
559	* precense.
560	*
561	* Other than the root component, no component will include directory separators
562	* (slashes).
563	*/
564	typedef struct RTPATHPARSED
565	{
566	/** Number of path components.
567	* This will always be set on VERR_BUFFER_OVERFLOW returns from RTPathParsed
568	* so the caller can calculate the required buffer size. */
569	uint16_t cComps;
570	/** Path property flags, RTPATH_PROP_XXX */
571	uint16_t fProps;
572	/** On success this is the length of the described path, i.e. sum of all
573	* component lengths and necessary separators.
574	* Do NOT use this to index in the source path in case it contains
575	* unnecessary slashes that RTPathParsed has ignored here. */
576	uint16_t cchPath;
577	/** Reserved for future use. */
578	uint16_t u16Reserved;
579	/** The offset of the filename suffix, offset of the NUL char if none. */
580	uint16_t offSuffix;
581	/** The lenght of the suffix. */
582	uint16_t cchSuffix;
583	/** Array of component descriptors (variable size).
584	* @note Don't try figure the end of the input path by adding up off and cch
585	* of the last component. If RTPATH_PROP_DIR_SLASH is set, there may
586	* be one or more trailing slashes that are unaccounted for! */
587	struct
588	{
589	/** The offset of the component. */
590	uint16_t off;
591	/** The length of the component. */
592	uint16_t cch;
593	} aComps[1];
594	} RTPATHPARSED;
595	/** Pointer to to a parsed path result. */
596	typedef RTPATHPARSED *PRTPATHPARSED;
597	/** Pointer to to a const parsed path result. */
598	typedef RTPATHPARSED *PCRTPATHPARSED;
599
600
601	/**
602	* Parses the path.
603	*
604	* @returns IPRT status code.
605	* @retval VERR_INVALID_POINTER if pParsed or pszPath is an invalid pointer.
606	* @retval VERR_INVALID_PARAMETER if cbOutput is less than the RTPATHPARSED
607	* strucuture. No output. (asserted)
608	* @retval VERR_BUFFER_OVERFLOW there are more components in the path than
609	* there is space in aComps. The required amount of space can be
610	* determined from the pParsed->cComps:
611	* @code
612	* RT_OFFSETOF(RTPATHPARSED, aComps[pParsed->cComps])
613	* @endcode
614	* @retval VERR_PATH_ZERO_LENGTH if the path is empty.
615	*
616	* @param pszPath The path to parse.
617	* @param pParsed Where to store the details of the parsed path.
618	* @param cbParsed The size of the buffer. Must be at least the
619	* size of RTPATHPARSED.
620	* @param fFlags Combination of RTPATH_STR_F_XXX flags.
621	* Most users will pass 0.
622	* @sa RTPathSplit, RTPathSplitA.
623	*/
624	RTDECL(int) RTPathParse(const char *pszPath, PRTPATHPARSED pParsed, size_t cbParsed, uint32_t fFlags);
625
626	/**
627	* Reassembles a path parsed by RTPathParse.
628	*
629	* This will be more useful as more APIs manipulating the RTPATHPARSED output
630	* are added.
631	*
632	* @returns IPRT status code.
633	* @retval VERR_BUFFER_OVERFLOW if @a cbDstPath is less than or equal to
634	* RTPATHPARSED::cchPath.
635	*
636	* @param pszSrcPath The source path.
637	* @param pParsed The parser output for @a pszSrcPath.
638	* @param fFlags Combination of RTPATH_STR_F_STYLE_XXX.
639	* Most users will pass 0.
640	* @param pszDstPath Pointer to the buffer where the path is to be
641	* reassembled.
642	* @param cbDstPath The size of the output buffer.
643	*/
644	RTDECL(int) RTPathParsedReassemble(const char *pszSrcPath, PRTPATHPARSED pParsed, uint32_t fFlags,
645	char *pszDstPath, size_t cbDstPath);
646
647
648	/**
649	* Output buffer for RTPathSplit and RTPathSplitA.
650	*/
651	typedef struct RTPATHSPLIT
652	{
653	/** Number of path components.
654	* This will always be set on VERR_BUFFER_OVERFLOW returns from RTPathParsed
655	* so the caller can calculate the required buffer size. */
656	uint16_t cComps;
657	/** Path property flags, RTPATH_PROP_XXX */
658	uint16_t fProps;
659	/** On success this is the length of the described path, i.e. sum of all
660	* component lengths and necessary separators.
661	* Do NOT use this to index in the source path in case it contains
662	* unnecessary slashes that RTPathSplit has ignored here. */
663	uint16_t cchPath;
664	/** Reserved (internal use). */
665	uint16_t u16Reserved;
666	/** The amount of memory used (on success) or required (on
667	* VERR_BUFFER_OVERFLOW) of this structure and it's strings. */
668	uint32_t cbNeeded;
669	/** Pointer to the filename suffix (the dot), if any. Points to the NUL
670	* character of the last component if none or if RTPATH_PROP_DIR_SLASH is
671	* present. */
672	const char *pszSuffix;
673	/** Array of component strings (variable size). */
674	char *apszComps[1];
675	} RTPATHSPLIT;
676	/** Pointer to a split path buffer. */
677	typedef RTPATHSPLIT *PRTPATHSPLIT;
678	/** Pointer to a const split path buffer. */
679	typedef RTPATHSPLIT const *PCRTPATHSPLIT;
680
681	/**
682	* Splits the path into individual component strings, carved from user supplied
683	* the given buffer block.
684	*
685	* @returns IPRT status code.
686	* @retval VERR_INVALID_POINTER if pParsed or pszPath is an invalid pointer.
687	* @retval VERR_INVALID_PARAMETER if cbOutput is less than the RTPATHSPLIT
688	* strucuture. No output. (asserted)
689	* @retval VERR_BUFFER_OVERFLOW there are more components in the path than
690	* there is space in aComps. The required amount of space can be
691	* determined from the pParsed->cComps:
692	* @code
693	* RT_OFFSETOF(RTPATHPARSED, aComps[pParsed->cComps])
694	* @endcode
695	* @retval VERR_PATH_ZERO_LENGTH if the path is empty.
696	* @retval VERR_FILENAME_TOO_LONG if the filename is too long (close to 64 KB).
697	*
698	* @param pszPath The path to parse.
699	* @param pSplit Where to store the details of the parsed path.
700	* @param cbSplit The size of the buffer pointed to by @a pSplit
701	* (variable sized array at the end). Must be at
702	* least the size of RTPATHSPLIT.
703	* @param fFlags Combination of RTPATH_STR_F_XXX flags.
704	* Most users will pass 0.
705	*
706	* @sa RTPathSplitA, RTPathParse.
707	*/
708	RTDECL(int) RTPathSplit(const char *pszPath, PRTPATHSPLIT pSplit, size_t cbSplit, uint32_t fFlags);
709
710	/**
711	* Splits the path into individual component strings, allocating the buffer on
712	* the default thread heap.
713	*
714	* @returns IPRT status code.
715	* @retval VERR_INVALID_POINTER if pParsed or pszPath is an invalid pointer.
716	* @retval VERR_PATH_ZERO_LENGTH if the path is empty.
717	*
718	* @param pszPath The path to parse.
719	* @param ppSplit Where to return the pointer to the output on
720	* success. This must be freed by calling
721	* RTPathSplitFree().
722	* @param fFlags Combination of RTPATH_STR_F_XXX flags.
723	* Most users will pass 0.
724	* @sa RTPathSplitFree, RTPathSplit, RTPathParse.
725	*/
726	#define RTPathSplitA(pszPath, ppSplit, fFlags) RTPathSplitATag(pszPath, ppSplit, fFlags, RTPATH_TAG)
727
728	/**
729	* Splits the path into individual component strings, allocating the buffer on
730	* the default thread heap.
731	*
732	* @returns IPRT status code.
733	* @retval VERR_INVALID_POINTER if pParsed or pszPath is an invalid pointer.
734	* @retval VERR_PATH_ZERO_LENGTH if the path is empty.
735	*
736	* @param pszPath The path to parse.
737	* @param ppSplit Where to return the pointer to the output on
738	* success. This must be freed by calling
739	* RTPathSplitFree().
740	* @param fFlags Combination of RTPATH_STR_F_XXX flags.
741	* Most users will pass 0.
742	* @param pszTag Allocation tag used for statistics and such.
743	* @sa RTPathSplitFree, RTPathSplit, RTPathParse.
744	*/
745	RTDECL(int) RTPathSplitATag(const char pszPath, PRTPATHSPLIT ppSplit, uint32_t fFlags, const char *pszTag);
746
747	/**
748	* Frees buffer returned by RTPathSplitA.
749	*
750	* @param pSplit What RTPathSplitA returned.
751	* @sa RTPathSplitA
752	*/
753	RTDECL(void) RTPathSplitFree(PRTPATHSPLIT pSplit);
754
755	/**
756	* Reassembles a path parsed by RTPathSplit.
757	*
758	* This will be more useful as more APIs manipulating the RTPATHSPLIT output are
759	* added.
760	*
761	* @returns IPRT status code.
762	* @retval VERR_BUFFER_OVERFLOW if @a cbDstPath is less than or equal to
763	* RTPATHSPLIT::cchPath.
764	*
765	* @param pParsed The parser output for @a pszSrcPath.
766	* @param fFlags Combination of RTPATH_STR_F_STYLE_XXX.
767	* Most users will pass 0.
768	* @param pszDstPath Pointer to the buffer where the path is to be
769	* reassembled.
770	* @param cbDstPath The size of the output buffer.
771	*/
772	RTDECL(int) RTPathSplitReassemble(PRTPATHSPLIT pSplit, uint32_t fFlags, char *pszDstPath, size_t cbDstPath);
773
774	/**
775	* Checks if the two paths leads to the file system object.
776	*
777	* If the objects exist, we'll query attributes for them. If that's not
778	* conclusive (some OSes) or one of them doesn't exist, we'll use a combination
779	* of RTPathAbs and RTPathCompare to determine the result.
780	*
781	* @returns true, false, or VERR_FILENAME_TOO_LONG.
782	* @param pszPath1 The first path.
783	* @param pszPath2 The seoncd path.
784	*/
785	RTDECL(int) RTPathIsSame(const char pszPath1, const char pszPath2);
786
787
788	/**
789	* Compares two paths.
790	*
791	* The comparison takes platform-dependent details into account,
792	* such as:
793	* <ul>
794	* <li>On DOS-like platforms, both separator chars (\|\\| and \|/\|) are considered
795	* to be equal.
796	* <li>On platforms with case-insensitive file systems, mismatching characters
797	* are uppercased and compared again.
798	* </ul>
799	*
800	* @returns @< 0 if the first path less than the second path.
801	* @returns 0 if the first path identical to the second path.
802	* @returns @> 0 if the first path greater than the second path.
803	*
804	* @param pszPath1 Path to compare (must be an absolute path).
805	* @param pszPath2 Path to compare (must be an absolute path).
806	*
807	* @remarks File system details are currently ignored. This means that you won't
808	* get case-insensitive compares on unix systems when a path goes into a
809	* case-insensitive filesystem like FAT, HPFS, HFS, NTFS, JFS, or
810	* similar. For NT, OS/2 and similar you'll won't get case-sensitive
811	* compares on a case-sensitive file system.
812	*/
813	RTDECL(int) RTPathCompare(const char pszPath1, const char pszPath2);
814
815	/**
816	* Checks if a path starts with the given parent path.
817	*
818	* This means that either the path and the parent path matches completely, or
819	* that the path is to some file or directory residing in the tree given by the
820	* parent directory.
821	*
822	* The path comparison takes platform-dependent details into account,
823	* see RTPathCompare() for details.
824	*
825	* @returns \|true\| when \a pszPath starts with \a pszParentPath (or when they
826	* are identical), or \|false\| otherwise.
827	*
828	* @param pszPath Path to check, must be an absolute path.
829	* @param pszParentPath Parent path, must be an absolute path.
830	* No trailing directory slash!
831	*
832	* @remarks This API doesn't currently handle root directory compares in a
833	* manner consistent with the other APIs. RTPathStartsWith(pszSomePath,
834	* "/") will not work if pszSomePath isn't "/".
835	*/
836	RTDECL(bool) RTPathStartsWith(const char pszPath, const char pszParentPath);
837
838	/**
839	* Appends one partial path to another.
840	*
841	* The main purpose of this function is to deal correctly with the slashes when
842	* concatenating the two partial paths.
843	*
844	* @retval VINF_SUCCESS on success.
845	* @retval VERR_BUFFER_OVERFLOW if the result is too big to fit within
846	* cbPathDst bytes. No changes has been made.
847	* @retval VERR_INVALID_PARAMETER if the string pointed to by pszPath is longer
848	* than cbPathDst-1 bytes (failed to find terminator). Asserted.
849	*
850	* @param pszPath The path to append pszAppend to. This serves as both
851	* input and output. This can be empty, in which case
852	* pszAppend is just copied over.
853	* @param cbPathDst The size of the buffer pszPath points to, terminator
854	* included. This should NOT be strlen(pszPath).
855	* @param pszAppend The partial path to append to pszPath. This can be
856	* NULL, in which case nothing is done.
857	*
858	* @remarks See the RTPathAppendEx remarks.
859	*/
860	RTDECL(int) RTPathAppend(char pszPath, size_t cbPathDst, const char pszAppend);
861
862	/**
863	* Appends one partial path to another.
864	*
865	* The main purpose of this function is to deal correctly with the slashes when
866	* concatenating the two partial paths.
867	*
868	* @retval VINF_SUCCESS on success.
869	* @retval VERR_BUFFER_OVERFLOW if the result is too big to fit within
870	* cbPathDst bytes. No changes has been made.
871	* @retval VERR_INVALID_PARAMETER if the string pointed to by pszPath is longer
872	* than cbPathDst-1 bytes (failed to find terminator). Asserted.
873	*
874	* @param pszPath The path to append pszAppend to. This serves as both
875	* input and output. This can be empty, in which case
876	* pszAppend is just copied over.
877	* @param cbPathDst The size of the buffer pszPath points to, terminator
878	* included. This should NOT be strlen(pszPath).
879	* @param pszAppend The partial path to append to pszPath. This can be
880	* NULL, in which case nothing is done.
881	* @param cchAppendMax The maximum number or characters to take from @a
882	* pszAppend. RTSTR_MAX is fine.
883	*
884	* @remarks On OS/2, Window and similar systems, concatenating a drive letter
885	* specifier with a slash prefixed path will result in an absolute
886	* path. Meaning, RTPathAppend(strcpy(szBuf, "C:"), sizeof(szBuf),
887	* "/bar") will result in "C:/bar". (This follows directly from the
888	* behavior when pszPath is empty.)
889	*
890	* On the other hand, when joining a drive letter specifier with a
891	* partial path that does not start with a slash, the result is not an
892	* absolute path. Meaning, RTPathAppend(strcpy(szBuf, "C:"),
893	* sizeof(szBuf), "bar") will result in "C:bar".
894	*/
895	RTDECL(int) RTPathAppendEx(char pszPath, size_t cbPathDst, const char pszAppend, size_t cchAppendMax);
896
897	/**
898	* Like RTPathAppend, but with the base path as a separate argument instead of
899	* in the path buffer.
900	*
901	* @retval VINF_SUCCESS on success.
902	* @retval VERR_BUFFER_OVERFLOW if the result is too big to fit within
903	* cbPathDst bytes.
904	* @retval VERR_INVALID_PARAMETER if the string pointed to by pszPath is longer
905	* than cbPathDst-1 bytes (failed to find terminator). Asserted.
906	*
907	* @param pszPathDst Where to store the resulting path.
908	* @param cbPathDst The size of the buffer pszPathDst points to,
909	* terminator included.
910	* @param pszPathSrc The base path to copy into @a pszPathDst before
911	* appending @a pszAppend.
912	* @param pszAppend The partial path to append to pszPathSrc. This can
913	* be NULL, in which case nothing is done.
914	*
915	*/
916	RTDECL(int) RTPathJoin(char pszPathDst, size_t cbPathDst, const char pszPathSrc,
917	const char *pszAppend);
918
919	/**
920	* Same as RTPathJoin, except that the output buffer is allocated.
921	*
922	* @returns Buffer containing the joined up path, call RTStrFree to free. NULL
923	* on allocation failure.
924	* @param pszPathSrc The base path to copy into @a pszPathDst before
925	* appending @a pszAppend.
926	* @param pszAppend The partial path to append to pszPathSrc. This can
927	* be NULL, in which case nothing is done.
928	*
929	*/
930	RTDECL(char ) RTPathJoinA(const char pszPathSrc, const char *pszAppend);
931
932	/**
933	* Extended version of RTPathJoin, both inputs can be specified as substrings.
934	*
935	* @retval VINF_SUCCESS on success.
936	* @retval VERR_BUFFER_OVERFLOW if the result is too big to fit within
937	* cbPathDst bytes.
938	* @retval VERR_INVALID_PARAMETER if the string pointed to by pszPath is longer
939	* than cbPathDst-1 bytes (failed to find terminator). Asserted.
940	*
941	* @param pszPathDst Where to store the resulting path.
942	* @param cbPathDst The size of the buffer pszPathDst points to,
943	* terminator included.
944	* @param pszPathSrc The base path to copy into @a pszPathDst before
945	* appending @a pszAppend.
946	* @param cchPathSrcMax The maximum number of bytes to copy from @a
947	* pszPathSrc. RTSTR_MAX is find.
948	* @param pszAppend The partial path to append to pszPathSrc. This can
949	* be NULL, in which case nothing is done.
950	* @param cchAppendMax The maximum number of bytes to copy from @a
951	* pszAppend. RTSTR_MAX is find.
952	*
953	*/
954	RTDECL(int) RTPathJoinEx(char *pszPathDst, size_t cbPathDst,
955	const char *pszPathSrc, size_t cchPathSrcMax,
956	const char *pszAppend, size_t cchAppendMax);
957
958	/**
959	* Callback for RTPathTraverseList that's called for each element.
960	*
961	* @returns IPRT style status code. Return VERR_TRY_AGAIN to continue, any other
962	* value will abort the traversing and be returned to the caller.
963	*
964	* @param pchPath Pointer to the start of the current path. This is
965	* not null terminated.
966	* @param cchPath The length of the path.
967	* @param pvUser1 The first user parameter.
968	* @param pvUser2 The second user parameter.
969	*/
970	typedef DECLCALLBACK(int) FNRTPATHTRAVERSER(char const pchPath, size_t cchPath, void pvUser1, void *pvUser2);
971	/** Pointer to a FNRTPATHTRAVERSER. */
972	typedef FNRTPATHTRAVERSER *PFNRTPATHTRAVERSER;
973
974	/**
975	* Traverses a string that can contain multiple paths separated by a special
976	* character.
977	*
978	* @returns IPRT style status code from the callback or VERR_END_OF_STRING if
979	* the callback returned VERR_TRY_AGAIN for all paths in the string.
980	*
981	* @param pszPathList The string to traverse.
982	* @param chSep The separator character. Using the null terminator
983	* is fine, but the result will simply be that there
984	* will only be one callback for the entire string
985	* (save any leading white space).
986	* @param pfnCallback The callback.
987	* @param pvUser1 First user argument for the callback.
988	* @param pvUser2 Second user argument for the callback.
989	*/
990	RTDECL(int) RTPathTraverseList(const char pszPathList, char chSep, PFNRTPATHTRAVERSER pfnCallback, void pvUser1, void *pvUser2);
991
992
993	/**
994	* Calculate a relative path between the two given paths.
995	*
996	* @returns IPRT status code.
997	* @retval VINF_SUCCESS on success.
998	* @retval VERR_BUFFER_OVERFLOW if the result is too big to fit within
999	* cbPathDst bytes.
1000	* @retval VERR_NOT_SUPPORTED if both paths start with different volume specifiers.
1001	* @param pszPathDst Where to store the resulting path.
1002	* @param cbPathDst The size of the buffer pszPathDst points to,
1003	* terminator included.
1004	* @param pszPathFrom The path to start from creating the relative path.
1005	* @param pszPathTo The path to reach with the created relative path.
1006	*/
1007	RTDECL(int) RTPathCalcRelative(char *pszPathDst, size_t cbPathDst,
1008	const char *pszPathFrom,
1009	const char *pszPathTo);
1010
1011	#ifdef IN_RING3
1012
1013	/**
1014	* Gets the path to the directory containing the executable.
1015	*
1016	* @returns iprt status code.
1017	* @param pszPath Buffer where to store the path.
1018	* @param cchPath Buffer size in bytes.
1019	*/
1020	RTDECL(int) RTPathExecDir(char *pszPath, size_t cchPath);
1021
1022	/**
1023	* Gets the user home directory.
1024	*
1025	* @returns iprt status code.
1026	* @param pszPath Buffer where to store the path.
1027	* @param cchPath Buffer size in bytes.
1028	*/
1029	RTDECL(int) RTPathUserHome(char *pszPath, size_t cchPath);
1030
1031	/**
1032	* Gets the user documents directory.
1033	*
1034	* The returned path isn't guaranteed to exist.
1035	*
1036	* @returns iprt status code.
1037	* @param pszPath Buffer where to store the path.
1038	* @param cchPath Buffer size in bytes.
1039	*/
1040	RTDECL(int) RTPathUserDocuments(char *pszPath, size_t cchPath);
1041
1042	/**
1043	* Gets the directory of shared libraries.
1044	*
1045	* This is not the same as RTPathAppPrivateArch() as Linux depends all shared
1046	* libraries in a common global directory where ld.so can find them.
1047	*
1048	* Linux: /usr/lib
1049	* Solaris: /opt/@<application@>/@<arch>@ or something
1050	* Windows: @<program files directory@>/@<application@>
1051	* Old path: same as RTPathExecDir()
1052	*
1053	* @returns iprt status code.
1054	* @param pszPath Buffer where to store the path.
1055	* @param cchPath Buffer size in bytes.
1056	*/
1057	RTDECL(int) RTPathSharedLibs(char *pszPath, size_t cchPath);
1058
1059	/**
1060	* Gets the directory for architecture-independent application data, for
1061	* example NLS files, module sources, ...
1062	*
1063	* Linux: /usr/shared/@<application@>
1064	* Solaris: /opt/@<application@>
1065	* Windows: @<program files directory@>/@<application@>
1066	* Old path: same as RTPathExecDir()
1067	*
1068	* @returns iprt status code.
1069	* @param pszPath Buffer where to store the path.
1070	* @param cchPath Buffer size in bytes.
1071	*/
1072	RTDECL(int) RTPathAppPrivateNoArch(char *pszPath, size_t cchPath);
1073
1074	/**
1075	* Gets the directory for architecture-dependent application data, for
1076	* example modules which can be loaded at runtime.
1077	*
1078	* Linux: /usr/lib/@<application@>
1079	* Solaris: /opt/@<application@>/@<arch>@ or something
1080	* Windows: @<program files directory@>/@<application@>
1081	* Old path: same as RTPathExecDir()
1082	*
1083	* @returns iprt status code.
1084	* @param pszPath Buffer where to store the path.
1085	* @param cchPath Buffer size in bytes.
1086	*/
1087	RTDECL(int) RTPathAppPrivateArch(char *pszPath, size_t cchPath);
1088
1089	/**
1090	* Gets the toplevel directory for architecture-dependent application data.
1091	*
1092	* This differs from RTPathAppPrivateArch on Solaris only where it will work
1093	* around the /opt/@<application@>/amd64 and /opt/@<application@>/i386 multi
1094	* architecture installation style.
1095	*
1096	* Linux: /usr/lib/@<application@>
1097	* Solaris: /opt/@<application@>
1098	* Windows: @<program files directory@>/@<application@>
1099	* Old path: same as RTPathExecDir()
1100	*
1101	* @returns iprt status code.
1102	* @param pszPath Buffer where to store the path.
1103	* @param cchPath Buffer size in bytes.
1104	*/
1105	RTDECL(int) RTPathAppPrivateArchTop(char *pszPath, size_t cchPath);
1106
1107	/**
1108	* Gets the directory for documentation.
1109	*
1110	* Linux: /usr/share/doc/@<application@>
1111	* Solaris: /opt/@<application@>
1112	* Windows: @<program files directory@>/@<application@>
1113	* Old path: same as RTPathExecDir()
1114	*
1115	* @returns iprt status code.
1116	* @param pszPath Buffer where to store the path.
1117	* @param cchPath Buffer size in bytes.
1118	*/
1119	RTDECL(int) RTPathAppDocs(char *pszPath, size_t cchPath);
1120
1121	/**
1122	* Gets the temporary directory path.
1123	*
1124	* @returns iprt status code.
1125	* @param pszPath Buffer where to store the path.
1126	* @param cchPath Buffer size in bytes.
1127	*/
1128	RTDECL(int) RTPathTemp(char *pszPath, size_t cchPath);
1129
1130	/**
1131	* Query information about a file system object.
1132	*
1133	* This API will resolve NOT symbolic links in the last component (just like
1134	* unix lstat()).
1135	*
1136	* @returns IPRT status code.
1137	* @retval VINF_SUCCESS if the object exists, information returned.
1138	* @retval VERR_PATH_NOT_FOUND if any but the last component in the specified
1139	* path was not found or was not a directory.
1140	* @retval VERR_FILE_NOT_FOUND if the object does not exist (but path to the
1141	* parent directory exists).
1142	*
1143	* @param pszPath Path to the file system object.
1144	* @param pObjInfo Object information structure to be filled on successful
1145	* return.
1146	* @param enmAdditionalAttribs
1147	* Which set of additional attributes to request.
1148	* Use RTFSOBJATTRADD_NOTHING if this doesn't matter.
1149	*/
1150	RTR3DECL(int) RTPathQueryInfo(const char *pszPath, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAdditionalAttribs);
1151
1152	/**
1153	* Query information about a file system object.
1154	*
1155	* @returns IPRT status code.
1156	* @retval VINF_SUCCESS if the object exists, information returned.
1157	* @retval VERR_PATH_NOT_FOUND if any but the last component in the specified
1158	* path was not found or was not a directory.
1159	* @retval VERR_FILE_NOT_FOUND if the object does not exist (but path to the
1160	* parent directory exists).
1161	*
1162	* @param pszPath Path to the file system object.
1163	* @param pObjInfo Object information structure to be filled on successful return.
1164	* @param enmAdditionalAttribs
1165	* Which set of additional attributes to request.
1166	* Use RTFSOBJATTRADD_NOTHING if this doesn't matter.
1167	* @param fFlags RTPATH_F_ON_LINK or RTPATH_F_FOLLOW_LINK.
1168	*/
1169	RTR3DECL(int) RTPathQueryInfoEx(const char *pszPath, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAdditionalAttribs, uint32_t fFlags);
1170
1171	/**
1172	* Changes the mode flags of a file system object.
1173	*
1174	* The API requires at least one of the mode flag sets (Unix/Dos) to
1175	* be set. The type is ignored.
1176	*
1177	* This API will resolve symbolic links in the last component since
1178	* mode isn't important for symbolic links.
1179	*
1180	* @returns iprt status code.
1181	* @param pszPath Path to the file system object.
1182	* @param fMode The new file mode, see @ref grp_rt_fs for details.
1183	*/
1184	RTR3DECL(int) RTPathSetMode(const char *pszPath, RTFMODE fMode);
1185
1186	/**
1187	* Gets the mode flags of a file system object.
1188	*
1189	* @returns iprt status code.
1190	* @param pszPath Path to the file system object.
1191	* @param pfMode Where to store the file mode, see @ref grp_rt_fs for details.
1192	*
1193	* @remark This is wrapper around RTPathQueryInfoEx(RTPATH_F_FOLLOW_LINK) and
1194	* exists to complement RTPathSetMode().
1195	*/
1196	RTR3DECL(int) RTPathGetMode(const char *pszPath, PRTFMODE pfMode);
1197
1198	/**
1199	* Changes one or more of the timestamps associated of file system object.
1200	*
1201	* This API will not resolve symbolic links in the last component (just
1202	* like unix lutimes()).
1203	*
1204	* @returns iprt status code.
1205	* @param pszPath Path to the file system object.
1206	* @param pAccessTime Pointer to the new access time.
1207	* @param pModificationTime Pointer to the new modification time.
1208	* @param pChangeTime Pointer to the new change time. NULL if not to be changed.
1209	* @param pBirthTime Pointer to the new time of birth. NULL if not to be changed.
1210	*
1211	* @remark The file system might not implement all these time attributes,
1212	* the API will ignore the ones which aren't supported.
1213	*
1214	* @remark The file system might not implement the time resolution
1215	* employed by this interface, the time will be chopped to fit.
1216	*
1217	* @remark The file system may update the change time even if it's
1218	* not specified.
1219	*
1220	* @remark POSIX can only set Access & Modification and will always set both.
1221	*/
1222	RTR3DECL(int) RTPathSetTimes(const char *pszPath, PCRTTIMESPEC pAccessTime, PCRTTIMESPEC pModificationTime,
1223	PCRTTIMESPEC pChangeTime, PCRTTIMESPEC pBirthTime);
1224
1225	/**
1226	* Changes one or more of the timestamps associated of file system object.
1227	*
1228	* @returns iprt status code.
1229	* @param pszPath Path to the file system object.
1230	* @param pAccessTime Pointer to the new access time.
1231	* @param pModificationTime Pointer to the new modification time.
1232	* @param pChangeTime Pointer to the new change time. NULL if not to be changed.
1233	* @param pBirthTime Pointer to the new time of birth. NULL if not to be changed.
1234	* @param fFlags RTPATH_F_ON_LINK or RTPATH_F_FOLLOW_LINK.
1235	*
1236	* @remark The file system might not implement all these time attributes,
1237	* the API will ignore the ones which aren't supported.
1238	*
1239	* @remark The file system might not implement the time resolution
1240	* employed by this interface, the time will be chopped to fit.
1241	*
1242	* @remark The file system may update the change time even if it's
1243	* not specified.
1244	*
1245	* @remark POSIX can only set Access & Modification and will always set both.
1246	*/
1247	RTR3DECL(int) RTPathSetTimesEx(const char *pszPath, PCRTTIMESPEC pAccessTime, PCRTTIMESPEC pModificationTime,
1248	PCRTTIMESPEC pChangeTime, PCRTTIMESPEC pBirthTime, uint32_t fFlags);
1249
1250	/**
1251	* Gets one or more of the timestamps associated of file system object.
1252	*
1253	* @returns iprt status code.
1254	* @param pszPath Path to the file system object.
1255	* @param pAccessTime Where to store the access time. NULL is ok.
1256	* @param pModificationTime Where to store the modification time. NULL is ok.
1257	* @param pChangeTime Where to store the change time. NULL is ok.
1258	* @param pBirthTime Where to store the creation time. NULL is ok.
1259	*
1260	* @remark This is wrapper around RTPathQueryInfo() and exists to complement
1261	* RTPathSetTimes(). If the last component is a symbolic link, it will
1262	* not be resolved.
1263	*/
1264	RTR3DECL(int) RTPathGetTimes(const char *pszPath, PRTTIMESPEC pAccessTime, PRTTIMESPEC pModificationTime,
1265	PRTTIMESPEC pChangeTime, PRTTIMESPEC pBirthTime);
1266
1267	/**
1268	* Changes the owner and/or group of a file system object.
1269	*
1270	* This API will not resolve symbolic links in the last component (just
1271	* like unix lchown()).
1272	*
1273	* @returns iprt status code.
1274	* @param pszPath Path to the file system object.
1275	* @param uid The new file owner user id. Pass NIL_RTUID to leave
1276	* this unchanged.
1277	* @param gid The new group id. Pass NIL_RTGUID to leave this
1278	* unchanged.
1279	*/
1280	RTR3DECL(int) RTPathSetOwner(const char *pszPath, uint32_t uid, uint32_t gid);
1281
1282	/**
1283	* Changes the owner and/or group of a file system object.
1284	*
1285	* @returns iprt status code.
1286	* @param pszPath Path to the file system object.
1287	* @param uid The new file owner user id. Pass NIL_RTUID to leave
1288	* this unchanged.
1289	* @param gid The new group id. Pass NIL_RTGID to leave this
1290	* unchanged.
1291	* @param fFlags RTPATH_F_ON_LINK or RTPATH_F_FOLLOW_LINK.
1292	*/
1293	RTR3DECL(int) RTPathSetOwnerEx(const char *pszPath, uint32_t uid, uint32_t gid, uint32_t fFlags);
1294
1295	/**
1296	* Gets the owner and/or group of a file system object.
1297	*
1298	* @returns iprt status code.
1299	* @param pszPath Path to the file system object.
1300	* @param pUid Where to store the owner user id. NULL is ok.
1301	* @param pGid Where to store the group id. NULL is ok.
1302	*
1303	* @remark This is wrapper around RTPathQueryInfo() and exists to complement
1304	* RTPathGetOwner(). If the last component is a symbolic link, it will
1305	* not be resolved.
1306	*/
1307	RTR3DECL(int) RTPathGetOwner(const char pszPath, uint32_t pUid, uint32_t *pGid);
1308
1309
1310	/** @name RTPathRename, RTDirRename & RTFileRename flags.
1311	* @{ */
1312	/** Do not replace anything. */
1313	#define RTPATHRENAME_FLAGS_NO_REPLACE UINT32_C(0)
1314	/** This will replace attempt any target which isn't a directory. */
1315	#define RTPATHRENAME_FLAGS_REPLACE RT_BIT(0)
1316	/** Don't allow symbolic links as part of the path.
1317	* @remarks this flag is currently not implemented and will be ignored. */
1318	#define RTPATHRENAME_FLAGS_NO_SYMLINKS RT_BIT(1)
1319	/** @} */
1320
1321	/**
1322	* Renames a path within a filesystem.
1323	*
1324	* This will rename symbolic links. If RTPATHRENAME_FLAGS_REPLACE is used and
1325	* pszDst is a symbolic link, it will be replaced and not its target.
1326	*
1327	* @returns IPRT status code.
1328	* @param pszSrc The source path.
1329	* @param pszDst The destination path.
1330	* @param fRename Rename flags, RTPATHRENAME_FLAGS_*.
1331	*/
1332	RTR3DECL(int) RTPathRename(const char pszSrc, const char pszDst, unsigned fRename);
1333
1334	/** @name RTPathUnlink flags.
1335	* @{ */
1336	/** Don't allow symbolic links as part of the path.
1337	* @remarks this flag is currently not implemented and will be ignored. */
1338	#define RTPATHUNLINK_FLAGS_NO_SYMLINKS RT_BIT(0)
1339	/** @} */
1340
1341	/**
1342	* Removes the last component of the path.
1343	*
1344	* @returns IPRT status code.
1345	* @param pszPath The path.
1346	* @param fUnlink Unlink flags, RTPATHUNLINK_FLAGS_*.
1347	*/
1348	RTR3DECL(int) RTPathUnlink(const char *pszPath, uint32_t fUnlink);
1349
1350	/**
1351	* A /bin/rm tool.
1352	*
1353	* @returns Program exit code.
1354	*
1355	* @param cArgs The number of arguments.
1356	* @param papszArgs The argument vector. (Note that this may be
1357	* reordered, so the memory must be writable.)
1358	*/
1359	RTDECL(RTEXITCODE) RTPathRmCmd(unsigned cArgs, char **papszArgs);
1360
1361	#endif /* IN_RING3 */
1362
1363	/** @} */
1364
1365	RT_C_DECLS_END
1366
1367	#endif
1368

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

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

Download in other formats: