Myopian: Add documentation for ls.

2020-05-31T23:14:37Z

Add documentation for ls.

New page

= .LS dot command =
== Usage ==

<code>.ls --help</code> entered at the basic prompt will print help.

This utility provides directory listings.

The help text is reproduced here:

<pre>
ls - list directory contents

ls [OPTION]... [FILE]...

List information about FILEs
(the current dir by default).

Sort entries alphabetically if
-StUX and --sort are not used.

FILTER FILES

-a, --all
do not ignore .*

-A, --almost-all
ignore . and ..

-B, --ignore-backups
do not list *.bak

Wildcards accepted.

LIST STYLE

-C
list entries by columns

-l
use a long listing format

-m
comma separated list

-x
list entries by lines

-1
list one file per line

--format=across : -x
--fromat=commas : -m
--format=horizontal : -x
--format=long : -l
--format=single-column : -1
--format=verbose : -l
--format=vertical : -C

-s, --size
print file size

-w, --width=COLS
set output width to COLS.

--lfn=off
print 8.3 filenames

--lfn=on
print lfn filenames

--lfn=both
print both 8.3 and lfn

SORT METHOD

-S
sort by size largest first

-t
sort by time newest first

-U
do not sort

-X
sort by extension

--sort=none : -U
--sort=size : -S
--sort=time : -t
--sort=extension : -X

-r, --reverse
reverse sort order

--gdf,
--group-directories-first
list directories before files

FILE SIZE FORMAT

-h, --human-readable
sizes in K,M,G (*1024)

--si
sizes in KB,MB,GB (*1000)

--block-size=SIZE
sizes scaled by SIZE

DATE-TIME FORMAT

--time-style=long-iso
2002-03-30 23:45

--time-style=iso
2002-03-30, 03-30 23:45

--time-style=locale
mar 30 2002 23:45

DIRECTORY PROCESSING

-d, --directory
list dirs and do not enter

-R, --recursive
list subdirs recursively

--system
include system files

OTHER

--help
print this help and exit

--version
print version info and exit
</pre>

== Notes ==

The <code>README.TXT</code> from the source is reproduced here.

<pre>
This is a near complete implementation of unix "ls" that
is capable of sorting directories with thousands of entries.

TODO:

* Add different list styles
Currently -l is always generated

* Change listing format depending on column width

* Add filename formatting with flag characters
and filename colouring.

* Parse the LS_COLOR environment variable for
colouring information. Currently this environment
variable and TIME_STYLE are both read but only
TIME_STYLE is processed.

NOTES:

The output format is limited to -l for now and chosen to
fit in 32 columns. The default is to list 8.3 filenames.

Try a variation like this one in 64 column mode:

.ls --gdf -AR --time-style=locale --lfn=on

USE OF MEMORY

A directory queue is maintained in two 8k pages and is
always paged entirely into memory at mmu6 and mmu7 when
accessed. The queue is fifo and exists in a circular
buffer occupying the 16k. In recursive mode, directories
that need to be visited are pushed into this queue. And
as directories are listed, they are popped out of the queue.

An obstack holding file pointer records is held in main
memory from the end of the program (around address 43000)
to the top of memory. Each file pointer record is a three-
byte pointer, the first byte indicating 8k page number and
the remaining two being a pointer into the page when it is
present in mmu7. These file pointer records are fixed size
and grow like an expanding array so are easily sortable with
quicksort. About 6000 records can be stored in main memory
allowing sorting of directories containing up to 6000 files.

Each file pointer record points at an actual file record.
These records are stored in extra 8k pages called LFN_PAGES.
A file record records 8.3 and lfn names, as well as time and
size information. An individual record is variable in size
because the lfn name is variable in size. Each page storing
records is managed by an obstack which will allocate memory
as needed. The number of pages available is statically
compiled into the program and is currently four which means
32k is available to store file records. Realistically this
places a much lower limit on the max number of files that
can be read from a directory at once, ie less than 6000.
If the limit is reached, the directory listing is split into
pieces. If more space is needed, more pages can be allocated
by changing a constant and re-building the program.

Utilities like .ls must co-exist with basic, as in they must
not disturb basic's state. This means .ls must allocate memory
from the operating system to load into and it must deallocate
that memory on exit. All tasks are taken care of automatically
when z88dk builds this type of dot command called "dotn".
</pre>

== Building ==

Source [https://gitlab.com/thesmog358/tbblue/-/tree/master/src/c/DotCommands/ls here].

[[Category:Developer Tools]]

Dot:ls - Revision history

Myopian: Add documentation for ls.