VirtualBox

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

Last change on this file since 22958 was 20374, checked in by vboxsync, 16 years ago

*: s/RT_\(BEGIN|END\)_DECLS/RT_C_DECLS_\1/g
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 16.1 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 */
344RTR3DECL(int) RTFsQuerySizes(const char *pszFsPath, PRTFOFF pcbTotal, RTFOFF *pcbFree,
345 uint32_t *pcbBlock, uint32_t *pcbSector);
346
347/**
348 * Query the mountpoint of a filesystem.
349 *
350 * @returns iprt status code.
351 * @returns VERR_BUFFER_OVERFLOW if cbMountpoint isn't enough.
352 * @param pszFsPath Path within the mounted filesystem.
353 * @param pszMountpoint Where to store the mountpoint path.
354 * @param cbMountpoint Size of the buffer pointed to by pszMountpoint.
355 */
356RTR3DECL(int) RTFsQueryMountpoint(const char *pszFsPath, char *pszMountpoint, size_t cbMountpoint);
357
358/**
359 * Query the label of a filesystem.
360 *
361 * @returns iprt status code.
362 * @returns VERR_BUFFER_OVERFLOW if cbLabel isn't enough.
363 * @param pszFsPath Path within the mounted filesystem.
364 * @param pszLabel Where to store the label.
365 * @param cbLabel Size of the buffer pointed to by pszLabel.
366 */
367RTR3DECL(int) RTFsQueryLabel(const char *pszFsPath, char *pszLabel, size_t cbLabel);
368
369/**
370 * Query the serial number of a filesystem.
371 *
372 * @returns iprt status code.
373 * @param pszFsPath Path within the mounted filesystem.
374 * @param pu32Serial Where to store the serial number.
375 */
376RTR3DECL(int) RTFsQuerySerial(const char *pszFsPath, uint32_t *pu32Serial);
377
378/**
379 * Query the name of the filesystem driver.
380 *
381 * @returns iprt status code.
382 * @returns VERR_BUFFER_OVERFLOW if cbFsDriver isn't enough.
383 * @param pszFsPath Path within the mounted filesystem.
384 * @param pszFsDriver Where to store the filesystem driver name.
385 * @param cbFsDriver Size of the buffer pointed to by pszFsDriver.
386 */
387RTR3DECL(int) RTFsQueryDriver(const char *pszFsPath, char *pszFsDriver, size_t cbFsDriver);
388
389#endif /* IN_RING3 */
390
391/**
392 * Filesystem properties.
393 */
394typedef struct RTFSPROPERTIES
395{
396 /** The maximum size of a filesystem object name.
397 * This does not include the '\\0'. */
398 uint32_t cbMaxComponent;
399
400 /** True if the filesystem is remote.
401 * False if the filesystem is local. */
402 bool fRemote;
403
404 /** True if the filesystem is case sensitive.
405 * False if the filesystem is case insensitive. */
406 bool fCaseSensitive;
407
408 /** True if the filesystem is mounted read only.
409 * False if the filesystem is mounted read write. */
410 bool fReadOnly;
411
412 /** True if the filesystem can encode unicode object names.
413 * False if it can't. */
414 bool fSupportsUnicode;
415
416 /** True if the filesystem is compresses.
417 * False if it isn't or we don't know. */
418 bool fCompressed;
419
420 /** True if the filesystem compresses of individual files.
421 * False if it doesn't or we don't know. */
422 bool fFileCompression;
423
424 /** @todo more? */
425} RTFSPROPERTIES;
426/** Pointer to a filesystem properties structure. */
427typedef RTFSPROPERTIES *PRTFSPROPERTIES;
428
429#ifdef IN_RING3
430
431/**
432 * Query the properties of a mounted filesystem.
433 *
434 * @returns iprt status code.
435 * @param pszFsPath Path within the mounted filesystem.
436 * @param pProperties Where to store the properties.
437 */
438RTR3DECL(int) RTFsQueryProperties(const char *pszFsPath, PRTFSPROPERTIES pProperties);
439
440
441/**
442 * Mountpoint enumerator callback.
443 *
444 * @returns iprt status code. Failure terminates the enumeration.
445 * @param pszMountpoint The mountpoint name.
446 * @param pvUser The user argument.
447 */
448typedef DECLCALLBACK(int) FNRTFSMOUNTPOINTENUM(const char *pszMountpoint, void *pvUser);
449/** Pointer to a FNRTFSMOUNTPOINTENUM(). */
450typedef FNRTFSMOUNTPOINTENUM *PFNRTFSMOUNTPOINTENUM;
451
452/**
453 * Enumerate mount points.
454 *
455 * @returns iprt status code.
456 * @param pfnCallback The callback function.
457 * @param pvUser The user argument to the callback.
458 */
459RTR3DECL(int) RTFsMountpointsEnum(PFNRTFSMOUNTPOINTENUM pfnCallback, void *pvUser);
460
461
462#endif /* IN_RING3 */
463
464/** @} */
465
466RT_C_DECLS_END
467
468#endif /* ___iprt_fs_h */
469
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