These docs are under active development and cover the v0.20 Kobicha security model.
Peios Learn
On this page
reference 5 min read

stat

stat displays the detailed status of a file. Where ls gives you a line per file, stat gives you everything the system records about one file: its type, its size, its timestamps, and the low-level metadata stored in its inode.

stat [options] file...

stat is a diagnostic tool. It dumps what a file's inode physically contains, verbatim. That makes it the right command for "tell me exactly what is recorded about this file" — and it means some of what it prints needs a word of explanation, below.

The default output

With no options, stat prints a labelled, multi-line block per file:

$ stat notes.txt
  File: notes.txt
  Size: 219             Blocks: 8          IO Block: 4096   regular file
Device: 8,2     Inode: 1572931     Links: 1
Access: (0644/-rw-r--r--)  Uid: ( 1000/    jack)   Gid: ( 1000/    jack)
Access: 2026-05-15 11:03:42.000000000 +0000
Modify: 2026-05-15 11:03:42.000000000 +0000
Change: 2026-05-15 11:03:18.000000000 +0000
 Birth: 2026-05-15 11:03:18.000000000 +0000

Reading it line by line:

  • File — the name, and for a symbolic link, what it points to.
  • Size / Blocks / IO Block / type — the size in bytes, the number of allocated disk blocks, the preferred I/O block size, and the file type in words.
  • Device / Inode / Links — the device the file lives on, its inode number (its unique index within that device), and the number of hard links to it.
  • Access / Uid / Gid — a numeric owner id, a group id, and a mode value. See the caveat below — these are not the access policy.
  • Access / Modify / Change / Birth — four timestamps: when the file was last read, last written, last had its metadata changed, and first created.

The Uid, Gid, and mode fields are decorative

The Access: (0644/-rw-r--r--) Uid: (…) Gid: (…) line needs care.

A file's inode carries a numeric owner id, a numeric group id, and a mode value, and stat reports them because stat reports the inode verbatim. But the Peios access model does not consult these fields. What a principal may do to a file is decided by the file's security descriptor — see Security descriptors. The numbers on the Uid/Gid/mode line are inert metadata: they are stored, they are reported, and they have no effect on any access decision.

Do not read that line as a permission summary. A file showing 0644 is not "world-readable" in any meaningful sense — whether anyone can read it depends entirely on its security descriptor. stat shows these fields for completeness as a low-level diagnostic; it does not claim they mean anything.

To see the parts of a file's security that do count, use ls -l, which shows the owner SID and the mode column built from the security descriptor.

Custom output formats

Two options replace the default block with output you control.

Option Effect
-c FORMAT, --format=FORMAT Print FORMAT for each file, substituting % directives. A newline is added after each file.
--printf=FORMAT Like --format, but interpret backslash escapes (\n, \t) in FORMAT and add no trailing newline. Include \n yourself if you want one. 
$ stat --format='%n is %s bytes' notes.txt
notes.txt is 219 bytes

File directives

Used in the format string when stating files (the default mode):

Directive Substitutes
%n File name.
%N Quoted file name; for a symlink, with the target shown.
%F File type in words (regular file, directory, …).
%s Total size, in bytes.
%b Number of allocated blocks.
%B Size in bytes of each block counted by %b.
%o Preferred I/O transfer block size.
%i Inode number.
%h Number of hard links.
%d / %D Device number, in decimal / in hexadecimal.
%t / %T For a device file, the major / minor device type, in hexadecimal.
%m Mount point of the file system the file is on.
%f Raw mode value, in hexadecimal.
%x / %X Last access time — human-readable / seconds since the epoch.
%y / %Y Last modification time — human-readable / seconds since the epoch.
%z / %Z Last status-change time — human-readable / seconds since the epoch.
%w / %W File creation (birth) time — human-readable / seconds since the epoch. - or 0 if unknown.

The directives %a and %A (the mode in octal and in symbolic form) and %u, %U, %g, %G (the owner and group, numeric and by name) report the decorative inode fields described above. They are available for completeness; they are not the file's access policy.

The %C directive (security context) is inactive — it produces no meaningful value on a standard Peios system.

File-system directives

With -f, stat reports on the file system a file lives on rather than the file itself, and the format string uses a different directive set:

Directive Substitutes
%n File name.
%i File-system ID, in hexadecimal.
%t / %T File-system type — in hexadecimal / in words.
%l Maximum length of a file name.
%s Block size, for fast transfers.
%S Fundamental block size, used for the block counts.
%b Total data blocks in the file system.
%f Free blocks.
%a Free blocks available to an ordinary principal.
%c Total inodes (file nodes).
%d Free inodes.

Options

Option Effect
-f, --file-system Report on the file system containing each file, instead of the file.
-L, --dereference Follow symbolic links — report on the link's target rather than the link itself.
-t, --terse Print the information on a single line, as bare values with no labels. Useful for scripts.

Exit status

Code Meaning
0 Every file was stated successfully.
1 A file could not be stated, or an option or format directive was invalid.

See also