# 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.

##

#### Nlink

Type: integer

Number of hard links. Corresponds with stx_nlinks.

##

#### 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.

## Any of

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.

## Any of

Type: string

Must be at least `1` characters long

Type: null

Required roles: FILESYSTEM_ATTRS_READ