VirtualBox

source: vbox/trunk/include/iprt/dir.h@ 19559

Last change on this file since 19559 was 19261, checked in by vboxsync, 16 years ago

iprt/dir.h: Corrected RTDirRemove docs.

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