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

Listing and paths

Before you can do anything with a file you usually have to find it — see what a directory holds, learn one file's details, turn a relative name into an absolute one. This topic covers the commands for that: listing directories, inspecting a single file, and resolving path names.

This page is the map. It names every command in the topic, says in one line what each is for, and points you at the page that covers it in full.

The commands

Command Purpose
ls List the contents of a directory. The everyday command for "what's in here?".
dir and vdir ls with a fixed output style. dir lists in columns; vdir lists in long format.
stat Show the detailed status of one file — its type, size, timestamps, and raw inode metadata.
pwd Print the directory you are currently working in.
readlink Print where a symbolic link points.
realpath Resolve a path to its canonical, absolute form — every symlink followed, every . and .. removed.
basename Strip the directory part off a path, leaving just the final name.
dirname The opposite of basename — strip the final name, leaving the directory.
pathchk Check whether a path name is valid and portable before you try to create it.
dircolors Produce the colour settings that ls uses when it colours its output.

These commands and file security

Most commands in this topic work purely on path strings — they never touch the file the path names. basename, dirname, realpath, and pathchk are all string operations.

Two report on real files, and they relate to file security differently:

  • ls -l surfaces security-descriptor information directly. On Peios a file's access is governed by its security descriptor — the record of who owns the file and who may do what to it. The long listing shows the owner and the parts of the descriptor that fit in a one-line-per-file format.
  • stat is a low-level diagnostic. It dumps the raw contents of a file's inode. The inode carries some numeric fields — an owner id, a group id, a mode value — that the Peios access model does not consult. stat reports them because it reports the inode verbatim, but they are not the file's access policy.

Neither command prints the full security descriptor; inspecting that is a job for the dedicated security tooling. If a line of ls -l looks unfamiliar, or you want to know why stat shows fields that "don't count", the explanation is in Security descriptors.

Where to start

If you want the everyday "what's in this directory" command and the meaning of every column it prints, read ls.

If you need the full detail of one specific file, read stat.

If you are writing a script and need to take a path apart or canonicalise it, the string commands — basename, dirname, realpath — are what you want.

See also