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