VirtualBox

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