DACSLF(1) DACS Tools and Utilities DACSLF(1)

NAME

dacslf — list files

SYNOPSIS

dacslf [jflags] [iflags] [cflags] [sflags] [hflags] [file...]
dacslsd
dacslsf
dacslss
dacstoday

DESCRIPTION

This program is part of the DACS suite.

Note

This is a beta version. Some features and options of dacslf may be buggy.

The dacslf command displays information about each argument that names a file. For files of type directory, dacslf can display information about the files within that directory. If no file argument is given, the contents of the current directory (".") are implied. A large number of options is available to select, organize, and format the output.

There are many implementations of the ls command. While they tend to have a core group of flags that have approximately the same effect, there are many subtle and not-so-subtle implementation and platform-dependent differences in flag names, syntaxes, and semantics, and in implementation details. The dacslf command is no different, with core flags behaving as expected but with many differences outside of them. Several new or convenient features that have proved to be difficult to approximate using scripts, aliases, or pipelines have been implemented, such as the ability to:

  • specify the formatting of each listed filename (modeled after stat(1));

  • list only directories, non-directories, or special files;

  • list only files modified or accessed within a certain number of days; and

  • configure coloured printing of filenames or listing lines based on a characteristic of that file or its name.

Some less-used or idiosyncratic features, flags, and behaviours found in other ls implementations have been changed or omitted.

OPTIONS

dacslf recognizes many options, which are placed into six groups according to their purposes or syntaxes. Some flags have synonyms. Some flags are mutually exclusive (e.g., -fmt causes -i to be disabled) and the order of flags on the command line is sometimes significant. Many flags may be repeated, but in some instances duplicates may be ignored or may affect the behaviour of earlier flags.

Joinable flags (jflags)

The following flags can be joined (i.e., conflated, like "-dl"), but they may also appear as separate flags ("-d -l").

-1

Emit single column output (i.e., print one file per line). Also: --single-column.

-a

Include 'dot' files when listing directories.

-A

Print filenames using absolute paths.

-c

Use the last change time instead of last modification time.

-d

Include the root level directory (also -r0).

-F

Append a file type indicator character to filenames. Also see the %T format specification.

-h

With -l, use human-friendly unit suffixes for sizes (B, K, M, G, T, P)

-i

Print the inode number (unless -fmt).

-k

Use 1024 for the blocksize (overrides prior -h).

-l

Use the long format (unless -fmt).

-m

Merge comma-separated filenames into lines.

-n

Prepend a line number to the format, starting at 1.

-p

Append a slash to each filename that is a directory.

-Q

Surround filenames with single quotes.

-r

Reverse the default or selected sort order.

-R

Recurse into directories and subdirectories.

-s

Display the number of file system blocks used by a file.

-u

Use the last access time instead of last modification time.

-U

Use the creation time, when available on the platform, instead of the last modification time.

-v

Verbose output. This prints the run-time values of various flags and platform characteristics.

-w

Emit unprintable filenames (do not escape them).

Individual flags (iflags)

The following individual flags are understood.

-Dd

List directories only (may also be available as command name lsd).

-Df

Order directories separately and list them first.

-Ds

List symbolic links only.

-Dx

List non-directories only.

-dfmt datefmt

Use strftime(3) format conversion specification datefmt for each date.

-f namefile

Read the names of files to be listed from namefile, one per line. This flag may be repeated. The command line may also include file arguments.

-fmt linefmt

Use a custom format specification for output lines (overrides -l). See Formatting specifications.

-o#

Emit only the first # lines. A value of zero (-o0 removes the limit, which is the default behaviour.

-S STR

Prepend STR to filenames (overrides -A).

-t[#]

Only list regular files that have been modified/changed/accessed/created (default, or with -c, -u, or -U, respectively) within the past # time units. (File creation time is not provided on some platforms.) A single-letter time unit may follow the #. The units are: d (days), w (weeks), m (months), y (years), H (hours), M (minutes), S (seconds). The default is days. The # must be greater than zero. When the command is invoked as today, this flag can be shortened to -#, where # is greater than zero. Example: -t7d selects files (and directories) that have been modified within the past seven days.

-te[#]

Like -te, except using the exact time specified instead of less than or equal to the time specified. Example: -u -t2w selects files (and directories) that were accessed exactly two weeks ago.

--aa

Like -a except exclude all '.' and '..' files. Synonym: --almost-all.

--aar

When run by the super-user, include dot directories other than '.' and '..'. Also: --almost-all-root.

--bssi

Use SI units (powers of 10) for blocksize reporting.

--esc

Escape individual problematic filename characters. Repeat for effect.

--h#

Set the units for the -h flag to 1024 or 1000 (the default). Example: --h1024 makes 12K approximately 12 * 1024.

--perms [+|-]PERMS

Select a file if octal permission PERMS, optionally preceded by a modifier character, match the file's mode permissions: if all of PERMS are set ("+"); if none of PERMS are set ("-"); or if without a modifier character, if PERMS match exactly. For example, the PERMS value +0444 matches files that are readable by any user (but may also be readable or writable), 0444 matches files that are readable by any user but have no other permissions, and -0444 matches files that have no "read" permissions but may possibly have other permissions.

--recurse #

Recurse at most # levels deep, where # is greater than zero.

--type TYPES

Select files having any type listed by TYPES, which is a list of one more more single character specifiers:


b : block devices
c : character devices
d, D, / : directories
f, F, r, R : regular files
l, @ : soft links
n : regular and more than one hard link
p, | : FIFO
s, = : socket
*, e : executable
E : not (regular and executable)
% : whiteout (platform dependent)

--version

Print the version stamp, then exit.

--

End of flag arguments.

Formatting specifications

Conversion specifiers are used with the -fmt flag to describe the content and format of the listing output. If a requested conversion is unavailable, a single space is emitted. Some conversions are not supported on some platforms.

To emit each file on a separate line, include the -1 flag.

Note: There is a bug in that padding (spaces) may be prepended to fields.

The following text interpolations are understood:

%b

Number of blocks used.

%c

Output line number, starting at one.

%d{abcdm}

Date/Time, depending on the single-letter modifier (a: st_atime, last access time; b: st_birthtime, creation time; c: st_ctime, last inode change time; d: respect the -c, -u, or -U flag, if given, otherwise the st_mtime default; m: st_mtime, last modification time), and formatted according to the -dfmt specification or its default.

%ds{abcdm}

Like %d, except emit the selected date/time as the seconds since the epoch.

%D

Output the device number (st_dev).

%f

Output the flags (st_flags).

%h

Output the size, in "human readable" form (st_size).

%i

Output the inode number (st_ino).

%l

Output the link count (st_nlink).

%m

Output the mode bits as a string (st_mode).

%M

Output the mode bits as an octal number (st_mode).

%n

The filename.

%R

Output the device number for device special files (st_rdev).

%s

Output the size, in bytes (st_size).

%T

Output the file type, as a single indicator character (st_mode), /: directory; *: executable; @: symbolic link; =: socket; |: FIFO; %: whiteout.

%u

Output the username as a string (st_uid).

%U

Output the username as a number (st_uid).

%g

Output the groupname as a string (st_gid).

%G

Output the groupname as a number (st_gid).

%%

Output a literal %.

Use the %+ form to highlight the field; e.g., %+s to highlight the size field. If there is no -fmt flag, the filename is always highlighted and anything else is printed normally.

Colour flags (cflags)

These individual flags are used to configure colourized output. Colourization is disabled by default. Some flags implicitly enable colourization. These flags can be repeated, with flags seen later overriding flags seen earlier.

-Ca

Default is to colour entire line, not only the filename. Enables colourization if not explicitly disabled.

-Cl

Use colour with long format or custom format only. Enables colourization if not explicitly disabled.

-Coff

Disable colourization.

-Con

Enable colourization.

-Cp filename

Use RGB definitions in filename, overriding build-time configuration.

-C colour

Set the default colour. The colour may be one of: black, red, green, yellow, blue, magenta, cyan, orange, white, black. Enables colourization if not explicitly disabled.

The colour may also be one of:


#red;green;blue (Example: "-C #254;197;68")
rgb-colour-name (Example: "-C RoyalBlue3")
bold (Example: "-C bold")
underline

Example: "-C red".

-Cspec colour

Apply the colour choice to the file type identified by spec. Enables colourization if not explicitly disabled. The spec is one or more of these single-character identifiers:


  +  : default for non-regular files
  -  : for regular files
  /  : for directories
  *  : for executables
  @  : for links
  .  : for regular dot files
  =  : for sockets
  |  : for FIFOs
  %  : for whiteouts

Example: "-C-/ red -C@ blue"

-Cg glob colour

Use colour for filenames selected by glob. Enables colourization if not explicitly disabled. Example:


   dacslf -Cg '*.pdf' red -Cg '*.core' yellow

Sort flags (sflags)

These individual flags are used to specify how the output is to be sorted.

--sa

Sort alphabetically, a-z, case sensitively.

--sai

Sort alphabetically, a-z, case insensitively.

--sb

Sort size bigger to smaller.

--sl

Sort by decreasing hard link count.

--sn

Sort newest modified to oldest.

--so

Sort oldest modified to newest.

--soff

Sorting is turned off.

--ss

Sort size smaller to bigger.

--su

Sort most recently used/accessed first.

--sul

Sort most recently used/accessed last.

--sz

Sort alphabetically, z-a, case sensitively.

--szi

Sort alphabetically, z-a, case insensitively.

--sgid

Sort extra flag: separate by gid.

--suid

Sort extra flag: separate by uid.

Help flags (hflags)

These individual flags cause various usage information to be printed to stdout. More than one of these flags can be given. After printing the help information, the program exits.

--help
--help-a

Print all help.

--help-c

Print all cflags (colour) help.

--help-f

Print all formatting specification help.

--help-h

Print help help.

--help-i

Print iflags (individual) help.

--help-j

Print jflags (joinable) help.

--help-s

Print sflags (sort) help.

The single-letter selectors can be combined (e.g., --help-cij). They can also be identified by their long name (e.g., --help-join or --help-format).

Command synonyms

For convenience several commands can be installed.

dacslsd [...] is equivalent to: 

dacslf -Dd [...]

dacslsf [...] is equivalent to: 

dacslf -Dx [...]

dacslss [...] is equivalent to: 

dacslf -Ds [...]

dacstoday [-#] [...] is equivalent to: 

dacslf -t[#] [...]

(default: 1)

dacstoday -e [-#] [...] is equivalent to: 

dacslf -te[#] [...]

ENVIRONMENT

BLOCKSIZE

The blocksize to use, if LF_BLOCKSIZE is not available.

HOME

The user's home directory, for rgb.txt.

LF_BLOCKSIZE

The blocksize to use; e.g., for the -s flag.

LF_COLOURS

A string containing zero or more colour-specification flags. These are overridden by colour-specification flags found on the command line. Example: 

LF_COLOURS="-C- yellow -C/ bold -Ca"; export LF_COLOURS

RGBPATH

The path for rgb.txt.

RGBSEARCHPATH

A colon-separated list of directories to search for rgb.txt.

TERM

The terminal identifier, to determine its characteristics, such as the number of columns.

FILES

If colourization is required, the colour dictionary rgb.txt may be read. If specified using the -Cp flag, that file is used; otherwise RGBPATH is used, if given; otherwise RGBSEARCHPATH is searched, if given; otherwise the users home directory is checked, if available; otherwise a compile-time search path is checked, if available.

EXIT STATUS

The dacslf utility exits 0 on success, and 1 if an error occurs (such as if an invalid parameter is seen or if file system traversal fails).

NOTES

Although this command can sometimes be a handy alternative to ls(1), it was mainly written as a means of testing and debugging elements of the DACS support library.

The current implementation is perhaps a little too monolithic. It might be better implemented as a set of independent processes: Scan one or more files/directories given on the command line, traversing/descending as required; Emit a list of file objects and meta information, emitting JSON (or similar structured output); Filter file objects from the input stream by applying well-defined boolean expressions to each object's metadata (the file selection/deselection options can be useful on their own); emit selected objects' metadata unchanged; sort input stream object metadata based on one or more specified metadata types; format and write requested object metadata. This component-based architecture would be less efficient (runtime and implementation-wise), and require more configuration/build/maintenance/documentation effort. The individual programs could be useful on their own; e.g., to implement an alternative to find(1).

EXAMPLES

The following will list the name of each file in the current directory, at least one space, the file mode, at least one space, and the file size in bytes. 

dacslf -1 -fmt '%n %m %s'

The following two commands, which are equivalent, list only directories in the current directory, including those with names beginning with a dot, and append a file type indicator to the file names (in this case, a slash). 

dacslf -a -Dd -F
dacslf -aF --type /

Only list the files on the command line that have been modified within the past seven days. 

dacslf -a -t7 *.c *.h

Print the names of regular files in yellow, directories in bold, and other names in black. 

dacslf -C- yellow -C/ bold -Ca

dacslf -C- yellow -C/ bold -l

Print the entire listing line for regular files in blue, others in black. 

dacslf -C- blue -Ca -l

DIAGNOSTICS

An error message may be written to stderr; e.g., if a file given on the command line does not exist or information about a file is unavailable due to permissions.

COMPATIBILITY

The program does not conform to IEEE Std 1003.1, 2004: ls(1) or any other standard.

SEE ALSO

FreeBSD: ls(1).

Linux: ls(1).

MacOS: ls(1).

IEEE Std 1003.1, 2004: ls(1).

BUGS

The treatment of both directories and symbolic links to directories can be inconsistent and/or incorrect across the multitude of flags because of option ordering and implementation-dependent (file inclusion/exclusion) application of selection.

The semantics of combinations of options can be counter-intuitive or just plain wrong.

AUTHOR

Distributed Systems Software (www.dss.ca)

COPYING

Copyright © 2003-2026 Distributed Systems Software. See the LICENSE file that accompanies the distribution for licensing information.

DACS Version 1.5.2 28-Aug-2026 DACSLF(1)

Table of Contents
Font:
 −− Set ++

$Id: dacslf.1.xml 3454 2026-08-01 20:39:04Z brachman $