FSINFO

NAME

SYNOPSIS

#include <sys/types.h>
#include <sys/fsinfo.h>
#include <unistd.h>
#include <fcntl.h>           /* Definition of AT_* constants */

int fsinfo(int dirfd, const char *pathname,
           struct fsinfo_params *params,
           void *buffer, size_t buf_size);

Note: There is no glibc wrapper for fsinfo(); see NOTES.  

DESCRIPTION

fsinfo() retrieves the desired filesystem attribute, as selected by the parameters pointed to by params, and stores its value in the buffer pointed to by buffer.

The parameter structure is optional, defaulting to all the parameters being 0 if the pointer is NULL. The structure looks like the following:

struct fsinfo_params {
    __u32 at_flags;     /* AT_SYMLINK_NOFOLLOW and similar flags */
    __u32 request;      /* Requested attribute */
    __u32 Nth;          /* Instance of attribute */
    __u32 Mth;          /* Subinstance of Nth instance */
    __u32 __reserved[6]; /* Reserved params; all must be 0 */
};

The filesystem to be queried is looked up using a combination of dfd, pathname and params->at_flags. This is discussed in more detail below.

The desired attribute is indicated by params->request. If params is NULL, this will default to fsinfo_attr_statfs, which retrieves some of the information returned by statfs(). The available attributes are described below in the "THE ATTRIBUTES" section.

Some attributes can have multiple values and some can even have multiple instances with multiple values. For example, a network filesystem might use multiple servers. The names of each of these servers can be retrieved by using params->Nth to iterate through all the instances until error ENODATA occurs, indicating the end of the list. Further, each server might have multiple addresses available; these can be enumerated using params->Nth to iterate the servers and params->Mth to iterate the addresses of the Nth server.

The amount of data written into the buffer depends on the attribute selected. Some attributes return variable-length strings and some return fixed-size structures. If either buffer is NULL or buf_size is 0 then the size of the attribute value will be returned and nothing will be written into the buffer.

The params->__reserved parameters must all be 0.  

Allowance for Future Attribute Expansion

To allow for the future expansion and addition of fields to any fixed-size structure attribute, fsinfo() makes the following guarantees:

1. It will always clear any excess space in the buffer.
2. It will always return the actual size of the data.
3. It will truncate the data to fit it into the buffer rather than giving an error.
4. Any new version of a structure will incorporate all the fields from the old version at same offsets.

So, for example, if the caller is running on an older version of the kernel with an older, smaller version of the structure than was asked for, the kernel will write the smaller version into the buffer and will clear the remainder of the buffer to make sure any additional fields are set to 0. The function will return the actual size of the data.

On the other hand, if the caller is running on a newer version of the kernel with a newer version of the structure that is larger than the buffer, the write to the buffer will be truncated to fit as necessary and the actual size of the data will be returned.

Note that this doesn't apply to variable-length string attributes.

Invoking fsinfo():

To access a file's status, no permissions are required on the file itself, but in the case of fsinfo() with a path, execute (search) permission is required on all of the directories in pathname that lead to the file.

fsinfo() uses pathname, dirfd and params->at_flags to locate the target file in one of a variety of ways:

[*] By absolute path.

pathname points to an absolute path and dirfd is ignored. The file is looked up by name, starting from the root of the filesystem as seen by the calling process.

[*] By cwd-relative path.

pathname points to a relative path and dirfd is AT_FDCWD. The file is looked up by name, starting from the current working directory.

[*] By dir-relative path.

pathname points to relative path and dirfd indicates a file descriptor pointing to a directory. The file is looked up by name, starting from the directory specified by dirfd.

[*] By file descriptor.

pathname is NULL and dirfd indicates a file descriptor. The file attached to the file descriptor is queried directly. The file descriptor may point to any type of file, not just a directory.

flags can be used to influence a path-based lookup. A value for flags is constructed by OR'ing together zero or more of the following constants:

AT_EMPTY_PATH

If pathname is an empty string, operate on the file referred to by dirfd (which may have been obtained using the open(2) O_PATH flag). If dirfd is AT_FDCWD, the call operates on the current working directory. In this case, dirfd can refer to any type of file, not just a directory. This flag is Linux-specific; define _GNU_SOURCE to obtain its definition.

AT_NO_AUTOMOUNT

Don't automount the terminal ("basename") component of pathname if it is a directory that is an automount point. This allows the caller to gather attributes of the filesystem holding an automount point (rather than the filesystem it would mount). This flag can be used in tools that scan directories to prevent mass-automounting of a directory of automount points. The AT_NO_AUTOMOUNT flag has no effect if the mount point has already been mounted over. This flag is Linux-specific; define _GNU_SOURCE to obtain its definition.

AT_SYMLINK_NOFOLLOW

If pathname is a symbolic link, do not dereference it: instead return information about the link itself, like lstat().

THE ATTRIBUTES

There is a range of attributes that can be selected from. These are:

fsinfo_attr_statfs

This retrieves the "dynamic" statfs information, such as block and file counts, that are expected to change whilst a filesystem is being used. This fills in the following structure:

struct fsinfo_statfs {
    __u64 f_blocks;     /* Total number of blocks in fs */
    __u64 f_bfree;      /* Total number of free blocks */
    __u64 f_bavail;     /* Number of free blocks available to ordinary user */
    __u64 f_files;      /* Total number of file nodes in fs */
    __u64 f_ffree;      /* Number of free file nodes */
    __u64 f_favail;     /* Number of free file nodes available to ordinary user */
    __u32 f_bsize;      /* Optimal block size */
    __u32 f_frsize;     /* Fragment size */
};

The fields correspond to those of the same name returned by statfs().

fsinfo_attr_fsinfo

This retrieves information about the fsinfo() system call itself. This fills in the following structure:

struct fsinfo_fsinfo {
    __u32 max_attr;
    __u32 max_cap;
};

The max_attr value indicates the number of attributes supported by the fsinfo() system call, and max_cap indicates the number of capability bits supported by the fsinfo_attr_capabilities attribute. The first corresponds to fsinfo_attr__nr and the second to fsinfo_cap__nr in the header file.

fsinfo_attr_ids

This retrieves a number of fixed IDs and other static information otherwise available through statfs(). The following structure is filled in:

struct fsinfo_ids {
    char  f_fs_name[15 + 1]; /* Filesystem name */
    __u64 f_flags;      /* Filesystem mount flags (MS_*) */
    __u64 f_fsid;       /* Short 64-bit Filesystem ID */
    __u64 f_sb_id;      /* Internal superblock ID */
    __u32 f_fstype;     /* Filesystem type from linux/magic.h */
    __u32 f_dev_major;  /* As st_dev_* from struct statx */
    __u32 f_dev_minor;
};

Most of these are filled in as for statfs(), with the addition of the filesystem's symbolic name in f_fs_name and an identifier for use in notifications in f_sb_id.

fsinfo_attr_limits

This retrieves information about the limits of what a filesystem can support. The following structure is filled in:

struct fsinfo_limits {
    __u64 max_file_size;
    __u64 max_uid;
    __u64 max_gid;
    __u64 max_projid;
    __u32 max_dev_major;
    __u32 max_dev_minor;
    __u32 max_hard_links;
    __u32 max_xattr_body_len;
    __u16 max_xattr_name_len;
    __u16 max_filename_len;
    __u16 max_symlink_len;
    __u16 __reserved[1];
};

These indicate the maximum supported sizes for a variety of filesystem objects, including the file size, the extended attribute name length and body length, the filename length and the symlink body length.

It also indicates the maximum representable values for a User ID, a Group ID, a Project ID, a device major number and a device minor number.

And finally, it indicates the maximum number of hard links that can be made to a file.

Note that some of these values may be zero if the underlying object or concept is not supported by the filesystem or the medium.

fsinfo_attr_supports

This retrieves information about what bits a filesystem supports in various masks. The following structure is filled in:

struct fsinfo_supports {
    __u64 stx_attributes;
    __u32 stx_mask;
    __u32 ioc_flags;
    __u32 win_file_attrs;
    __u32 __reserved[1];
};

The stx_attributes and stx_mask fields indicate what bits in the struct statx fields of the matching names are supported by the filesystem.

The ioc_flags field indicates what FS_*_FL flag bits as used through the FS_IOC_GET/SETFLAGS ioctls are supported by the filesystem.

The win_file_attrs indicates what DOS/Windows file attributes a filesystem supports, if any.

fsinfo_attr_capabilities

This retrieves information about what features a filesystem supports as a series of single bit indicators. The following structure is filled in:

struct fsinfo_capabilities {
    __u8 capabilities[(fsinfo_cap__nr + 7) / 8];
};

where the bit of interest can be found by:

        p->capabilities[bit / 8] & (1 << (bit % 8)))

The bits are listed by enum fsinfo_capability and fsinfo_cap__nr is one more than the last capability bit listed in the header file.

Note that the number of capability bits actually supported by the kernel can be found using the fsinfo_attr_fsinfo attribute.

The capability bits and their meanings are listed below in the "THE CAPABILITIES" section.

fsinfo_attr_timestamp_info

This retrieves information about what timestamp resolution and scope is supported by a filesystem for each of the file timestamps. The following structure is filled in:

struct fsinfo_timestamp_info {
        __s64 minimum_timestamp;
        __s64 maximum_timestamp;
        __u16 atime_gran_mantissa;
        __u16 btime_gran_mantissa;
        __u16 ctime_gran_mantissa;
        __u16 mtime_gran_mantissa;
        __s8  atime_gran_exponent;
        __s8  btime_gran_exponent;
        __s8  ctime_gran_exponent;
        __s8  mtime_gran_exponent;
        __u32 __reserved[1];
};

where minimum_timestamp and maximum_timestamp are the limits on the timestamps that the filesystem supports and *time_gran_mantissa and *time_gran_exponent indicate the granularity of each timestamp in terms of seconds, using the formula:

mantissa * pow(10, exponent) Seconds

where exponent may be negative and the result may be a fraction of a second.

Four timestamps are detailed: Access time, Birth/creation time, Change time and Modification time. Capability bits are defined that specify whether each of these exist in the filesystem or not.

Note that the timestamp description may be approximated or inaccurate if the file is actually remote or is the union of multiple objects.

fsinfo_attr_volume_id

This retrieves the system's superblock volume identifier as a variable-length string. This does not necessarily represent a value stored in the medium but might be constructed on the fly.

For instance, for a block device this is the block device identifier (eg. "sdb2"); for AFS this would be the numeric volume identifier.

fsinfo_attr_volume_uuid

This retrieves the volume UUID, if there is one, as a little-endian binary UUID. This fills in the following structure:

struct fsinfo_volume_uuid {
    __u8 uuid[16];
};

fsinfo_attr_volume_name

This retrieves the filesystem's volume name as a variable-length string. This is expected to represent a name stored in the medium.

For a block device, this might be a label stored in the superblock. For a network filesystem, this might be a logical volume name of some sort.

fsinfo_attr_cell_name
fsinfo_attr_domain_name

These two attributes are variable-length string attributes that may be used to obtain information about network filesystems. An AFS volume, for instance, belongs to a named cell. CIFS shares may belong to a domain.

fsinfo_attr_realm_name

This attribute is variable-length string that indicates the Kerberos realm that a filesystem's authentication tokens should come from.

fsinfo_attr_server_name

This attribute is a multiple-value attribute that lists the names of the servers that are backing a network filesystem. Each value is a variable-length string. The values are enumerated by calling fsinfo() multiple times, incrementing params->Nth each time until an ENODATA error occurs, thereby indicating the end of the list.

fsinfo_attr_server_address

This attribute is a multiple-instance, multiple-value attribute that lists the addresses of the servers that are backing a network filesystem. Each value is a structure of the following type:

struct fsinfo_server_address {
    struct __kernel_sockaddr_storage address;
};

Where the address may be AF_INET, AF_INET6, AF_RXRPC or any other type as appropriate to the filesystem.

The values are enumerated by calling fsinfo() multiple times, incrementing params->Nth to step through the servers and params->Mth to step through the addresses of the Nth server each time until ENODATA errors occur, thereby indicating either the end of a server's address list or the end of the server list.

Barring the server list changing whilst being accessed, it is expected that the params->Nth will correspond to params->Nth for fsinfo_attr_server_name.

fsinfo_attr_parameter

This attribute is a multiple-value attribute that lists the values of the mount parameters for a filesystem as variable-length strings.

The parameters are enumerated by calling fsinfo() multiple times, incrementing params->Nth to step through them until error ENODATA is given.

Parameter strings are presented in a form akin to the way they're passed to the context created by the fsopen() system call. For example, straight text parameters will be rendered as something like:

"o data=journal"
"o noquota"

Where the initial "word" indicates the option form.

fsinfo_attr_source

This attribute is a multiple-value attribute that lists the mount sources for a filesystem as variable-length strings. Normally only one source will be available, but the possibility of having more than one is allowed for.

The sources are enumerated by calling fsinfo() multiple times, incrementing params->Nth to step through them until error ENODATA is given.

Source strings are presented in a form akin to the way they're passed to the context created by the fsopen() system call. For example, they will be rendered as something like:

"s /dev/sda1"
"s example.com/pub/linux/"

Where the initial "word" indicates the option form.

fsinfo_attr_name_encoding

This attribute is variable-length string that indicates the filename encoding used by the filesystem. The default is "utf8". Note that this may indicate a non-8-bit encoding if that's what the underlying filesystem actually supports.

fsinfo_attr_name_codepage

This attribute is variable-length string that indicates the codepage used to translate filenames from the filesystem to the system if this is applicable to the filesystem.

fsinfo_attr_io_size

This retrieves information about the I/O sizes supported by the filesystem. The following structure is filled in:

struct fsinfo_io_size {
    __u32 block_size;
    __u32 max_single_read_size;
    __u32 max_single_write_size;
    __u32 best_read_size;
    __u32 best_write_size;
};

Where block_size indicates the fundamental I/O block size of the filesystem as something O_DIRECT read/write sizes must be a multiple of; max_single_write_size and max_single_write_size indicate the maximum sizes for individual unbuffered data transfer operations; and best_read_size and best_write_size indicate the recommended I/O sizes.

Note that any of these may be zero if inapplicable or indeterminable.

THE CAPABILITIES

There are number of capability bits in a bit array that can be retrieved using fsinfo_attr_capabilities. These give information about features of the filesystem driver and the specific filesystem.

fsinfo_cap_is_kernel_fs
fsinfo_cap_is_block_fs
fsinfo_cap_is_flash_fs
fsinfo_cap_is_network_fs
fsinfo_cap_is_automounter_fs

These indicate the primary type of the filesystem. kernel filesystems are special communication interfaces that substitute files for system calls; examples include procfs and sysfs. block filesystems require a block device on which to operate; examples include ext4 and XFS. flash filesystems require an MTD device on which to operate; examples include JFFS2. network filesystems require access to the network and contact one or more servers; examples include NFS and AFS. automounter filesystems are kernel special filesystems that host automount points and triggers to dynamically create automount points. Examples include autofs and AFS's dynamic root.

fsinfo_cap_automounts

The filesystem may have automount points that can be triggered by pathwalk.

fsinfo_cap_adv_locks

The filesystem supports advisory file locks. For a network filesystem, this indicates that the advisory file locks are cross-client (and also between server and its local filesystem on something like NFS).

fsinfo_cap_mand_locks

The filesystem supports mandatory file locks. For a network filesystem, this indicates that the mandatory file locks are cross-client (and also between server and its local filesystem on something like NFS).

fsinfo_cap_leases

The filesystem supports leases. For a network filesystem, this means that the server will tell the client to clean up its state on a file before passing the lease to another client.

fsinfo_cap_uids
fsinfo_cap_gids
fsinfo_cap_projids

These indicate that the filesystem supports numeric user IDs, group IDs and project IDs respectively.

fsinfo_cap_id_names
fsinfo_cap_id_guids

These indicate that the filesystem employs textual names and/or GUIDs as identifiers.

fsinfo_cap_windows_attrs

Indicates that the filesystem supports some Windows FILE_* attributes.

fsinfo_cap_user_quotas
fsinfo_cap_group_quotas
fsinfo_cap_project_quotas

These indicate that the filesystem supports quotas for users, groups and projects respectively.

fsinfo_cap_xattrs
fsinfo_cap_symlinks
fsinfo_cap_hard_links
fsinfo_cap_hard_links_1dir
fsinfo_cap_device_files
fsinfo_cap_unix_specials

These indicate that the filesystem supports respectively extended attributes; symbolic links; hard links spanning direcories; hard links, but only within a directory; block and character device files; and UNIX special files, such as FIFO and socket.

fsinfo_cap_journal
fsinfo_cap_data_is_journalled

The first of these indicates that the filesystem has a journal and the second that the file data changes are being journalled.

fsinfo_cap_o_sync
fsinfo_cap_o_direct

These indicate that O_SYNC and O_DIRECT are supported respectively.

fsinfo_cap_volume_id
fsinfo_cap_volume_uuid
fsinfo_cap_volume_name
fsinfo_cap_volume_fsid
fsinfo_cap_cell_name
fsinfo_cap_domain_name
fsinfo_cap_realm_name

These indicate if various attributes are supported by the filesystem, where fsinfo_cap_X here corresponds to fsinfo_attr_X.

fsinfo_cap_iver_all_change
fsinfo_cap_iver_data_change
fsinfo_cap_iver_mono_incr

These indicate if i_version on an inode in the filesystem is supported and how it behaves. all_change indicates that i_version is incremented on metadata changes as well as data changes. data_change indicates that i_version is only incremented on data changes, including truncation. mono_incr indicates that i_version is incremented by exactly 1 for each change made.

fsinfo_cap_resource_forks

This indicates that the filesystem supports some sort of resource fork or alternate data stream on a file. This isn't the same as an extended attribute.

fsinfo_cap_name_case_indep
fsinfo_cap_name_non_utf8
fsinfo_cap_name_has_codepage

These indicate certain facts about the filenames in a filesystem: whether they're case-independent; if they're not UTF-8; and if there's a codepage employed to map the names.

fsinfo_cap_sparse

This indicates that the filesystem supports sparse files.

fsinfo_cap_not_persistent

This indicates that the filesystem is not persistent, and that any data stored here will not be saved in the event that the filesystem is unmounted, the machine is rebooted or the machine loses power.

fsinfo_cap_no_unix_mode

This indicates that the filesystem doesn't support the UNIX mode permissions bits.

fsinfo_cap_has_atime
fsinfo_cap_has_btime
fsinfo_cap_has_ctime
fsinfo_cap_has_mtime

These indicate as to what timestamps a filesystem supports, including: Access time, Birth/creation time, Change time (metadata and data) and Modification time (data only).

RETURN VALUE

ERRORS

EACCES

Search permission is denied for one of the directories in the path prefix of pathname. (See also path_resolution(7).)

EBADF

dirfd is not a valid open file descriptor.

EFAULT

pathname is NULL or pathname, params or buffer point to a location outside the process's accessible address space.

EINVAL

Reserved flag specified in params->at_flags or one of params->__reserved[] is not 0.

EOPNOTSUPP

Unsupported attribute requested in params->request. This may be beyond the limit of the supported attribute set or may just not be one that's supported by the filesystem.

ENODATA

Unavailable attribute value requested by params->Nth and/or params->Mth.

ELOOP

Too many symbolic links encountered while traversing the pathname.

ENAMETOOLONG

pathname is too long.

ENOENT

A component of pathname does not exist, or pathname is an empty string and AT_EMPTY_PATH was not specified in params->at_flags.

ENOMEM

Out of memory (i.e., kernel memory).

ENOTDIR

A component of the path prefix of pathname is not a directory or pathname is relative and dirfd is a file descriptor referring to a file other than a directory.

VERSIONS

CONFORMING TO

NOTES

SEE ALSO

Index

NAME

SYNOPSIS

DESCRIPTION

Allowance for Future Attribute Expansion

Invoking fsinfo():

THE ATTRIBUTES

THE CAPABILITIES

RETURN VALUE

ERRORS

VERSIONS

CONFORMING TO

NOTES

SEE ALSO