VirtualBox

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

Last change on this file since 7329 was 7170, checked in by vboxsync, 17 years ago

Doxygen fixes. (DOXYGEN -> DOXYGEN_RUNNING, ++)

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 17.0 KB
Line 
1/** @file
2 * innotek Portable Runtime - Path Manipulation.
3 */
4
5/*
6 * Copyright (C) 2006-2007 innotek GmbH
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__BEGIN_DECLS
38
39/** @defgroup grp_rt_path RTPath - Path Manipulation
40 * @ingroup grp_rt
41 * @{
42 */
43
44
45/** @def RTPATH_SLASH
46 * The prefered slash character.
47 *
48 * @remark IPRT will always accept unix slashes. So, normally you would
49 * never have to use this define.
50 */
51#if defined(RT_OS_OS2) || defined(RT_OS_WINDOWS)
52# define RTPATH_SLASH '\\'
53#else
54# define RTPATH_SLASH '/'
55#endif
56
57/** @deprecated Use '/'! */
58#define RTPATH_DELIMITER RTPATH_SLASH
59
60
61/** @def RTPATH_SLASH_STR
62 * The prefered slash character as a string, handy for concatenations
63 * with other strings.
64 *
65 * @remark IPRT will always accept unix slashes. So, normally you would
66 * never have to use this define.
67 */
68#if defined(RT_OS_OS2) || defined(RT_OS_WINDOWS)
69# define RTPATH_SLASH_STR "\\"
70#else
71# define RTPATH_SLASH_STR "/"
72#endif
73
74
75/** @def RTPATH_IS_SLASH
76 * Checks if a character is a slash.
77 *
78 * @returns true if it's a slash and false if not.
79 * @returns @param ch Char to check.
80 */
81#if defined(RT_OS_OS2) || defined(RT_OS_WINDOWS)
82# define RTPATH_IS_SLASH(ch) ( (ch) == '\\' || (ch) == '/' )
83#else
84# define RTPATH_IS_SLASH(ch) ( (ch) == '/' )
85#endif
86
87
88/** @def RTPATH_IS_VOLSEP
89 * Checks if a character marks the end of the volume specification.
90 *
91 * @remark This is sufficent for the drive letter consept on PC.
92 * However it might be insufficient on other platforms
93 * and even on PC a UNC volume spec won't be detected this way.
94 * Use the RTPath@<too be created@>() instead.
95 *
96 * @returns true if it is and false if it isn't.
97 * @returns @param ch Char to check.
98 */
99#if defined(RT_OS_OS2) || defined(RT_OS_WINDOWS)
100# define RTPATH_IS_VOLSEP(ch) ( (ch) == ':' )
101#else
102# define RTPATH_IS_VOLSEP(ch) (false)
103#endif
104
105
106/** @def RTPATH_IS_SEP
107 * Checks if a character is path component separator
108 *
109 * @returns true if it is and false if it isn't.
110 * @returns @param ch Char to check.
111 * @
112 */
113#define RTPATH_IS_SEP(ch) ( RTPATH_IS_SLASH(ch) || RTPATH_IS_VOLSEP(ch) )
114
115
116/**
117 * Checks if the path exists.
118 *
119 * Symbolic links will all be attempted resolved.
120 *
121 * @returns true if it exists and false if it doesn't.
122 * @param pszPath The path to check.
123 */
124RTDECL(bool) RTPathExists(const char *pszPath);
125
126/**
127 * Get the real path (no symlinks, no . or .. components), must exist.
128 *
129 * @returns iprt status code.
130 * @param pszPath The path to resolve.
131 * @param pszRealPath Where to store the real path.
132 * @param cchRealPath Size of the buffer.
133 */
134RTDECL(int) RTPathReal(const char *pszPath, char *pszRealPath, unsigned cchRealPath);
135
136/**
137 * Same as RTPathReal only the result is RTStrDup()'ed.
138 *
139 * @returns Pointer to real path. Use RTStrFree() to free this string.
140 * @returns NULL if RTPathReal() or RTStrDup() fails.
141 * @param pszPath The path to resolve.
142 */
143RTDECL(char *) RTPathRealDup(const char *pszPath);
144
145/**
146 * Get the absolute path (no symlinks, no . or .. components), doesn't have to exist.
147 *
148 * @returns iprt status code.
149 * @param pszPath The path to resolve.
150 * @param pszAbsPath Where to store the absolute path.
151 * @param cchAbsPath Size of the buffer.
152 */
153RTDECL(int) RTPathAbs(const char *pszPath, char *pszAbsPath, unsigned cchAbsPath);
154
155/**
156 * Same as RTPathAbs only the result is RTStrDup()'ed.
157 *
158 * @returns Pointer to the absolute path. Use RTStrFree() to free this string.
159 * @returns NULL if RTPathAbs() or RTStrDup() fails.
160 * @param pszPath The path to resolve.
161 */
162RTDECL(char *) RTPathAbsDup(const char *pszPath);
163
164/**
165 * Get the absolute path (no symlinks, no . or .. components), assuming the
166 * given base path as the current directory. The resulting path doesn't have
167 * to exist.
168 *
169 * @returns iprt status code.
170 * @param pszBase The base path to act like a current directory.
171 * When NULL, the actual cwd is used (i.e. the call
172 * is equivalent to RTPathAbs(pszPath, ...).
173 * @param pszPath The path to resolve.
174 * @param pszAbsPath Where to store the absolute path.
175 * @param cchAbsPath Size of the buffer.
176 */
177RTDECL(int) RTPathAbsEx(const char *pszBase, const char *pszPath, char *pszAbsPath, unsigned cchAbsPath);
178
179/**
180 * Same as RTPathAbsEx only the result is RTStrDup()'ed.
181 *
182 * @returns Pointer to the absolute path. Use RTStrFree() to free this string.
183 * @returns NULL if RTPathAbsEx() or RTStrDup() fails.
184 * @param pszBase The base path to act like a current directory.
185 * When NULL, the actual cwd is used (i.e. the call
186 * is equivalent to RTPathAbs(pszPath, ...).
187 * @param pszPath The path to resolve.
188 */
189RTDECL(char *) RTPathAbsExDup(const char *pszBase, const char *pszPath);
190
191/**
192 * Strips the filename from a path.
193 *
194 * @param pszPath Path which filename should be stripped.
195 * If only filename in the string a '.' will be returned.
196 */
197RTDECL(void) RTPathStripFilename(char *pszPath);
198
199/**
200 * Strips the extension from a path.
201 *
202 * @param pszPath Path which extension should be stripped.
203 */
204RTDECL(void) RTPathStripExt(char *pszPath);
205
206/**
207 * Strips the trailing slashes of a path name.
208 *
209 * @param pszPath Path to strip.
210 */
211RTDECL(void) RTPathStripTrailingSlash(char *pszPath);
212
213/**
214 * Finds the filename in a path.
215 *
216 * @returns Pointer to filename within pszPath.
217 * @returns NULL if no filename (i.e. empty string or ends with a slash).
218 * @param pszPath Path to find filename in.
219 */
220RTDECL(char *) RTPathFilename(const char *pszPath);
221
222/**
223 * Finds the extension part of in a path.
224 *
225 * @returns Pointer to extension within pszPath.
226 * @returns NULL if no extension.
227 * @param pszPath Path to find extension in.
228 */
229RTDECL(char *) RTPathExt(const char *pszPath);
230
231/**
232 * Checks if a path have an extension.
233 *
234 * @returns true if extension present.
235 * @returns false if no extension.
236 * @param pszPath Path to check.
237 */
238RTDECL(bool) RTPathHaveExt(const char *pszPath);
239
240/**
241 * Checks if a path includes more than a filename.
242 *
243 * @returns true if path present.
244 * @returns false if no path.
245 * @param pszPath Path to check.
246 */
247RTDECL(bool) RTPathHavePath(const char *pszPath);
248
249/**
250 * Compares two paths.
251 *
252 * The comparison takes platform-dependent details into account,
253 * such as:
254 * <ul>
255 * <li>On DOS-like platforms, both |\| and |/| separator chars are considered
256 * to be equal.
257 * <li>On platforms with case-insensitive file systems, mismatching characters
258 * are uppercased and compared again.
259 * </ul>
260 *
261 * File system details are currently ignored. This means that you won't get
262 * case-insentive compares on unix systems when a path goes into a case-insensitive
263 * filesystem like FAT, HPFS, HFS, NTFS, JFS, or similar. For NT, OS/2 and similar
264 * you'll won't get case-sensitve compares on a case-sensitive file system.
265 *
266 * @param pszPath1 Path to compare (must be an absolute path).
267 * @param pszPath2 Path to compare (must be an absolute path).
268 *
269 * @returns @< 0 if the first path less than the second path.
270 * @returns 0 if the first path identical to the second path.
271 * @returns @> 0 if the first path greater than the second path.
272 */
273RTDECL(int) RTPathCompare(const char *pszPath1, const char *pszPath2);
274
275/**
276 * Checks if a path starts with the given parent path.
277 *
278 * This means that either the path and the parent path matches completely, or that
279 * the path is to some file or directory residing in the tree given by the parent
280 * directory.
281 *
282 * The path comparison takes platform-dependent details into account,
283 * see RTPathCompare() for details.
284 *
285 * @param pszPath Path to check, must be an absolute path.
286 * @param pszParentPath Parent path, must be an absolute path.
287 * No trailing directory slash!
288 *
289 * @returns |true| when \a pszPath starts with \a pszParentPath (or when they
290 * are identical), or |false| otherwise.
291 *
292 * @remark This API doesn't currently handle root directory compares in a manner
293 * consistant with the other APIs. RTPathStartsWith(pszSomePath, "/") will
294 * not work if pszSomePath isn't "/".
295 */
296RTDECL(bool) RTPathStartsWith(const char *pszPath, const char *pszParentPath);
297
298
299#ifdef IN_RING3
300
301/**
302 * Gets the program path.
303 *
304 * @returns iprt status code.
305 * @param pszPath Buffer where to store the path.
306 * @param cchPath Buffer size in bytes.
307 */
308RTDECL(int) RTPathProgram(char *pszPath, unsigned cchPath);
309
310/**
311 * Gets the user home directory.
312 *
313 * @returns iprt status code.
314 * @param pszPath Buffer where to store the path.
315 * @param cchPath Buffer size in bytes.
316 */
317RTDECL(int) RTPathUserHome(char *pszPath, unsigned cchPath);
318
319/**
320 * Gets the directory of shared libraries. This is not the same as
321 * RTPathAppPrivateArch() as Linux depends all shared libraries in
322 * a common global directory where ld.so can found them.
323 *
324 * Linux: /usr/lib
325 * Windows: @<program files directory@>/@<application@>
326 * Old path: same as RTPathProgram()
327 *
328 * @returns iprt status code.
329 * @param pszPath Buffer where to store the path.
330 * @param cchPath Buffer size in bytes.
331 */
332RTDECL(int) RTPathSharedLibs(char *pszPath, unsigned cchPath);
333
334/**
335 * Gets the directory for architecture-independent application data, for
336 * example NLS files, module sources, ...
337 *
338 * Linux: /usr/shared/@<application@>
339 * Windows: @<program files directory@>/@<application@>
340 * Old path: same as RTPathProgram()
341 *
342 * @returns iprt status code.
343 * @param pszPath Buffer where to store the path.
344 * @param cchPath Buffer size in bytes.
345 */
346RTDECL(int) RTPathAppPrivateNoArch(char *pszPath, unsigned cchPath);
347
348/**
349 * Gets the directory for architecture-dependent application data, for
350 * example modules which can be loaded at runtime.
351 *
352 * Linux: /usr/lib/@<application@>
353 * Windows: @<program files directory@>/@<application@>
354 * Old path: same as RTPathProgram()
355 *
356 * @returns iprt status code.
357 * @param pszPath Buffer where to store the path.
358 * @param cchPath Buffer size in bytes.
359 */
360RTDECL(int) RTPathAppPrivateArch(char *pszPath, unsigned cchPath);
361
362/**
363 * Gets the directory for documentation.
364 *
365 * Linux: /usr/share/doc/@<application@>
366 * Windows: @<program files directory@>/@<application@>
367 * Old path: same as RTPathProgram()
368 *
369 * @returns iprt status code.
370 * @param pszPath Buffer where to store the path.
371 * @param cchPath Buffer size in bytes.
372 */
373RTDECL(int) RTPathAppDocs(char *pszPath, unsigned cchPath);
374
375/**
376 * Query information about a file system object.
377 *
378 * This API will not resolve symbolic links in the last component (just
379 * like unix lstat()).
380 *
381 * @returns VINF_SUCCESS if the object exists, information returned.
382 * @returns VERR_PATH_NOT_FOUND if any but the last component in the specified
383 * path was not found or was not a directory.
384 * @returns VERR_FILE_NOT_FOUND if the object does not exist (but path to the
385 * parent directory exists).
386 * @returns some other iprt status code.
387 *
388 * @param pszPath Path to the file system object.
389 * @param pObjInfo Object information structure to be filled on successful return.
390 * @param enmAdditionalAttribs
391 * Which set of additional attributes to request.
392 * Use RTFSOBJATTRADD_NOTHING if this doesn't matter.
393 */
394RTR3DECL(int) RTPathQueryInfo(const char *pszPath, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAdditionalAttribs);
395
396/**
397 * Changes the mode flags of a file system object.
398 *
399 * The API requires at least one of the mode flag sets (Unix/Dos) to
400 * be set. The type is ignored.
401 *
402 * This API will resolve symbolic links in the last component since
403 * mode isn't important for symbolic links.
404 *
405 * @returns iprt status code.
406 * @param pszPath Path to the file system object.
407 * @param fMode The new file mode, see @ref grp_rt_fs for details.
408 */
409RTR3DECL(int) RTPathSetMode(const char *pszPath, RTFMODE fMode);
410
411/**
412 * Gets the mode flags of a file system object.
413 *
414 * @returns iprt status code.
415 * @param pszPath Path to the file system object.
416 * @param pfMode Where to store the file mode, see @ref grp_rt_fs for details.
417 *
418 * @remark This is wrapper around RTPathReal() + RTPathQueryInfo()
419 * and exists to complement RTPathSetMode().
420 */
421RTR3DECL(int) RTPathGetMode(const char *pszPath, PRTFMODE pfMode);
422
423/**
424 * Changes one or more of the timestamps associated of file system object.
425 *
426 * This API will not resolve symbolic links in the last component (just
427 * like unix lutimes()).
428 *
429 * @returns iprt status code.
430 * @param pszPath Path to the file system object.
431 * @param pAccessTime Pointer to the new access time.
432 * @param pModificationTime Pointer to the new modifcation time.
433 * @param pChangeTime Pointer to the new change time. NULL if not to be changed.
434 * @param pBirthTime Pointer to the new time of birth. NULL if not to be changed.
435 *
436 * @remark The file system might not implement all these time attributes,
437 * the API will ignore the ones which aren't supported.
438 *
439 * @remark The file system might not implement the time resolution
440 * employed by this interface, the time will be chopped to fit.
441 *
442 * @remark The file system may update the change time even if it's
443 * not specified.
444 *
445 * @remark POSIX can only set Access & Modification and will always set both.
446 */
447RTR3DECL(int) RTPathSetTimes(const char *pszPath, PCRTTIMESPEC pAccessTime, PCRTTIMESPEC pModificationTime,
448 PCRTTIMESPEC pChangeTime, PCRTTIMESPEC pBirthTime);
449
450/**
451 * Gets one or more of the timestamps associated of file system object.
452 *
453 * @returns iprt status code.
454 * @param pszPath Path to the file system object.
455 * @param pAccessTime Where to store the access time. NULL is ok.
456 * @param pModificationTime Where to store the modifcation time. NULL is ok.
457 * @param pChangeTime Where to store the change time. NULL is ok.
458 * @param pBirthTime Where to store the creation time. NULL is ok.
459 *
460 * @remark This is wrapper around RTPathQueryInfo() and exists to complement RTPathSetTimes().
461 */
462RTR3DECL(int) RTPathGetTimes(const char *pszPath, PRTTIMESPEC pAccessTime, PRTTIMESPEC pModificationTime,
463 PRTTIMESPEC pChangeTime, PRTTIMESPEC pBirthTime);
464
465/**
466 * Changes the owner and/or group of a file system object.
467 *
468 * This API will not resolve symbolic links in the last component (just
469 * like unix lchown()).
470 *
471 * @returns iprt status code.
472 * @param pszPath Path to the file system object.
473 * @param uid The new file owner user id. Use -1 (or ~0) to leave this unchanged.
474 * @param gid The new group id. Use -1 (or ~0) to leave this unchanged.
475 */
476RTR3DECL(int) RTPathSetOwner(const char *pszPath, uint32_t uid, uint32_t gid);
477
478/**
479 * Gets the owner and/or group of a file system object.
480 *
481 * @returns iprt status code.
482 * @param pszPath Path to the file system object.
483 * @param pUid Where to store the owner user id. NULL is ok.
484 * @param pGid Where to store the group id. NULL is ok.
485 *
486 * @remark This is wrapper around RTPathQueryInfo() and exists to complement RTPathGetOwner().
487 */
488RTR3DECL(int) RTPathGetOwner(const char *pszPath, uint32_t *pUid, uint32_t *pGid);
489
490
491/** @name RTPathRename, RTDirRename & RTFileRename flags.
492 * @{ */
493/** This will replace attempt any target which isn't a directory. */
494#define RTPATHRENAME_FLAGS_REPLACE RT_BIT(0)
495/** @} */
496
497/**
498 * Renames a path within a filesystem.
499 *
500 * @returns IPRT status code.
501 * @param pszSrc The source path.
502 * @param pszDst The destination path.
503 * @param fRename Rename flags, RTPATHRENAME_FLAGS_*.
504 */
505RTR3DECL(int) RTPathRename(const char *pszSrc, const char *pszDst, unsigned fRename);
506
507#endif /* IN_RING3 */
508
509/** @} */
510
511__END_DECLS
512
513#endif
514
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette