VirtualBox

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

Last change on this file since 4878 was 4071, checked in by vboxsync, 17 years ago

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