filesystem library

File Attributes

Table Of All Supported Attributes

name of attribute	return type	description	POSIX	Win32
`filename`	`string_type`	the name of the file or directory		rw
`hidden`	`bool`	whether the file is hidden or visible	r (filename starts with '.')
POSIX file types (see POSIX documentation for further informations)
`is_directory`	`bool`	whether the file is a directory	r
`is_regular`	`bool`	this is a regular file	r
`is_link`	`bool`		r
`is_char_device`	`bool`		r
`is_block_device`	`bool`		r
`is_fifo`	`bool`		r
`is_socket`	`bool`		r
POSIX members of `stat`
`size`	`off_t`	total file size (characters)	r
`block_size`	`blksize_t`	blocksize for filesystem I/O	r
`blocks`	`blkcnt_t`	number of blocks allocated	r
`device`	`dev_t`	device	r
`inode`	`ino_t`	inode	r
`no_links`	`nlink_t`	number of hard links	r
`rdev`	`dev_t`	device type (if inode device)	r
times
`access_time`	`std::time_t`	time of last access	rw
`modification_time`	`std::time_t`	time of last modification	rw
`change_time`	`std::time_t`	time of last change	r
permissions for user
`set_uid`	`bool`	whether the UID bit is set	rw
`user_read`	`bool`		rw
`user_write`	`bool`		rw
`user_execute`	`bool`		rw
`user_id`	`uid_t`	user ID of owner	rw
`user_name`	`string_type`	user name of owner	rw
permissions for group
`set_gid`	`bool`	whether the GID bit is set	rw
`group_read`	`bool`		rw
`group_write`	`bool`		rw
`group_execute`	`bool`		rw
`group_id`	`gid_t`	group ID of owner	rw
`group_name`	`string_type`	group name of owner	rw
permissions for others
`sticky`	`bool`	whether the sticky bit is set	rw
`others_read`	`bool`		rw
`others_write`	`bool`		rw
`others_execute`	`bool`		rw
			r

The protection member of stat (according to POSIX) is not supported since it can be accessed via the permission attributes like user_read, etc.

Return Types

The return type of filename, user_name and group_name is boost::filesystem::string_type.
off_t, blksize_t, blkcnt_t, dev_t, ino_t, nlink_t, uid_t and gid_t are defined in boost::filesystem::sys_types. They are typedefs to corresponding types provided by the underlying operating system.

Requirements

All implemented attributes meet some requirements which should also be met by user defined new file attributes:

a method static bool is_specialized () specifies whether the attributes is implemented and does what it is expected to do.
a method static bool is_readable () must return true if the method get does something reasonable.
the method static bool is_writeble () returns true if the method set is provided by this implementation and actually changes the attribute of the file.
a typedef some_type value_type; from the type which represents the actual value of the attribute with the name must exist within the attribute's class definition.
if is_specialized and is_readable both return true a method static value_type get (entry_rep const &) must exist where entry_rep is a class containing all the details of the representation of the attributes of the file.
if is_specialized and is_writeable both return true a method static void set (entry_rep &, value_type const &) must exist. entry_rep is the same as in method get.

User Defined Attributes

The user can define its own file attributes but they must meet the requirements above. There are only a few things which are guaranteed in the interface of entry_rep. One is the method string_type entry_rep::entry () which returns the name of the file. The following example uses this method to return whether the filename starts with a specific letter:

	template <char_type C>
	class first_letter {
	public:
		typedef bool value_type;
		
		static bool is_specialized () {
			return true;
		}
		static bool is_readable () {
			return true;
		}
		static bool is_writeable () {
			return false;
		}
		
		static value_type get (entry_rep const &r) {
			return (!r.entry ().empty () && r.entry () [0] == C);
		}
	};

and it can be used to copy all files with names starting with 'a' into a vector:

	std::vector  v;
	boost::filesystem::dir_it i ("."), end;
	for (; i != end; ++i) {
		if (boost::filesystem::get <first_letter <'a'> > (i)) {
			v.push_back (*i);
		}
	}