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