1 | /** @file
|
---|
2 | * IPRT - Directory Manipulation.
|
---|
3 | */
|
---|
4 |
|
---|
5 | /*
|
---|
6 | * Copyright (C) 2006-2010 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_dir_h
|
---|
27 | #define ___iprt_dir_h
|
---|
28 |
|
---|
29 | #include <iprt/cdefs.h>
|
---|
30 | #include <iprt/types.h>
|
---|
31 | #include <iprt/fs.h>
|
---|
32 |
|
---|
33 |
|
---|
34 | RT_C_DECLS_BEGIN
|
---|
35 |
|
---|
36 | /** @defgroup grp_rt_dir RTDir - Directory Manipulation
|
---|
37 | * @ingroup grp_rt
|
---|
38 | * @{
|
---|
39 | */
|
---|
40 |
|
---|
41 | /**
|
---|
42 | * Check for the existence of a directory.
|
---|
43 | *
|
---|
44 | * All symbolic links will be attemped resolved. If that is undesirable, please
|
---|
45 | * use RTPathQueryInfo instead.
|
---|
46 | *
|
---|
47 | * @returns true if exist and is a directory.
|
---|
48 | * @returns false if not exists or isn't a directory.
|
---|
49 | * @param pszPath Path to the directory.
|
---|
50 | */
|
---|
51 | RTDECL(bool) RTDirExists(const char *pszPath);
|
---|
52 |
|
---|
53 | /**
|
---|
54 | * Creates a directory.
|
---|
55 | *
|
---|
56 | * @returns iprt status code.
|
---|
57 | * @param pszPath Path to the directory to create.
|
---|
58 | * @param fMode The mode of the new directory.
|
---|
59 | */
|
---|
60 | RTDECL(int) RTDirCreate(const char *pszPath, RTFMODE fMode);
|
---|
61 |
|
---|
62 | /**
|
---|
63 | * Creates a directory including all parent directories in the path
|
---|
64 | * if they don't exist.
|
---|
65 | *
|
---|
66 | * @returns iprt status code.
|
---|
67 | * @param pszPath Path to the directory to create.
|
---|
68 | * @param fMode The mode of the new directories.
|
---|
69 | */
|
---|
70 | RTDECL(int) RTDirCreateFullPath(const char *pszPath, RTFMODE fMode);
|
---|
71 |
|
---|
72 | /**
|
---|
73 | * Creates a new directory with a unique name using the given template.
|
---|
74 | *
|
---|
75 | * One or more trailing X'es in the template will be replaced by random alpha
|
---|
76 | * numeric characters until a RTDirCreate succeeds or we run out of patience.
|
---|
77 | * For instance:
|
---|
78 | * "/tmp/myprog-XXXXXX"
|
---|
79 | *
|
---|
80 | * As an alternative to trailing X'es, it
|
---|
81 | * is possible to put 3 or more X'es somewhere inside the directory name. In
|
---|
82 | * the following string only the last bunch of X'es will be modified:
|
---|
83 | * "/tmp/myprog-XXX-XXX.tmp"
|
---|
84 | *
|
---|
85 | * The directory is created with mode 0700.
|
---|
86 | *
|
---|
87 | * @returns iprt status code.
|
---|
88 | * @param pszTemplate The directory name template on input. The actual
|
---|
89 | * directory name on success. Empty string on failure.
|
---|
90 | */
|
---|
91 | RTDECL(int) RTDirCreateTemp(char *pszTemplate);
|
---|
92 |
|
---|
93 | /**
|
---|
94 | * Creates a new directory with a unique name by appending a number.
|
---|
95 | *
|
---|
96 | * First it is tried to create the directory without any numbers appended.
|
---|
97 | * When this fails a number string is appended (starting with 1) separated by
|
---|
98 | * the optional separator. The numbers are zero padded.
|
---|
99 | *
|
---|
100 | * On success @a pszPath contains the path created.
|
---|
101 | *
|
---|
102 | * @returns iprt status code.
|
---|
103 | * @param pszPath Path to the directory to create.
|
---|
104 | * @param cbSize The size of pszPath. Needs enough space for holding the
|
---|
105 | * digits and the optional separator.
|
---|
106 | * @param fMode The mode of the new directory.
|
---|
107 | * @param cchDigits How many digits should the number maximal have.
|
---|
108 | * @param chSep The separator used between the path and the number. Can
|
---|
109 | * be zero. (optional)
|
---|
110 | */
|
---|
111 | RTDECL(int) RTDirCreateUniqueNumbered(char *pszPath, size_t cbSize, RTFMODE fMode, signed int cchDigits, char chSep);
|
---|
112 |
|
---|
113 | /**
|
---|
114 | * Removes a directory if empty.
|
---|
115 | *
|
---|
116 | * @returns iprt status code.
|
---|
117 | * @param pszPath Path to the directory to remove.
|
---|
118 | */
|
---|
119 | RTDECL(int) RTDirRemove(const char *pszPath);
|
---|
120 |
|
---|
121 | /**
|
---|
122 | * Removes a directory tree recursively.
|
---|
123 | *
|
---|
124 | * @returns iprt status code.
|
---|
125 | * @param pszPath Path to the directory to remove recursively.
|
---|
126 | * @param fFlags Flags, see RTDIRRMREC_F_XXX.
|
---|
127 | *
|
---|
128 | * @remarks This will not work on a root directory.
|
---|
129 | */
|
---|
130 | RTDECL(int) RTDirRemoveRecursive(const char *pszPath, uint32_t fFlags);
|
---|
131 |
|
---|
132 | /** @name RTDirRemoveRecursive flags.
|
---|
133 | * @{ */
|
---|
134 | /** Delete the content of the directory and the directory itself. */
|
---|
135 | #define RTDIRRMREC_F_CONTENT_AND_DIR UINT32_C(0)
|
---|
136 | /** Only delete the content of the directory, omit the directory it self. */
|
---|
137 | #define RTDIRRMREC_F_CONTENT_ONLY RT_BIT_32(0)
|
---|
138 | /** Mask of valid flags. */
|
---|
139 | #define RTDIRRMREC_F_VALID_MASK UINT32_C(0x00000001)
|
---|
140 | /** @} */
|
---|
141 |
|
---|
142 | /**
|
---|
143 | * Flushes the specified directory.
|
---|
144 | *
|
---|
145 | * This API is not implemented on all systems. On some systems it may be
|
---|
146 | * unnecessary if you've already flushed the file. If you really care for your
|
---|
147 | * data and is entering dangerous territories, it doesn't hurt calling it after
|
---|
148 | * flushing and closing the file.
|
---|
149 | *
|
---|
150 | * @returns IPRT status code.
|
---|
151 | * @retval VERR_NOT_IMPLEMENTED must be expected.
|
---|
152 | * @retval VERR_NOT_SUPPORTED must be expected.
|
---|
153 | * @param pszPath Path to the directory.
|
---|
154 | */
|
---|
155 | RTDECL(int) RTDirFlush(const char *pszPath);
|
---|
156 |
|
---|
157 | /**
|
---|
158 | * Flushes the parent directory of the specified file.
|
---|
159 | *
|
---|
160 | * This is just a wrapper around RTDirFlush.
|
---|
161 | *
|
---|
162 | * @returns IPRT status code, see RTDirFlush for details.
|
---|
163 | * @param pszChild Path to the file which parent should be flushed.
|
---|
164 | */
|
---|
165 | RTDECL(int) RTDirFlushParent(const char *pszChild);
|
---|
166 |
|
---|
167 |
|
---|
168 | /** Pointer to an open directory (sort of handle). */
|
---|
169 | typedef struct RTDIR *PRTDIR;
|
---|
170 |
|
---|
171 |
|
---|
172 | /**
|
---|
173 | * Filter option for RTDirOpenFiltered().
|
---|
174 | */
|
---|
175 | typedef enum RTDIRFILTER
|
---|
176 | {
|
---|
177 | /** The usual invalid 0 entry. */
|
---|
178 | RTDIRFILTER_INVALID = 0,
|
---|
179 | /** No filter should be applied (and none was specified). */
|
---|
180 | RTDIRFILTER_NONE,
|
---|
181 | /** The Windows NT filter.
|
---|
182 | * The following wildcard chars: *, ?, <, > and "
|
---|
183 | * The matching is done on the uppercased strings. */
|
---|
184 | RTDIRFILTER_WINNT,
|
---|
185 | /** The UNIX filter.
|
---|
186 | * The following wildcard chars: *, ?, [..]
|
---|
187 | * The matching is done on exact case. */
|
---|
188 | RTDIRFILTER_UNIX,
|
---|
189 | /** The UNIX filter, uppercased matching.
|
---|
190 | * Same as RTDIRFILTER_UNIX except that the strings are uppercased before comparing. */
|
---|
191 | RTDIRFILTER_UNIX_UPCASED,
|
---|
192 |
|
---|
193 | /** The usual full 32-bit value. */
|
---|
194 | RTDIRFILTER_32BIT_HACK = 0x7fffffff
|
---|
195 | } RTDIRFILTER;
|
---|
196 |
|
---|
197 |
|
---|
198 | /**
|
---|
199 | * Directory entry type.
|
---|
200 | *
|
---|
201 | * This is the RTFS_TYPE_MASK stuff shifted down 12 bits and
|
---|
202 | * identical to the BSD/LINUX ABI.
|
---|
203 | */
|
---|
204 | typedef enum RTDIRENTRYTYPE
|
---|
205 | {
|
---|
206 | /** Unknown type (DT_UNKNOWN). */
|
---|
207 | RTDIRENTRYTYPE_UNKNOWN = 0,
|
---|
208 | /** Named pipe (fifo) (DT_FIFO). */
|
---|
209 | RTDIRENTRYTYPE_FIFO = 001,
|
---|
210 | /** Character device (DT_CHR). */
|
---|
211 | RTDIRENTRYTYPE_DEV_CHAR = 002,
|
---|
212 | /** Directory (DT_DIR). */
|
---|
213 | RTDIRENTRYTYPE_DIRECTORY = 004,
|
---|
214 | /** Block device (DT_BLK). */
|
---|
215 | RTDIRENTRYTYPE_DEV_BLOCK = 006,
|
---|
216 | /** Regular file (DT_REG). */
|
---|
217 | RTDIRENTRYTYPE_FILE = 010,
|
---|
218 | /** Symbolic link (DT_LNK). */
|
---|
219 | RTDIRENTRYTYPE_SYMLINK = 012,
|
---|
220 | /** Socket (DT_SOCK). */
|
---|
221 | RTDIRENTRYTYPE_SOCKET = 014,
|
---|
222 | /** Whiteout (DT_WHT). */
|
---|
223 | RTDIRENTRYTYPE_WHITEOUT = 016
|
---|
224 | } RTDIRENTRYTYPE;
|
---|
225 |
|
---|
226 |
|
---|
227 | /**
|
---|
228 | * Directory entry.
|
---|
229 | *
|
---|
230 | * This is inspired by the POSIX interfaces.
|
---|
231 | */
|
---|
232 | #pragma pack(1)
|
---|
233 | typedef struct RTDIRENTRY
|
---|
234 | {
|
---|
235 | /** The unique identifier (within the file system) of this file system object (d_ino).
|
---|
236 | *
|
---|
237 | * Together with INodeIdDevice, this field can be used as a OS wide unique id
|
---|
238 | * when both their values are not 0. This field is 0 if the information is not
|
---|
239 | * available. */
|
---|
240 | RTINODE INodeId;
|
---|
241 | /** The entry type. (d_type)
|
---|
242 | * RTDIRENTRYTYPE_UNKNOWN is a common return value here since not all file
|
---|
243 | * systems (or Unixes) stores the type of a directory entry and instead
|
---|
244 | * expects the user to use stat() to get it. So, when you see this you
|
---|
245 | * should use RTPathQueryInfo to get the type, or if if you're lazy, use
|
---|
246 | * RTDirReadEx. */
|
---|
247 | RTDIRENTRYTYPE enmType;
|
---|
248 | /** The length of the filename, excluding the terminating nul character. */
|
---|
249 | uint16_t cbName;
|
---|
250 | /** The filename. (no path)
|
---|
251 | * Using the pcbDirEntry parameter of RTDirRead makes this field variable in size. */
|
---|
252 | char szName[260];
|
---|
253 | } RTDIRENTRY;
|
---|
254 | #pragma pack()
|
---|
255 | /** Pointer to a directory entry. */
|
---|
256 | typedef RTDIRENTRY *PRTDIRENTRY;
|
---|
257 |
|
---|
258 |
|
---|
259 | /**
|
---|
260 | * Directory entry with extended information.
|
---|
261 | *
|
---|
262 | * This is inspired by the PC interfaces.
|
---|
263 | */
|
---|
264 | #pragma pack(1)
|
---|
265 | typedef struct RTDIRENTRYEX
|
---|
266 | {
|
---|
267 | /** Full information about the object. */
|
---|
268 | RTFSOBJINFO Info;
|
---|
269 | /** The length of the short field (number of RTUTF16 entries (not chars)).
|
---|
270 | * It is 16-bit for reasons of alignment. */
|
---|
271 | uint16_t cwcShortName;
|
---|
272 | /** The short name for 8.3 compatibility.
|
---|
273 | * Empty string if not available.
|
---|
274 | * Since the length is a bit tricky for a UTF-8 encoded name, and since this
|
---|
275 | * is practically speaking only a windows thing, it is encoded as UCS-2. */
|
---|
276 | RTUTF16 wszShortName[14];
|
---|
277 | /** The length of the filename. */
|
---|
278 | uint16_t cbName;
|
---|
279 | /** The filename. (no path)
|
---|
280 | * Using the pcbDirEntry parameter of RTDirReadEx makes this field variable in size. */
|
---|
281 | char szName[260];
|
---|
282 | } RTDIRENTRYEX;
|
---|
283 | #pragma pack()
|
---|
284 | /** Pointer to a directory entry. */
|
---|
285 | typedef RTDIRENTRYEX *PRTDIRENTRYEX;
|
---|
286 |
|
---|
287 |
|
---|
288 | /**
|
---|
289 | * Opens a directory.
|
---|
290 | *
|
---|
291 | * @returns iprt status code.
|
---|
292 | * @param ppDir Where to store the open directory pointer.
|
---|
293 | * @param pszPath Path to the directory to open.
|
---|
294 | */
|
---|
295 | RTDECL(int) RTDirOpen(PRTDIR *ppDir, const char *pszPath);
|
---|
296 |
|
---|
297 | /**
|
---|
298 | * Opens a directory filtering the entries using dos style wildcards.
|
---|
299 | *
|
---|
300 | * @returns iprt status code.
|
---|
301 | * @param ppDir Where to store the open directory pointer.
|
---|
302 | * @param pszPath Path to the directory to search, this must include wildcards.
|
---|
303 | * @param enmFilter The kind of filter to apply. Setting this to RTDIRFILTER_NONE makes
|
---|
304 | * this function behave like RTDirOpen.
|
---|
305 | */
|
---|
306 | RTDECL(int) RTDirOpenFiltered(PRTDIR *ppDir, const char *pszPath, RTDIRFILTER enmFilter);
|
---|
307 |
|
---|
308 | /**
|
---|
309 | * Closes a directory.
|
---|
310 | *
|
---|
311 | * @returns iprt status code.
|
---|
312 | * @param pDir Pointer to open directory returned by RTDirOpen() or RTDirOpenFiltered().
|
---|
313 | */
|
---|
314 | RTDECL(int) RTDirClose(PRTDIR pDir);
|
---|
315 |
|
---|
316 | /**
|
---|
317 | * Reads the next entry in the directory.
|
---|
318 | *
|
---|
319 | * @returns VINF_SUCCESS and data in pDirEntry on success.
|
---|
320 | * @returns VERR_NO_MORE_FILES when the end of the directory has been reached.
|
---|
321 | * @returns VERR_BUFFER_OVERFLOW if the buffer is too small to contain the filename. If
|
---|
322 | * pcbDirEntry is specified it will be updated with the required buffer size.
|
---|
323 | * @returns suitable iprt status code on other errors.
|
---|
324 | *
|
---|
325 | * @param pDir Pointer to the open directory.
|
---|
326 | * @param pDirEntry Where to store the information about the next
|
---|
327 | * directory entry on success.
|
---|
328 | * @param pcbDirEntry Optional parameter used for variable buffer size.
|
---|
329 | *
|
---|
330 | * On input the variable pointed to contains the size of the pDirEntry
|
---|
331 | * structure. This must be at least OFFSET(RTDIRENTRY, szName[2]) bytes.
|
---|
332 | *
|
---|
333 | * On successful output the field is updated to
|
---|
334 | * OFFSET(RTDIRENTRY, szName[pDirEntry->cbName + 1]).
|
---|
335 | *
|
---|
336 | * When the data doesn't fit in the buffer and VERR_BUFFER_OVERFLOW is
|
---|
337 | * returned, this field contains the required buffer size.
|
---|
338 | *
|
---|
339 | * The value is unchanged in all other cases.
|
---|
340 | */
|
---|
341 | RTDECL(int) RTDirRead(PRTDIR pDir, PRTDIRENTRY pDirEntry, size_t *pcbDirEntry);
|
---|
342 |
|
---|
343 | /**
|
---|
344 | * Reads the next entry in the directory returning extended information.
|
---|
345 | *
|
---|
346 | * @returns VINF_SUCCESS and data in pDirEntry on success.
|
---|
347 | * @returns VERR_NO_MORE_FILES when the end of the directory has been reached.
|
---|
348 | * @returns VERR_BUFFER_OVERFLOW if the buffer is too small to contain the filename. If
|
---|
349 | * pcbDirEntry is specified it will be updated with the required buffer size.
|
---|
350 | * @returns suitable iprt status code on other errors.
|
---|
351 | *
|
---|
352 | * @param pDir Pointer to the open directory.
|
---|
353 | * @param pDirEntry Where to store the information about the next
|
---|
354 | * directory entry on success.
|
---|
355 | * @param pcbDirEntry Optional parameter used for variable buffer size.
|
---|
356 | *
|
---|
357 | * On input the variable pointed to contains the size of the pDirEntry
|
---|
358 | * structure. This must be at least OFFSET(RTDIRENTRYEX, szName[2]) bytes.
|
---|
359 | *
|
---|
360 | * On successful output the field is updated to
|
---|
361 | * OFFSET(RTDIRENTRYEX, szName[pDirEntry->cbName + 1]).
|
---|
362 | *
|
---|
363 | * When the data doesn't fit in the buffer and VERR_BUFFER_OVERFLOW is
|
---|
364 | * returned, this field contains the required buffer size.
|
---|
365 | *
|
---|
366 | * The value is unchanged in all other cases.
|
---|
367 | * @param enmAdditionalAttribs
|
---|
368 | * Which set of additional attributes to request.
|
---|
369 | * Use RTFSOBJATTRADD_NOTHING if this doesn't matter.
|
---|
370 | * @param fFlags RTPATH_F_ON_LINK or RTPATH_F_FOLLOW_LINK.
|
---|
371 | */
|
---|
372 | RTDECL(int) RTDirReadEx(PRTDIR pDir, PRTDIRENTRYEX pDirEntry, size_t *pcbDirEntry, RTFSOBJATTRADD enmAdditionalAttribs, uint32_t fFlags);
|
---|
373 |
|
---|
374 |
|
---|
375 | /**
|
---|
376 | * Renames a file.
|
---|
377 | *
|
---|
378 | * Identical to RTPathRename except that it will ensure that the source is a directory.
|
---|
379 | *
|
---|
380 | * @returns IPRT status code.
|
---|
381 | * @returns VERR_ALREADY_EXISTS if the destination file exists.
|
---|
382 | *
|
---|
383 | * @param pszSrc The path to the source file.
|
---|
384 | * @param pszDst The path to the destination file.
|
---|
385 | * This file will be created.
|
---|
386 | * @param fRename See RTPathRename.
|
---|
387 | */
|
---|
388 | RTDECL(int) RTDirRename(const char *pszSrc, const char *pszDst, unsigned fRename);
|
---|
389 |
|
---|
390 |
|
---|
391 | /**
|
---|
392 | * Query information about an open directory.
|
---|
393 | *
|
---|
394 | * @returns iprt status code.
|
---|
395 | *
|
---|
396 | * @param pDir Pointer to the open directory.
|
---|
397 | * @param pObjInfo Object information structure to be filled on successful return.
|
---|
398 | * @param enmAdditionalAttribs Which set of additional attributes to request.
|
---|
399 | * Use RTFSOBJATTRADD_NOTHING if this doesn't matter.
|
---|
400 | */
|
---|
401 | RTR3DECL(int) RTDirQueryInfo(PRTDIR pDir, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAdditionalAttribs);
|
---|
402 |
|
---|
403 |
|
---|
404 | /**
|
---|
405 | * Changes one or more of the timestamps associated of file system object.
|
---|
406 | *
|
---|
407 | * @returns iprt status code.
|
---|
408 | * @returns VERR_NOT_SUPPORTED is returned if the operation isn't supported by the OS.
|
---|
409 | *
|
---|
410 | * @param pDir Pointer to the open directory.
|
---|
411 | * @param pAccessTime Pointer to the new access time. NULL if not to be changed.
|
---|
412 | * @param pModificationTime Pointer to the new modifcation time. NULL if not to be changed.
|
---|
413 | * @param pChangeTime Pointer to the new change time. NULL if not to be changed.
|
---|
414 | * @param pBirthTime Pointer to the new time of birth. NULL if not to be changed.
|
---|
415 | *
|
---|
416 | * @remark The file system might not implement all these time attributes,
|
---|
417 | * the API will ignore the ones which aren't supported.
|
---|
418 | *
|
---|
419 | * @remark The file system might not implement the time resolution
|
---|
420 | * employed by this interface, the time will be chopped to fit.
|
---|
421 | *
|
---|
422 | * @remark The file system may update the change time even if it's
|
---|
423 | * not specified.
|
---|
424 | *
|
---|
425 | * @remark POSIX can only set Access & Modification and will always set both.
|
---|
426 | */
|
---|
427 | RTR3DECL(int) RTDirSetTimes(PRTDIR pDir, PCRTTIMESPEC pAccessTime, PCRTTIMESPEC pModificationTime,
|
---|
428 | PCRTTIMESPEC pChangeTime, PCRTTIMESPEC pBirthTime);
|
---|
429 |
|
---|
430 | /** @} */
|
---|
431 |
|
---|
432 | RT_C_DECLS_END
|
---|
433 |
|
---|
434 | #endif
|
---|
435 |
|
---|