VirtualBox

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

Last change on this file since 25477 was 24889, checked in by vboxsync, 15 years ago

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