path.h@ 46050

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

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

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

Download in other formats: