VirtualBox

source: vbox/trunk/include/iprt/fs.h@ 3054

Last change on this file since 3054 was 2981, checked in by vboxsync, 17 years ago

InnoTek -> innotek: all the headers and comments.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 15.7 KB
Line 
1/** @file
2 * innotek Portable Runtime - Filesystem.
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
22#ifndef __iprt_fs_h__
23#define __iprt_fs_h__
24
25#include <iprt/cdefs.h>
26#include <iprt/types.h>
27#include <iprt/time.h>
28
29
30__BEGIN_DECLS
31
32/** @defgroup grp_rt_fs RTFs - Filesystem and Volume
33 * @ingroup grp_rt
34 * @{
35 */
36
37
38/** @name Filesystem Object Mode Flags.
39 *
40 * There are two sets of flags: the unix mode flags and the dos
41 * attributes.
42 *
43 * APIs returning mode flags will provide both sets.
44 *
45 * When specifying mode flags to any API at least one of
46 * them must be given. If one set is missing the API will
47 * synthesize it from the one given if it requires it.
48 *
49 * Both sets match their x86 ABIs, the DOS/NT one is simply shifted
50 * up 16 bits. The DOS/NT range is bits 16 to 31 inclusivly. The
51 * Unix range is bits 0 to 15 (inclusivly).
52 *
53 * @{
54 */
55
56/** Set user id on execution (S_ISUID). */
57#define RTFS_UNIX_ISUID 0004000U
58/** Set group id on execution (S_ISGID). */
59#define RTFS_UNIX_ISGID 0002000U
60/** Sticky bit (S_ISVTX / S_ISTXT). */
61#define RTFS_UNIX_ISTXT 0001000U
62
63/** Owner RWX mask (S_IRWXU). */
64#define RTFS_UNIX_IRWXU 0000700U
65/** Owner readable (S_IRUSR). */
66#define RTFS_UNIX_IRUSR 0000400U
67/** Owner writable (S_IWUSR). */
68#define RTFS_UNIX_IWUSR 0000200U
69/** Owner executable (S_IXUSR). */
70#define RTFS_UNIX_IXUSR 0000100U
71
72/** Group RWX mask (S_IRWXG). */
73#define RTFS_UNIX_IRWXG 0000070U
74/** Group readable (S_IRGRP). */
75#define RTFS_UNIX_IRGRP 0000040U
76/** Group writable (S_IWGRP). */
77#define RTFS_UNIX_IWGRP 0000020U
78/** Group executable (S_IXGRP). */
79#define RTFS_UNIX_IXGRP 0000010U
80
81/** Other RWX mask (S_IRWXO). */
82#define RTFS_UNIX_IRWXO 0000007U
83/** Other readable (S_IROTH). */
84#define RTFS_UNIX_IROTH 0000004U
85/** Other writable (S_IWOTH). */
86#define RTFS_UNIX_IWOTH 0000002U
87/** Other executable (S_IXOTH). */
88#define RTFS_UNIX_IXOTH 0000001U
89
90/** Named pipe (fifo) (S_IFIFO). */
91#define RTFS_TYPE_FIFO 0010000U
92/** Character device (S_IFCHR). */
93#define RTFS_TYPE_DEV_CHAR 0020000U
94/** Directory (S_IFDIR). */
95#define RTFS_TYPE_DIRECTORY 0040000U
96/** Block device (S_IFBLK). */
97#define RTFS_TYPE_DEV_BLOCK 0060000U
98/** Regular file (S_IFREG). */
99#define RTFS_TYPE_FILE 0100000U
100/** Symbolic link (S_IFLNK). */
101#define RTFS_TYPE_SYMLINK 0120000U
102/** Socket (S_IFSOCK). */
103#define RTFS_TYPE_SOCKET 0140000U
104/** Whiteout (S_IFWHT). */
105#define RTFS_TYPE_WHITEOUT 0160000U
106/** Type mask (S_IFMT). */
107#define RTFS_TYPE_MASK 0170000U
108
109/** Unix attribute mask. */
110#define RTFS_UNIX_MASK 0xffffU
111/** The mask of all the NT, OS/2 and DOS attributes. */
112#define RTFS_DOS_MASK (0x7fffU << RTFS_DOS_SHIFT)
113
114/** The shift value. */
115#define RTFS_DOS_SHIFT 16
116/** The mask of the OS/2 and DOS attributes. */
117#define RTFS_DOS_MASK_OS2 (0x003fU << RTFS_DOS_SHIFT)
118/** The mask of the NT attributes. */
119#define RTFS_DOS_MASK_NT (0x7fffU << RTFS_DOS_SHIFT)
120
121/** Readonly object. */
122#define RTFS_DOS_READONLY (0x0001U << RTFS_DOS_SHIFT)
123/** Hidden object. */
124#define RTFS_DOS_HIDDEN (0x0002U << RTFS_DOS_SHIFT)
125/** System object. */
126#define RTFS_DOS_SYSTEM (0x0004U << RTFS_DOS_SHIFT)
127/** Directory. */
128#define RTFS_DOS_DIRECTORY (0x0010U << RTFS_DOS_SHIFT)
129/** Archived object.
130 * This bit is set by the filesystem after each modification of a file. */
131#define RTFS_DOS_ARCHIVED (0x0020U << RTFS_DOS_SHIFT)
132/** Undocumented / Reserved, used to be the FAT volume label. */
133#define RTFS_DOS_NT_DEVICE (0x0040U << RTFS_DOS_SHIFT)
134/** Normal object, no other attribute set (NT). */
135#define RTFS_DOS_NT_NORMAL (0x0080U << RTFS_DOS_SHIFT)
136/** Temporary object (NT). */
137#define RTFS_DOS_NT_TEMPORARY (0x0100U << RTFS_DOS_SHIFT)
138/** Sparse file (NT). */
139#define RTFS_DOS_NT_SPARSE_FILE (0x0200U << RTFS_DOS_SHIFT)
140/** Reparse point (NT). */
141#define RTFS_DOS_NT_REPARSE_POINT (0x0400U << RTFS_DOS_SHIFT)
142/** Compressed object (NT).
143 * For a directory, compression is the default for new files. */
144#define RTFS_DOS_NT_COMPRESSED (0x0800U << RTFS_DOS_SHIFT)
145/** Physically offline data (NT).
146 * MSDN say, don't mess with this one. */
147#define RTFS_DOS_NT_OFFLINE (0x1000U << RTFS_DOS_SHIFT)
148/** Not content indexed by the content indexing service (NT). */
149#define RTFS_DOS_NT_NOT_CONTENT_INDEXED (0x2000U << RTFS_DOS_SHIFT)
150/** Encryped object (NT).
151 * For a directory, encrypted is the default for new files. */
152#define RTFS_DOS_NT_ENCRYPTED (0x4000U << RTFS_DOS_SHIFT)
153
154/** @} */
155
156
157/** @name Filesystem Object Type Predicates.
158 * @{ */
159/** Checks the mode flags indicate a named pipe (fifo) (S_ISFIFO). */
160#define RTFS_IS_FIFO(fMode) ( ((fMode) & RTFS_TYPE_MASK) == RTFS_TYPE_FIFO )
161/** Checks the mode flags indicate a character device (S_ISCHR). */
162#define RTFS_IS_DEV_CHAR(fMode) ( ((fMode) & RTFS_TYPE_MASK) == RTFS_TYPE_DEV_CHAR )
163/** Checks the mode flags indicate a directory (S_ISDIR). */
164#define RTFS_IS_DIRECTORY(fMode) ( ((fMode) & RTFS_TYPE_MASK) == RTFS_TYPE_DIRECTORY )
165/** Checks the mode flags indicate a block device (S_ISBLK). */
166#define RTFS_IS_DEV_BLOCK(fMode) ( ((fMode) & RTFS_TYPE_MASK) == RTFS_TYPE_DEV_BLOCK )
167/** Checks the mode flags indicate a regular file (S_ISREG). */
168#define RTFS_IS_FILE(fMode) ( ((fMode) & RTFS_TYPE_MASK) == RTFS_TYPE_FILE )
169/** Checks the mode flags indicate a symbolic link (S_ISLNK). */
170#define RTFS_IS_SYMLINK(fMode) ( ((fMode) & RTFS_TYPE_MASK) == RTFS_TYPE_SYMLINK )
171/** Checks the mode flags indicate a socket (S_ISSOCK). */
172#define RTFS_IS_SOCKET(fMode) ( ((fMode) & RTFS_TYPE_MASK) == RTFS_TYPE_SOCKET )
173/** Checks the mode flags indicate a whiteout (S_ISWHT). */
174#define RTFS_IS_WHITEOUT(fMode) ( ((fMode) & RTFS_TYPE_MASK) == RTFS_TYPE_WHITEOUT )
175/** @} */
176
177
178/**
179 * The available additional information in a RTFSOBJATTR object.
180 */
181typedef enum RTFSOBJATTRADD
182{
183 /** No additional information is available / requested. */
184 RTFSOBJATTRADD_NOTHING = 1,
185 /** The additional unix attributes (RTFSOBJATTR::u::Unix) are available / requested. */
186 RTFSOBJATTRADD_UNIX,
187 /** The additional extended attribute size (RTFSOBJATTR::u::EASize) is available / requested. */
188 RTFSOBJATTRADD_EASIZE,
189 /** The last valid item (inclusive).
190 * The valid range is RTFSOBJATTRADD_NOTHING thru RTFSOBJATTRADD_LAST. */
191 RTFSOBJATTRADD_LAST = RTFSOBJATTRADD_EASIZE,
192
193 /** The usual 32-bit hack. */
194 RTFSOBJATTRADD_32BIT_SIZE_HACK = 0x7fffffff
195} RTFSOBJATTRADD;
196
197
198/**
199 * Filesystem object attributes.
200 */
201#pragma pack(1)
202typedef struct RTFSOBJATTR
203{
204 /** Mode flags (st_mode). RTFS_UNIX_*, RTFS_TYPE_*, and RTFS_DOS_*. */
205 RTFMODE fMode;
206
207 /** The additional attributes available. */
208 RTFSOBJATTRADD enmAdditional;
209
210 /**
211 * Additional attributes.
212 *
213 * Unless explicitly specified to an API, the API can provide additional
214 * data as it is provided by the underlying OS.
215 */
216 union RTFSOBJATTRUNION
217 {
218 /** Additional Unix Attributes
219 * These are available when RTFSOBJATTRADD is set in fUnix.
220 */
221 struct RTFSOBJATTRUNIX
222 {
223 /** The user owning the filesystem object (st_uid).
224 * This field is ~0U if not supported. */
225 RTUID uid;
226
227 /** The group the filesystem object is assigned (st_gid).
228 * This field is ~0U if not supported. */
229 RTGID gid;
230
231 /** Number of hard links to this filesystem object (st_nlink).
232 * This field is 1 if the filesystem doesn't support hardlinking or
233 * the information isn't available.
234 */
235 uint32_t cHardlinks;
236
237 /** The device number of the device which this filesystem object resides on (st_dev).
238 * This field is 0 if this information is not available. */
239 RTDEV INodeIdDevice;
240
241 /** The unique identifier (within the filesystem) of this filesystem object (st_ino).
242 * Together with INodeIdDevice, this field can be used as a OS wide unique id
243 * when both their values are not 0.
244 * This field is 0 if the information is not available. */
245 RTINODE INodeId;
246
247 /** User flags (st_flags).
248 * This field is 0 if this information is not available. */
249 uint32_t fFlags;
250
251 /** The current generation number (st_gen).
252 * This field is 0 if this information is not available. */
253 uint32_t GenerationId;
254
255 /** The device number of a character or block device type object (st_rdev).
256 * This field is 0 if the file isn't of a character or block device type and
257 * when the OS doesn't subscribe to the major+minor device idenfication scheme. */
258 RTDEV Device;
259 } Unix;
260
261 /**
262 * Extended attribute size is available when RTFS_DOS_HAVE_EA_SIZE is set.
263 */
264 struct RTFSOBJATTREASIZE
265 {
266 /** Size of EAs. */
267 RTFOFF cb;
268 } EASize;
269 } u;
270} RTFSOBJATTR;
271#pragma pack()
272/** Pointer to a filesystem object attributes structure. */
273typedef RTFSOBJATTR *PRTFSOBJATTR;
274/** Pointer to a const filesystem object attributes structure. */
275typedef const RTFSOBJATTR *PCRTFSOBJATTR;
276
277
278/**
279 * Filesystem object information structure.
280 *
281 * This is returned by the RTPathQueryInfo(), RTFileQueryInfo() and RTDirRead() APIs.
282 */
283#pragma pack(1)
284typedef struct RTFSOBJINFO
285{
286 /** Logical size (st_size).
287 * For normal files this is the size of the file.
288 * For symbolic links, this is the length of the path name contained
289 * in the symbolic link.
290 * For other objects this fields needs to be specified.
291 */
292 RTFOFF cbObject;
293
294 /** Disk allocation size (st_blocks * DEV_BSIZE). */
295 RTFOFF cbAllocated;
296
297 /** Time of last access (st_atime). */
298 RTTIMESPEC AccessTime;
299
300 /** Time of last data modification (st_mtime). */
301 RTTIMESPEC ModificationTime;
302
303 /** Time of last status change (st_ctime).
304 * If not available this is set to ModificationTime.
305 */
306 RTTIMESPEC ChangeTime;
307
308 /** Time of file birth (st_birthtime).
309 * If not available this is set to ChangeTime.
310 */
311 RTTIMESPEC BirthTime;
312
313 /** Attributes. */
314 RTFSOBJATTR Attr;
315
316} RTFSOBJINFO;
317#pragma pack()
318/** Pointer to a filesystem object information structure. */
319typedef RTFSOBJINFO *PRTFSOBJINFO;
320/** Pointer to a const filesystem object information structure. */
321typedef const RTFSOBJINFO *PCRTFSOBJINFO;
322
323
324#ifdef IN_RING3
325
326/**
327 * Query the sizes of a filesystem.
328 *
329 * @returns iprt status code.
330 * @param pszFsPath Path within the mounted filesystem.
331 * @param pcbTotal Where to store the total filesystem space. (Optional)
332 * @param pcbFree Where to store the remaining free space in the filesystem. (Optional)
333 * @param pcbBlock Where to store the block size. (Optional)
334 * @param pcbSector Where to store the sector size. (Optional)
335 */
336RTR3DECL(int) RTFsQuerySizes(const char *pszFsPath, PRTFOFF pcbTotal, RTFOFF *pcbFree,
337 uint32_t *pcbBlock, uint32_t *pcbSector);
338
339/**
340 * Query the mountpoint of a filesystem.
341 *
342 * @returns iprt status code.
343 * @returns VERR_BUFFER_OVERFLOW if cbMountpoint isn't enough.
344 * @param pszFsPath Path within the mounted filesystem.
345 * @param pszMountpoint Where to store the mountpoint path.
346 * @param cbMountpoint Size of the buffer pointed to by pszMountpoint.
347 */
348RTR3DECL(int) RTFsQueryMountpoint(const char *pszFsPath, char *pszMountpoint, size_t cbMountpoint);
349
350/**
351 * Query the label of a filesystem.
352 *
353 * @returns iprt status code.
354 * @returns VERR_BUFFER_OVERFLOW if cbLabel isn't enough.
355 * @param pszFsPath Path within the mounted filesystem.
356 * @param pszLabel Where to store the label.
357 * @param cbLabel Size of the buffer pointed to by pszLabel.
358 */
359RTR3DECL(int) RTFsQueryLabel(const char *pszFsPath, char *pszLabel, size_t cbLabel);
360
361/**
362 * Query the serial number of a filesystem.
363 *
364 * @returns iprt status code.
365 * @param pszFsPath Path within the mounted filesystem.
366 * @param pu32Serial Where to store the serial number.
367 */
368RTR3DECL(int) RTFsQuerySerial(const char *pszFsPath, uint32_t *pu32Serial);
369
370/**
371 * Query the name of the filesystem driver.
372 *
373 * @returns iprt status code.
374 * @returns VERR_BUFFER_OVERFLOW if cbFsDriver isn't enough.
375 * @param pszFsPath Path within the mounted filesystem.
376 * @param pszFsDriver Where to store the filesystem driver name.
377 * @param cbFsDriver Size of the buffer pointed to by pszFsDriver.
378 */
379RTR3DECL(int) RTFsQueryDriver(const char *pszFsPath, char *pszFsDriver, size_t cbFsDriver);
380
381#endif /* IN_RING3 */
382
383/**
384 * Filesystem properties.
385 */
386typedef struct RTFSPROPERTIES
387{
388 /** The maximum size of a filesystem object name.
389 * This does not include the '\\0'. */
390 uint32_t cbMaxComponent;
391
392 /** True if the filesystem is remote.
393 * False if the filesystem is local. */
394 bool fRemote;
395
396 /** True if the filesystem is case sensitive.
397 * False if the filesystem is case insensitive. */
398 bool fCaseSensitive;
399
400 /** True if the filesystem is mounted read only.
401 * False if the filesystem is mounted read write. */
402 bool fReadOnly;
403
404 /** True if the filesystem can encode unicode object names.
405 * False if it can't. */
406 bool fSupportsUnicode;
407
408 /** True if the filesystem is compresses.
409 * False if it isn't or we don't know. */
410 bool fCompressed;
411
412 /** True if the filesystem compresses of individual files.
413 * False if it doesn't or we don't know. */
414 bool fFileCompression;
415
416 /** @todo more? */
417} RTFSPROPERTIES;
418/** Pointer to a filesystem properties structure. */
419typedef RTFSPROPERTIES *PRTFSPROPERTIES;
420
421#ifdef IN_RING3
422
423/**
424 * Query the properties of a mounted filesystem.
425 *
426 * @returns iprt status code.
427 * @param pszFsPath Path within the mounted filesystem.
428 * @param pProperties Where to store the properties.
429 */
430RTR3DECL(int) RTFsQueryProperties(const char *pszFsPath, PRTFSPROPERTIES pProperties);
431
432
433/**
434 * Mountpoint enumerator callback.
435 *
436 * @returns iprt status code. Failure terminates the enumeration.
437 * @param pszMountpoint The mountpoint name.
438 * @param pvUser The user argument.
439 */
440typedef DECLCALLBACK(int) FNRTFSMOUNTPOINTENUM(const char *pszMountpoint, void *pvUser);
441/** Pointer to a FNRTFSMOUNTPOINTENUM(). */
442typedef FNRTFSMOUNTPOINTENUM *PFNRTFSMOUNTPOINTENUM;
443
444/**
445 * Enumerate mount points.
446 *
447 * @returns iprt status code.
448 * @param pfnCallback The callback function.
449 * @param pvUser The user argument to the callback.
450 */
451RTR3DECL(int) RTFsMountpointsEnum(PFNRTFSMOUNTPOINTENUM pfnCallback, void *pvUser);
452
453
454#endif /* IN_RING3 */
455
456/** @} */
457
458__END_DECLS
459
460#endif /* __iprt_fs_h__ */
461
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