← Back to branch summary

~ubuntu-branches/ubuntu/gutsy/virtualbox-ose/gutsy

« back to all changes in this revision

Viewing changes to include/iprt/dir.h

  • Committer: Bazaar Package Importer
  • Author(s): Steve Kowalik
  • Date: 2007-09-08 16:44:58 UTC
  • Revision ID: james.westby@ubuntu.com-20070908164458-wao29470vqtr8ksy
Tags: upstream-1.5.0-dfsg2
Import upstream version 1.5.0-dfsg2

Show diffs side-by-side

added added

removed removed

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