LS(1B)

💅 LS(1B) — the (BSD) list contents of directory bible 🗂️✨

okay bestie, listen up — this is the BSD System Compatibility flavour of ls, living at /ucb/ls, and she is that girl. she lists stuff, she's got opinions about sorting, and she will absolutely colorize your filenames if you let her. let's get into it 🫶

✨ NAME ✨

ls — (BSD) list contents of directory. that's it, that's the whole job, and she does it iconically 💅

🎀 SYNOPSIS 🎀

/ucb/ls [-aAcCdfFgHilLqrRstu1hSUX] [file ...]

🌸 DESCRIPTION 🌸

so here's the vibe: for every directory argument you hand her, ls lists what's inside that directory. for every file argument, she just repeats the name back at you plus whatever other info you asked for. simple, clean, slay.

the output is sorted alphabetically by default — no cap, that's just how she rolls. if you give her no argument at all, she lists the current directory. and if you give her several arguments? she sorts the arguments appropriately first, but — important — file arguments show up before directories and their contents. periodt.

there are several options, and yes we're going through all of them:

• -a — list all the entries. usually files that begin with a . get suppressed, but not today bestie.
• -A — list all entries except . and ... this is the default if ls is invoked by the super-user 👑.
• -c — use the time of last modification to the inode (mode, etc.) instead of last modification to the file, for sorting (-t) or printing (-l).
• -C — output printed in multiple columns, sorted down the columns. this format is selected by default if standard output refers to a terminal.
• -d — if the argument is a directory, list only its name, not its contents (mostly used with -l to get status on the directory itself).
• -f — force each argument to be interpreted as a directory and list the name found in each slot. this option turns off -l, -t, -s, and -r, and turns on -a; the order is the order in which entries appear in the directory. chaotic? maybe. iconic? absolutely.
• -F — indicates the file type as a letter appended to each pathname:

/   directory
*   executable file
@   symbolic link
|   named pipe
=   socket
>   door

• -g — if combined with -l, the group ID is added to the output.
• -i — print the i-number in the first column of the report for each file listed.
• -l — list in long format, giving mode, number of links, owner, size in bytes, and time of last modification for each file (see below 👇). if the file is a special file, the size field will instead contain the major and minor device numbers. symbolic links specified as arguments are not followed with this option unless the -H or -L option is also present.
• -L — follow symbolic links in arguments.
• -q — non-printable characters are printed as question marks ?. this is the default if standard output refers to a terminal.
• -r — reverse the order of sort, to get reverse alphabetic or oldest first as appropriate.
• -R — lists subdirectories recursively. she goes deep 🕳️
• -s — give size in blocks, including indirect blocks, for each entry.
• -t — sort by time modified (latest first) instead of by name, as is normal.
• -u — use time of last access instead of last modification for sorting (-t) or printing (-l).
• -1 — print one filename per output line. this is the default if standard output does not refer to a terminal.

the following option was introduced with POSIX.1-2001:

• -H — follow symbolic links given as arguments.

the following options are available as extensions:

• -h — print file sizes in human-readable powers of 1024, i.e. K for kilobyte, M for megabyte, G for gigabyte, T for terabyte, P for petabyte, and E for exabyte. no more counting zeros bestie 🔥
• -S — sort by file size.
• -U — do not sort at all. feral behaviour, honestly.
• -X — sort by file name extension, i.e. by the component of the file name following the last dot.

---

🧚 the mode string, decoded 🧚

the mode printed under the -l option contains 10 characters, and here's how to read them. the first character is:

• d if the entry is a directory
• b if the entry is a block-type special file
• c if the entry is a character-type special file
• p if the entry is a named pipe
• l if the entry is a symbolic link
• S if the entry is a socket
• s if the entry is a XENIX semaphore
• m if the entry is a XENIX shared data (memory) file
• D if the entry is a door
• - if the entry is a plain file

the next 9 characters are interpreted as three sets of three bits each. the first set refers to owner permissions, the next to permissions to others in the same user-group, and the last to all others. within each set, the three characters indicate permission respectively to read, to write, or to execute the file as a program. and for a directory, execute permission is interpreted to mean permission to search the directory for a specified file. the permissions are indicated as follows:

• r if the file is readable
• w if the file is writable
• x if the file is executable
• - if the indicated permission is not granted

the group-execute permission character is given as:

• s if the file has set-group-ID mode
• S if the set-group-ID bit is set on the file but it is not executable

likewise, the user-execute permission character is given as:

• s if the file has set-user-ID mode
• S if the set-user-ID bit is set on the file but it is not executable

the last character of the mode (normally x or -) is:

• t if the sticky bit of the mode is on
• T if the sticky bit is on but the file is not executable

see chmod(1) for the meaning of this mode. iykyk 🎀

---

when the sizes of the files in a directory are listed, a total count of blocks, including indirect blocks is printed.

🌈 colors, because obviously 🌈

if ls writes its output to a terminal that supports colors or boldface, the file names printed are colorized according to their types:

• blue/bold if the file is a directory
• yellow/bold if the file is a special file
• yellow if the file is a named pipe
• cyan if the file is a symbolic link
• magenta/bold if the file is a socket or a door
• magenta if the file is a XENIX special file
• green/bold if the file is executable

for lc, colors are enabled even if the output is not written to a terminal. this is mainly useful if the output is filtered through a pager which handles colors, such as pg(1). cute little pipeline queen behaviour 💜

🦋 FILES 🦋

• /etc/passwd — to get user IDs.
• /etc/group — to get group IDs.

🍓 ENVIRONMENT VARIABLES 🍓

• COLUMNS — overrides the auto-detected terminal width.
• LANG, LC_ALL — see locale(7).
• LC_COLLATE — affects the order of printed items when sorting by name.
• LC_CTYPE — determines whether a character is printable.
• LC_TIME — sets the format of time strings printed with the -l option.
• TERM — used to determine the terminal type.

👑 SEE ALSO 👑

chmod(1), locale(7)

---

and that's the whole page, bestie 🫶 this one's brought to you by the Heirloom Toolchest, dated 1/29/05, filed under LS(1B) — go forth and list your directories with main character energy ✨💅🌸