filesystem.stat

Return filesystem information for a given path.

realpath(str): absolute real path of the entry (if SYMLINK)

type(str): DIRECTORY | FILE | SYMLINK | OTHER

size(int): size of the entry

allocation_size(int): on-disk size of entry

mode(int): file mode/permission

uid(int): user id of file owner

gid(int): group id of file owner

atime(float): timestamp for when file was last accessed. NOTE: this timestamp may be changed from userspace.

mtime(float): timestamp for when file data was last modified NOTE: this timestamp may be changed from userspace.

ctime(float): timestamp for when file was last changed.

btime(float): timestamp for when file was initially created. NOTE: depending on platform this may be changed from userspace.

dev(int): device id of the device containing the file. In the context of the TrueNAS API, this is sufficient to uniquely identify a given dataset.

mount_id(int): the mount id for the filesystem underlying the given path. Bind mounts will have same device id, but different mount IDs. This value is sufficient to uniquely identify the particular mount which can be used to identify children of the given mountpoint.

inode(int): inode number of the file. This number uniquely identifies the file on the given device, but once a file is deleted its inode number may be reused.

nlink(int): number of hard lnks to the file.

acl(bool): extended ACL is present on file

is_mountpoint(bool): path is a mountpoint

is_ctldir(bool): path is within special .zfs directory

attributes(list): list of statx file attributes that apply to the file. See statx(2) manpage for more details.

Type: object

Type: array
No Additional Items

Tuple Validation

Parameter 1: path

path

Type: string

Must be at least 1 characters long

FilesystemStatData

Type: object
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)
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"
  • "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