filesystem.stat

Return filesystem information for a given path.

The reported timestamps reflect statx() values. The atime and mtime timestamps are mutable from userspace, and btime may also be mutable from userspace depending on the platform.

The returned attributes list contains the statx() file attributes that apply to the file (see the statx(2) manpage for details). ZFS flags set via filesystem.set_zfs_attributes are surfaced here: an immutable file reports IMMUTABLE and an append-only file reports APPEND.

Note

mount_id uniquely identifies the particular mount underlying the path. Bind mounts share the same dev (device id) but have distinct mount_id values, so mount_id (not dev) must be used to identify children of a given mountpoint.

Type: object

Type: array
No Additional Items

Tuple Validation

Parameter 1: path

path

Type: string

Absolute filesystem path to get statistics for.

Must be at least 1 characters long

FilesystemStatData

Type: object

File or directory statistics information.

 No Additional Properties

Realpath

Type: string

Canonical path of the entry, eliminating any symbolic links.

Must be at least 1 characters long

Type

Type: enum (of string)

Type of filesystem entry.

Must be one of:
  • "DIRECTORY"
  • "FILE"
  • "SYMLINK"
  • "OTHER"

Size

Type: integer

Size in bytes of a plain file. This corresonds with stx_size.

Allocation Size

Type: integer

Allocated size of file. Calculated by multiplying stx_blocks by 512.

Mode

Type: integer

Entry's mode including file type information and file permission bits. This corresponds with stx_mode.

Mount Id

Type: integer

The mount ID of the mount containing the entry. This corresponds to the number in first field of /proc/self/mountinfo and stxmntid.

Uid

Type: integer

User ID of the entry's owner. This corresponds with stx_uid.

Gid

Type: integer

Group ID of the entry's owner. This corresponds with stx_gid.

Atime

Type: number

Time of last access. Corresponds with stx_atime. This is mutable from userspace.

Mtime

Type: number

Time of last modification. Corresponds with stx_mtime. This is mutable from userspace.

Ctime

Type: number

Time of last status change. Corresponds with stx_ctime.

Btime

Type: number

Time of creation. Corresponds with stx_btime.

Dev

Type: integer

The ID of the device containing the filesystem where the file resides. This is not sufficient to uniquely identify a particular filesystem mount. mountid must be used for that purpose. This corresponds with stdev.

Inode

Type: integer

The inode number of the file. This corresponds with stx_ino.

Acl

Type: boolean

Specifies whether ACL is present on the entry. If this is the case then file permission bits as reported in mode may not be representative of the actual permissions.

Is Mountpoint

Type: boolean

Specifies whether the entry is also the mountpoint of a filesystem.

Is Ctldir

Type: boolean

Specifies whether the entry is located within the ZFS ctldir (for example a snapshot).

Attributes

Type: array of enum (of string)

Extra file attribute indicators for entry as returned by statx. Expanded from stx_attributes.

 No Additional Items
Each item of this array must be:
Type: enum (of string)
Must be one of:
  • "COMPRESSED"
  • "APPEND"
  • "NODUMP"
  • "ENCRYPTED"
  • "IMMUTABLE"
  • "AUTOMOUNT"
  • "MOUNT_ROOT"
  • "VERIFY"
  • "DAX"

User


Username associated with uid. Will be None if the User ID does not map to existing user.

Type: string

Must be at least 1 characters long

Type: null

Group


Groupname associated with gid. Will be None if the Group ID does not map to existing group.

Type: string

Must be at least 1 characters long

Type: null


Required roles: FILESYSTEM_ATTRS_READ