6 * Copyright (C) 2006-2016 Oracle Corporation
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.
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.
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.
29 #include <iprt/cdefs.h>
30 #include <iprt/types.h>
31 #include <iprt/time.h>
36 /** @defgroup grp_rt_fs RTFs - Filesystem and Volume
42 /** @name Filesystem Object Mode Flags.
44 * There are two sets of flags: the unix mode flags and the dos attributes.
46 * APIs returning mode flags will provide both sets.
48 * When specifying mode flags to any API at least one of them must be given. If
49 * one set is missing the API will synthesize it from the one given if it
52 * Both sets match their x86 ABIs, the DOS/NT one is simply shifted up 16 bits.
53 * The DOS/NT range is bits 16 to 31 inclusively. The Unix range is bits 0 to 15
56 * @remarks These constants have been comitted to a binary format and must not
57 * be changed in any incompatible ways.
62 /** Set user id on execution (S_ISUID). */
63 #define RTFS_UNIX_ISUID 0004000U
64 /** Set group id on execution (S_ISGID). */
65 #define RTFS_UNIX_ISGID 0002000U
66 /** Sticky bit (S_ISVTX / S_ISTXT). */
67 #define RTFS_UNIX_ISTXT 0001000U
69 /** Owner RWX mask (S_IRWXU). */
70 #define RTFS_UNIX_IRWXU 0000700U
71 /** Owner readable (S_IRUSR). */
72 #define RTFS_UNIX_IRUSR 0000400U
73 /** Owner writable (S_IWUSR). */
74 #define RTFS_UNIX_IWUSR 0000200U
75 /** Owner executable (S_IXUSR). */
76 #define RTFS_UNIX_IXUSR 0000100U
78 /** Group RWX mask (S_IRWXG). */
79 #define RTFS_UNIX_IRWXG 0000070U
80 /** Group readable (S_IRGRP). */
81 #define RTFS_UNIX_IRGRP 0000040U
82 /** Group writable (S_IWGRP). */
83 #define RTFS_UNIX_IWGRP 0000020U
84 /** Group executable (S_IXGRP). */
85 #define RTFS_UNIX_IXGRP 0000010U
87 /** Other RWX mask (S_IRWXO). */
88 #define RTFS_UNIX_IRWXO 0000007U
89 /** Other readable (S_IROTH). */
90 #define RTFS_UNIX_IROTH 0000004U
91 /** Other writable (S_IWOTH). */
92 #define RTFS_UNIX_IWOTH 0000002U
93 /** Other executable (S_IXOTH). */
94 #define RTFS_UNIX_IXOTH 0000001U
96 /** All UNIX access permission bits (0777). */
97 #define RTFS_UNIX_ALL_ACCESS_PERMS 0000777U
98 /** All UNIX permission bits, including set id and sticky bits. */
99 #define RTFS_UNIX_ALL_PERMS 0007777U
101 /** Named pipe (fifo) (S_IFIFO). */
102 #define RTFS_TYPE_FIFO 0010000U
103 /** Character device (S_IFCHR). */
104 #define RTFS_TYPE_DEV_CHAR 0020000U
105 /** Directory (S_IFDIR). */
106 #define RTFS_TYPE_DIRECTORY 0040000U
107 /** Block device (S_IFBLK). */
108 #define RTFS_TYPE_DEV_BLOCK 0060000U
109 /** Regular file (S_IFREG). */
110 #define RTFS_TYPE_FILE 0100000U
111 /** Symbolic link (S_IFLNK). */
112 #define RTFS_TYPE_SYMLINK 0120000U
113 /** Socket (S_IFSOCK). */
114 #define RTFS_TYPE_SOCKET 0140000U
115 /** Whiteout (S_IFWHT). */
116 #define RTFS_TYPE_WHITEOUT 0160000U
117 /** Type mask (S_IFMT). */
118 #define RTFS_TYPE_MASK 0170000U
119 /** The shift count to convert between RTFS_TYPE_MASK and DIRENTRYTYPE. */
120 #define RTFS_TYPE_DIRENTRYTYPE_SHIFT 12
122 /** Unix attribute mask. */
123 #define RTFS_UNIX_MASK 0xffffU
124 /** The mask of all the NT, OS/2 and DOS attributes. */
125 #define RTFS_DOS_MASK (0x7fffU << RTFS_DOS_SHIFT)
127 /** The shift value. */
128 #define RTFS_DOS_SHIFT 16
129 /** The mask of the OS/2 and DOS attributes. */
130 #define RTFS_DOS_MASK_OS2 (0x003fU << RTFS_DOS_SHIFT)
131 /** The mask of the NT attributes. */
132 #define RTFS_DOS_MASK_NT (0x7fffU << RTFS_DOS_SHIFT)
134 /** Readonly object. */
135 #define RTFS_DOS_READONLY (0x0001U << RTFS_DOS_SHIFT)
136 /** Hidden object. */
137 #define RTFS_DOS_HIDDEN (0x0002U << RTFS_DOS_SHIFT)
138 /** System object. */
139 #define RTFS_DOS_SYSTEM (0x0004U << RTFS_DOS_SHIFT)
141 #define RTFS_DOS_DIRECTORY (0x0010U << RTFS_DOS_SHIFT)
143 * This bit is set by the filesystem after each modification of a file. */
144 #define RTFS_DOS_ARCHIVED (0x0020U << RTFS_DOS_SHIFT)
145 /** Undocumented / Reserved, used to be the FAT volume label. */
146 #define RTFS_DOS_NT_DEVICE (0x0040U << RTFS_DOS_SHIFT)
147 /** Normal object, no other attribute set (NT). */
148 #define RTFS_DOS_NT_NORMAL (0x0080U << RTFS_DOS_SHIFT)
149 /** Temporary object (NT). */
150 #define RTFS_DOS_NT_TEMPORARY (0x0100U << RTFS_DOS_SHIFT)
151 /** Sparse file (NT). */
152 #define RTFS_DOS_NT_SPARSE_FILE (0x0200U << RTFS_DOS_SHIFT)
153 /** Reparse point (NT). */
154 #define RTFS_DOS_NT_REPARSE_POINT (0x0400U << RTFS_DOS_SHIFT)
155 /** Compressed object (NT).
156 * For a directory, compression is the default for new files. */
157 #define RTFS_DOS_NT_COMPRESSED (0x0800U << RTFS_DOS_SHIFT)
158 /** Physically offline data (NT).
159 * MSDN say, don't mess with this one. */
160 #define RTFS_DOS_NT_OFFLINE (0x1000U << RTFS_DOS_SHIFT)
161 /** Not content indexed by the content indexing service (NT). */
162 #define RTFS_DOS_NT_NOT_CONTENT_INDEXED (0x2000U << RTFS_DOS_SHIFT)
163 /** Encryped object (NT).
164 * For a directory, encrypted is the default for new files. */
165 #define RTFS_DOS_NT_ENCRYPTED (0x4000U << RTFS_DOS_SHIFT)
170 /** @name Filesystem Object Type Predicates.
172 /** Checks the mode flags indicate a named pipe (fifo) (S_ISFIFO). */
173 #define RTFS_IS_FIFO(fMode) ( ((fMode) & RTFS_TYPE_MASK) == RTFS_TYPE_FIFO )
174 /** Checks the mode flags indicate a character device (S_ISCHR). */
175 #define RTFS_IS_DEV_CHAR(fMode) ( ((fMode) & RTFS_TYPE_MASK) == RTFS_TYPE_DEV_CHAR )
176 /** Checks the mode flags indicate a directory (S_ISDIR). */
177 #define RTFS_IS_DIRECTORY(fMode) ( ((fMode) & RTFS_TYPE_MASK) == RTFS_TYPE_DIRECTORY )
178 /** Checks the mode flags indicate a block device (S_ISBLK). */
179 #define RTFS_IS_DEV_BLOCK(fMode) ( ((fMode) & RTFS_TYPE_MASK) == RTFS_TYPE_DEV_BLOCK )
180 /** Checks the mode flags indicate a regular file (S_ISREG). */
181 #define RTFS_IS_FILE(fMode) ( ((fMode) & RTFS_TYPE_MASK) == RTFS_TYPE_FILE )
182 /** Checks the mode flags indicate a symbolic link (S_ISLNK). */
183 #define RTFS_IS_SYMLINK(fMode) ( ((fMode) & RTFS_TYPE_MASK) == RTFS_TYPE_SYMLINK )
184 /** Checks the mode flags indicate a socket (S_ISSOCK). */
185 #define RTFS_IS_SOCKET(fMode) ( ((fMode) & RTFS_TYPE_MASK) == RTFS_TYPE_SOCKET )
186 /** Checks the mode flags indicate a whiteout (S_ISWHT). */
187 #define RTFS_IS_WHITEOUT(fMode) ( ((fMode) & RTFS_TYPE_MASK) == RTFS_TYPE_WHITEOUT )
192 * Filesystem type IDs returned by RTFsQueryType.
194 * This enum is subject to changes and must not be used as part of any ABI or
195 * binary format (file, network, etc).
197 * @remarks When adding new entries, please update RTFsTypeName(). Also, try
198 * add them to the most natural group.
200 typedef enum RTFSTYPE
202 /** Unknown file system. */
203 RTFSTYPE_UNKNOWN
= 0,
205 /** Universal Disk Format. */
207 /** ISO 9660, aka Compact Disc File System (CDFS). */
209 /** Filesystem in Userspace. */
211 /** VirtualBox shared folders. */
229 /** New Technology File System. */
231 /** FAT12, FAT16 and FAT32 lumped into one basket.
232 * The partition size limit of FAT12 and FAT16 will be the factor
233 * limiting the file size (except, perhaps for the 64KB cluster case on
234 * non-Windows hosts). */
238 /** Zettabyte File System. */
240 /** Unix File System. */
242 /** Network File System. */
246 /** Hierarchical File System. */
248 /** @todo RTFSTYPE_HFS_PLUS? */
255 /** High Performance File System. */
257 /** Journaled File System (v2). */
260 /** The end of valid Filesystem types IDs. */
262 /** The usual 32-bit type blow up. */
263 RTFSTYPE_32BIT_HACK
= 0x7fffffff
265 /** Pointer to a Filesystem type ID. */
266 typedef RTFSTYPE
*PRTFSTYPE
;
270 * The available additional information in a RTFSOBJATTR object.
272 typedef enum RTFSOBJATTRADD
274 /** No additional information is available / requested. */
275 RTFSOBJATTRADD_NOTHING
= 1,
276 /** The additional unix attributes (RTFSOBJATTR::u::Unix) are available /
279 /** The additional unix attributes (RTFSOBJATTR::u::UnixOwner) are
280 * available / requested. */
281 RTFSOBJATTRADD_UNIX_OWNER
,
282 /** The additional unix attributes (RTFSOBJATTR::u::UnixGroup) are
283 * available / requested. */
284 RTFSOBJATTRADD_UNIX_GROUP
,
285 /** The additional extended attribute size (RTFSOBJATTR::u::EASize) is available / requested. */
286 RTFSOBJATTRADD_EASIZE
,
287 /** The last valid item (inclusive).
288 * The valid range is RTFSOBJATTRADD_NOTHING thru RTFSOBJATTRADD_LAST. */
289 RTFSOBJATTRADD_LAST
= RTFSOBJATTRADD_EASIZE
,
291 /** The usual 32-bit hack. */
292 RTFSOBJATTRADD_32BIT_SIZE_HACK
= 0x7fffffff
295 /** The number of bytes reserved for the additional attribute union. */
296 #define RTFSOBJATTRUNION_MAX_SIZE 128
299 * Additional Unix Attributes (RTFSOBJATTRADD_UNIX).
301 typedef struct RTFSOBJATTRUNIX
303 /** The user owning the filesystem object (st_uid).
304 * This field is NIL_UID if not supported. */
307 /** The group the filesystem object is assigned (st_gid).
308 * This field is NIL_GID if not supported. */
311 /** Number of hard links to this filesystem object (st_nlink).
312 * This field is 1 if the filesystem doesn't support hardlinking or
313 * the information isn't available.
317 /** The device number of the device which this filesystem object resides on (st_dev).
318 * This field is 0 if this information is not available. */
321 /** The unique identifier (within the filesystem) of this filesystem object (st_ino).
322 * Together with INodeIdDevice, this field can be used as a OS wide unique id
323 * when both their values are not 0.
324 * This field is 0 if the information is not available. */
327 /** User flags (st_flags).
328 * This field is 0 if this information is not available. */
331 /** The current generation number (st_gen).
332 * This field is 0 if this information is not available. */
333 uint32_t GenerationId
;
335 /** The device number of a character or block device type object (st_rdev).
336 * This field is 0 if the file isn't of a character or block device type and
337 * when the OS doesn't subscribe to the major+minor device idenfication scheme. */
343 * Additional Unix Attributes (RTFSOBJATTRADD_UNIX_OWNER).
345 * @remarks This interface is mainly for TAR.
347 typedef struct RTFSOBJATTRUNIXOWNER
349 /** The user owning the filesystem object (st_uid).
350 * This field is NIL_UID if not supported. */
353 * Empty if not available or not supported, truncated if too long. */
354 char szName
[RTFSOBJATTRUNION_MAX_SIZE
- sizeof(RTUID
)];
355 } RTFSOBJATTRUNIXOWNER
;
359 * Additional Unix Attributes (RTFSOBJATTRADD_UNIX_GROUP).
361 * @remarks This interface is mainly for TAR.
363 typedef struct RTFSOBJATTRUNIXGROUP
365 /** The user owning the filesystem object (st_uid).
366 * This field is NIL_GID if not supported. */
369 * Empty if not available or not supported, truncated if too long. */
370 char szName
[RTFSOBJATTRUNION_MAX_SIZE
- sizeof(RTGID
)];
371 } RTFSOBJATTRUNIXGROUP
;
375 * Filesystem object attributes.
377 typedef struct RTFSOBJATTR
379 /** Mode flags (st_mode). RTFS_UNIX_*, RTFS_TYPE_*, and RTFS_DOS_*. */
382 /** The additional attributes available. */
383 RTFSOBJATTRADD enmAdditional
;
386 * Additional attributes.
388 * Unless explicitly specified to an API, the API can provide additional
389 * data as it is provided by the underlying OS.
391 union RTFSOBJATTRUNION
393 /** Additional Unix Attributes - RTFSOBJATTRADD_UNIX. */
394 RTFSOBJATTRUNIX Unix
;
395 /** Additional Unix Owner Attributes - RTFSOBJATTRADD_UNIX_OWNER. */
396 RTFSOBJATTRUNIXOWNER UnixOwner
;
397 /** Additional Unix Group Attributes - RTFSOBJATTRADD_UNIX_GROUP. */
398 RTFSOBJATTRUNIXGROUP UnixGroup
;
401 * Extended attribute size is available when RTFS_DOS_HAVE_EA_SIZE is set.
403 struct RTFSOBJATTREASIZE
408 /** Reserved space. */
409 uint8_t abReserveSpace
[128];
412 /** Pointer to a filesystem object attributes structure. */
413 typedef RTFSOBJATTR
*PRTFSOBJATTR
;
414 /** Pointer to a const filesystem object attributes structure. */
415 typedef const RTFSOBJATTR
*PCRTFSOBJATTR
;
419 * Filesystem object information structure.
421 * This is returned by the RTPathQueryInfo(), RTFileQueryInfo() and RTDirRead() APIs.
423 typedef struct RTFSOBJINFO
425 /** Logical size (st_size).
426 * For normal files this is the size of the file.
427 * For symbolic links, this is the length of the path name contained
428 * in the symbolic link.
429 * For other objects this fields needs to be specified.
433 /** Disk allocation size (st_blocks * DEV_BSIZE). */
436 /** Time of last access (st_atime). */
437 RTTIMESPEC AccessTime
;
439 /** Time of last data modification (st_mtime). */
440 RTTIMESPEC ModificationTime
;
442 /** Time of last status change (st_ctime).
443 * If not available this is set to ModificationTime.
445 RTTIMESPEC ChangeTime
;
447 /** Time of file birth (st_birthtime).
448 * If not available this is set to ChangeTime.
450 RTTIMESPEC BirthTime
;
456 /** Pointer to a filesystem object information structure. */
457 typedef RTFSOBJINFO
*PRTFSOBJINFO
;
458 /** Pointer to a const filesystem object information structure. */
459 typedef const RTFSOBJINFO
*PCRTFSOBJINFO
;
465 * Query the sizes of a filesystem.
467 * @returns iprt status code.
468 * @param pszFsPath Path within the mounted filesystem.
469 * @param pcbTotal Where to store the total filesystem space. (Optional)
470 * @param pcbFree Where to store the remaining free space in the filesystem. (Optional)
471 * @param pcbBlock Where to store the block size. (Optional)
472 * @param pcbSector Where to store the sector size. (Optional)
474 * @sa RTFileQueryFsSizes
476 RTR3DECL(int) RTFsQuerySizes(const char *pszFsPath
, PRTFOFF pcbTotal
, RTFOFF
*pcbFree
,
477 uint32_t *pcbBlock
, uint32_t *pcbSector
);
480 * Query the mountpoint of a filesystem.
482 * @returns iprt status code.
483 * @returns VERR_BUFFER_OVERFLOW if cbMountpoint isn't enough.
484 * @param pszFsPath Path within the mounted filesystem.
485 * @param pszMountpoint Where to store the mountpoint path.
486 * @param cbMountpoint Size of the buffer pointed to by pszMountpoint.
488 RTR3DECL(int) RTFsQueryMountpoint(const char *pszFsPath
, char *pszMountpoint
, size_t cbMountpoint
);
491 * Query the label of a filesystem.
493 * @returns iprt status code.
494 * @returns VERR_BUFFER_OVERFLOW if cbLabel isn't enough.
495 * @param pszFsPath Path within the mounted filesystem.
496 * @param pszLabel Where to store the label.
497 * @param cbLabel Size of the buffer pointed to by pszLabel.
499 RTR3DECL(int) RTFsQueryLabel(const char *pszFsPath
, char *pszLabel
, size_t cbLabel
);
502 * Query the serial number of a filesystem.
504 * @returns iprt status code.
505 * @param pszFsPath Path within the mounted filesystem.
506 * @param pu32Serial Where to store the serial number.
508 RTR3DECL(int) RTFsQuerySerial(const char *pszFsPath
, uint32_t *pu32Serial
);
511 * Query the name of the filesystem driver.
513 * @returns iprt status code.
514 * @returns VERR_BUFFER_OVERFLOW if cbFsDriver isn't enough.
515 * @param pszFsPath Path within the mounted filesystem.
516 * @param pszFsDriver Where to store the filesystem driver name.
517 * @param cbFsDriver Size of the buffer pointed to by pszFsDriver.
519 RTR3DECL(int) RTFsQueryDriver(const char *pszFsPath
, char *pszFsDriver
, size_t cbFsDriver
);
522 * Query the name of the filesystem the file is located on.
524 * @returns iprt status code.
525 * @param pszFsPath Path within the mounted filesystem. It must exist.
526 * In case this is a symlink, the file it refers to is
528 * @param penmType Where to store the filesystem type, this is always
529 * set. See RTFSTYPE for the values.
531 RTR3DECL(int) RTFsQueryType(const char *pszFsPath
, PRTFSTYPE penmType
);
533 #endif /* IN_RING3 */
536 * Gets the name of a filesystem type.
538 * @returns Pointer to a read-only string containing the name.
539 * @param enmType A valid filesystem ID. If outside the valid range,
540 * the returned string will be pointing to a static
541 * memory buffer which will be changed on subsequent
542 * calls to this function by any thread.
544 RTDECL(const char *) RTFsTypeName(RTFSTYPE enmType
);
547 * Filesystem properties.
549 typedef struct RTFSPROPERTIES
551 /** The maximum size of a filesystem object name.
552 * This does not include the '\\0'. */
553 uint32_t cbMaxComponent
;
555 /** True if the filesystem is remote.
556 * False if the filesystem is local. */
559 /** True if the filesystem is case sensitive.
560 * False if the filesystem is case insensitive. */
563 /** True if the filesystem is mounted read only.
564 * False if the filesystem is mounted read write. */
567 /** True if the filesystem can encode unicode object names.
568 * False if it can't. */
569 bool fSupportsUnicode
;
571 /** True if the filesystem is compresses.
572 * False if it isn't or we don't know. */
575 /** True if the filesystem compresses of individual files.
576 * False if it doesn't or we don't know. */
577 bool fFileCompression
;
581 /** Pointer to a filesystem properties structure. */
582 typedef RTFSPROPERTIES
*PRTFSPROPERTIES
;
583 /** Pointer to a const filesystem properties structure. */
584 typedef RTFSPROPERTIES
const *PCRTFSPROPERTIES
;
589 * Query the properties of a mounted filesystem.
591 * @returns iprt status code.
592 * @param pszFsPath Path within the mounted filesystem.
593 * @param pProperties Where to store the properties.
595 RTR3DECL(int) RTFsQueryProperties(const char *pszFsPath
, PRTFSPROPERTIES pProperties
);
598 * Checks if the given volume is case sensitive or not.
600 * This may be misleading in some cases as we lack the necessary APIs to query
601 * the information on some system (or choose not to use them) and are instead
602 * returning the general position on case sensitive file name of the system.
604 * @returns @c true if case sensitive, @c false if not.
605 * @param pszFsPath Path within the mounted file system.
607 RTR3DECL(bool) RTFsIsCaseSensitive(const char *pszFsPath
);
610 * Mountpoint enumerator callback.
612 * @returns iprt status code. Failure terminates the enumeration.
613 * @param pszMountpoint The mountpoint name.
614 * @param pvUser The user argument.
616 typedef DECLCALLBACK(int) FNRTFSMOUNTPOINTENUM(const char *pszMountpoint
, void *pvUser
);
617 /** Pointer to a FNRTFSMOUNTPOINTENUM(). */
618 typedef FNRTFSMOUNTPOINTENUM
*PFNRTFSMOUNTPOINTENUM
;
621 * Enumerate mount points.
623 * @returns iprt status code.
624 * @param pfnCallback The callback function.
625 * @param pvUser The user argument to the callback.
627 RTR3DECL(int) RTFsMountpointsEnum(PFNRTFSMOUNTPOINTENUM pfnCallback
, void *pvUser
);
630 #endif /* IN_RING3 */
636 #endif /* !___iprt_fs_h */