VirtualBox

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

Last change on this file since 3810 was 3630, checked in by vboxsync, 17 years ago

iprt_hdr_h -> _iprt_hdr_h

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